Chart Data Model

Purpose

vcti-chart provides a chart data model that exports to self- contained HTML files for use in web applications, prompt UIs, reports, or anywhere you need interactive chart visualisations.

Define a chart once in Python, then export it to a standalone HTML file that renders with any JavaScript charting framework — Plotly.js, ECharts, Chart.js, or any other. The Jinja2 template controls which JS library is used and how the chart looks. Adding support for a new JS library means writing a new template — no Python code changes.

Define chart in Python  →  Pass to Jinja2 template  →  Standalone HTML file

Python chart libraries (Plotly, Bokeh) are also supported for interactive exploration in Jupyter during development.

Dependencies: numpy, pandas, vcti-enum.

How It Works

┌──────────────────────┐
│     ChartStack       │   Define chart: layers, panels, properties
│  Layer → Panel → Stack│
│  to_dict() → dict    │   All values as JSON-safe Python types
└──────────┬───────────┘
           │
┌──────────▼───────────┐
│   Jinja2 Template    │   User-provided (or built-in default)
│                      │
│  {{ chart.* }}       │   Template accesses chart dict directly
│  {{ tojson }}        │   Reshapes into library-specific JS config
│  → output.html       │   Standalone, self-contained HTML artifact
└──────────────────────┘

No Python-side JS serialisers. The Jinja2 template does all the library- specific reshaping. to_dict() provides the raw ingredients.

Installation

From GitHub (recommended for development)

# Latest main branch
pip install vcti-chart



### In `requirements.txt`

vcti-chart>=1.0.0

### In `pyproject.toml` dependencies

```toml
dependencies = [
    "vcti-chart>=1.0.0",
]

Quick Start

1. Define a chart

from vcti.chart import (
    Chart, Facet, Panel, Variable, VariableInfo, DataArray,
    CoordSysType, XyLayer, XyPlotConfig, LineType, MarkerType,
)

# Create the shared independent variable (x-axis)
time = Variable("time", DataArray([0, 1, 2, 3, 4]),
                VariableInfo(name="Time", unit="s"))

# Create a dependent variable (y-axis metadata)
temp = Variable("temperature",
                metadata=VariableInfo(name="Temperature", unit="°C"))

# Build the hierarchy: Chart → Facet → Panel → Layer
chart = Chart()
facet = Facet(CoordSysType.CARTESIAN, domain_var=time)
panel = Panel(CoordSysType.CARTESIAN, range_var=temp)
panel.layers.add("line", XyLayer(
    values=DataArray([20, 22, 25, 23, 21]),
    config=XyPlotConfig(line_type=LineType.SOLID, marker_type=MarkerType.CIRCLE),
))
facet.panels.add("temp", panel)
chart.facets.add("main", facet)

2. Serialise for template consumption (primary workflow)

import json

data = chart.to_dict()   # JSON-safe dict for Jinja2 templates
print(json.dumps(data, indent=2))

The to_dict() output is the contract consumed by Jinja2 templates via the external vcti-template package.

3. Use with Python chart libraries (convenience)

# Plotly (for Jupyter / interactive exploration)
from vcti.chart.converters.plotly import get_figure
fig = get_figure(chart)
fig.show()

# Bokeh
from vcti.chart.converters.bokeh import chart_to_bokeh
from bokeh.io import show
show(chart_to_bokeh(chart))

Hierarchy

Chart                              Top-level container (grid layout)
  └── Facet                        Panels sharing a domain variable
        ├── domain_var: Variable   Shared x-axis data + metadata
        ├── axes_layout            Parallel or serial arrangement
        └── Panel                  One dependent variable
              ├── range_var        Y-axis metadata (name, unit)
              └── Layer            Visual representation
                    ├── XyLayer    Line / scatter / area
                    ├── BarLayer   Bar chart
                    └── SectorLayer Pie / donut

Documentation

• Design -- Concepts, architecture decisions, and trade-offs
• Source Guide -- File structure and dependency map
• API Reference -- Autodoc for all modules