Datachart

https://eriknovak.github.io/datachart/latest
Admin
Datachart is a Python data visualization package built on Matplotlib for creating simple, highly...
Tokens:673,570
Snippets:3,568
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Target datachart 1.x. Pre-1.0 names were removed, not deprecated: use AXIS_SCALE (not SCALE), COLOR_NORM (not NORMALIZE), value_format (not valfmt), show_values (not show_heatmap_values)
- Also removed in 1.0: stats.correlation is stats.pearson, update_config/reset_config are config.update/config.reset, and save_figure(format=...) is save_figure(fmt=...)
- Import chart functions from datachart.charts; Panel, Grid, Annotate, save_figure and stats from datachart.utils; config from datachart.config; constants (THEME, FIG_SIZE, SHOW_GRID, LEGEND_LOCATION, ...) from datachart.constants
- Chart data is a list of dicts, one per record, and each chart expects its own keys: LineChart x/y, BarChart label/y, Histogram x, BoxPlot/ViolinPlot/SwarmPlot label/value
- ScatterChart records take x/y plus optional size, hue and annotation. Check the chart's guide for the record keys of every other chart
- A list of record lists draws several series. Name them with a list of subtitles; subplots=True gives each series its own axes
- There is no pandas DataFrame input. Pass df.to_dict("records") with the columns renamed to the chart's keys
- Every argument after data is keyword-only. An unknown parameter or constant value raises an error rather than being ignored
- Set global style with config.set_theme(THEME.X), config.update(...) or `with config.using_theme(...)`. Per-chart overrides go in style={...} with theme keys such as plot_line_color. Prefer these over editing the matplotlib axes
- Every chart returns a DatachartFigure, which is a matplotlib Figure. Panel overlays finished figures on shared axes; {"figure": fig, "y_axis": "right"} puts one on a second y-axis
- Grid arranges finished figures in cells, with nested lists as rows. A Grid can sit inside another Grid but not inside a Panel
- Save with save_figure(fig, path, fmt=[...]). fig.show(interactive=True) needs the datachart[interactive] extra
- Docs index: https://eriknovak.github.io/datachart/latest/llms.txt. Append index.md to any page URL to get it as markdown

================
CODE SNIPPETS
================
### Prompt with a documentation link for a grouped bar chart

Source: https://eriknovak.github.io/datachart/latest/ai-assistants

Paste the URL of the guide page into the prompt so the assistant fetches the current docs. The example asks for a grouped bar chart of a medal table and points to the barchart guide.

```text
Draw a grouped bar chart of the medal table with datachart. Read the guide
first: https://eriknovak.github.io/datachart/latest/how-to-guides/charts/barchart/index.md

```

--------------------------------

### get method signature and usage example

Source: https://eriknovak.github.io/datachart/latest/references/config?q=

Signature and example for the get method of the datachart configuration object. The example retrieves the 'font_general_color' attribute, returning '#000000'. Falls back to the default value when the attribute is not set.

```python
get(attr: str, default: Any = None) -> Any


```

```python
>>> from datachart.config import config
>>> config.get("font_general_color")
'#000000'


```

--------------------------------

### Task record example and output

Source: https://eriknovak.github.io/datachart/latest/how-to-guides/charts/ganttchart

Shows the structure of a task record in the `house` schedule. The record includes required keys `task`, `start`, and `end` (temporal objects, not strings), and optional keys `group`, `progress`, `depends_on`, and `emphasis`. The output is the record for the 'Foundations' task.

```python
house[4]

```

```python
{'task': 'Foundations',
 'start': datetime.date(2025, 5, 19),
 'end': datetime.date(2025, 6, 20),
 'group': 'Groundwork',
 'progress': 0.8,
 'depends_on': ['Site clearing']}

```

--------------------------------

### config.list_themes usage example

Source: https://eriknovak.github.io/datachart/latest/references/config

Example of checking that 'default' is among the themes returned by config.list_themes().

```python
>>> from datachart.config import config
>>> "default" in config.list_themes()
True

```

--------------------------------

### Install datachart with interactive extra

Source: https://eriknovak.github.io/datachart/latest

Install datachart with the interactive extra for zoom, pan, and hover-to-inspect.

```bash
pip install -U "datachart[interactive]"
```

--------------------------------

### reset example

Source: https://eriknovak.github.io/datachart/latest/references/config

Resets the global configuration to the default theme. The example shows resetting and then reading the theme name.

```python
>>> from datachart.config import config
>>> config.reset()
>>> config.theme
'default'
```

--------------------------------

### config.save_theme usage example

Source: https://eriknovak.github.io/datachart/latest/references/config

Example of saving the live configuration to house.json and saving the registered theme 'ink' to ink.json.

```python
>>> from datachart.config import config
>>> config.update({"font_general_size": 14})
>>> config.save_theme("house.json")
>>> config.save_theme("ink.json", name="ink")

```

--------------------------------

