Incrementality.contribution_over_spend#

Incrementality.contribution_over_spend(frequency, start_date=None, end_date=None, include_carryover=True, num_samples=None, random_state=None, central_tendency='median')[source]#

Compute incremental contribution per unit of spend.

Wraps compute_incremental_contribution() (with counterfactual_spend_factor=0) and divides by total spend. The interpretation depends on the model’s target variable – e.g. ROAS when the target is revenue, customers per dollar when the target is acquisitions.

Parameters:

frequency{“original”, “weekly”, “monthly”, “quarterly”, “yearly”, “all_time”}: Time aggregation frequency.
start_date, end_datestr or pd.Timestamp, optional: Date range for computation.
include_carryoverbool, default=True: Include adstock carryover effects.
num_samplesint or None, optional: Number of posterior samples to use. If None, all samples are used.
random_stateRandomState or Generator or None, optional: Random state for reproducible subsampling.
central_tendency{“median”, “mean”}, default=”median”: Central tendency of the counterfactual predictions. Only meaningful for non-linear links; see compute_incremental_contribution().

Returns:

xr.DataArray: Contribution per unit spend with dimensions (chain, draw, date, channel, *custom_dims). Zero spend results in NaN for that channel/period.

Raises:

ValueError: If frequency is invalid, the requested dates fall outside the fitted data range, or central_tendency is not "median" or "mean"; or, at compute time, if a mu_effect’s declared reach is narrower than what was measured, or a post-fit mutation of an auxiliary input (e.g. MMM.sample_posterior_predictive(..., clone_model=False)) is detected; or if the model produces non-finite predictions. See spend_reach for the full story on each.
NotImplementedError: If the model’s link function has no IncrementalReducer, if a channel-dependent mu_effect has not opted in via incrementality_spec(), or if the accounted nodes do not reproduce the full move in the linear predictor.

Warns:

UserWarning: If a spend counterfactual’s reach could not be measured (no interior date could be probed), the evaluation falls back to the full date axis, which is correct but slower than a window, and the completeness check above is skipped for lack of anything to compare. See measure().

Examples

>>> roas = mmm.incrementality.contribution_over_spend(
...     frequency="quarterly",
...     start_date="2024-01-01",
...     end_date="2024-12-31",
... )