tessl/pypi-vincent

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

Overview

Eval results

Files

Styling and Properties

Name: tessl/pypi-vincent
Author: tessl

Comprehensive styling system for Vincent visualizations using PropertySet and ValueRef classes. Provides full control over visual appearance, animations, and interactions through Vega's property system.

Capabilities

Property Sets

PropertySet defines visual properties for marks and axes, supporting all Vega visual properties for comprehensive styling control.

class PropertySet(GrammarClass):
    """Visual property definitions for marks and axes"""
    
    # Position Properties
    @property
    def x(self):
        """ValueRef: Left-most x-coordinate position"""
    
    @property
    def x2(self):
        """ValueRef: Right-most x-coordinate position"""
    
    @property
    def y(self):
        """ValueRef: Bottom-most y-coordinate position"""
    
    @property
    def y2(self):
        """ValueRef: Top-most y-coordinate position"""
    
    @property
    def width(self):
        """ValueRef: Width of the mark"""
    
    @property
    def height(self):
        """ValueRef: Height of the mark"""
    
    # Style Properties
    @property
    def fill(self):
        """ValueRef: Fill color specification"""
    
    @property
    def fillOpacity(self):
        """ValueRef: Fill opacity (0-1)"""
    
    @property
    def stroke(self):
        """ValueRef: Stroke/outline color specification"""
    
    @property
    def strokeOpacity(self):
        """ValueRef: Stroke opacity (0-1)"""
    
    @property
    def strokeWidth(self):
        """ValueRef: Stroke width in pixels"""
    
    @property
    def opacity(self):
        """ValueRef: Overall opacity (0-1)"""
    
    # Text Properties
    @property
    def text(self):
        """ValueRef: Text content for text marks"""
    
    @property
    def fontSize(self):
        """ValueRef: Font size in pixels"""
    
    @property
    def fontWeight(self):
        """ValueRef: Font weight ('normal', 'bold', numeric values)"""
    
    @property
    def fontStyle(self):
        """ValueRef: Font style ('normal', 'italic')"""
    
    @property
    def align(self):
        """ValueRef: Text alignment ('left', 'center', 'right')"""
    
    @property
    def baseline(self):
        """ValueRef: Text baseline ('top', 'middle', 'bottom', 'alphabetic')"""
    
    # Line Properties
    @property
    def interpolate(self):
        """ValueRef: Line interpolation method ('linear', 'step', 'basis', etc.)"""
    
    @property
    def tension(self):
        """ValueRef: Tension parameter for curve interpolation (0-1)"""
    
    # Symbol Properties
    @property
    def size(self):
        """ValueRef: Symbol size in square pixels"""
    
    @property
    def shape(self):
        """ValueRef: Symbol shape ('circle', 'square', 'triangle', etc.)"""

Usage Example:

import vincent

# Create PropertySet for mark styling
props = vincent.PropertySet()
props.fill = vincent.ValueRef(value='steelblue')
props.stroke = vincent.ValueRef(value='darkblue')  
props.strokeWidth = vincent.ValueRef(value=2)
props.opacity = vincent.ValueRef(value=0.8)

# Position properties using scale references
props.x = vincent.ValueRef(scale='x', field='data.x')
props.y = vincent.ValueRef(scale='y', field='data.y')
props.width = vincent.ValueRef(scale='x', band=True)

Value References

ValueRef provides flexible value specification system supporting constants, data field references, scale mappings, and computed values.

class ValueRef(GrammarClass):
    """Container for value-referencing properties of marks"""
    
    @property
    def value(self):
        """
        Constant value specification
        
        Can be int, float, or string for constant values.
        Ignored if field property is defined.
        
        Returns:
        int, float, or str: Constant value
        """
    
    @property
    def field(self):
        """
        Data field reference in dot-notation
        
        References data field like 'data.x' where first element
        is always 'data' regardless of actual data name.
        
        Returns:
        str: Field reference in dot-notation
        """
    
    @property
    def group(self):
        """
        Group property reference
        
        References enclosing group's data properties.
        Special values 'width' and 'height' return group dimensions.
        
        Returns:
        str or bool: Group property reference
        """
    
    @property
    def scale(self):
        """
        Scale name reference
        
        Scale is applied to value and field attributes.
        
        Returns:
        str: Scale name
        """
    
    @property
    def mult(self):
        """
        Multiplier applied after scaling
        
        Returns:
        int or float: Multiplication factor
        """
    
    @property
    def offset(self):
        """
        Additive offset applied after scaling and multipliers
        
        Returns:
        int or float: Offset value
        """
    
    @property
    def band(self):
        """
        Use scale range band
        
        If True and scale is defined, uses the range band of
        the referenced ordinal scale.
        
        Returns:
        bool: Whether to use scale band
        """

