MMMSummaryFactory.saturation_curves#

MMMSummaryFactory.saturation_curves(hdi_probs=None, output_format=None, data=None, max_value=1.0, num_points=100, num_samples=None, random_state=None, original_scale=True)[source]#

Create saturation curves summary DataFrame.

Samples saturation response curves from the posterior distribution using the model’s sample_saturation_curve() method, then computes summary statistics (mean, median, HDI).

Supports multi-dimensional data with custom_dims (e.g., country, region). When custom dimensions are present, curves are generated for each combination of channel and custom dimension values.

Requires model to be provided (has saturation transformation).

Parameters:
hdi_probssequence of float, optional

HDI probability levels (default: uses factory default)

output_format{“pandas”, “polars”}, optional

Output DataFrame format (default: uses factory default)

dataMMMIDataWrapper or None, optional

Optional data wrapper to use for sampling curves. If None (default), uses self.data. This allows sampling curves from a different InferenceData, such as from a subset of samples or another model.

max_valuefloat, default 1.0

Maximum value for the curve x-axis, in scaled space (consistent with model internals). This represents the maximum spend level in scaled units. To convert from original scale, divide by channel_scale: max_scaled = original_max / mmm.data.get_channel_scale().mean()

num_pointsint, default 100

Number of points between 0 and max_value to evaluate the curve at. Higher values give smoother curves but take longer.

num_samplesint or None, optional

Number of posterior samples to use for generating curves. By default None (use all posterior samples for accurate HDI). Using fewer samples speeds up computation and reduces memory usage while still capturing posterior uncertainty.

random_stateint, np.random.Generator, or None, optional

Random state for reproducible subsampling. Can be an integer seed, a numpy Generator instance, or None for non-reproducible sampling. Only used when num_samples is not None and less than total available samples.

original_scalebool, default True

Whether to return curve y-values in original scale. If True (default), y-axis values (contribution) are multiplied by target_scale to convert from scaled to original units. If False, values remain in scaled space as used internally by the model.

Returns:
pd.DataFrame or pl.DataFrame

Summary DataFrame with columns:

  • x: Input value (spend level, in scaled space)

  • channel: Channel name

  • <custom_dims>: One column for each custom dimension (e.g., country)

  • mean: Mean saturation response

  • median: Median saturation response

  • abs_error_{prob}_lower: HDI lower bound for each prob

  • abs_error_{prob}_upper: HDI upper bound for each prob

See also

MMM.sample_saturation_curve

Underlying method for sampling curves

adstock_curves

For adstock curves

Examples

>>> df = mmm.summary.saturation_curves()
>>> df = mmm.summary.saturation_curves(num_points=200)
>>> df = mmm.summary.saturation_curves(hdi_probs=[0.80, 0.94])
>>> df = mmm.summary.saturation_curves(max_value=2.0, num_samples=500)