nispace.plotting.catplot

nispace.plotting.catplot(fig, ax, data_long, categorical_var='variable', continuous_var='value', group_var=None, categorical_axis='x', sort_categories=False, category_order=None, color_how='continuous', color_which='auto', color_center=None, labels=None, limits=None, bars=None, violins=None, scatters=None, dots=None, errorbars=None, hline=None, vline=None, hlines=None, vlines=None, legend=None)[source]

Draw a categorical plot combining any mix of bars, violins, scatter points, summary dots, and errorbars, built on top of seaborn.objects.

Values along continuous_var are shown per level of categorical_var (optionally further split by group_var), with automatic coloring by either the continuous variable (diverging colormap if data cross zero, sequential otherwise) or the categorical variable.

Parameters:

  • fig (matplotlib.figure.Figure) – Parent figure, needed to relocate the legend onto ax after plotting.

  • ax (matplotlib.axes.Axes) – Axes to draw into.

  • data_long (pandas.DataFrame) – Long-format data with at least the columns named by categorical_var and continuous_var (and group_var if given).

  • categorical_var (str, default "variable", "value") – Column names for the categorical grouping variable and the plotted continuous values.

  • continuous_var (str, default "variable", "value") – Column names for the categorical grouping variable and the plotted continuous values.

  • group_var (str, optional) – Column name for an additional grouping/dodge variable (e.g. for side-by-side sub-categories within each categorical_var level).

  • categorical_axis ({"x", "y"}, default "x") – Which plot axis carries the categorical variable; the other axis carries continuous_var.

  • sort_categories (False or {"mean", "median"}, default False) – If truthy, sort categories by their mean/median continuous_var value (descending). Ignored if category_order is given.

  • category_order (list, optional) – Explicit category order; takes precedence over sort_categories.

  • color_how ({"continuous", "categorical", False}, default "continuous") – Whether to color elements by continuous_var (per-point color scale), by categorical_var (discrete “Spectral” palette), or not at all.

  • color_which ("auto" or str, default "auto") – Colormap/palette name. For color_how=”continuous”, “auto” resolves to “icefire” (diverging) if the data cross zero, else “inferno”.

  • color_center (bool, optional) – For continuous coloring, force the color scale to be centered at 0 (symmetric limits). Auto-enabled when color_which=”auto” picks the diverging colormap.

  • labels (dict, optional) – Forwarded to Plot.label() (e.g. {"x": "...", "y": "...", "color": "..."}).

  • limits (dict, optional) – Forwarded to Plot.limit(); a “color” key sets explicit color-scale limits and is popped out before the rest is passed through.

  • bars (dict, optional) – Per-layer options, each merged over its own defaults via defaults | user_dict (so only overridden keys need to be passed). Common keys: "plot" (bool, whether to draw the layer), "label" (bool or str, legend label; True auto-derives one from the layer’s aggregation method), "kwargs" (dict forwarded to the underlying matplotlib/seaborn artist). bars/dots/errorbars also take "agg_method" (e.g. “mean”, “ci”); layers with a group_var split also take "dodge_width".

  • violins (dict, optional) – Per-layer options, each merged over its own defaults via defaults | user_dict (so only overridden keys need to be passed). Common keys: "plot" (bool, whether to draw the layer), "label" (bool or str, legend label; True auto-derives one from the layer’s aggregation method), "kwargs" (dict forwarded to the underlying matplotlib/seaborn artist). bars/dots/errorbars also take "agg_method" (e.g. “mean”, “ci”); layers with a group_var split also take "dodge_width".

  • scatters (dict, optional) – Per-layer options, each merged over its own defaults via defaults | user_dict (so only overridden keys need to be passed). Common keys: "plot" (bool, whether to draw the layer), "label" (bool or str, legend label; True auto-derives one from the layer’s aggregation method), "kwargs" (dict forwarded to the underlying matplotlib/seaborn artist). bars/dots/errorbars also take "agg_method" (e.g. “mean”, “ci”); layers with a group_var split also take "dodge_width".

  • dots (dict, optional) – Per-layer options, each merged over its own defaults via defaults | user_dict (so only overridden keys need to be passed). Common keys: "plot" (bool, whether to draw the layer), "label" (bool or str, legend label; True auto-derives one from the layer’s aggregation method), "kwargs" (dict forwarded to the underlying matplotlib/seaborn artist). bars/dots/errorbars also take "agg_method" (e.g. “mean”, “ci”); layers with a group_var split also take "dodge_width".

  • errorbars (dict, optional) – Per-layer options, each merged over its own defaults via defaults | user_dict (so only overridden keys need to be passed). Common keys: "plot" (bool, whether to draw the layer), "label" (bool or str, legend label; True auto-derives one from the layer’s aggregation method), "kwargs" (dict forwarded to the underlying matplotlib/seaborn artist). bars/dots/errorbars also take "agg_method" (e.g. “mean”, “ci”); layers with a group_var split also take "dodge_width".

  • hline (dict, optional) – Single reference line at one or more fixed positions (keys: "plot", "y"/"x", "color", "linewidth", "linestyle", "zorder", "kwargs").

  • vline (dict, optional) – Single reference line at one or more fixed positions (keys: "plot", "y"/"x", "color", "linewidth", "linestyle", "zorder", "kwargs").

  • hlines (list of dict, optional) – Multiple independently styled reference lines; each dict supports "y"/"x", "color", "linewidth", "linestyle", "zorder", and "label" (added to the axes legend if given).

  • vlines (list of dict, optional) – Multiple independently styled reference lines; each dict supports "y"/"x", "color", "linewidth", "linestyle", "zorder", and "label" (added to the axes legend if given).

  • legend (dict, optional) – Legend placement/formatting (keys: "plot", "loc", "bbox_to_anchor", "nice_labels" (apply nice_stats_labels() to auto-derived labels), "kwargs").

Returns:

The finalized, already-rendered Plot object.

Return type:

seaborn.objects.Plot