BarChart

A value per category as bars; series grouped, stacked, or overlaid. The Bar Chart guide shows every feature on real data; this page is the contract: the function, the shape of its data, the keys style takes, and the constant each parameter accepts.

Function

datachart.charts.BarChart

BarChart(
    data: list[BarRecordAttrs] | list[list[BarRecordAttrs]],
    *,
    title: str | None = None,
    xlabel: str | None = None,
    ylabel: str | None = None,
    subtitle: str | list[str | None] | None = None,
    emphasis: (
        EMPHASIS | str | list[str | None] | None
    ) = None,
    figsize: FIG_SIZE | tuple[float, float] | None = None,
    xmin: int | float | None = None,
    xmax: int | float | None = None,
    ymin: int | float | None = None,
    ymax: int | float | None = None,
    show_legend: bool | None = None,
    legend: LegendSettingAttrs | None = None,
    show_grid: SHOW_GRID | str | bool | None = None,
    show_yerr: bool | None = None,
    show_values: bool | None = None,
    value_format: VALUE_FORMAT | str | None = None,
    aspect_ratio: ASPECT_RATIO | str | None = None,
    orientation: ORIENTATION | str | None = None,
    bar_mode: BAR_MODE | str | None = None,
    sort: SORT | str | None = None,
    sort_by: str | None = None,
    emphasis_rule: EmphasisRuleAttrs | None = None,
    scalex: AXIS_SCALE | str | None = None,
    scaley: AXIS_SCALE | str | None = None,
    subplots: bool | None = None,
    max_cols: int | None = None,
    sharex: bool | None = None,
    sharey: bool | None = None,
    style: (
        BarStyleAttrs | list[BarStyleAttrs | None] | None
    ) = None,
    xticks: (
        list[int | float] | list[list[int | float]] | None
    ) = None,
    xticklabels: list[str] | list[list[str]] | None = None,
    xtickrotate: int | list[int | None] | None = None,
    yticks: (
        list[int | float] | list[list[int | float]] | None
    ) = None,
    yticklabels: list[str] | list[list[str]] | None = None,
    ytickrotate: int | list[int | None] | None = None,
    xticks_format: (
        VALUE_FORMAT | DATE_FORMAT | str | None
    ) = None,
    yticks_format: (
        VALUE_FORMAT | DATE_FORMAT | str | None
    ) = None,
    vlines: (
        VLineSettingAttrs
        | list[VLineSettingAttrs]
        | list[
            VLineSettingAttrs
            | list[VLineSettingAttrs]
            | None
        ]
        | None
    ) = None,
    hlines: (
        HLineSettingAttrs
        | list[HLineSettingAttrs]
        | list[
            HLineSettingAttrs
            | list[HLineSettingAttrs]
            | None
        ]
        | None
    ) = None,
    dlines: (
        DLineSettingAttrs
        | list[DLineSettingAttrs]
        | list[
            DLineSettingAttrs
            | list[DLineSettingAttrs]
            | None
        ]
        | None
    ) = None,
    brackets: (
        BracketSettingAttrs
        | list[BracketSettingAttrs]
        | list[
            BracketSettingAttrs
            | list[BracketSettingAttrs]
            | None
        ]
        | None
    ) = None,
    vspans: (
        VSpanSettingAttrs
        | list[VSpanSettingAttrs]
        | list[
            VSpanSettingAttrs
            | list[VSpanSettingAttrs]
            | None
        ]
        | None
    ) = None,
    hspans: (
        HSpanSettingAttrs
        | list[HSpanSettingAttrs]
        | list[
            HSpanSettingAttrs
            | list[HSpanSettingAttrs]
            | None
        ]
        | None
    ) = None,
    texts: (
        TextSettingAttrs
        | list[TextSettingAttrs]
        | list[
            TextSettingAttrs | list[TextSettingAttrs] | None
        ]
        | None
    ) = None,
    label: str | list[str | None] | None = None,
    y: str | list[str | None] | None = None,
    yerr: str | list[str | None] | None = None
) -> DatachartFigure

