Incrementality.marginal_contribution_over_spend#

Incrementality.marginal_contribution_over_spend(frequency, period_start=None, period_end=None, include_carryover=True, num_samples=None, random_state=None, spend_increase_pct=0.01)[source]#

Compute marginal contribution per additional unit of spend.

Unlike contribution_over_spend() which measures total efficiency (zero-out counterfactual), this method measures the marginal efficiency at the current spend level – i.e. the slope of the response curve at the current operating point. This captures diminishing returns: a heavily invested channel may have a low marginal efficiency even if its total efficiency is high. See the module docstring for the marginal incrementality formula.

Parameters:

frequency{“original”, “weekly”, “monthly”, “quarterly”, “yearly”, “all_time”}: Time aggregation frequency.
period_start, period_endstr 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.
spend_increase_pctfloat, default=0.01: Fractional spend increase for the perturbation (default 1 %). Must be > 0. Smaller values give a closer approximation to the true derivative but may suffer from numerical noise.

Returns:

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

Raises:

ValueError: If spend_increase_pct <= 0.

Examples

>>> mroas = mmm.incrementality.marginal_contribution_over_spend(
...     frequency="quarterly",
...     period_start="2024-01-01",
...     period_end="2024-12-31",
... )