MMMPlotSuite.saturation_curves

MMMPlotSuite.saturation_curves(curve, original_scale=False, constant_data=None, posterior_data=None, n_samples=10, hdi_probs=None, random_seed=None, dims=None, colors=None, plot_collection=None, backend=None)

Overlay saturation scatter plots with posterior predictive curves and HDI bands.

Builds on saturation_scatterplot() by adding: - Sample curves from the posterior distribution - HDI bands showing uncertainty - Smooth saturation curves over the scatter plot

Parameters:

curvexr.DataArray

Posterior predictive saturation curves with required dimensions: - “chain”, “draw”: MCMC samples - “x”: Input values for curve evaluation - “channel”: Channel names

Generate using: mmm.saturation.sample_curve(...)

original_scalebool, default False

Plot in original scale (True) or scaled space (False). If True, requires channel_contribution_original_scale in posterior.

constant_dataxr.Dataset, optional

Dataset containing constant_data group. If None, uses self.idata.constant_data. This parameter allows testing with mock data and plotting alternative scenarios.

posterior_dataxr.Dataset, optional

Dataset containing posterior group. If None, uses self.idata.posterior. This parameter allows testing with mock posterior samples and comparing model fits.

n_samplesint, default 10

Number of sample curves to draw per subplot. Set to 0 to show only HDI bands without individual samples.

hdi_probsfloat or list of float, optional

HDI probability levels for credible intervals. Examples: 0.94 (single band), [0.5, 0.94] (multiple bands). If None, no HDI bands are drawn.

random_seednp.random.Generator, optional

Random number generator for reproducible curve sampling. If None, uses np.random.default_rng().

dimsdict[str, str | int | list], optional

Dimension filters to apply. Examples: - {“geo”: “US”} - {“geo”: [“US”, “UK”]}

If provided, only the selected slice(s) will be plotted.

colorslist of str, optional

List of colors for each channel, in the same order as the channel dimension. If None, uses the default color cycle. Examples: [“#1f77b4”, “#ff7f0e”, “#2ca02c”]

plot_collectionPlotCollection, optional

Existing PlotCollection to add plots to. If None, creates a new one. This allows building composite visualizations by calling multiple plot methods on the same PlotCollection.

backendstr, optional

Plotting backend to use. Options: “matplotlib”, “plotly”, “bokeh”. If None, uses global config via mmm_plot_config[“plot.backend”]. Default is “matplotlib”.

Returns:

PlotCollection

arviz_plots PlotCollection object containing the plot.

Use .show() to display or .save("filename") to save.

Raises:

ValueError

If curve is missing required dimensions (“x” or “channel”).

ValueError

If original_scale=True but channel_contribution_original_scale not in posterior.

See also

saturation_scatterplot

Base scatter plot without curves

LegacyMMMPlotSuite.saturation_curves

Legacy matplotlib-only implementation

Notes

Breaking changes from legacy implementation:

• Returns PlotCollection instead of (Figure, Axes)

• Lost subplot_kwargs, rc_params parameters

• Different HDI calculation (uses arviz_plots instead of custom)

Examples

Generate and plot saturation curves:

# Generate curves using saturation transformation
curve = mmm.saturation.sample_curve(
    idata=mmm.idata.posterior[["saturation_beta", "saturation_lam"]],
    max_value=2.0,
)
pc = mmm.plot.saturation_curves(curve)
pc.show()

Add HDI bands:

pc = mmm.plot.saturation_curves(curve, hdi_probs=[0.5, 0.94])
pc.show()

Original scale with custom seed:

import numpy as np

rng = np.random.default_rng(42)
mmm.add_original_scale_contribution_variable(var=["channel_contribution"])
pc = mmm.plot.saturation_curves(
    curve, original_scale=True, n_samples=15, random_seed=rng
)
pc.show()

Filter by dimension:

pc = mmm.plot.saturation_curves(curve, dims={"geo": "US"})
pc.show()