Usage Examples:

import vincent

# Constant value
constant_ref = vincent.ValueRef(value=100)

# Data field reference with scale
field_ref = vincent.ValueRef(field='data.value', scale='y')

# Computed value with offset and multiplier  
computed_ref = vincent.ValueRef(
    field='data.x', 
    scale='x', 
    mult=1.5, 
    offset=10
)

# Band scale reference
band_ref = vincent.ValueRef(scale='x', band=True)

# Group dimension reference
group_ref = vincent.ValueRef(group='width')

Mark Properties

MarkProperties defines property sets for different mark interaction states, enabling animations and dynamic styling.

class MarkProperties(GrammarClass):
    """Property sets for different mark states"""
    
    @property
    def enter(self):
        """
        Properties applied when data is loaded
        
        Returns:
        PropertySet: Entry state properties
        """
    
    @property
    def exit(self):
        """
        Properties applied when data is removed
        
        Returns:
        PropertySet: Exit state properties
        """
    
    @property
    def update(self):
        """
        Properties applied for all non-exiting data
        
        Returns:
        PropertySet: Update state properties
        """
    
    @property
    def hover(self):
        """
        Properties applied on mouse-over
        
        On mouse out, update properties are applied.
        
        Returns:
        PropertySet: Hover state properties
        """

Usage Example:

import vincent

# Create mark properties with different states
mark_props = vincent.MarkProperties()

# Entry state - initial appearance
mark_props.enter = vincent.PropertySet()
mark_props.enter.fill = vincent.ValueRef(value='lightblue')
mark_props.enter.opacity = vincent.ValueRef(value=0)

# Update state - normal appearance
mark_props.update = vincent.PropertySet()
mark_props.update.fill = vincent.ValueRef(value='steelblue')
mark_props.update.opacity = vincent.ValueRef(value=1)

# Hover state - interactive appearance
mark_props.hover = vincent.PropertySet()
mark_props.hover.fill = vincent.ValueRef(value='orange')
mark_props.hover.opacity = vincent.ValueRef(value=0.8)

Color System Integration

Vincent integrates with ColorBrewer palettes for consistent and effective color schemes:

from vincent.colors import brews

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

Usage Example:

from vincent.colors import brews
import vincent

# Use a ColorBrewer palette for fill colors
colors = brews['Set1']  # Gets a qualitative color palette

# Create ValueRef with palette color
fill_ref = vincent.ValueRef(value=colors[0])  # First color in palette

# Or use in a scale domain
color_scale = vincent.Scale()
color_scale.name = 'color'
color_scale.type = 'ordinal'
color_scale.range = colors[:5]  # Use first 5 colors

Property System Patterns

Responsive Properties

Properties can respond to data values and user interactions:

# Color encoding based on data values
color_ref = vincent.ValueRef(
    field='data.category',
    scale='color'  # Maps categories to colors
)

# Size encoding based on data magnitude
size_ref = vincent.ValueRef(
    field='data.value',
    scale='size',
    mult=2  # Scale up the size
)

Animation Properties

Properties support smooth transitions between states:

# Entry animation - fade in
enter_props = vincent.PropertySet()
enter_props.opacity = vincent.ValueRef(value=0)

# Update animation - full opacity
update_props = vincent.PropertySet()  
update_props.opacity = vincent.ValueRef(value=1)

Conditional Properties

Properties can be conditionally applied based on data or interaction state through the hover, enter, exit, and update property sets, enabling rich interactive visualizations.

Install with Tessl CLI