Creates the bar chart.

Bars compare a numeric value across discrete categories: each label gets a bar whose length encodes its value. Use it when the categories are few and unordered (or ordinal) and the question is "which is bigger, and by how much"; several series can be grouped, stacked, or overlaid via bar_mode. For a continuous x-axis reach for LineChart, for distributions for Histogram.

Examples:

>>> from datachart.charts import BarChart
>>> figure = BarChart(
...     data=[
...         {"label": "cat1", "y": 5},
...         {"label": "cat2", "y": 10},
...         {"label": "cat3", "y": 15},
...         {"label": "cat4", "y": 20},
...         {"label": "cat5", "y": 25}
...     ],
...     title="Basic Bar Chart",
...     xlabel="LABEL",
...     ylabel="Y"
... )

PARAMETER	DESCRIPTION
`data`	The data points for the bar chart(s). Can be a single list of data points for one chart, or a list of lists for multiple charts/subplots. TYPE: `list[BarRecordAttrs] \| list[list[BarRecordAttrs]]`
`title`	The title of the chart. TYPE: `str \| None` DEFAULT: `None`
`xlabel`	The x-axis label. TYPE: `str \| None` DEFAULT: `None`
`ylabel`	The y-axis label. TYPE: `str \| None` DEFAULT: `None`
`subtitle`	The subtitle(s) for individual charts. Used as legend labels. TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`emphasis`	The emphasis role(s) for individual charts, aligned like `style`: "background" mutes a chart (theme muted color, lowered alpha, behind the others, no legend entry), "highlight" bolds its edges and brings it to the front, None leaves it unchanged. See `EMPHASIS`. TYPE: `EMPHASIS \| str \| list[str \| None] \| None` DEFAULT: `None`
`figsize`	The size of the figure as (width, height) in inches. See `FIG_SIZE`. TYPE: `FIG_SIZE \| tuple[float, float] \| None` DEFAULT: `None`
`xmin`	The minimum x-axis value. TYPE: `int \| float \| None` DEFAULT: `None`
`xmax`	The maximum x-axis value. TYPE: `int \| float \| None` DEFAULT: `None`
`ymin`	The minimum y-axis value. TYPE: `int \| float \| None` DEFAULT: `None`
`ymax`	The maximum y-axis value. TYPE: `int \| float \| None` DEFAULT: `None`
`show_legend`	Whether to show the legend. TYPE: `bool \| None` DEFAULT: `None`
`legend`	The per-figure legend setting: title, location, column count and alignment; each field falls back to the theme. See `LegendSettingAttrs`. TYPE: `LegendSettingAttrs \| None` DEFAULT: `None`
`show_grid`	Which grid lines to show ("both", "x", "y"); `False` draws none. See `SHOW_GRID`. TYPE: `SHOW_GRID \| str \| bool \| None` DEFAULT: `None`
`show_yerr`	Whether to show y-axis error bars. TYPE: `bool \| None` DEFAULT: `None`
`show_values`	Whether to show bar value labels at the edge of each bar. TYPE: `bool \| None` DEFAULT: `None`
`value_format`	Format string for bar value labels: a `VALUE_FORMAT` constant or any `"{x:.1f}"`, `"{:.1f}%"`, or `"%g"` style string. TYPE: `VALUE_FORMAT \| str \| None` DEFAULT: `None`
`aspect_ratio`	The aspect ratio of the axes ("auto" or "equal"). See `ASPECT_RATIO`. TYPE: `ASPECT_RATIO \| str \| None` DEFAULT: `None`
`bar_mode`	How multiple bar series share the axis: "group" (side-by-side), "stack" (stacked), or "overlay" (overlapping). See `BAR_MODE`. TYPE: `BAR_MODE \| str \| None` DEFAULT: `None`
`sort`	The order the categories are drawn in: None (input order), "ascending", or "descending" by value. One order serves every series, keyed by the total across them; ties keep input order. See `SORT`. TYPE: `SORT \| str \| None` DEFAULT: `None`
`sort_by`	The subtitle of the one series whose values key the sort instead of the total. A category that series lacks sorts last. TYPE: `str \| None` DEFAULT: `None`
`emphasis_rule`	A one-key dict that highlights the bars matching it and mutes the rest: `{"above": v}` or `{"below": v}` (strict), `{"between": (lo, hi)}` (inclusive), `{"top": n}` or `{"bottom": n}`. Reads each bar's own value; a record's own `emphasis` key wins over the rule. See `EmphasisRuleAttrs`. TYPE: `EmphasisRuleAttrs \| None` DEFAULT: `None`
`orientation`	The orientation of the bars ("vertical" or "horizontal"). See `ORIENTATION`. TYPE: `ORIENTATION \| str \| None` DEFAULT: `None`
`scalex`	The x-axis scale ("linear", "log", "symlog", "asinh"). Useful for horizontal bars. See `AXIS_SCALE`. TYPE: `AXIS_SCALE \| str \| None` DEFAULT: `None`
`scaley`	The y-axis scale ("linear", "log", "symlog", "asinh"). Useful for vertical bars. See `AXIS_SCALE`. TYPE: `AXIS_SCALE \| str \| None` DEFAULT: `None`
`subplots`	Whether to create separate subplots for each chart. TYPE: `bool \| None` DEFAULT: `None`
`max_cols`	Maximum number of columns in subplots (when subplots=True). TYPE: `int \| None` DEFAULT: `None`
`sharex`	Whether to share the x-axis in subplots. TYPE: `bool \| None` DEFAULT: `None`
`sharey`	Whether to share the y-axis in subplots. TYPE: `bool \| None` DEFAULT: `None`
`style`	Style configuration(s) for the bar(s). TYPE: `BarStyleAttrs \| list[BarStyleAttrs \| None] \| None` DEFAULT: `None`
`xticks`	Custom x-axis tick positions. TYPE: `list[int \| float] \| list[list[int \| float]] \| None` DEFAULT: `None`
`xticklabels`	Custom x-axis tick labels. TYPE: `list[str] \| list[list[str]] \| None` DEFAULT: `None`
`xtickrotate`	Rotation angle for x-axis tick labels. TYPE: `int \| list[int \| None] \| None` DEFAULT: `None`
`yticks`	Custom y-axis tick positions. TYPE: `list[int \| float] \| list[list[int \| float]] \| None` DEFAULT: `None`
`yticklabels`	Custom y-axis tick labels. TYPE: `list[str] \| list[list[str]] \| None` DEFAULT: `None`
`ytickrotate`	Rotation angle for y-axis tick labels. TYPE: `int \| list[int \| None] \| None` DEFAULT: `None`
`xticks_format`	The x-axis tick label format: a `DATE_FORMAT` member or `strftime` pattern on a datetime axis, else a `VALUE_FORMAT` member or `"{x:.1f}"` style string. TYPE: `VALUE_FORMAT \| DATE_FORMAT \| str \| None` DEFAULT: `None`
`yticks_format`	The y-axis tick label format, as `xticks_format`. TYPE: `VALUE_FORMAT \| DATE_FORMAT \| str \| None` DEFAULT: `None`
`vlines`	Vertical line(s) to plot. TYPE: `VLineSettingAttrs \| list[VLineSettingAttrs] \| list[VLineSettingAttrs \| list[VLineSettingAttrs] \| None] \| None` DEFAULT: `None`
`hlines`	Horizontal line(s) to plot. TYPE: `HLineSettingAttrs \| list[HLineSettingAttrs] \| list[HLineSettingAttrs \| list[HLineSettingAttrs] \| None] \| None` DEFAULT: `None`
`dlines`	Diagonal line(s) to plot, by slope and intercept. TYPE: `DLineSettingAttrs \| list[DLineSettingAttrs] \| list[DLineSettingAttrs \| list[DLineSettingAttrs] \| None] \| None` DEFAULT: `None`
`brackets`	Pairwise comparison bracket(s) to draw between two categories, with an optional text such as a p-value. TYPE: `BracketSettingAttrs \| list[BracketSettingAttrs] \| list[BracketSettingAttrs \| list[BracketSettingAttrs] \| None] \| None` DEFAULT: `None`
`vspans`	Vertical reference band(s) to shade, between two x positions. TYPE: `VSpanSettingAttrs \| list[VSpanSettingAttrs] \| list[VSpanSettingAttrs \| list[VSpanSettingAttrs] \| None] \| None` DEFAULT: `None`
`hspans`	Horizontal reference band(s) to shade, between two y positions. TYPE: `HSpanSettingAttrs \| list[HSpanSettingAttrs] \| list[HSpanSettingAttrs \| list[HSpanSettingAttrs] \| None] \| None` DEFAULT: `None`
`texts`	Text annotation(s) to draw. TYPE: `TextSettingAttrs \| list[TextSettingAttrs] \| list[TextSettingAttrs \| list[TextSettingAttrs] \| None] \| None` DEFAULT: `None`
`label`	The key name in data for label values (default: "label"). TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`y`	The key name in data for y-axis values (default: "y"). TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`yerr`	The key name in data for y-axis error values (default: "yerr"). TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`DatachartFigure`	The figure containing the bar chart.

