# datachart

> Data visualization package, simple to use, highly customizable

datachart is a Python data visualization package built on matplotlib.
It provides simple chart functions (BarChart, LineChart, StackedAreaChart, BumpChart, ScatterChart,
Histogram, Heatmap, ContourChart, HexbinChart, BoxPlot, ViolinPlot, SwarmPlot, RaincloudPlot,
RidgelinePlot,
ParallelCoords, PyramidChart, RadialChart, CalendarHeatmap, GanttChart, DumbbellChart, SankeyChart, NetworkChart,
ScatterMatrix,
Treemap), figure
composition via Panel (overlaying charts on shared axes) and Grid
(arranging charts in a grid), and a global configuration system with
predefined themes.

Install with `pip install datachart`. All charts return a matplotlib
Figure. Style is controlled globally via `datachart.config.config` and
themes; per-chart overrides go in each chart's `style` parameter.


## Getting Started

- [Home](https://eriknovak.github.io/datachart/0.10.2/index.md): Landing page with a chart gallery, links to the guides and reference, installation, and a first example.
- [AI Assistants](https://eriknovak.github.io/datachart/0.10.2/ai-assistants/index.md): Pointing an AI coding assistant at these docs: llms.txt and per-page markdown, the Context7 and GitMCP servers, and a project-rules snippet describing the package.
- [How-to Guides](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/index.md): Map of the guide sections: charts, composition, styling, utility.

## Charts

- [Charts](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/index.md): Map of the chart guides by family, with Panel and Grid support per chart, and the highlighting guide.
- [Line Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/linechart/index.md): Line chart basics on the global temperature record, line and area style, value labels, reference lines and bands, annotations, several series with emphasis, legend and confidence bands, subplots, datetime axes, axis scales, and worked examples on real data.
- [Stacked Area Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/stackedareachart/index.md): Stacked area chart basics on world electricity generation by source, legend, band style, zero, percent and streamgraph baselines, value labels, emphasis, reference lines and bands, subplots, Panel and Grid composition, and worked examples on real data.
- [Bump Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/bumpchart/index.md): Bump chart basics on world population ranks, ranking by value or given ranks, ties and gaps, end labels, curved lines, value labels, emphasis, reference bands, Panel and Grid composition, and worked examples on real data.
- [Bar Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/barchart/index.md): Bar chart basics on the Paris 2024 medal table, horizontal bars, sorting, value labels, emphasis, reference lines and bands, annotations, date labels, grouped, stacked and overlaid series, legend, subplots, error bars, axis scales, and worked examples on real data.
- [Pyramid Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/pyramidchart/index.md): Pyramid chart basics on an ageing population by age and sex, naming the sides, mirrored value axis range and ticks, value labels, sorting, emphasis, reference lines and bands, error bars, date labels, custom data keys, and Grid comparisons of young and ageing populations.
- [Radial Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/radialchart/index.md): Radial chart basics on a year of coastal weather data, the line, bar, scatter and histogram visuals, start angle and direction, donut holes, sorting and emphasis, tip values and labels, wedge and ring bands, bar modes, subplots, error bands, log radius, and worked examples with Grid and Panel.
- [Gantt Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/ganttchart/index.md): Gantt chart basics on an illustrative house build, date windows and calendar periods, row order, groups and group headers, milestones, progress and duration labels, dependency arrows, the today line, reference lines, notes, emphasis on the critical path, plan against forecast, Grid composition, and worked examples on a sprint, a research grant, and a product launch.
- [Dumbbell Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/dumbbellchart/index.md): Dumbbell chart basics on WHO life expectancy data, orientation, sorting by start, end, or change, endpoint names and legend, endpoint and delta value labels, direction arrows, markers and connectors, emphasis rules, reference lines, text notes, overlaid and subplot charts, Panel and Grid composition, and worked examples on real data.
- [Calendar Heatmap](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/calendarheatmap/index.md): Calendar heatmap basics on daily cyclist counts, week start, month and weekday labels, colorbar and cell values, calendar style, normalization, emphasis, text notes, one calendar per year and the year filter, multiple datasets, Grid composition, themes, and worked examples on illustrative daily data.
- [Histogram](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/histogram/index.md): Histogram basics on Palmer penguin flipper lengths, choosing the number of bins, bar and step styles, orientation, value labels, reference lines and bands, text notes, stacked and overlaid series, emphasis rules, legend, shared subplots, density, density-curve and cumulative views, log count axes, custom data keys, and worked examples on marathon times, an A/B test, and request latency.
- [Box Plot](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/boxplot/index.md): Box plot basics on the Palmer penguins, axis ticks and formats, box order, box style, horizontal boxes, outliers, notched boxes and median differences, median labels, emphasis rules, reference lines and bands, text notes, date labels, swarms and violins with Panel, subplots with shared axes, log scales, custom data keys, and worked examples with Grid.
- [Violin Plot](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/violinplot/index.md): Violin plot basics on the Palmer penguins, inner marks, bandwidth, split violins, legend, median labels, violin style, horizontal violins, emphasis and emphasis rules, reference lines and bands, text notes, date labels, box and swarm overlays with Panel, subplots with shared axes, log scales, custom data keys, and worked examples on real and illustrative data.
- [Swarm Plot](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/swarmplot/index.md): Swarm plot basics on the ages of US presidents at inauguration, point style, swarm and strip modes, horizontal swarms, min, median and max labels, group and single-point emphasis, reference lines and bands, named points, date labels, swarms over boxes and violins, overlaid and subplot series, log scale, and worked examples on real and illustrative data.
- [Raincloud Plot](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/raincloudplot/index.md): Raincloud plot basics on the Palmer penguins, cloud, rain and box style, cloud bandwidth, swarm and strip rain, box outliers, value labels, horizontal rainclouds, emphasis and emphasis rules, reference lines and bands, text notes, date labels, legend, subplots, Panel and Grid composition, log scale, custom data keys, and worked examples on reaction times, test scores, and delivery times.
- [Ridgeline Plot](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/ridgelineplot/index.md): Ridgeline plot basics on a year of daily temperatures in Ljubljana, ridge style, row overlap, per-row and common density scales, median and quartile marks, fill and outline, sorting by median, bandwidth, the shared value range, orientation, emphasis rules, reference lines and bands, legend, text notes, subplots, Panel and Grid composition, and worked examples on illustrative data.
- [Scatter Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/scatterchart/index.md): Scatter chart basics on WHO life expectancy and World Bank GDP per capita, log axes and tick labels, marker style, hue grouping, bubble sizes, point and value labels, regression lines with confidence bands and correlation, equal aspect ratio, emphasis and emphasis rules, reference lines and bands, text notes, legend, shared subplots, datetime axis, custom data keys, and worked examples with Panel on real and illustrative data.
- [Heatmap](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/heatmap/index.md): Heatmap basics on the monthly climate of six cities, tick labels, square cells, colorbar placement and cell values, sequential and diverging colormaps, value ranges and log-style normalization, emphasis rules and grids, text notes, multiple heatmaps with shared axes, blank cells, axis ranges, date labels, and worked examples on real and illustrative data.
- [Contour Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/contourchart/index.md): Contour chart basics on an illustrative two-peak hill, tick formats, equal aspect ratio, filled bands and colorbars, inline labels, level counts, lists and rules, contour style and colormaps, normalization, reference lines and bands, landmark notes, overlaid seasonal densities, legend, emphasis and emphasis rules, shared-level subplots, Panel and Grid composition, 2-D density estimates, log axes, a datetime axis, and worked examples on real data.
- [Hexbin Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/hexbinchart/index.md): Hexbin chart basics on illustrative apartment listings, from an overplotted scatter to hexagon counts, axis ticks and formats, colorbar label and placement, grid size, minimum count, log normalization, aggregating a per-point value, hexagon style, emphasis rules, reference lines and bands, text notes, subplots with a shared color range, Panel and Grid composition, equal aspect, datetime axis, themes, and worked examples.
- [Sankey Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/sankeychart/index.md): Sankey chart basics on an illustrative national energy flow, the links data contract, inferred and explicit node columns, column labels, ribbon values and value formats, ribbons colored by source, target or grey, node width, gaps, stroke and outlines, label halos, text notes, subplots, Grid composition, themes, and worked examples on annotator agreement, a signup funnel, and the Titanic.
- [Network Chart](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/networkchart/index.md): Network chart basics on the Florentine families marriage network, node labels and label positions, spring, circular and fixed layouts, large networks, directed edges, edge weights and node sizes, groups and the grouped layout, per-node emphasis and emphasis rules, edge values, node and edge style, text notes, subplots, Grid composition, themes, and worked examples on code reviews and container traffic.
- [Treemap](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/treemap/index.md): Treemap basics on world population by continent and country, flat and nested groups, tile values and shares, per-record emphasis and emphasis rules, the group legend, tile style, text annotations, subplots, composing with Grid, themes, and worked examples on real data.
- [Parallel Coordinates](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/parallelcoords/index.md): Parallel coordinates basics on the Palmer penguins, choosing and ordering dimensions, categorical and numeric hue, category order, legend, line, axis, tick and dimension label style, emphasis and emphasis rules, text notes, overlaid sets with per-set style and hue, date dimensions, and worked examples on car specs, a hyperparameter search, and a Grid of species profiles.
- [Highlighting](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/styling/highlighting/index.md): Emphasizing and muting data series on any chart with the emphasis option, by role or by rule.
- [Scatter Matrix](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/charts/scattermatrix/index.md): Scatter matrix basics on the Palmer penguins, columns or records, selecting dimensions, hue groups and the single legend, histogram, density or blank diagonals, the lower triangle, correlation text and Simpson's paradox, regression lines, shared axes, grid lines, scatter matrix style, Grid composition, themes, and worked examples on real and illustrative data.

## Composition

- [Composition](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/composition/index.md): Map of Panel, Grid, and text annotations with Annotate.
- [Panel](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/utility/panel/index.md): Overlaying charts in one coordinate space with Panel: two value axes, legend, drawing order, emphasis, limits and scales, bar mode, nesting, horizontal panels, configuration, and worked examples.
- [Grid](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/utility/grid/index.md): Grid basics on the climate of Ljubljana and eight European cities, titles and shared axis labels, figure size, automatic layout, nested rows, blank cells, shared axes, irregular layouts, nested grids and panels, subplot figures, annotations, and worked examples on real data.
- [Text Annotations](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/utility/annotations/index.md): Text annotation basics on Ljubljana's climate normals, data and axes coordinates, targets and connectors, connector looks, text and box style, per-subplot notes, annotating finished figures, panels and subplots with Annotate, the text configuration, and worked examples on real data.

## Styling

- [Styling](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/styling/index.md): Map of themes, the theme gallery, and colormaps.
- [Themes](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/styling/themes/index.md): Applying the predefined themes through the config singleton, what a theme controls, building a custom theme with register_theme, and sharing it as a JSON theme file.
- [Theme Gallery](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/styling/theme-gallery/index.md): Each predefined theme's swatches with hex codes and six signature charts, grouped by use.
- [Colormaps](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/styling/colormaps/index.md): Every COLORS palette as a strip and six-series swatches, grouped by kind, with chips for the predefined themes that use it and the role; which kind fits which theme attribute.

## Utility

- [Utility](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/utility/index.md): Map of the statistics, figure saving, and interactive figure guides.
- [Statistics](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/utility/stats/index.md): Statistics basics on the Palmer penguins: centers, spreads, shape, correlation, trend lines, bootstrap intervals, binning, smoothers on the NASA temperature record, density estimates, each fed back into a chart, and worked examples on real data.
- [Saving Figures](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/utility/saving/index.md): Saving figures with save_figure: vector or raster formats and dpi, transparent backgrounds, several formats in one call, embedding SVG or PNG in web pages, and worked examples for a manuscript, a slide, and a documentation page.
- [Interactive Figures](https://eriknovak.github.io/datachart/0.10.2/how-to-guides/utility/interactive/index.md): Zooming, panning, and hovering over marks with show(interactive=True): the interactive extra, notebook and script behavior, what the hover annotation of every chart type shows, and worked examples for finding an outlier, reading a two-axis panel, and checking a grid.

## API Reference

- [Datachart Module](https://eriknovak.github.io/datachart/0.10.2/references/index.md): Top-level module reference, with a where-to-look table over the reference pages.
- [Charts Module](https://eriknovak.github.io/datachart/0.10.2/references/charts/index.md): Map of the chart reference pages by family, with each chart's data record, style typing, and guide.
- [LineChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/linechart/index.md): The LineChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [StackedAreaChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/stackedareachart/index.md): The StackedAreaChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [BumpChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/bumpchart/index.md): The BumpChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [BarChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/barchart/index.md): The BarChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [PyramidChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/pyramidchart/index.md): The PyramidChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [RadialChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/radialchart/index.md): The RadialChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [CalendarHeatmap](https://eriknovak.github.io/datachart/0.10.2/references/charts/calendarheatmap/index.md): The CalendarHeatmap function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [GanttChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/ganttchart/index.md): The GanttChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [DumbbellChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/dumbbellchart/index.md): The DumbbellChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [Histogram](https://eriknovak.github.io/datachart/0.10.2/references/charts/histogram/index.md): The Histogram function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [BoxPlot](https://eriknovak.github.io/datachart/0.10.2/references/charts/boxplot/index.md): The BoxPlot function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [ViolinPlot](https://eriknovak.github.io/datachart/0.10.2/references/charts/violinplot/index.md): The ViolinPlot function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [SwarmPlot](https://eriknovak.github.io/datachart/0.10.2/references/charts/swarmplot/index.md): The SwarmPlot function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [RaincloudPlot](https://eriknovak.github.io/datachart/0.10.2/references/charts/raincloudplot/index.md): The RaincloudPlot function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [RidgelinePlot](https://eriknovak.github.io/datachart/0.10.2/references/charts/ridgelineplot/index.md): The RidgelinePlot function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [ScatterChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/scatterchart/index.md): The ScatterChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [Heatmap](https://eriknovak.github.io/datachart/0.10.2/references/charts/heatmap/index.md): The Heatmap function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [ContourChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/contourchart/index.md): The ContourChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [HexbinChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/hexbinchart/index.md): The HexbinChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [ParallelCoords](https://eriknovak.github.io/datachart/0.10.2/references/charts/parallelcoords/index.md): The ParallelCoords function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [NetworkChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/networkchart/index.md): The NetworkChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [ScatterMatrix](https://eriknovak.github.io/datachart/0.10.2/references/charts/scattermatrix/index.md): The ScatterMatrix function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [SankeyChart](https://eriknovak.github.io/datachart/0.10.2/references/charts/sankeychart/index.md): The SankeyChart function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [Treemap](https://eriknovak.github.io/datachart/0.10.2/references/charts/treemap/index.md): The Treemap function and its parameters, its data record, the keys its style takes, and the constants its parameters accept.
- [Utils Module](https://eriknovak.github.io/datachart/0.10.2/references/utils/index.md): Panel, Grid, Annotate, and save_figure signatures, with a table of which utility fits which task.
- [stats](https://eriknovak.github.io/datachart/0.10.2/references/utils/stats/index.md): Statistical function signatures, grouped by center, spread, shape, association, trend line, intervals, binning, smoothing, and density.
- [config](https://eriknovak.github.io/datachart/0.10.2/references/config/index.md): The Config class and the global config instance, with a table of which method fits which task.
- [themes](https://eriknovak.github.io/datachart/0.10.2/references/themes/index.md): The predefined theme dictionaries, with a table of each theme's look and its THEME member.
- [constants](https://eriknovak.github.io/datachart/0.10.2/references/constants/index.md): Enums and constants (THEME, FIG_SIZE, ORIENTATION, COLORS, ...).
- [typings](https://eriknovak.github.io/datachart/0.10.2/references/typings/index.md): The shared TypedDict contracts, per-figure settings, shared style groups, and theme style, with a table pointing to each chart's own typings.