Correlated-random-effects MMM

CorrelatedRandomEffectsMMM is experimental. The implementation has deterministic contract tests, but the historical cross-library posterior qualification claims are unverified by this review (tests/mmm/test_correlated_random_effects.py:144). Do not describe it as fully qualified because a graph builds or a run completes.

from ammm.mmm import GeometricAdstock, LogisticSaturation
from ammm.mmm.correlated_random_effects import CorrelatedRandomEffectsMMM

model = CorrelatedRandomEffectsMMM(
    unit="geo", date_column="date", target_column="revenue",
    channel_columns=["tv", "social"],
    adstock=GeometricAdstock(l_max=4), saturation=LogisticSaturation(),
)

The likelihood analytically integrates a Gaussian random unit intercept. A Mundlak-style adjustment uses centred unit time means of the transformed media basis, excluding its amplitude, and eligible control summaries standardised across units. This models a particular dependence of unit effects on predictor history; it does not remove arbitrary omitted-variable bias.

The balanced panel has one unit dimension, shared media and control parameters, shared residual scale and complete fitted-unit prediction. CRE requires exact GeometricAdstock with trailing, normalised alpha parameterisation, LogisticSaturation, adstock first and maximum scaling reduced across units. The between-summary design must have full rank and satisfy N - 1 - p >= 2; this is a design requirement, not a claim of sufficient statistical information.

Prediction conditions unit effects on factual training residuals and freezes fitted CRE summaries. Changed planned spend must not redefine the unit’s historical adjustment. Missing or unseen units are rejected. Log link, annual seasonality, time-varying parameters, custom effects, holidays, calibration, causal-graph options, cost-per-unit configuration and fixed-budget optimisation are outside the current contract.

The previously cited PC-CRE-01 posterior comparison and remediation outcomes have not been verified against a retrievable report in this documentation review. Keep CRE experimental and retrieve the retained report, frozen profile, data and commits before relying on those historical claims. Deterministic implementation tests (tests/mmm/test_correlated_random_effects.py:144) do not establish cross-library posterior parity or repeated-data interval coverage. See the geo_cre configuration and identification discussion.

Implementation reference at 7cb7f20: src/ammm/mmm/correlated_random_effects.py:182.