### config.load_theme usage example

Source: https://eriknovak.github.io/datachart/latest/references/config

Example of loading a theme from house.json and applying it with set_theme. The active theme becomes 'house'.

```python
>>> from datachart.config import config
>>> config.set_theme(config.load_theme("house.json"))
>>> config.theme
'house'

```

--------------------------------

### Install datachart with pip

Source: https://eriknovak.github.io/datachart/latest

Install the datachart package from PyPI.

```bash
pip install datachart
```

--------------------------------

### get usage example

Source: https://eriknovak.github.io/datachart/latest/references/config

Example usage of get to retrieve the 'font_general_color' attribute, returning '#000000'.

```python
>>> from datachart.config import config
>>> config.get("font_general_color")
'#000000'

```

--------------------------------

### Apply a theme with config.set_theme()

Source: https://eriknovak.github.io/datachart/latest/how-to-guides/styling/themes

Applies the MINIMAL theme to the global configuration and then builds and shows the demo chart. Set the theme before building charts because charts read the configuration when they are built.

```python
config.set_theme(THEME.MINIMAL)
demo().show()
```

--------------------------------

### set_theme example

Source: https://eriknovak.github.io/datachart/latest/references/config

Sets the global configuration to match a theme. The example shows setting the theme to THEME.DEFAULT and then reading the active theme name.

```python
>>> from datachart.constants import THEME
>>> from datachart.config import config
>>> config.set_theme(THEME.DEFAULT)
>>> config.theme
'default'
```

--------------------------------

### Import HexbinChart and ScatterChart

Source: https://eriknovak.github.io/datachart/latest/how-to-guides/charts/hexbinchart

Import the HexbinChart and ScatterChart classes from the datachart.charts module. This is the required import for the examples in this guide.

```python
from datachart.charts import HexbinChart, ScatterChart

```

--------------------------------

### update example

Source: https://eriknovak.github.io/datachart/latest/references/config

Updates the global configuration with individual style attributes. The example sets a font color and reads it back.

```python
>>> from datachart.config import config
>>> config.update({"font_general_color": "#FFFFFF"})
>>> config.get("font_general_color")
'#FFFFFF'
```

--------------------------------

### Install dependencies with uv sync

Source: https://eriknovak.github.io/datachart/latest/development

Creates the virtual environment in .venv and installs the package with development dependencies in one step.

```bash
uv sync --group dev

```

--------------------------------

### Serve documentation with mkdocs

Source: https://eriknovak.github.io/datachart/latest/development

Starts live-reloading the documentation. The optional -a localhost:9999 flag sets the address. Notebooks execute at build time and their runs are cached in .cache/mkdocs-jupyter; delete that directory after changing the package to re-render outputs.

```bash
mkdocs serve [-a localhost:9999]

```

--------------------------------

### Import chart and annotation utilities

Source: https://eriknovak.github.io/datachart/latest/how-to-guides/utility/annotations

Imports BarChart, LineChart, Annotate, Grid, and Panel from datachart. Required for the examples in this guide.

```python
from datachart.charts import BarChart, LineChart
from datachart.utils import Annotate, Grid, Panel

```

--------------------------------

### Import ImageChart, ScatterChart, and Panel

Source: https://eriknovak.github.io/datachart/latest/how-to-guides/charts/imagechart?q=

Imports the required classes from datachart: ImageChart and ScatterChart from datachart.charts, and Panel from datachart.utils. This is the standard import block for the guide's examples.

```python
import numpy as np

from datachart.charts import ImageChart, ScatterChart
from datachart.utils import Panel
```

--------------------------------

### register_theme example

Source: https://eriknovak.github.io/datachart/latest/references/config

Registers a custom theme and applies it. The example creates a theme based on DEFAULT_THEME with a modified font size, sets it, and reads the attribute.

```python
>>> from datachart.config import config
>>> from datachart.themes import DEFAULT_THEME
>>> config.register_theme("mine", {**DEFAULT_THEME, "font_general_size": 14})
>>> config.set_theme("mine")
>>> config.get("font_general_size")
14
```

--------------------------------

### Create records with custom keys and preview first two

Source: https://eriknovak.github.io/datachart/latest/how-to-guides/charts/ridgelineplot

Builds a list of records with custom keys 'month' and 'celsius' from the temperatures data, then shows the first two entries. The output is the displayed result of records[:2].

```python
records = [{"month": point["label"], "celsius": point["value"]} for point in temperatures]
records[:2]
```

```python
[{'month': 'Jan', 'celsius': 7.8}, {'month': 'Jan', 'celsius': -0.3}]
```

--------------------------------

### Basic GanttChart example

Source: https://eriknovak.github.io/datachart/latest/how-to-guides/charts/ganttchart

Creates a basic gantt chart with only the `data` argument. Each task is a bar from its start to its end, one row per task in input order with the first at the top. Groups color the bars and fill the legend, a `progress` fraction fills part of a bar with a darker inner bar, and tasks that end when they start are shown as milestone markers.

