Metadata-Version: 2.4
Name: vcti-chart
Version: 2.0.0
Summary: Chart data model with template-based HTML export for any JS charting framework
Author: Visual Collaboration Technologies Inc.
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pydantic>=2.0
Requires-Dist: vcti-enum>=1.0.3
Requires-Dist: vcti-deck>=1.0.1
Provides-Extra: plotly
Requires-Dist: plotly; extra == "plotly"
Provides-Extra: bokeh
Requires-Dist: bokeh; extra == "bokeh"
Provides-Extra: all
Requires-Dist: plotly; extra == "all"
Requires-Dist: bokeh; extra == "all"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: plotly; extra == "test"
Requires-Dist: bokeh; extra == "test"
Dynamic: license-file

# 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)

```bash
# 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

```python
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)

```python
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)

```python
# 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](docs/design.md) -- Concepts, architecture decisions, and trade-offs
- [Source Guide](docs/source-guide.md) -- File structure and dependency map
- [API Reference](docs/api.md) -- Autodoc for all modules
