Histogram

The distribution of one numeric variable, binned. The Histogram 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.Histogram

Histogram(
    data: (
        list[HistDataPointAttrs]
        | list[list[HistDataPointAttrs]]
    ),
    *,
    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,
    emphasis_rule: EmphasisRuleAttrs | 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_density: bool | None = None,
    show_cumulative: 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
    ) = ORIENTATION.VERTICAL,
    bar_mode: BAR_MODE | str | None = None,
    num_bins: int | None = None,
    scalex: SCALE | str | None = None,
    scaley: SCALE | str | None = None,
    subplots: bool | None = None,
    max_cols: int | None = None,
    sharex: bool | None = None,
    sharey: bool | None = None,
    style: (
        HistStyleAttrs | list[HistStyleAttrs | 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,
    vlines: (
        VLineSettingAttrs
        | list[VLineSettingAttrs]
        | list[
            VLineSettingAttrs
            | list[VLineSettingAttrs]
            | None
        ]
        | None
    ) = None,
    hlines: (
        HLineSettingAttrs
        | list[HLineSettingAttrs]
        | list[
            HLineSettingAttrs
            | list[HLineSettingAttrs]
            | 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,
    x: str | list[str | None] | None = None
) -> plt.Figure

Creates the histogram.

A histogram bins a single numeric variable and draws the count (or density) per bin, revealing the shape of its distribution: center, spread, skew, modes, and outliers. Use it to inspect one variable or compare a few overlaid distributions. For side-by-side group summaries use BoxPlot or ViolinPlot.

Examples:

>>> from datachart.charts import Histogram
>>> figure = Histogram(
...     data=[
...         {"x": 1},
...         {"x": 2},
...         {"x": 3},
...         {"x": 4},
...         {"x": 5}
...     ],
...     title="Basic Histogram",
...     xlabel="X",
...     ylabel="Y"
... )

PARAMETER	DESCRIPTION
data	The data points for the histogram(s). Can be a single list of data points for one chart, or a list of lists for multiple charts/subplots. TYPE: list[HistDataPointAttrs] | list[list[HistDataPointAttrs]]
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 it and brings it to the front, None leaves it unchanged. When any chart carries a role, the histograms draw individually overlaid instead of stacked. TYPE: EMPHASIS | str | list[str | None] | None DEFAULT: None
emphasis_rule	A rule that highlights the histograms matching it and mutes the rest: {"above": v} or {"below": v} (strict), {"between": (lo, hi)} (inclusive), {"top": n} or {"bottom": n}, read against a summary of each histogram's own x values, chosen by by: "mean" (default), "median", "min", "max", or "sum". An explicit emphasis role wins, and a count ranks across every histogram. See EmphasisRuleAttrs. TYPE: EmphasisRuleAttrs | None DEFAULT: None
figsize	The size of the figure. 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 (e.g., "both", "x", "y"); False draws none. TYPE: SHOW_GRID | str | bool | None DEFAULT: None
show_density	Whether to plot the density histogram. TYPE: bool | None DEFAULT: None
show_cumulative	Whether to plot the cumulative histogram. TYPE: bool | None DEFAULT: None
show_values	Whether to print each bin's height at its top; empty bins stay bare. TYPE: bool | None DEFAULT: None
value_format	Format string for the 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
orientation	The orientation of the histogram (vertical or horizontal). TYPE: ORIENTATION | str | None DEFAULT: ORIENTATION.VERTICAL
bar_mode	How multiple histogram series share the axis: "stack" (stacked on shared bins, the default) or "overlay" (each series drawn individually over the others). "group" has no histogram meaning and behaves like "overlay". See BAR_MODE. TYPE: BAR_MODE | str | None DEFAULT: None
num_bins	The number of bins to split the data into. TYPE: int | None DEFAULT: None
scalex	The x-axis scale (e.g., "log", "linear"). Useful for log-distributed data. TYPE: SCALE | str | None DEFAULT: None
scaley	The y-axis scale (e.g., "log", "linear"). TYPE: 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 histogram(s). TYPE: HistStyleAttrs | list[HistStyleAttrs | 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
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
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
x	The key name in data for x-axis values (default: "x"). TYPE: str | list[str | None] | None DEFAULT: None

RETURNS	DESCRIPTION
plt.Figure	The figure containing the histogram.

Data

Each record in data is a HistDataPointAttrs; the x parameter renames its keys.

datachart.typings.HistDataPointAttrs

Bases: TypedDict

The data point attributes for the histogram chart.

ATTRIBUTE	DESCRIPTION
x	The x-axis value. TYPE: int | float

Style

style takes the keys of HistStyleAttrs. 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.

datachart.typings.HistStyleAttrs

Bases: TypedDict

The typing for the histogram chart style.

ATTRIBUTE	DESCRIPTION
plot_hist_color	The color of the histogram. TYPE: str | None
plot_hist_alpha	The alpha value of the histogram. TYPE: float | None
plot_hist_zorder	The zorder of the histogram. TYPE: int | float | None
plot_hist_fill	The fill of the histogram. TYPE: str | None
plot_hist_hatch	The hatch style in the histogram. TYPE: HATCH_STYLE | str | None
plot_hist_type	The type of the histogram. TYPE: HISTOGRAM_TYPE | str | None
plot_hist_align	The alignment of the histogram. TYPE: str | None
plot_hist_edge_width	The edge width of the histogram. TYPE: int | float | None
plot_hist_edge_color	The edge color of the histogram. TYPE: str | None
plot_xticks_label_rotate	The label rotation of the xticks in the histogram chart. TYPE: int | float | None
plot_yticks_label_rotate	The label rotation of the yticks in the histogram chart. TYPE: int | float | None

Constants

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

Parameter	Constant
style={"plot_hist_type": ...}	HISTOGRAM_TYPE
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
scalex	SCALE
scaley	SCALE