```python
GanttChart(
    # add the data to the chart
    data=house
).show()

```

--------------------------------

### Get maximum with datachart.utils.stats.maximum

Source: https://eriknovak.github.io/datachart/latest/references/utils/stats

Signature and usage example for datachart.utils.stats.maximum. Missing values (None, NaN, infinities) are ignored. Numeric values return a float; other ordered values (e.g., datetimes) return their maximum unchanged.

```python
maximum(values: list[Any]) -> Any
```

```python
>>> from datachart.utils.stats import maximum
>>> maximum([1, 2, 3, 4, 5])
5.0
```

--------------------------------

### Get minimum with datachart.utils.stats.minimum

Source: https://eriknovak.github.io/datachart/latest/references/utils/stats

Signature and usage example for datachart.utils.stats.minimum. Missing values (None, NaN, infinities) are ignored. Numeric values return a float; other ordered values (e.g., datetimes) return their minimum unchanged.

```python
minimum(values: list[Any]) -> Any
```

```python
>>> from datachart.utils.stats import minimum
>>> minimum([1, 2, 3, 4, 5])
1.0
```

--------------------------------

### Create a DumbbellChart with delta value labels

Source: https://eriknovak.github.io/datachart/latest/references/charts/dumbbellchart?q=

Constructs a DumbbellChart with three data records, a title, start and end names, and delta value labels. The example shows the required import and the constructor call with keyword arguments.

```python
>>> from datachart.charts import DumbbellChart
>>> figure = DumbbellChart(
...     data=[
...         {"label": "Norway", "start": 79.8, "end": 83.2},
...         {"label": "Chile", "start": 77.1, "end": 81.2},
...         {"label": "India", "start": 62.5, "end": 70.9},
...     ],
...     title="Life Expectancy",
...     start_name="2000",
...     end_name="2019",
...     show_values=True,
...     value_kind="delta",
... )
```

--------------------------------

### Create a basic RaincloudPlot with sample data

Source: https://eriknovak.github.io/datachart/latest/references/charts/raincloudplot?q=

Imports RaincloudPlot and creates a figure with two groups (Group A and Group B), each with three values. The example sets a title and axis labels. Use this as a starting point for building raincloud plots with your own data.

```python
>>> from datachart.charts import RaincloudPlot
>>> figure = RaincloudPlot(
...     data=[
...         {"label": "Group A", "value": 10},
...         {"label": "Group A", "value": 15},
...         {"label": "Group A", "value": 12},
...         {"label": "Group B", "value": 20},
...         {"label": "Group B", "value": 25},
...         {"label": "Group B", "value": 22},
...     ],
...     title="Basic Raincloud Plot",
...     xlabel="Group",
...     ylabel="Value"
... )
```

--------------------------------

### Style dumbbell dots and connectors with the style dictionary

Source: https://eriknovak.github.io/datachart/latest/how-to-guides/charts/dumbbellchart

Applies a custom style dictionary to control dot colors, size, edge width, and connector appearance. Attributes are listed in datachart.typings.DumbbellStyleAttrs; any omitted attribute keeps the active theme's value. This example uses a muted start and saturated end to emphasize the final value.

```python
DumbbellChart(
    data=life,
    title="Life expectancy at birth",
    xlabel="Years",
    figsize=FIG_SIZE.FULL_MEDIUM,
    start_name="2000",
    end_name="2019",
    legend={"title": "Year", "location": LEGEND_LOCATION.LOWER_RIGHT},
    # a muted start, a saturated end, and a wide light connector
    style={
        "plot_dumbbell_start_color": "#b0bec5",
        "plot_dumbbell_end_color": "#00796b",
        "plot_dumbbell_size": 90,
        "plot_dumbbell_edge_width": 0,
        "plot_dumbbell_connector_color": "#cfd8dc",
        "plot_dumbbell_connector_width": 5,
    },
).show()
```

--------------------------------

### kde2d example

Source: https://eriknovak.github.io/datachart/latest/references/utils/stats

Example usage of kde2d. Shows the x and y grid coordinates and the z values for a small dataset with grid_size=(3,2) and cut=0.

```python
>>> from datachart.utils.stats import kde2d
>>> surface = kde2d([1, 2, 3, 4], [1, 3, 2, 4], grid_size=(3, 2), cut=0)
>>> surface["x"], surface["y"]
([1.0, 2.5, 4.0], [1.0, 4.0])
>>> [[round(z, 3) for z in row] for row in surface["z"]]
[[0.075, 0.038, 0.001], [0.001, 0.038, 0.075]]

```

--------------------------------

### median example

Source: https://eriknovak.github.io/datachart/latest/references/utils/stats

Example usage of median. Returns the median of the list.

```python
>>> from datachart.utils.stats import median
>>> median([1, 2, 3, 4, 5])
3.0
```
Tokens:
Raw