TransformationPlots.saturation_curves#

TransformationPlots.saturation_curves(curves, original_scale=True, n_samples=10, hdi_prob=0.94, random_seed=None, apply_cost_per_unit=True, idata=None, dims=None, figsize=None, backend=None, return_as_pc=False, scatter_kwargs=None, hdi_kwargs=None, mean_curve_kwargs=None, sample_curves_kwargs=None, **pc_kwargs)[source]#

Overlay saturation curves with posterior sample lines and HDI bands.

Renders a scatter plot of observed data, posterior sample curves, and a credible interval band for each channel panel.

The curves y-values are plotted as-is — this function does not rescale them. Pass curves whose scale matches the original_scale flag so they align with the scatter plot:

  • original_scale=True (default) — pass curves generated with mmm.sample_saturation_curve(original_scale=True) so that y-values are already in original (un-scaled) units.

  • original_scale=False — pass curves from mmm.saturation.sample_curve(...) or mmm.sample_saturation_curve(original_scale=False) (model- internal scaled space).

A heuristic warning is emitted when the curve magnitude appears inconsistent with the requested scale.

Parameters:
curvesxr.DataArray

Posterior-predictive saturation curves. Typical sources:

  • mmm.sample_saturation_curve(original_scale=True) — curves already in original scale (use with original_scale=True).

  • mmm.sample_saturation_curve(original_scale=False) or mmm.saturation.sample_curve(params) — curves in scaled space (use with original_scale=False).

Expected dims: (chain, draw, channel, [custom_dims], x).

original_scalebool, default True

Controls the scatter-plot scale (contributions). The caller must ensure curves are in the matching scale.

n_samplesint, default 10

Number of posterior sample curves to draw per panel. Set to 0 to disable sample curves.

hdi_probfloat or None, default 0.94

Credible interval probability for the HDI band. Set to None to disable HDI band rendering.

random_seednp.random.Generator, optional

RNG for reproducible sample selection.

apply_cost_per_unitbool, default True

If True and cost-per-unit data is available, the x-axis shows spend.

idataaz.InferenceData, optional

Override instance data.

dimsdict, optional

Dimension filters.

figsizetuple[float, float], optional

Convenience shorthand for figure size.

backendstr, optional

Rendering backend.

return_as_pcbool, default False

Return PlotCollection instead of matplotlib tuple.

scatter_kwargsdict, optional

Extra keyword arguments forwarded to the scatter visual (azp.visuals.scatter_xy).

hdi_kwargsdict, optional

Extra keyword arguments forwarded to the HDI band visual (azp.visuals.fill_between_y).

mean_curve_kwargsdict, optional

Extra keyword arguments forwarded to the mean curve visual (azp.visuals.line_xy).

sample_curves_kwargsdict, optional

Extra keyword arguments forwarded to each sample curve visual (azp.visuals.line_xy).

**pc_kwargs

Forwarded to PlotCollection.wrap().

Returns:
tuple[Figure, NDArray[Axes]] or PlotCollection