RaincloudPlot

A half violin, the raw points, and a box per group. The Raincloud 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.RaincloudPlot

RaincloudPlot(
    data: (
        list[RaincloudDataPointAttrs]
        | list[list[RaincloudDataPointAttrs]]
    ),
    *,
    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_outliers: bool | None = True,
    show_values: bool | None = None,
    value_format: VALUE_FORMAT | str | None = None,
    mode: SWARM_MODE | str = SWARM_MODE.SWARM,
    jitter: float = 0.4,
    bandwidth: BANDWIDTH | str | float | None = None,
    aspect_ratio: ASPECT_RATIO | str | None = None,
    orientation: (
        ORIENTATION | str | None
    ) = ORIENTATION.VERTICAL,
    scaley: SCALE | str | None = None,
    subplots: bool | None = None,
    max_cols: int | None = None,
    sharex: bool | None = None,
    sharey: bool | None = None,
    style: (
        RaincloudStyleAttrs
        | list[RaincloudStyleAttrs | 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
) -> plt.Figure

Creates the raincloud plot.

A raincloud plot draws each group as a cloud (a half violin of its density), its rain (the raw observations), and a box (the quartile summary) side by side at one category position, all in the group's palette color. Use it when you want the shape, the summary statistics, and the individual observations in a single view, for example when reporting experimental results per condition. Vertical rainclouds keep the cloud on the right; horizontal ones keep it above.

Examples:

>>> from datachart.charts import RaincloudPlot
>>> figure = RaincloudPlot(
...     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 Raincloud Plot",
...     xlabel="Group",
...     ylabel="Value"
... )

PARAMETER	DESCRIPTION
`data`	The data points for the raincloud plot(s). Can be a single list of data points for one chart, or a list of lists for multiple charts (drawn as subplots). Each data point should have a `label` (category) and `value` (numeric). TYPE: `list[RaincloudDataPointAttrs] \| list[list[RaincloudDataPointAttrs]]`
`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. TYPE: `str \| list[str \| None] \| None` DEFAULT: `None`
`emphasis`	The emphasis role(s), aligned with the group labels of one call (a single value applies to every group): "background" mutes a group's cloud, rain, and box, "highlight" bolds their edges, None leaves them 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; one entry per group. 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_outliers`	Whether the box shows outliers. TYPE: `bool \| None` DEFAULT: `True`
`show_values`	Whether to print each group's median beside its box, and its minimum and maximum beside the rain points holding them. 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`
`mode`	How the rain spreads across its width. See `SWARM_MODE`: "swarm" packs the points so none overlap; "strip" jitters them uniformly. TYPE: `SWARM_MODE \| str` DEFAULT: `SWARM_MODE.SWARM`
`jitter`	The strip jitter width, as a fraction of the category width like `SwarmPlot`, scaled down to the rain's narrower cell. Only used with `mode="strip"`. TYPE: `float` DEFAULT: `0.4`
`bandwidth`	The cloud's KDE bandwidth: None or "scott" (Scott's rule), "silverman" (Silverman's rule), or a scalar factor. See `BANDWIDTH`. TYPE: `BANDWIDTH \| str \| float \| 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 rainclouds (vertical or horizontal). TYPE: `ORIENTATION \| str \| None` DEFAULT: `ORIENTATION.VERTICAL`
`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); the violin keys style the cloud, the swarm keys the rain, and the box keys the box. TYPE: `RaincloudStyleAttrs \| list[RaincloudStyleAttrs \| 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`

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

Data

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

datachart.typings.RaincloudDataPointAttrs

Bases: TypedDict

The data point attributes for the raincloud plot.

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

Style

style takes the keys of RaincloudStyleAttrs. RaincloudStyleAttrs is the union of ViolinStyleAttrs, SwarmStyleAttrs and BoxStyleAttrs, one per part of the chart. 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.RaincloudStyleAttrs

Bases: ViolinStyleAttrs, SwarmStyleAttrs, BoxStyleAttrs

The typing for the raincloud plot style.

The union of the violin (cloud), swarm (rain), and box style keys; each key styles its own part of the raincloud.

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`
`mode`	`SWARM_MODE`
`bandwidth`	`BANDWIDTH`
`aspect_ratio`	`ASPECT_RATIO`
`orientation`	`ORIENTATION`
`scaley`	`SCALE`
`xticks_format`	`VALUE_FORMAT`, `DATE_FORMAT`
`yticks_format`	`VALUE_FORMAT`, `DATE_FORMAT`