or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

charts.mddata-management.mdindex.mdstyling-properties.mdvisualization-grammar.md
tile.json

tessl/pypi-vincent

A Python to Vega translator for creating interactive data visualizations from Python data structures.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/vincent@0.4.x

To install, run

npx @tessl/cli install tessl/pypi-vincent@0.4.0

index.mddocs/

Vincent

Vincent is a Python library that translates Python data structures into Vega visualization grammar. It enables developers to create interactive data visualizations by converting Python data (tuples, lists, dictionaries, and Pandas DataFrames) into Vega JSON specifications, bridging Python's data processing capabilities with JavaScript's visualization strengths.

Package Information

  • Package Name: vincent
  • Language: Python
  • Installation: pip install vincent
  • Dependencies: pandas (required)

Core Imports

import vincent

Direct access to specific components:

from vincent import (
    Chart, Bar, Line, Area, Scatter, StackedBar, StackedArea, 
    GroupedBar, Map, Pie, Word, Visualization, Data, Transform,
    PropertySet, ValueRef, DataRef, Scale, MarkProperties, 
    MarkRef, Mark, AxisProperties, Axis, initialize_notebook
)

Basic Usage

import vincent
import pandas as pd

# Create sample data
data = [10, 20, 30, 40, 50]

# Create a simple bar chart
bar = vincent.Bar(data)
bar.width = 400
bar.height = 200

# Output as Vega JSON specification
vega_spec = bar.to_json()

# For Jupyter notebooks
vincent.initialize_notebook()
bar  # Will display the visualization

Using with pandas DataFrames:

import pandas as pd
import vincent

# Create DataFrame
df = pd.DataFrame({
    'x': range(10),
    'y': [i**2 for i in range(10)]
})

# Create line chart from DataFrame
line = vincent.Line(df, columns=['x', 'y'])
line.axis_titles(x='X Values', y='Y Values')

Architecture

Vincent follows the Vega grammar specification with a hierarchical structure:

  • Visualization: Top-level container for complete Vega specifications
  • Charts: High-level chart constructors (Bar, Line, Area, etc.) that extend Visualization
  • Grammar Components: Core Vega elements (Data, Scales, Marks, Axes, etc.)
  • Data Handling: Automatic conversion between Python data structures and Vega data format
  • Property System: Comprehensive styling and configuration through PropertySet and ValueRef

This design enables both simple chart creation for common use cases and full control over Vega grammar for advanced visualizations.

Capabilities

Chart Construction

High-level chart constructors for common visualization types including bar charts, line charts, scatter plots, area charts, pie charts, maps, and word clouds. These provide intuitive APIs while generating complete Vega specifications.

class Chart(Visualization):
    def __init__(self, data=None, columns=None, key_on='idx', iter_idx=None,
                 width=960, height=500, grouped=False, no_data=False, *args, **kwargs): ...

class Bar(Chart): ...
class Line(Chart): ...
class Area(Chart): ...
class Scatter(Chart): ...
class GroupedBar(Chart): ...
class Map(Chart): ...
class Pie(Chart): ...
class Word(Chart): ...

# Aliases for stacked charts
StackedBar = Bar
StackedArea = Area

Charts

Data Management

Data handling and transformation capabilities including automatic data type detection, pandas integration, and support for multiple data formats. Enables seamless conversion between Python data structures and Vega data specifications.

class Data(GrammarClass):
    def __init__(self, name=None, **kwargs): ...
    
    @classmethod
    def from_pandas(cls, data, columns=None, key_on='idx', name=None,
                    series_key='data', grouped=False, records=False, **kwargs): ...
    
    @classmethod
    def from_iter(cls, data, name=None): ...
    
    @classmethod
    def from_mult_iters(cls, name=None, idx=None, **kwargs): ...

class Transform(GrammarClass):
    # Supports transform types: array, copy, cross, facet, filter, flatten, 
    # fold, formula, slice, sort, stats, truncate, unique, window, zip,
    # force, geo, geopath, link, pie, stack, treemap, wordcloud
    pass

Data Management

Visualization Grammar

Core Vega grammar components for building custom visualizations including scales, marks, axes, legends, and property systems. Provides full access to Vega's visualization capabilities.

class Visualization(GrammarClass):
    def __init__(self, *args, **kwargs): ...
    def to_json(self): ...

class Scale(GrammarClass):
    # Properties: name, type, domain, range, reverse, round
    # Types: ordinal, linear, log, pow, sqrt, quantile, quantize, threshold
    pass

class Mark(GrammarClass):
    # Properties: type, from_, properties, key, delay, ease
    pass

class Axis(GrammarClass):
    # Properties: type, scale, orient, title, format, ticks, etc.
    pass

Visualization Grammar

Styling and Properties

Comprehensive styling system using PropertySet and ValueRef for controlling visual appearance, animations, and interactions. Supports all Vega visual properties and value referencing patterns.

class PropertySet(GrammarClass):
    # Position properties: x, x2, y, y2, width, height
    # Style properties: fill, fillOpacity, stroke, strokeOpacity, strokeWidth
    # Text properties: text, fontSize, fontWeight, fontStyle, align, baseline
    pass

class ValueRef(GrammarClass):
    # Properties: value, field, group, scale, mult, offset, band
    pass

class MarkProperties(GrammarClass):
    # Properties: enter, exit, update, hover (PropertySet for each)
    pass

Styling and Properties

Utility Functions

def initialize_notebook():
    """Initialize IPython notebook display elements for Vincent visualizations."""

def data_type(data, grouped=False, columns=None, key_on='idx', iter_idx=None):
    """Automatic data type detection and conversion for various Python data structures."""

Color Palettes

from vincent.colors import brews

# brews is a dictionary containing ColorBrewer palettes:
# Sequential: YlGn, YlGnBu, GnBu, BuGn, PuBuGn, PuBu, BuPu, RdPu, PuRd, 
#            OrRd, YlOrRd, YlOrBr, Purples, Blues, Greens, Oranges, Reds, Greys
# Diverging: Spectral, RdYlGn, RdBu, PiYG, PRGn, RdYlBu, BrBG, RdGy, PuOr  
# Qualitative: Set2, Accent, Set1, Set3, Dark2, Paired, Pastel2, Pastel1