nispace.plotting.nullplot

nispace.plotting.nullplot(fig, ax, data_long, categorical_var='variable', continuous_var='value', categorical_axis='x', category_order=None, color_which='viridis_r', quantiles_below_median=[0.01, 0.05, 0.25], bands=None, median_line=None, violins=None, labels=None, limits=None, legend=None)[source]

Draw a null distribution as shaded percentile bands with a median line (and optionally overlaid violins), per level of categorical_var.

Built on seaborn.objects. For each category, the empirical quantiles of continuous_var (from data_long, typically a long-format table of null permutation values) are computed at quantiles_below_median and their mirror image above the median, then drawn as nested translucent bands with the median as a solid line.

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.

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

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

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

  • category_order (list, optional) – Explicit category order.

  • color_which (str or None, default "viridis_r") – Palette used to color the nested bands (one color per quantile pair) and the median line; if the name can’t be resolved, treated as a single fixed color for all bands, and None uses plain grey.

  • quantiles_below_median (list of float, default [0.01, 0.05, 0.25]) – Quantiles below 0.5 defining the band edges; each is mirrored to 1 - q to form one band, giving nested bands from widest to narrowest.

  • bands (dict, optional) – Band styling/labeling (keys: "plot", "label", "label_prefix", "alpha", "edgewidth", "edgestyle", "edgealpha", "kwargs").

  • median_line (dict, optional) – Median line styling (keys: "plot", "label", "alpha", "kwargs").

  • violins (dict, optional) – Optional overlaid violin plot of the raw null distribution (keys: "plot", "label", "legend", "kwargs").

  • labels (dict, optional) – Forwarded to Plot.label(); the continuous axis defaults to continuous_var unless overridden.

  • limits (dict, optional) – Forwarded to Plot.limit().

  • legend (dict, optional) – Legend placement/formatting (keys: "plot", "loc", "bbox_to_anchor", "nice_labels", "kwargs").

Returns:

The finalized, already-rendered Plot object.

Return type:

seaborn.objects.Plot