ViolinPlot

The density profile of each group's distribution. The Violin Plot 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.ViolinPlot

ViolinPlot(
    data: (
        list[ViolinDataPointAttrs]
        | list[list[ViolinDataPointAttrs]]
    ),
    *,
    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_values: bool | None = None,
    value_format: VALUE_FORMAT | str | None = None,
    aspect_ratio: ASPECT_RATIO | str | None = None,
    orientation: (
        ORIENTATION | str | None
    ) = ORIENTATION.VERTICAL,
    sort: SORT | 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: (
        ViolinStyleAttrs
        | list[ViolinStyleAttrs | 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,
    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,
    value: str | list[str | None] | None = None,
    inner: VIOLIN_INNER | str | None = VIOLIN_INNER.BOX,
    bandwidth: BANDWIDTH | str | float | None = None,
    split: str | None = None
) -> plt.Figure

Creates the violin plot.

A violin plot draws the kernel density estimate of each group's numeric distribution as a mirrored profile, showing shape (multimodality, skew, tails) that a box plot hides. Use it to compare distributions across groups when shape matters and each group has enough samples for a density estimate.

Examples:

>>> from datachart.charts import ViolinPlot
>>> figure = ViolinPlot(
...     data=[
...         {"label": "Group A", "value": 10},
...         {"label": "Group A", "value": 15},
...         {"label": "Group A", "value": 12},
...         {"label": "Group B", "value": 20},
...         {"label": "Group B", "value": 25},
...         {"label": "Group B", "value": 22},
...     ],
...     title="Basic Violin Plot",
...     xlabel="Group",
...     ylabel="Value"
... )

PARAMETER	DESCRIPTION
`data`	The data points for the violin plot(s). Can be a single list of data points for one chart, or a list of lists for subplots (requires `subplots=True`). Each data point should have a `label` (category) and `value` (numeric). TYPE: `list[ViolinDataPointAttrs] \| list[list[ViolinDataPointAttrs]]`
`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: the subplot title and the legend label. TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`emphasis`	The emphasis role(s), aligned with the violin labels of one call in input order, whatever the `sort` (a single value applies to every violin): "background" mutes a violin body and its inner marks, "highlight" bolds the body edge, None leaves it unchanged. TYPE: `EMPHASIS \| str \| list[str \| None] \| None` DEFAULT: `None`
`emphasis_rule`	A rule that highlights the groups 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 group's values, chosen by `by`: `"median"` (default), `"mean"`, `"min"`, `"max"`, or `"sum"`. An explicit `emphasis` role wins, and a count ranks across every group of every chart. 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_values`	Whether to print each group's median beside its median line. 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 violins (vertical or horizontal). TYPE: `ORIENTATION \| str \| None` DEFAULT: `ORIENTATION.VERTICAL`
`sort`	The order the groups are drawn in: None (input order), "ascending", or "descending" by each group's median; ties keep input order. One call draws one violin dataset per axes, so there is no second series to key on and no `sort_by`. See `SORT`. TYPE: `SORT \| 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; required for a list of datasets. 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 violin(s). TYPE: `ViolinStyleAttrs \| list[ViolinStyleAttrs \| 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`
`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/category values (default: "label"). TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`value`	The key name in data for numeric values (default: "value"). TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`inner`	The marks drawn inside each body: "box" (quartile bar, 1.5·IQR whisker, median dot), "quartiles" (dashed median, dotted Q1/Q3), "median" (one line), or None (body only). See `VIOLIN_INNER`. TYPE: `VIOLIN_INNER \| str \| None` DEFAULT: `VIOLIN_INNER.BOX`
`bandwidth`	The KDE bandwidth: None or "scott" (Scott's rule), "silverman", or a scalar factor. See `BANDWIDTH`. TYPE: `BANDWIDTH \| str \| float \| None` DEFAULT: `None`
`split`	The key name in data whose exactly two distinct values become the left and right halves of each violin, colored from the multiple palette and listed in the legend. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`plt.Figure`	The figure containing the violin plot.

Data

Each record in data is a ViolinDataPointAttrs; the label and value parameters rename its keys.

datachart.typings.ViolinDataPointAttrs

Bases: TypedDict

The data point attributes for the violin plot.

ATTRIBUTE	DESCRIPTION
`label`	The category label. TYPE: `str`
`value`	The numeric value. TYPE: `int \| float`

Style

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

Bases: TypedDict

The typing for the violin plot style.

ATTRIBUTE	DESCRIPTION
`plot_violin_color`	The violin fill color. TYPE: `str \| None`
`plot_violin_alpha`	The alpha value of the violin body. TYPE: `float \| None`
`plot_violin_linewidth`	The line width of the body edge. TYPE: `int \| float \| None`
`plot_violin_edgecolor`	The edge color of the body; defaults to the fill. TYPE: `str \| None`
`plot_violin_width`	The maximum width of the body. TYPE: `int \| float \| None`
`plot_violin_inner_color`	The color of the inner marks; defaults to the font color. TYPE: `str \| None`
`plot_violin_inner_linewidth`	The line width of the inner marks. TYPE: `int \| float \| None`
`plot_violin_median_color`	The color of the median dot. TYPE: `str \| None`
`plot_violin_median_size`	The size of the median dot. TYPE: `int \| float \| None`
`plot_violin_hatch`	The hatch pattern of the body. TYPE: `HATCH_STYLE \| str \| None`

Constants

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

Parameter	Constant
`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`
`scaley`	`SCALE`
`xticks_format`	`VALUE_FORMAT`, `DATE_FORMAT`
`yticks_format`	`VALUE_FORMAT`, `DATE_FORMAT`
`inner`	`VIOLIN_INNER`
`bandwidth`	`BANDWIDTH`