tessl/pypi-altair

Vega-Altair: A declarative statistical visualization library for Python.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Chart Composition

Name: tessl/pypi-altair
Author: tessl

Functions for combining multiple charts through layering, concatenation, faceting, and repetition to create complex multi-view visualizations. Chart composition enables building sophisticated dashboards and analytical displays from simpler chart components.

Capabilities

Layering

Functions for overlaying multiple charts with different marks or encodings on the same coordinate system.

def layer(*charts, **kwargs):
    """
    Layer multiple charts on top of each other.
    
    Parameters:
    - *charts: Variable number of Chart objects to layer
    - **kwargs: Additional layer properties (resolve, etc.)
    
    Returns:
    LayerChart: Layered chart specification
    """

class LayerChart:
    def __init__(self, layer=None, **kwargs):
        """
        Chart with multiple layered mark specifications.
        
        Parameters:
        - layer: List of layer specifications
        """
        
    def resolve_axis(self, **kwargs):
        """Resolve axis sharing across layers."""
        
    def resolve_legend(self, **kwargs):
        """Resolve legend sharing across layers."""
        
    def resolve_scale(self, **kwargs):
        """Resolve scale sharing across layers."""

Concatenation

Functions for arranging charts side-by-side or in grids without sharing coordinate systems.

def concat(*charts, columns=None, spacing=None, **kwargs):
    """
    Concatenate charts in a flexible layout.
    
    Parameters:
    - *charts: Variable number of Chart objects
    - columns: Number of columns for grid layout
    - spacing: Spacing between charts
    
    Returns:
    ConcatChart: Concatenated chart specification
    """

def hconcat(*charts, spacing=None, **kwargs):
    """
    Horizontally concatenate charts.
    
    Parameters:
    - *charts: Variable number of Chart objects
    - spacing: Horizontal spacing between charts
    
    Returns:
    HConcatChart: Horizontally concatenated chart
    """

def vconcat(*charts, spacing=None, **kwargs):
    """
    Vertically concatenate charts.
    
    Parameters:
    - *charts: Variable number of Chart objects  
    - spacing: Vertical spacing between charts
    
    Returns:
    VConcatChart: Vertically concatenated chart
    """

class ConcatChart:
    def __init__(self, concat=None, columns=None, **kwargs):
        """General concatenated chart layout."""
        
class HConcatChart:
    def __init__(self, hconcat=None, **kwargs):
        """Horizontally concatenated chart layout."""
        
class VConcatChart:
    def __init__(self, vconcat=None, **kwargs):
        """Vertically concatenated chart layout."""

Faceting

Functions for creating small multiples based on data dimensions.

def facet(
    chart,
    facet=None,
    columns=None,
    spacing=None,
    **kwargs
):
    """
    Create faceted chart with small multiples.
    
    Parameters:
    - chart: Base chart specification
    - facet: Faceting field specification
    - columns: Number of columns in facet grid
    - spacing: Spacing between facet panels
    
    Returns:
    FacetChart: Faceted chart specification
    """

class FacetChart:
    def __init__(self, facet=None, spec=None, **kwargs):
        """
        Chart with faceted small multiples.
        
        Parameters:
        - facet: Facet field specification
        - spec: Base chart specification for each panel
        """

Repetition

Functions for repeating chart specifications with different field mappings.

def repeat(
    chart=None,
    repeat=None,
    columns=None,
    **kwargs
):
    """
    Repeat chart specification with different field mappings.
    
    Parameters:
    - chart: Base chart template
    - repeat: Repeat specification (row/column field lists)
    - columns: Number of columns for repeat grid
    
    Returns:
    RepeatChart: Repeated chart specification
    """

class RepeatChart:
    def __init__(self, repeat=None, spec=None, **kwargs):
        """
        Chart with repeated specifications.
        
        Parameters:
        - repeat: Repeat field mappings
        - spec: Template chart specification
        """

Resolution Control

Classes and methods for controlling how scales, axes, and legends are shared across composed charts.

class Resolve:
    def __init__(self, axis=None, legend=None, scale=None):
        """
        Resolution specification for composed charts.
        
        Parameters:
        - axis: Axis resolution configuration
        - legend: Legend resolution configuration  
        - scale: Scale resolution configuration
        """

class AxisResolveMap:
    def __init__(self, x=None, y=None, **kwargs):
        """Axis resolution for specific encodings."""

class LegendResolveMap:
    def __init__(self, color=None, size=None, shape=None, **kwargs):
        """Legend resolution for specific encodings."""

class ScaleResolveMap:
    def __init__(self, x=None, y=None, color=None, size=None, **kwargs):
        """Scale resolution for specific encodings."""

# Resolution modes
ResolveMode = Union['independent', 'shared']

Usage Examples

Basic Layering

import altair as alt

# Layer line and points
line = alt.Chart(data).mark_line().encode(
    x='x:Q',
    y='mean(y):Q'
)

points = alt.Chart(data).mark_circle().encode(
    x='x:Q',
    y='y:Q',
    color='category:N'
)

layered = alt.layer(line, points).resolve_scale(
    color='independent'
)

Horizontal Concatenation

# Side-by-side charts
chart1 = alt.Chart(data).mark_bar().encode(
    x='category:N',
    y='count():Q'
)

