PyramidChart

Two series as horizontal bars mirrored around a shared category axis. The Pyramid 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.PyramidChart

PyramidChart(
    data: list[list[BarDataPointAttrs]],
    *,
    title: str | None = None,
    xlabel: str | None = None,
    ylabel: str | None = None,
    subtitle: str | list[str | None] | None = None,
    figsize: FIG_SIZE | tuple[float, float] | None = None,
    xmin: int | float | None = None,
    xmax: 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,
    sort: SORT | str | None = None,
    sort_by: str | None = None,
    emphasis_rule: EmphasisRuleAttrs | None = None,
    style: (
        BarStyleAttrs | list[BarStyleAttrs | None] | None
    ) = None,
    xticks: list[int | float] | None = None,
    xticklabels: list[str] | None = None,
    xtickrotate: int | None = None,
    yticks: list[int | float] | None = None,
    yticklabels: list[str] | None = None,
    ytickrotate: int | None = None,
    xticks_format: (
        VALUE_FORMAT | DATE_FORMAT | str | None
    ) = None,
    yticks_format: (
        VALUE_FORMAT | DATE_FORMAT | str | None
    ) = None,
    vlines: (
        VLineSettingAttrs | list[VLineSettingAttrs] | None
    ) = None,
    hlines: (
        HLineSettingAttrs | list[HLineSettingAttrs] | None
    ) = None,
    vspans: (
        VSpanSettingAttrs | list[VSpanSettingAttrs] | None
    ) = None,
    hspans: (
        HSpanSettingAttrs | list[HSpanSettingAttrs] | None
    ) = None,
    texts: (
        TextSettingAttrs | list[TextSettingAttrs] | None
    ) = None,
    label: str | list[str | None] | None = None,
    y: str | list[str | None] | None = None,
    yerr: str | list[str | None] | None = None
) -> plt.Figure

Creates the pyramid chart.

A pyramid chart draws exactly two series as horizontal bars mirrored around a shared category axis, the first series to the left and the second to the right: the classic age-sex population pyramid. Use it to compare the distribution of two groups over the same ordered categories, such as age bands, where the symmetry (or lack of it) is the message.

Both series are supplied as positive values; value ticks and labels show absolute values. Unlike the other chart fronts, the axis parameters are spatial: xlabel, xticks, and xmax address the horizontal value axis, and ylabel the vertical category axis.

Examples:

>>> from datachart.charts import PyramidChart
>>> figure = PyramidChart(
...     data=[
...         [
...             {"label": "0-14", "y": 12},
...             {"label": "15-29", "y": 18},
...             {"label": "30-44", "y": 22},
...         ],
...         [
...             {"label": "0-14", "y": 11},
...             {"label": "15-29", "y": 19},
...             {"label": "30-44", "y": 24},
...         ],
...     ],
...     subtitle=["Group A", "Group B"],
...     title="Basic Pyramid Chart",
...     show_legend=True,
... )

PARAMETER	DESCRIPTION
`data`	Exactly two lists of data points — the first is the left side, the second the right. Values are positive for both sides; the chart mirrors the left side itself. TYPE: `list[list[BarDataPointAttrs]]`
`title`	The title of the chart. TYPE: `str \| None` DEFAULT: `None`
`xlabel`	The label of the horizontal value axis. TYPE: `str \| None` DEFAULT: `None`
`ylabel`	The label of the vertical category axis. TYPE: `str \| None` DEFAULT: `None`
`subtitle`	The names of the two sides. Used as legend labels. TYPE: `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`	Not supported; the value axis is always symmetric around zero. Raises when passed. TYPE: `int \| float \| None` DEFAULT: `None`
`xmax`	The maximum per-side value; the value axis spans (-xmax, xmax). 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 error bars on the 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`
`sort`	The order the categories are drawn in: None (input order), "ascending", or "descending" by value. One order serves both sides, keyed by the total of the two; ties keep input order. See `SORT`. TYPE: `SORT \| str \| None` DEFAULT: `None`
`sort_by`	The subtitle of the one side whose values key the sort instead of the total. A category that side 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 positive value; a record's own `emphasis` key wins over the rule. TYPE: `EmphasisRuleAttrs \| None` DEFAULT: `None`
`style`	Style configuration(s) for the bars, per side. TYPE: `BarStyleAttrs \| list[BarStyleAttrs \| None] \| None` DEFAULT: `None`
`xticks`	Custom value-axis tick positions, as positive values; each is mirrored to both halves. TYPE: `list[int \| float] \| None` DEFAULT: `None`
`xticklabels`	Custom value-axis tick labels (same length as `xticks`), applied to both mirrored halves. TYPE: `list[str] \| None` DEFAULT: `None`
`xtickrotate`	Rotation angle for value-axis tick labels. TYPE: `int \| None` DEFAULT: `None`
`yticks`	Custom category-axis tick positions. TYPE: `list[int \| float] \| None` DEFAULT: `None`
`yticklabels`	Custom category-axis tick labels. TYPE: `list[str] \| None` DEFAULT: `None`
`ytickrotate`	Rotation angle for category-axis tick labels. TYPE: `int \| 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] \| None` DEFAULT: `None`
`hlines`	Horizontal line(s) to plot. TYPE: `HLineSettingAttrs \| list[HLineSettingAttrs] \| None` DEFAULT: `None`
`vspans`	Vertical reference band(s) to shade, between two x positions. TYPE: `VSpanSettingAttrs \| list[VSpanSettingAttrs] \| None` DEFAULT: `None`
`hspans`	Horizontal reference band(s) to shade, between two y positions. TYPE: `HSpanSettingAttrs \| list[HSpanSettingAttrs] \| None` DEFAULT: `None`
`texts`	Text annotation(s) to draw. TYPE: `TextSettingAttrs \| list[TextSettingAttrs] \| 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 the bar values (default: "y"). TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`yerr`	The key name in data for the bar error values (default: "yerr"). TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`plt.Figure`	The figure containing the pyramid chart.

Data

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

Style

style takes the keys of BarStyleAttrs. The chart also reads the shared groups it draws: value labels (ValueLabelStyleAttrs), reference lines (VLineStyleAttrs and HLineStyleAttrs), 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.

Constants

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

Parameter	Constant
`figsize`	`FIG_SIZE`
`legend={"location": ..., "alignment": ...}`	`LEGEND_LOCATION`, `LEGEND_ALIGN`
`show_grid`	`SHOW_GRID`
`value_format`	`VALUE_FORMAT`
`sort`	`SORT`
`xticks_format`	`VALUE_FORMAT`, `DATE_FORMAT`
`yticks_format`	`VALUE_FORMAT`, `DATE_FORMAT`