MMM.sample_adstock_curve#

MMM.sample_adstock_curve(amount=FieldInfo(annotation=NoneType, required=False, default=1.0, description='Amount to apply the adstock transformation to.', metadata=[Gt(gt=0)]), num_samples=FieldInfo(annotation=NoneType, required=False, default=500, description='Number of posterior samples to use.', metadata=[Gt(gt=0)]), random_state=None, idata=FieldInfo(annotation=NoneType, required=False, default=None, description='Optional InferenceData to sample from.'))[source]#

Sample adstock curves from posterior parameters.

This method samples the adstock transformation curves using posterior parameters from the fitted model. It allows visualization of the carryover effect of media exposure over time.

Parameters:
amountfloat, optional

Amount to apply the adstock transformation to. By default 1.0. This represents an impulse of spend at time 0, and the curve shows how this effect decays over subsequent time periods.

num_samplesint or None, optional

Number of posterior samples to use for generating curves. By default 500. Samples are drawn randomly from the full posterior (across all chains and draws). Using fewer samples speeds up computation and reduces memory usage while still capturing posterior uncertainty. If None, all posterior samples are used without subsampling.

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.

idataaz.InferenceData or None, optional

Optional InferenceData to sample from. If None (default), uses self.idata. This allows sampling curves from different posterior distributions, such as from a different model or a subset of samples.

Returns:
xr.DataArray

Sampled adstock curves with dimensions: - Simple model: (time since exposure, channel, sample) - Panel model: (time since exposure, *custom_dims, channel, sample)

The “sample” dimension indexes the posterior samples used. The “time since exposure” coordinate represents time periods from 0 to l_max (the maximum lag for the adstock transformation).

Raises:
ValueError

If called before model is fitted (idata doesn’t exist) and no idata provided

ValueError

If idata exists but no posterior (model not fitted)

Notes

  • The adstock curve shows the carryover effect of a single impulse of media exposure over time, unlike saturation curves which show diminishing returns.

  • For panel models, curves are generated for each combination of custom dimensions (e.g., each country) and channel.

  • The returned array includes a “sample” dimension for uncertainty quantification. Use .mean(dim='sample') for point estimates and .quantile() for credible intervals.

  • Posterior samples are drawn randomly without replacement when num_samples is less than the total available samples.

Examples

Sample curves with default parameters:

>>> curves = mmm.sample_adstock_curve()
>>> curves.dims
('sample', 'time since exposure', 'channel')

Sample curves using all posterior samples:

>>> curves_all = mmm.sample_adstock_curve(num_samples=None)

Sample curves with custom amount and reproducible sampling:

>>> curves = mmm.sample_adstock_curve(
...     amount=100.0, num_samples=1000, random_state=42
... )

Sample curves from a different InferenceData:

>>> external_idata = az.from_netcdf("other_model.nc")
>>> curves = mmm.sample_adstock_curve(idata=external_idata)