Model-implied incrementality

PanelMMM.compute_incrementality(...) evaluates a fitted historical spend intervention from paired retained posterior draws. It returns factual media contribution minus counterfactual media contribution in the target units supplied to ammm.

result = mmm.compute_incrementality(
    spend_factor=0.0,
    start_date="2025-01-06",
    end_date="2025-03-31",
    channels=["tv", "search"],
    carry_out="complete",
)

unilateral_increment contains a separate intervention for each requested channel. joint_increment always applies the intervention to all fitted media channels. unilateral_window_total and joint_window_total sum their own per-date paired draws. The joint result is independently evaluated; it is not constructed by summing unilateral totals.

Media inputs and interventions follow fitted channel identities, including when channel_columns uses a different order. The channel forward-pass APIs align labelled arrays to fitted channel coordinates; unlabelled arrays use declared channel_columns order. Their results use fitted channel order. Duplicate or unknown channel labels are rejected, and save/load preserves this contract.

The date coordinate is the outcome date. intervened_date is true only for an outcome date inside the inclusive spend window. With carry_out="complete", later returned dates represent finite adstock carry-out and have intervened_date=False.

The first release accepts historical contiguous fitted-date windows, finite non-negative scalar factors, and the released time-series, fixed-effects (FE) and correlated-random-effects (CRE) estimators. It supports NoAdstock, GeometricAdstock, and DelayedAdstock in trailing mode, with NoSaturation or LogisticSaturation. It rejects time-varying parameters, arbitrary additive effects, unsupported transforms, named RE, future dates and incomplete carry-out tails. The experimental one-pair media interaction is an explicit exception for its supported static time-series profile. Its evaluator includes the shared interaction in both factual and counterfactual response and records additive_channel_response=False. Unilateral interventions overlap, so use the independently evaluated joint result for portfolio totals; do not sum unilateral increments. Channel contribution/spend ratios remain main-effect allocations and exclude the shared interaction.

The result is conditional on the fitted model and preserves its fitted-history boundary, retained sample labels and FE/CRE unit conditioning. It neither refits the model nor samples outcome noise. It does not establish causal identification: that requires a credible intervention, adjustment or design assumptions, valid measurement and suitable identifying variation.

For models without the interaction, metadata records additive_channel_response: True. Each channel’s contribution then depends only on its own spend, so a joint intervention equals the sum of the corresponding unilateral interventions. This is a property of the additive specification, not evidence that channels have no effect on one another. For cross-channel questions, see Halo effects between revenue channels.