Experimental media interactions
MediaInteractionEffect adds one signed interaction between two advertising
channels to a static time-series PanelMMM. Use it to investigate questions
such as whether TV and radio are more effective together. It does not model
mediation, cross-product revenue transfers or causal identification.
This feature remains experimental after implementation review, numerical checks and bounded recovery controls. Six informative synthetic cases pass their prespecified diagnostic and recovery checks, including stages that estimate response shapes and amplitudes. General interval coverage, detection power and robustness to correlated campaign schedules remain unqualified. Independent variation and substantive modelling assumptions remain necessary.
Specification and timing
Let z_c be the existing logistic saturation shape applied to the channel’s
adstocked, scaled spend, before its amplitude beta_c. The mean is:
mu = baseline + sum(beta_c * z_c) + gamma * z_tv * z_radio
The interaction shares each channel’s adstock and saturation shape; it does not introduce another lag or shape parameter. Because exposures are calculated before amplitude, the interaction remains defined when a main-effect amplitude is zero. Multiplying the transformed exposures allows carried-over TV exposure to interact with radio exposure. It differs from multiplying same-period raw spend and then applying an independent adstock and saturation transformation.
The interaction is symmetric: positive gamma represents complementarity on
the additive target scale, while negative gamma represents attenuation.
Neither establishes that TV causes radio’s effectiveness to change rather than
the reverse. Negative marginal responses are possible and are not clipped.
The default prior is scalar Normal(mu=0, sigma=0.5) in scaled-target units.
It allows either sign. Its scale is an initial regularisation choice, so inspect
prior predictions using the intended spend schedules and target scale. A
positive-only prior cannot test for attenuation; changing the posterior median’s
sign under another prior does not demonstrate no interaction.
Python example
This example builds a graph from synthetic inputs. The synthetic outcome is a placeholder, so this is an API example rather than a recovery study.
import numpy as np
import pandas as pd
from ammm.mmm import GeometricAdstock, LogisticSaturation, MediaInteractionEffect
from ammm.mmm.panel import PanelMMM
from ammm.prior import Prior
rng = np.random.default_rng(42)
X = pd.DataFrame({
"date": pd.date_range("2025-01-06", periods=40, freq="7D"),
"tv": rng.uniform(0, 100, 40),
"radio": rng.uniform(0, 60, 40),
})
y = pd.Series(rng.normal(200, 10, 40), name="revenue")
mmm = PanelMMM(
date_column="date",
channel_columns=["tv", "radio"],
target_column="revenue",
estimator={"type": "time_series"},
adstock=GeometricAdstock(l_max=4),
saturation=LogisticSaturation(),
)
mmm.mu_effects.append(MediaInteractionEffect(
channels=("tv", "radio"),
prior=Prior("Normal", mu=0, sigma=0.5),
))
mmm.build_model(X, y)
Before fitting, perform prior predictive checks. After fitting, assess sampler diagnostics, posterior predictions and sensitivity to plausible interaction priors. Treat an interval containing zero as inconclusive as to sign at that interval level; claims of negligible interaction require a practical threshold.
YAML example
Given a CSV with date, tv, radio and revenue columns, this specification
builds the same effect through the ordinary YAML builder or pipeline:
data:
dataset_path: dataset.csv
date_column: date
target:
column: revenue
type: revenue
estimator:
type: time_series
media:
channels: [tv, radio]
adstock:
type: geometric
l_max: 4
saturation:
type: logistic
effects:
- type: media_interaction
channels: [tv, radio]
prior:
distribution: Normal
mu: 0
sigma: 0.5
fit:
random_seed: 42
Omit optimization from pipeline configurations for this profile. The supported
operations and explicit gates are:
| Operation | Interaction support |
|---|---|
| Python/YAML construction, fitting and save/load | Supported for the profile below |
| Ordinary posterior prediction | Recomputes the interaction from live media |
Historical compute_incrementality | Evaluates complete media response from paired retained draws |
Low-level PanelBudgetOptimizerWrapper | Defaults to complete media response |
| Component and wide contribution summaries | Include the interaction as a separate component |
High-level ScenarioPlanner, current/manual/optimised scenarios | Rejected because channel-only totals cannot represent the shared component |
Direct PlanningEvaluator | Rejected |
| Pipeline Stage 70 optimisation | Rejected; fitting with the optional stage disabled remains supported |
| Experimental-evidence and legacy lift calibration | Rejected |
| FE, CRE, RE, panel dimensions, time-varying parameters, other custom effects or multiple pairs | Rejected |
The admitted profile requires exact LogisticSaturation, trailing NoAdstock,
GeometricAdstock or DelayedAdstock, adstock before saturation, and an ordinary
Normal likelihood with identity mean. Native half-life and fixed numeric
transform parameters remain supported. Native controls and yearly seasonality
are allowed. The interaction prior must be an untransformed scalar Normal with
finite numeric location and strictly positive finite scale.
Reporting, interventions and optimisation
channel_contribution and total_media_contribution_original_scale retain their
main-effect meanings. interaction_contribution_original_scale reports the
separate shared term. media_response_original_scale and
total_media_response_original_scale include the interaction exactly once.
For retained models:
interaction = mmm.summary.contributions(component="interaction")
components = mmm.summary.mean_contributions_over_time()
increments = mmm.compute_incrementality(spend_factor=0.0)
Unilateral removal results include the interaction change induced by that
channel’s intervention. They are overlapping counterfactuals, so their sum is
not a portfolio total. Use joint_increment for the independently evaluated
all-channel intervention. The result records additive_channel_response=False.
Selecting channels filters unilateral results; the joint intervention still
changes all fitted media. Historical outcome windows retain the existing
carry-in and finite carry-out policies.
Channel contribution/spend ROAS and cost-per-target remain main-effect allocations. They exclude the shared interaction and are not removal metrics. Saturation and channel forward-pass curves also show main effects only; interaction-aware counterfactuals require the complete response evaluator. Pipeline decomposition exports retain a separate interaction table and scope note; response-curve tables identify their main-effect scope.
The low-level optimiser defaults to total_media_response_original_scale for
interaction models. An explicitly selected
total_media_contribution_original_scale objective still optimises main effects
only. The allocation records the selected response_variable in its attributes;
these objectives answer different questions. Response-distribution samples include the shared contribution and
complete response separately, without assigning the interaction to a channel.
For interaction models, budget eligibility follows observed positive spend, so a channel with zero main-effect amplitude can still receive budget through the interaction. Channels with all-zero fitted spend remain excluded.
Before prediction, load, historical evaluation and optimiser construction, all sampled media-response ancestors must be retained with finite values and valid dimensions and coordinates. Missing draws are rejected instead of regenerated from priors. Fixed numeric transform parameters need no posterior draws.
Related guides
Qualification and teaching demo
The halo_interactions bundle repurposes the existing anonymous weekly demo
history. It aliases channel_1 as TV and channel_2 as radio, retains the other
four media and observed revenue, and adds date-only annual controls. These are
teaching aliases; the original media identities and any interaction truth are
unknown. No halo effect is injected into the outcome.
Run the local pipeline without the optional external advisor:
python3 runme.py --demo halo_interactions --no-ai-advisor
See data/demo/halo_interactions/README.md and provenance.json in the checkout
for the mapping and standalone additive-versus-interaction comparison command.
Its two expanding holdouts use fresh training-only scales and native carry-in.
Improved predictive performance does not establish causal complementarity.
The separate qualification entry point runs a fixed-shape analytical sampling benchmark, then a frozen nonlinear parameter-recovery pilot and prior sensitivity:
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
python -m scripts.qualify_media_interaction benchmark \
--output .planning/interaction-benchmark-new
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
python -m scripts.qualify_media_interaction pilot \
--benchmark .planning/interaction-benchmark-new/benchmark.json \
--output .planning/interaction-pilot-new
Use normal compiled PyTensor execution, without linker=py. Every output path
must be new. The pilot retains diagnostic failures and budget skips explicitly;
its two replicates per cell cannot qualify interval coverage or detection power.
The bounded execution on 22 October 2026 passed the analytical sampling benchmark, but only nine of 18 nonlinear baseline fits and three of four prior-sensitivity fits passed all diagnostic thresholds. Every eligible interaction 94% HDI included zero. The teaching challenger completed eight eligible fits, with no consistent held-out improvement over the additive baseline. These results retain the experimental boundary; satisfactory sampling diagnostics alone do not establish interaction recovery or causal complementarity.
A separate diagnostic ablation fixes generating adstock/saturation shapes, then also fixes or estimates main-effect amplitudes. It adds four fits across the independent and synchronised positive-truth histories and reuses their two fully free pilot fits. Reuse requires matching retained data, scales, controls, model configuration, fit hashes and inference source. Fixed generating values provide privileged information for diagnosis; they are not practical estimates.
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
python -m scripts.ablate_media_interaction \
--reference .planning/tv-radio-qualification-20261022 \
--output .planning/interaction-ablation-new
Freeze and review the ablation protocol before sampling. The six comparison rows retain failures and historical eligibility; four new fits cannot establish coverage, detection power or causal identification.
The completed informative-design control uses six paired positive/null/negative cases with unknown amplitudes and fixed or sampled shapes. All six pass the prespecified diagnostic and recovery gate. With shapes and amplitudes estimated, the original-unit gamma results are:
| Generating gamma | Estimated mean | 94% highest-density interval |
|---|---|---|
| +0.4 | 0.396 | [0.241, 0.567] |
| 0 | 0.009 | [-0.082, 0.107] |
| -0.4 | -0.460 | [-0.793, -0.218] |
These are conditional checks under one favourable spend design and paired noise history, not independent simulation replications. The control changes the noise realisation and sampling budget relative to the earlier pilot, so the comparison does not isolate a spend-design effect. The optional 7,200-fit study has been withdrawn; it is not required to close this experimental implementation. No larger study or remote runner was started.
The retained six-case runner remains available for a separately reviewed rerun. It requires a protocol and independent review and never starts a larger study:
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 \
python -m scripts.qualify_media_interaction_control \
--review path/to/accepted-control-review.md \
--output .planning/interaction-informative-control-new
Applying the experimental feature to client data
Use the existing additive-versus-interaction challenger only when a genuine dataset, media identities and justified controls are available. The teaching demo aliases do not supply empirical TV/radio evidence. Confirm that the pair has usable separate and joint variation after accounting for carryover and saturation, because raw spend correlation alone does not establish separation.
Compare the additive baseline and signed-prior interaction candidates with the same controls and held-out periods, using fresh training-only scales. Assess sampling diagnostics, prior/posterior predictions and sensitivity to plausible interaction priors before interpreting the interval. An eligible interval including zero is inconclusive as to sign; an ineligible fit is descriptive only. Predictive improvement does not establish causal complementarity. Further simulation work should address a specific unresolved question from that use.