Typings Module
datachart.typings
Module containing the typings.
The typings module holds the dictionary contracts of the package: the records
a chart's data takes, the settings passed beside it (reference lines and
bands, texts, legend, emphasis rule, colorbar), and the style keys a chart's
style and the theme accept. A per-chart contract is documented on that
chart's reference page; the shared ones on the typings page.
Typings by Chart
The records a chart's data takes and the keys its style accepts are documented on the chart's own reference page, next to the function that reads them.
Trends and Comparisons
| Chart | Shows | Data | Style |
|---|---|---|---|
| LineChart | A value along an ordered axis, one line per series. | LineDataPointAttrs |
LineStyleAttrs |
| StackedAreaChart | Parts of a total along an ordered axis, filled on top of each other. | LineDataPointAttrs |
StackedAreaStyleAttrs |
| BumpChart | Rank over time, one line per series. | LineDataPointAttrs |
BumpStyleAttrs |
| BarChart | A value per category as bars; series grouped, stacked, or overlaid. | BarDataPointAttrs |
BarStyleAttrs |
| PyramidChart | Two series as horizontal bars mirrored around a shared category axis. | BarDataPointAttrs |
BarStyleAttrs |
| RadialChart | Series on polar axes, as a radar line, an area, bars, or a histogram. | RadialDataPointAttrs |
LineStyleAttrs, BarStyleAttrs, HistStyleAttrs, ScatterStyleAttrs |
| CalendarHeatmap | One colored cell per day, weeks as columns and weekdays as rows. | CalendarHeatmapDataAttrs |
CalendarHeatmapStyleAttrs |
| GanttChart | A schedule: one bar per task from its start to its end over a date axis. | GanttTaskAttrs |
GanttStyleAttrs |
| DumbbellChart | Two values per category, a dot at each and a connector between them. | DumbbellRecordAttrs |
DumbbellStyleAttrs |
Distributions
| Chart | Shows | Data | Style |
|---|---|---|---|
| Histogram | The distribution of one numeric variable, binned. | HistDataPointAttrs |
HistStyleAttrs |
| BoxPlot | Median, quartiles, whiskers, and outliers per group. | BoxDataPointAttrs |
BoxStyleAttrs |
| ViolinPlot | The density profile of each group's distribution. | ViolinDataPointAttrs |
ViolinStyleAttrs |
| SwarmPlot | Every observation as a point, spread within its group. | SwarmDataPointAttrs |
SwarmStyleAttrs |
| RaincloudPlot | A half violin, the raw points, and a box per group. | RaincloudDataPointAttrs |
RaincloudStyleAttrs |
| RidgelinePlot | One density ridge per group, stacked and partly overlapping. | RidgelineDataPointAttrs |
RidgelineStyleAttrs |
Relationships
| Chart | Shows | Data | Style |
|---|---|---|---|
| ScatterChart | One point per observation, placed by two numeric variables. | ScatterDataPointAttrs |
ScatterStyleAttrs |
| Heatmap | A two-dimensional matrix as colored cells. | HeatmapDataAttrs |
HeatmapStyleAttrs |
| ContourChart | A surface sampled on a grid, as iso-lines or filled bands. | ContourDataAttrs |
ContourStyleAttrs |
| HexbinChart | Point density on the plane, as colored hexagons. | HexbinDataAttrs |
HexbinStyleAttrs |
| ParallelCoords | Each record as a polyline across one axis per dimension. | ParallelCoordsDataPointAttrs |
ParallelCoordsStyleAttrs |
| NetworkChart | Nodes joined by edges, placed by a layout. | NetworkSingleChartAttrs |
NetworkStyleAttrs |
| ScatterMatrix | A scatter chart for every pair of dimensions, distributions on the diagonal. | ScatterMatrixDataPointAttrs |
StyleAttrs |
Flows
| Chart | Shows | Data | Style |
|---|---|---|---|
| SankeyChart | Weighted flows between categories, as ribbons between node columns. | SankeySingleChartAttrs |
SankeyStyleAttrs |
Part of a Whole
| Chart | Shows | Data | Style |
|---|---|---|---|
| Treemap | Part-of-whole data as nested rectangles sized by value. | TreemapSingleChartAttrs |
TreemapStyleAttrs |
Settings
The dictionaries a chart takes beside its data: reference lines and bands, text annotations, the legend, the emphasis rule, and the colorbar. Each is a parameter of the chart function, and a field left out or set to None falls back to the theme.
| I want to… | Pass | As |
|---|---|---|
| mark a value on the x or y axis | vlines, hlines |
VLineSettingAttrs, HLineSettingAttrs |
| shade a range of the x or y axis | vspans, hspans |
VSpanSettingAttrs, HSpanSettingAttrs |
| write a note on the chart | texts |
TextSettingAttrs |
| title, place, or lay out the legend | legend |
LegendSettingAttrs |
| highlight the series or marks matching a rule | emphasis_rule |
EmphasisRuleAttrs |
| place or format the colorbar | colorbar |
ColorbarSettingAttrs |
datachart.typings.VLineSettingAttrs
Bases: TypedDict
The vertical reference line setting, passed to a chart front as vlines.
| ATTRIBUTE | DESCRIPTION |
|---|---|
x |
The x-axis position of the line.
TYPE:
|
ymin |
The minimum y-axis position value.
TYPE:
|
ymax |
The maximum y-axis position value.
TYPE:
|
style |
The vertical line style attributes.
TYPE:
|
label |
The label of the vertical line.
TYPE:
|
datachart.typings.HLineSettingAttrs
Bases: TypedDict
The horizontal reference line setting, passed to a chart front as hlines.
| ATTRIBUTE | DESCRIPTION |
|---|---|
y |
The x-axis position of the line.
TYPE:
|
xmin |
The minimum y-axis position value.
TYPE:
|
xmax |
The maximum y-axis position value.
TYPE:
|
style |
The horizontal line style attributes.
TYPE:
|
label |
The label of the horizontal line.
TYPE:
|
datachart.typings.VSpanSettingAttrs
Bases: TypedDict
The vertical reference band setting, passed to a chart front as vspans.
A vertical band shades the region between two x-axis positions over the full height of the axes. On a radial chart the bounds are angles in degrees and the band is a wedge over the full radius.
| ATTRIBUTE | DESCRIPTION |
|---|---|
xmin |
The lower x-axis bound. Defaults to the axis minimum.
TYPE:
|
xmax |
The upper x-axis bound. Defaults to the axis maximum.
TYPE:
|
style |
The vertical band style attributes.
TYPE:
|
label |
The label of the band (shown in the legend).
TYPE:
|
datachart.typings.HSpanSettingAttrs
Bases: TypedDict
The horizontal reference band setting, passed to a chart front as hspans.
A horizontal band shades the region between two y-axis positions over the full width of the axes. On a radial chart the bounds are radii and the band is an annulus over the full circle.
| ATTRIBUTE | DESCRIPTION |
|---|---|
ymin |
The lower y-axis bound. Defaults to the axis minimum.
TYPE:
|
ymax |
The upper y-axis bound. Defaults to the axis maximum.
TYPE:
|
style |
The horizontal band style attributes.
TYPE:
|
label |
The label of the band (shown in the legend).
TYPE:
|
datachart.typings.TextSettingAttrs
Bases: TypedDict
The text annotation setting, passed to a chart front as texts.
| ATTRIBUTE | DESCRIPTION |
|---|---|
text |
The annotation text.
TYPE:
|
x |
The x-axis position of the text.
TYPE:
|
y |
The y-axis position of the text.
TYPE:
|
coords |
The coordinate system of the text position:
TYPE:
|
target |
The data point the connector points to, always in data coordinates. When present, a connector is drawn from the text to the target.
TYPE:
|
style |
The per-text style attributes.
TYPE:
|
subplot |
The 0-based index, in render order, of the
subplot the text lands in. Read only by
TYPE:
|
datachart.typings.LegendSettingAttrs
Bases: TypedDict
The per-figure legend setting, passed to a chart front as legend.
Every field is optional; a None field falls back to the theme's
plot_legend_* attribute of the same name.
| ATTRIBUTE | DESCRIPTION |
|---|---|
title |
The legend title; an empty string draws none.
TYPE:
|
location |
The legend location. An outside member places the legend beside the axes.
TYPE:
|
ncols |
The number of legend columns.
TYPE:
|
alignment |
The legend alignment.
TYPE:
|
datachart.typings.EmphasisRuleAttrs
Bases: TypedDict
The emphasis rule setting, passed to a chart front as emphasis_rule.
Exactly one comparison key: a unit matching it is highlighted and every
other unit muted. Each front selects its own unit — a bar, leaf, node,
row, cell or bin reads its one value; a group or series reads a summary
of its values, chosen by by. A unit's explicit emphasis role wins.
| ATTRIBUTE | DESCRIPTION |
|---|---|
above |
Highlight values strictly above this.
TYPE:
|
below |
Highlight values strictly below this.
TYPE:
|
between |
Highlight
values within
TYPE:
|
top |
Highlight the
TYPE:
|
bottom |
Highlight the
TYPE:
|
by |
The summary a
group or series is read by. Groups default to
TYPE:
|
datachart.typings.ColorbarSettingAttrs
Bases: TypedDict
The per-figure colorbar setting, passed to a chart front as colorbar.
Every field is optional. location is the control: it places the bar on
any edge of the chart. With no location, orientation derives the edge:
vertical means right, horizontal means top. When both are given location
wins.
| ATTRIBUTE | DESCRIPTION |
|---|---|
label |
The caption beside the bar, reading along
it; drawn in the
TYPE:
|
location |
The chart edge the bar sits on.
TYPE:
|
format |
The format of the bar's tick
labels, with the value named
TYPE:
|
ticks |
Explicit tick positions on the bar; positions outside the mapped value range are not drawn.
TYPE:
|
orientation |
The orientation; derives
the edge when
TYPE:
|
Shared Style
Style groups several charts read from their style dictionary: the value labels show_values prints, the area fill, the regression line, reference lines and bands, and text annotations. A chart's reference page says which of them it draws, and every key is also a theme key.
datachart.typings.ValueLabelStyleAttrs
Bases: TypedDict
The typing for the value labels: the numbers a chart prints beside its
marks when show_values is on. One style serves every chart that takes
show_values; the plot_bar_value_* keys of BarStyleAttrs are aliases.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_value_fontsize |
The font size of the value labels.
TYPE:
|
plot_value_color |
The color of the value labels.
TYPE:
|
plot_value_padding |
The gap between a mark and its value label, in points.
TYPE:
|
plot_value_halo_width |
The width, in points, of the halo, in the axes face color, stroked around the value labels so they stay legible over marks and lines.
TYPE:
|
datachart.typings.AreaStyleAttrs
Bases: TypedDict
The typing for the area style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_area_alpha |
The alpha value of the area.
TYPE:
|
plot_area_color |
The color of the area.
TYPE:
|
plot_area_linewidth |
The line width of the area.
TYPE:
|
plot_area_hatch |
The hatch style of the area.
TYPE:
|
plot_area_zorder |
The zorder of the area.
TYPE:
|
datachart.typings.RegressionStyleAttrs
Bases: TypedDict
The typing for regression line style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_regression_color |
The regression line color.
TYPE:
|
plot_regression_alpha |
The alpha of the regression line.
TYPE:
|
plot_regression_width |
The line width.
TYPE:
|
plot_regression_style |
The line style.
TYPE:
|
plot_regression_ci_alpha |
Confidence interval alpha.
TYPE:
|
datachart.typings.VLineStyleAttrs
Bases: TypedDict
The typing for the vertical line style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_vline_color |
The color of the vertical line.
TYPE:
|
plot_vline_style |
The style of the vertical line.
TYPE:
|
plot_vline_width |
The width of the vertical line.
TYPE:
|
plot_vline_alpha |
The alpha value of the vertical line.
TYPE:
|
datachart.typings.HLineStyleAttrs
Bases: TypedDict
The typing for the horizontal line style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_hline_color |
The color of the horizontal line.
TYPE:
|
plot_hline_style |
The style of the horizontal line.
TYPE:
|
plot_hline_width |
The width of the horizontal line.
TYPE:
|
plot_hline_alpha |
The alpha value of the horizontal line.
TYPE:
|
datachart.typings.VSpanStyleAttrs
Bases: TypedDict
The typing for the vertical reference band style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_vspan_color |
The fill color of the band. Defaults to the theme's muted color.
TYPE:
|
plot_vspan_alpha |
The alpha value of the band.
TYPE:
|
plot_vspan_hatch |
The hatch pattern of the band.
TYPE:
|
plot_vspan_edge_color |
The edge color of the band; the hatch draws in it.
TYPE:
|
plot_vspan_edge_width |
The edge line width of the band.
TYPE:
|
plot_vspan_zorder |
The zorder of the band. Defaults to sit over the grid and under the marks.
TYPE:
|
datachart.typings.HSpanStyleAttrs
Bases: TypedDict
The typing for the horizontal reference band style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_hspan_color |
The fill color of the band. Defaults to the theme's muted color.
TYPE:
|
plot_hspan_alpha |
The alpha value of the band.
TYPE:
|
plot_hspan_hatch |
The hatch pattern of the band.
TYPE:
|
plot_hspan_edge_color |
The edge color of the band; the hatch draws in it.
TYPE:
|
plot_hspan_edge_width |
The edge line width of the band.
TYPE:
|
plot_hspan_zorder |
The zorder of the band. Defaults to sit over the grid and under the marks.
TYPE:
|
datachart.typings.TextStyleAttrs
Bases: TypedDict
The typing for the text annotation style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_text_color |
The text color; falls back to the general font color.
TYPE:
|
plot_text_size |
The text font size.
TYPE:
|
plot_text_weight |
The text font weight.
TYPE:
|
plot_text_halign |
The horizontal alignment of the text.
TYPE:
|
plot_text_valign |
The vertical alignment of the text.
TYPE:
|
plot_text_alpha |
The alpha value of the text.
TYPE:
|
plot_text_box_visible |
Whether to draw the background box.
TYPE:
|
plot_text_box_style |
The matplotlib box style (e.g.
TYPE:
|
plot_text_box_facecolor |
The face color of the box.
TYPE:
|
plot_text_box_edgecolor |
The edge color of the box.
TYPE:
|
plot_text_box_edge_width |
The edge width of the box.
TYPE:
|
plot_text_box_alpha |
The alpha value of the box.
TYPE:
|
plot_text_arrow_style |
The connector look (see
TYPE:
|
plot_text_arrow_curve |
The connector curvature; overrides the look's own.
TYPE:
|
plot_text_arrow_color |
The connector color.
TYPE:
|
plot_text_arrow_width |
The connector line width.
TYPE:
|
Theme Style
The keys a theme defines and config holds: colors, fonts, axes, legend, grid, the theme-driven defaults, and the sketch and ink looks. StyleAttrs is their union together with every chart's own style keys; the config methods and register_theme take it, and the Themes guide shows how a theme is built from it.
datachart.typings.StyleAttrs
Bases: ColorStyleAttrs, FontStyleAttrs, AxesStyleAttrs, LegendStyleAttrs, AreaStyleAttrs, GridStyleAttrs, LineStyleAttrs, StackedAreaStyleAttrs, BumpStyleAttrs, SankeyStyleAttrs, TreemapStyleAttrs, NetworkStyleAttrs, BarStyleAttrs, ValueLabelStyleAttrs, HistStyleAttrs, VLineStyleAttrs, HLineStyleAttrs, VSpanStyleAttrs, HSpanStyleAttrs, TextStyleAttrs, HeatmapStyleAttrs, CalendarHeatmapStyleAttrs, GanttStyleAttrs, DumbbellStyleAttrs, ContourStyleAttrs, HexbinStyleAttrs, ScatterStyleAttrs, RegressionStyleAttrs, BoxStyleAttrs, SwarmStyleAttrs, ViolinStyleAttrs, RidgelineStyleAttrs, ParallelCoordsStyleAttrs, ScatterMatrixStyleAttrs, ThemeDefaultAttrs, SketchStyleAttrs, InkStyleAttrs
The style attributes. Combines all style typings.
datachart.typings.ColorStyleAttrs
Bases: TypedDict
The typing for the general color style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
color_general_singular |
The colors used where a chart needs one color rather than a series palette: the parallel coords numeric hue ramp and the network node base color (palette name, single color, or list of hex colors).
TYPE:
|
color_general_multiple |
The colors used when the datasets share one coordinate space, which is the default for every chart (palette name, single color, or list of hex colors).
TYPE:
|
color_parallel_hue |
The color palette for parallel coords hue categories (palette name, single color, or list of hex colors);
TYPE:
|
color_parallel_hue_continuous |
The sequential ramp for parallel coords numeric hue columns (palette name, single color, or list of hex colors).
TYPE:
|
muted_color |
The color applied to background-emphasis layers.
TYPE:
|
muted_alpha |
The alpha applied to background-emphasis layers.
TYPE:
|
datachart.typings.FontStyleAttrs
Bases: TypedDict
The typing for the font style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
font_general_family |
The general font family.
TYPE:
|
font_general_sansserif |
The general sans-serif font.
TYPE:
|
font_general_serif |
The general serif font stack, used when the family is "serif".
TYPE:
|
font_general_color |
The general font color.
TYPE:
|
font_general_size |
The general font size.
TYPE:
|
font_general_style |
The general font style.
TYPE:
|
font_general_weight |
The general font weight.
TYPE:
|
font_title_size |
The title font size.
TYPE:
|
font_title_color |
The title font color.
TYPE:
|
font_title_style |
The title font style.
TYPE:
|
font_title_weight |
The title font weight.
TYPE:
|
font_subtitle_size |
The subtitle font size.
TYPE:
|
font_subtitle_color |
The subtitle font color.
TYPE:
|
font_subtitle_style |
The subtitle font style.
TYPE:
|
font_subtitle_weight |
The subtitle font weight.
TYPE:
|
font_xlabel_size |
The xlabel font size.
TYPE:
|
font_xlabel_color |
The xlabel font color.
TYPE:
|
font_xlabel_style |
The xlabel font style.
TYPE:
|
font_xlabel_weight |
The xlabel font weight.
TYPE:
|
font_ylabel_size |
The ylabel font size.
TYPE:
|
font_ylabel_color |
The ylabel font color.
TYPE:
|
font_ylabel_style |
The ylabel font style.
TYPE:
|
font_ylabel_weight |
The ylabel font weight.
TYPE:
|
datachart.typings.AxesStyleAttrs
Bases: TypedDict
The typing for the axes style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
axes_spines_top_visible |
Make the top plot spine visible.
TYPE:
|
axes_spines_right_visible |
Make the right plot spine visible.
TYPE:
|
axes_spines_bottom_visible |
Make the bottom plot spine visible.
TYPE:
|
axes_spines_left_visible |
Make the left plot spine visible.
TYPE:
|
axes_spines_width |
The width of the spines.
TYPE:
|
axes_spines_zorder |
The zorder of the spines.
TYPE:
|
axes_ticks_length |
The length of the ticks.
TYPE:
|
axes_ticks_label_size |
The size of the tick labels.
TYPE:
|
figure_facecolor |
The color of the figure ground.
TYPE:
|
axes_facecolor |
The color of the axes ground; label
halos and etch washes take it.
TYPE:
|
axes_spines_color |
The color of the spines.
TYPE:
|
axes_ticks_color |
The color of the tick marks.
TYPE:
|
datachart.typings.LegendStyleAttrs
Bases: TypedDict
The typing for the legend style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_legend_shadow |
Show the legends shadow.
TYPE:
|
plot_legend_frameon |
Show the legends frame.
TYPE:
|
plot_legend_alignment |
The legend alignment.
TYPE:
|
plot_legend_location |
The legend location.
TYPE:
|
plot_legend_font_size |
The font size within the legend.
TYPE:
|
plot_legend_title_size |
The title size of the legend.
TYPE:
|
plot_legend_label_color |
The label color of the legend.
TYPE:
|
plot_legend_title |
The legend title; an empty string draws none.
TYPE:
|
plot_legend_ncols |
The number of legend columns.
TYPE:
|
plot_legend_edge_color |
The legend frame color.
TYPE:
|
plot_legend_face_color |
The legend background color.
TYPE:
|
datachart.typings.GridStyleAttrs
Bases: TypedDict
The typing for the grid style.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_grid_alpha |
The alpha value of the grid.
TYPE:
|
plot_grid_color |
The color of the grid.
TYPE:
|
plot_grid_linewidth |
The line width of the grid.
TYPE:
|
plot_grid_linestyle |
The line style of the grid.
TYPE:
|
plot_grid_zorder |
The zorder of the grid.
TYPE:
|
datachart.typings.ThemeDefaultAttrs
Bases: TypedDict
The typing for theme-driven defaults and cycles.
| ATTRIBUTE | DESCRIPTION |
|---|---|
chart_default_show_grid |
The theme default
for
TYPE:
|
chart_default_show_values |
The theme default for
TYPE:
|
chart_default_node_label_position |
The theme default for the network chart's
TYPE:
|
plot_hatch_cycle |
The hatch patterns assigned
per bar/histogram series, parallel to the color cycle; with
TYPE:
|
plot_linestyle_cycle |
The
line styles assigned per line, bump and radial line series, parallel
to the color cycle. An explicit per-chart line style wins.
TYPE:
|
plot_marker_cycle |
The markers assigned per scatter and radial scatter series,
parallel to the color cycle, and per network node group: a marker,
or
TYPE:
|
datachart.typings.SketchStyleAttrs
Bases: TypedDict
The typing for the sketch attributes: the theme's render-scoped rc-level
look (path wobble, halo stroke). The panel snapshots the wobble at build
time and applies it inside a scoped matplotlib rc context, so no global rc
setting changes; the halo resolves like any style key, so a chart's style
can override it. Composition keeps the look of the figures it was built from.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_sketch_params |
The path wobble as
matplotlib sketch parameters
TYPE:
|
plot_sketch_halo_width |
The extra width, added to
the line width, of the halo (in the axes face color) stroked under series lines (line,
radial, regression), so crossing lines read as cut-outs; marks, text
and patches stay clean.
TYPE:
|
datachart.typings.InkStyleAttrs
Bases: TypedDict
The typing for the ink attributes: marks drawn as a quill and an etching
needle would draw them. Every attribute resolves when the chart is built and
rides on its artists, so composition keeps the look; None turns it off.
| ATTRIBUTE | DESCRIPTION |
|---|---|
plot_ink_stroke |
The broad-nib pen the
series lines (line, bump, radial, regression) are drawn with, as a
filled ribbon whose width varies along the line. Keys:
TYPE:
|
plot_etch |
The
etching that replaces the hatch tile of a hatched fill with
hand-drawn lines clipped to its outline; the hatch pattern still
picks the lines and
TYPE:
|
plot_value_etch |
The steps a value
scale draws in when
TYPE:
|