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:

OperationInteraction support
Python/YAML construction, fitting and save/loadSupported for the profile below
Ordinary posterior predictionRecomputes the interaction from live media
Historical compute_incrementalityEvaluates complete media response from paired retained draws
Low-level PanelBudgetOptimizerWrapperDefaults to complete media response
Component and wide contribution summariesInclude the interaction as a separate component
High-level ScenarioPlanner, current/manual/optimised scenariosRejected because channel-only totals cannot represent the shared component
Direct PlanningEvaluatorRejected
Pipeline Stage 70 optimisationRejected; fitting with the optional stage disabled remains supported
Experimental-evidence and legacy lift calibrationRejected
FE, CRE, RE, panel dimensions, time-varying parameters, other custom effects or multiple pairsRejected

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.

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 gammaEstimated mean94% highest-density interval
+0.40.396[0.241, 0.567]
00.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.