chart2 = alt.Chart(data).mark_point().encode(
    x='x:Q',
    y='y:Q',
    color='category:N'
)

combined = alt.hconcat(chart1, chart2, spacing=20)

Vertical Concatenation

# Stacked charts
top_chart = alt.Chart(data).mark_line().encode(
    x='date:T',
    y='value:Q'
).properties(height=200)

bottom_chart = alt.Chart(data).mark_bar().encode(
    x='date:T',
    y='volume:Q'
).properties(height=100)

stacked = alt.vconcat(top_chart, bottom_chart)

Grid Layout with Concat

# 2x2 grid of charts
chart1 = alt.Chart(data).mark_point().encode(x='a:Q', y='b:Q')
chart2 = alt.Chart(data).mark_point().encode(x='c:Q', y='d:Q')  
chart3 = alt.Chart(data).mark_bar().encode(x='category:N', y='count():Q')
chart4 = alt.Chart(data).mark_line().encode(x='date:T', y='value:Q')

grid = alt.concat(
    chart1, chart2, chart3, chart4,
    columns=2,
    spacing=10
)

Faceted Small Multiples

# Facet by category
base = alt.Chart(data).mark_point().encode(
    x='x:Q',
    y='y:Q'
)

faceted = base.facet(
    column=alt.Column('category:N', header=alt.Header(title='Category')),
    columns=3
)

# Facet with both row and column
faceted_2d = base.facet(
    column=alt.Column('category:N'),
    row=alt.Row('type:N'),
    spacing=10
)

Repeat Chart

# Scatterplot matrix
scatter_matrix = alt.Chart(data).mark_circle().encode(
    x=alt.X(alt.repeat('column'), type='quantitative'),
    y=alt.Y(alt.repeat('row'), type='quantitative'),
    color='species:N'
).properties(
    width=150,
    height=150
).repeat(
    row=['petalLength', 'petalWidth'],
    column=['sepalLength', 'sepalWidth']
)

Complex Dashboard Layout

# Multi-panel dashboard
base = alt.Chart(data)

# Time series
time_series = base.mark_line().encode(
    x='date:T',
    y='value:Q',
    color='category:N'
).properties(width=400, height=200)

# Bar chart
bars = base.mark_bar().encode(
    x='category:N', 
    y='mean(value):Q'
).properties(width=150, height=200)

# Scatter plot
scatter = base.mark_circle().encode(
    x='x:Q',
    y='y:Q', 
    size='value:Q',
    color='category:N'
).properties(width=200, height=200)

# Histogram
hist = base.mark_bar().encode(
    x=alt.X('value:Q', bin=True),
    y='count()'
).properties(width=200, height=200)

# Compose dashboard
dashboard = alt.vconcat(
    time_series,
    alt.hconcat(bars, scatter, hist, spacing=10),
    spacing=15
)

Layered Chart with Brushing

# Base chart with brush selection
brush = alt.selection_interval()

base = alt.Chart(data).add_selection(brush)

# Background points
background = base.mark_circle(
    color='lightgray',
    opacity=0.5
).encode(
    x='x:Q',
    y='y:Q'
)

# Highlighted points
highlighted = base.mark_circle().encode(
    x='x:Q',
    y='y:Q',
    color=alt.condition(brush, 'category:N', alt.value('lightgray'))
)

# Regression line for selected data
regression = base.mark_line(
    color='red',
    size=3
).transform_filter(
    brush
).transform_regression('y', 'x')

layered_interactive = alt.layer(
    background, highlighted, regression
)

Resolution Control

# Independent scales for layered charts
chart1 = alt.Chart(data1).mark_bar().encode(
    x='category:N',
    y='value1:Q'
)

chart2 = alt.Chart(data2).mark_line().encode(
    x='category:N',
    y='value2:Q'
)

# Allow independent y-scales
layered = alt.layer(chart1, chart2).resolve_scale(
    y='independent'
).resolve_axis(
    y='independent'  
)

# Shared color legend
multi_chart = alt.hconcat(
    chart1, chart2
).resolve_legend(
    color='shared'
)

Types

from typing import Union, List, Dict, Any, Optional

# Chart composition types
ComposedChart = Union[LayerChart, ConcatChart, HConcatChart, VConcatChart, FacetChart, RepeatChart]

# Layout specifications
LayoutAlign = Union['all', 'each', 'none']
Spacing = Union[int, Dict[str, int]]

# Repeat specifications
RepeatMapping = Dict[str, List[str]]
RepeatRef = Dict[str, str]

# Facet specifications
FacetMapping = Union[str, Dict[str, Any]]
FacetFieldDef = Dict[str, Any]

# Resolution specifications
ResolveMode = Union['independent', 'shared']

class ResolveConfig:
    axis: Optional[Dict[str, ResolveMode]] = None
    legend: Optional[Dict[str, ResolveMode]] = None
    scale: Optional[Dict[str, ResolveMode]] = None

# Layout configuration
class CompositionConfig:
    columns: Optional[int] = None
    spacing: Optional[Spacing] = None
    align: Optional[LayoutAlign] = None
    bounds: Optional[Union['full', 'flush']] = None
    center: Optional[bool] = None

Install with Tessl CLI