Data

Each record in data is a BarRecordAttrs; the emphasis, label, y and yerr parameters rename its keys.

datachart.typings.BarRecordAttrs

Bases: TypedDict

One record of the bar chart.

ATTRIBUTE	DESCRIPTION
`label`	The label. TYPE: `str`
`y`	The y-axis value. TYPE: `int \| float`
`yerr`	The y-axis error value. TYPE: `int \| float \| None`
`emphasis`	The bar's own emphasis role ("background" or "highlight"); wins over the chart's `emphasis_rule`. TYPE: `EMPHASIS \| str \| None`

Style

style takes the keys of BarStyleAttrs. The chart also reads the shared groups it draws: value labels (ValueLabelStyleAttrs), reference lines (VLineStyleAttrs, HLineStyleAttrs and DLineStyleAttrs), pairwise brackets (BracketStyleAttrs), reference bands (VSpanStyleAttrs and HSpanStyleAttrs) and text annotations (TextStyleAttrs). Every key falls back to the theme, so the same keys set the default look through config.

datachart.typings.BarStyleAttrs

Bases: TypedDict

The typing for the bar chart style.

ATTRIBUTE	DESCRIPTION
`plot_bar_color`	The bar color. TYPE: `str \| None`
`plot_bar_alpha`	The alpha value of the bar. TYPE: `float \| None`
`plot_bar_width`	The width of the bar. TYPE: `int \| float \| None`
`plot_bar_zorder`	The zorder of the bar. TYPE: `int \| float \| None`
`plot_bar_hatch`	The hatch style of the bar. TYPE: `HATCH_STYLE \| str \| None`
`plot_bar_edge_width`	The edge width of the bar. TYPE: `int \| float \| None`
`plot_bar_edge_color`	The edge color of the bar. TYPE: `str \| None`
`plot_bar_error_color`	The color of the error line of the bar. TYPE: `str \| None`

Constants

The parameters that accept a constant, with the class in datachart.constants that lists its values.

Parameter	Constant
`xticks_format`	`VALUE_FORMAT`, `DATE_FORMAT`
`emphasis`	`EMPHASIS`
`figsize`	`FIG_SIZE`
`legend={"location": ..., "alignment": ...}`	`LEGEND_LOCATION`, `LEGEND_ALIGN`
`show_grid`	`SHOW_GRID`
`value_format`	`VALUE_FORMAT`
`aspect_ratio`	`ASPECT_RATIO`
`orientation`	`ORIENTATION`
`bar_mode`	`BAR_MODE`
`sort`	`SORT`
`scalex`	`AXIS_SCALE`
`scaley`	`AXIS_SCALE`
`yticks_format`	`VALUE_FORMAT`, `DATE_FORMAT`

Composition

Whether the figure composes with each composition function.

Function	Composes
`Grid`	yes
`Panel`	yes