Incrementality.contribution_over_spend#

Incrementality.contribution_over_spend(frequency, start_date=None, end_date=None, include_carryover=True, num_samples=None, random_state=None)[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.

Returns:
xr.DataArray

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

Examples

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