tessl/pypi-vincent

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

Overview

Eval results

Files

Data Management

Name: tessl/pypi-vincent
Author: tessl

Data handling and transformation capabilities for Vincent visualizations. Provides seamless conversion between Python data structures and Vega data specifications, with extensive support for pandas integration and data transformations.

Capabilities

Data Container

The core Data class that represents data sources in Vincent visualizations, supporting both embedded data and external data references.

class Data(GrammarClass):
    """Data container for visualization"""
    
    def __init__(self, name=None, **kwargs):
        """
        Initialize a Data object
        
        Parameters:
        - name: Name of the data set (str or None, defaults to 'table')
        - **kwargs: Additional attributes to set on initialization
        """
    
    @classmethod
    def from_pandas(cls, data, columns=None, key_on='idx', name=None,
                    series_key='data', grouped=False, records=False, **kwargs):
        """
        Create Data object from pandas DataFrame or Series
        
        Parameters:
        - data: pandas DataFrame or Series
        - columns: DataFrame columns to convert (list or None for all)
        - key_on: Value to key on for x-axis data (str, default 'idx')
        - name: Name for the data set (str or None)
        - series_key: Key name for Series data (str, default 'data')
        - grouped: Whether to treat data as grouped (bool, default False)
        - records: Whether to output records format (bool, default False)
        - **kwargs: Additional attributes for initialization
        
        Returns:
        Data: Vincent Data object with converted pandas data
        """
    
    @classmethod  
    def from_iter(cls, data, name=None):
        """
        Create Data object from Python iterables
        
        Parameters:
        - data: Python list, tuple, or dictionary iterable
        - name: Name of the data set (str or None)
        
        Returns:
        Data: Vincent Data object with converted iterable data
        """
    
    @classmethod
    def from_mult_iters(cls, name=None, idx=None, **kwargs):
        """
        Create Data object from multiple iterables
        
        Parameters:
        - name: Name of the data set (str or None, defaults to 'table')
        - idx: Index iterator (iterable or None)
        - **kwargs: Named iterables to combine into data structure
        
        Returns:
        Data: Vincent Data object with combined iterator data
        """

Usage Examples:

import vincent
import pandas as pd

# From pandas DataFrame
df = pd.DataFrame({'x': [1, 2, 3], 'y': [10, 20, 30]})
data = vincent.Data.from_pandas(df)

# From Python list
list_data = [('A', 10), ('B', 20), ('C', 30)]
data = vincent.Data.from_iter(list_data)

# From multiple iterables
x_vals = [1, 2, 3, 4]
y_vals = [10, 20, 15, 25]
data = vincent.Data.from_mult_iters(x=x_vals, y=y_vals)

Data Transformations

Comprehensive data transformation system supporting all Vega transform types for data processing and manipulation.

class Transform(GrammarClass):
    """Container for data transformation operations"""
    
    @property 
    def type(self):
        """
        Transform type specification
        
        Valid transform types:
        - Data manipulation: 'array', 'copy', 'cross', 'facet', 'filter', 
          'flatten', 'fold', 'formula', 'slice', 'sort', 'stats', 'truncate', 
          'unique', 'window', 'zip'
        - Layout algorithms: 'force', 'treemap', 'wordcloud'
        - Geographic: 'geo', 'geopath'
        - Specialized: 'link', 'pie', 'stack'
        
        Returns:
        str: Transform type name
        """

Common Transform Types:

filter: Filter data based on conditions
formula: Compute new data fields using expressions
sort: Sort data by specified fields
stats: Calculate statistical summaries
pie: Apply pie layout for pie charts
stack: Stack data for stacked charts
wordcloud: Generate word cloud layout

Usage Example:

import vincent

# Create transform for filtering data
transform = vincent.Transform()
transform.type = 'filter'
transform.test = 'datum.value > 10'

# Create transform for computing new fields
formula_transform = vincent.Transform()
formula_transform.type = 'formula'
formula_transform.field = 'scaled_value'
formula_transform.expr = 'datum.value * 2'

Data References

System for referencing data fields in scales and other visualization components.

class DataRef(GrammarClass):
    """Definitions for how data is referenced by scales"""
    
    @property
    def data(self):
        """
        Name of data-set containing the domain values
        
        Returns:
        str: Data set name
        """
    
    @property  
    def field(self):
        """
        Reference to desired data field(s)
        
        Returns:
        str or list: Field name(s) in dot-notation (e.g., 'data.x')
        
        If multiple fields are given, values from all fields are included.
        """

Usage Example:

import vincent

# Create data reference for a scale domain
data_ref = vincent.DataRef()
data_ref.data = 'table'
data_ref.field = 'data.x'  # Reference the 'x' field

# Multiple field reference
multi_ref = vincent.DataRef()
multi_ref.data = 'table' 
multi_ref.field = ['data.x', 'data.y']  # Reference both x and y fields

Data Format Conversion

Vincent automatically handles conversion between different data formats:

Pandas Integration

DataFrame: Converts to row-oriented JSON format with column names as keys
Series: Converts to array format with index preservation
Index handling: Maintains pandas index as 'idx' field or custom key_on field
Grouping support: Handles grouped DataFrames for multi-series visualizations