tessl/pypi-vincent
A Python to Vega translator for creating interactive data visualizations from Python data structures.
visualization-grammar.mddocs/
Visualization Grammar
Core Vega grammar components for building custom visualizations. These classes provide direct access to the underlying Vega specification elements, enabling full control over visualization structure and behavior.
Capabilities
Visualization Container
The top-level container class that holds the complete Vega specification and manages all visualization components.
class Visualization(GrammarClass):
"""Visualization container class for complete Vega specifications"""
def __init__(self, *args, **kwargs):
"""
Initialize a Visualization
Sets data, marks, scales, and axes properties to empty KeyedLists
if not defined by arguments. Legends are set to empty list.
"""
def to_json(self):
"""
Export complete Vega specification as JSON
Returns:
str: JSON string containing complete Vega specification
"""
@property
def data(self):
"""KeyedList of Data objects (keyed by 'name')"""
@property
def scales(self):
"""KeyedList of Scale objects (keyed by 'name')"""
@property
def marks(self):
"""KeyedList of Mark objects (keyed by 'type')"""
@property
def axes(self):
"""KeyedList of Axis objects (keyed by 'type')"""
@property
def legends(self):
"""List of Legend objects"""Scales
Maps data values to visual properties like position, color, and size. Supports all Vega scale types with comprehensive configuration options.
class Scale(GrammarClass):
"""Definitions for mapping from data space to visual space"""
@property
def name(self):
"""
Unique name for the scale
Returns:
str: Scale name used for referencing by other components
"""
@property
def type(self):
"""
Type of the scale
Valid types:
- 'ordinal': Ordinal scale for categorical data
- 'linear': Linear scale for continuous quantitative data
- 'log': Logarithmic scale
- 'pow': Power scale with configurable exponent
- 'sqrt': Square root scale (power scale with exponent 0.5)
- 'quantile': Quantile scale for statistical distributions
- 'quantize': Quantizing scale for binning continuous data
- 'threshold': Threshold scale for custom breakpoints
Returns:
str: Scale type name
"""
@property
def domain(self):
"""
Input domain for the scale
Can be:
- DataRef object referencing data fields
- List of explicit values
- Dict with min/max values for continuous scales
Returns:
DataRef, list, or dict: Domain specification
"""
@property
def range(self):
"""
Output range for the scale
Can be:
- List of explicit output values
- String specifying range type ('width', 'height', 'category10', etc.)
- Dict with min/max values
Returns:
list, str, or dict: Range specification
"""
@property
def reverse(self):
"""Whether to reverse the scale output (bool, default False)"""
@property
def round(self):
"""Whether to round scale output to integers (bool, default False)"""Marks
Visual mark definitions that render data as geometric shapes and graphical elements.
class Mark(GrammarClass):
"""Visual mark definitions for rendering data"""
@property
def type(self):
"""
Type of mark to render
Valid types:
- 'rect': Rectangles (for bar charts, heatmaps)
- 'symbol': Symbols/points (for scatter plots)
- 'line': Lines (for line charts)
- 'area': Filled areas (for area charts)
- 'arc': Arcs (for pie charts)
- 'text': Text labels
- 'path': Custom paths
- 'image': Images
- 'group': Grouped marks
Returns:
str: Mark type name
"""
@property
def from_(self):
"""
Data source reference for the mark
Returns:
MarkRef: Reference to data source and transforms
"""
@property
def properties(self):
"""
Visual properties for different mark states
Returns:
MarkProperties: Properties for enter, exit, update, hover states
"""
@property
def key(self):
"""Key field for object constancy during updates (str or None)"""
@property
def delay(self):
"""Animation delay specification (ValueRef or None)"""
@property
def ease(self):
"""Animation easing function (str or None)"""
class MarkRef(GrammarClass):
"""Data source references for marks"""
@property
def data(self):
"""Name of the source Data (str)"""
@property
def transform(self):
"""List of Transform objects to apply to data (list)"""Axes
Visual axis definitions for interpreting marks and providing coordinate system context.
class Axis(GrammarClass):
"""Definitions for visualization axes"""
@property
def type(self):
"""
Type of axis
Valid values: 'x' or 'y'
Returns:
str: Axis type
"""
@property
def scale(self):
"""
Name of the scale this axis represents
Returns:
str: Scale name reference
"""
@property
def orient(self):
"""
Axis orientation
Valid values: 'top', 'bottom', 'left', 'right'
Returns:
str: Orientation specification
"""
@property
def title(self):
"""Axis title text (str or None)"""
@property
def titleOffset(self):
"""Offset for axis title positioning (int or None)"""
@property
def format(self):
"""Number/date format string for axis labels (str or None)"""
@property
def ticks(self):
"""Approximate number of tick marks (int or None)"""
@property
def values(self):
"""Explicit tick values (list or None)"""
@property
def subdivide(self):
"""Number of minor ticks between major ticks (int or None)"""
@property
def tickPadding(self):
"""Padding between ticks and labels (int or None)"""
@property
def tickSize(self):
"""Size of tick marks (int or None)"""
@property
def tickSizeMajor(self):
"""Size of major tick marks (int or None)"""
@property
def tickSizeMinor(self):
"""Size of minor tick marks (int or None)"""
@property
def tickSizeEnd(self):
"""Size of end tick marks (int or None)"""
@property
def offset(self):
"""Axis offset from chart area (int or None)"""
@property
def layer(self):
"""Rendering layer ('front' or 'back', str or None)"""
@property
def grid(self):
"""Whether to show grid lines (bool or None)"""
@property
def properties(self):
"""Axis styling properties (AxisProperties or None)"""
class AxisProperties(GrammarClass):
"""Styling properties for axes"""
@property
def major_ticks(self):
"""PropertySet for major tick mark styling"""
@property
def minor_ticks(self):
"""PropertySet for minor tick mark styling"""
@property
def labels(self):
"""PropertySet for axis label styling"""
@property
def title(self):
"""PropertySet for axis title styling"""
@property
def axis(self):
"""PropertySet for axis line styling"""Legends
Legend definitions for visualizing scales and providing data interpretation context.
class Legend(GrammarClass):
"""Definition for Vega Legends"""
@property
def size(self):
"""Scale name for legend size encoding (str or None)"""
@property
def shape(self):
"""Scale name for legend shape encoding (str or None)"""
@property
def fill(self):
"""Scale name for legend fill color encoding (str or None)"""
@property
def stroke(self):
"""Scale name for legend stroke color encoding (str or None)"""
@property
def orient(self):
"""
Legend orientation
Valid values: 'left', 'right', 'top', 'bottom'
Returns:
str: Orientation specification or None
"""
@property
def title(self):
"""Legend title text (str or None)"""
@property
def format(self):
"""Format string for legend labels (str or None)"""
@property
def values(self):
"""Explicit legend values (list or None)"""
@property
def properties(self):
"""Legend styling properties (LegendProperties or None)"""
class LegendProperties(GrammarClass):
"""Styling properties for legends"""
@property
def title(self):
"""PropertySet for legend title styling"""
@property
def labels(self):
"""PropertySet for legend label styling"""
@property
def symbols(self):
"""PropertySet for legend symbol styling"""
@property
def gradient(self):
"""PropertySet for continuous color gradient styling"""
@property
def legend(self):
"""PropertySet for overall legend styling"""Core Grammar Classes
class GrammarClass(object):
"""Base class for all Vincent grammar components"""
def to_json(self):
"""Export object as JSON string"""
def validate(self):
"""Validate object properties and structure"""
class KeyedList(list):
"""List subclass supporting keyed access for grammar elements"""
def __init__(self, attr_name='name'):
"""Initialize with attribute name for keying (str)"""
class ValidationError(Exception):
"""Exception raised when validation fails"""
class LoadError(Exception):
"""Exception raised when loading fails"""Install with Tessl CLI
npx tessl i tessl/pypi-vincent