Correlated-random-effects Estimator

The released cre preset fits a one-unit correlated-random-effects (CRE) marketing-mix model. It combines shared media and control slopes with a Gaussian random unit intercept and an explicit adjustment for association between persistent unit differences and the declared predictors.

Released contract

estimator:
  type: cre
  unit: geo

The v1 surface has these deliberate limits:

Use the bundled starting point at data/demo/geo_cre/config.yml.

Run it from the repository root:

python3 runme.py --demo geo_cre

Statistical meaning

For unit i and date t, CRE augments the shared-slope level equation with unit summaries of the declared regressors. The media summaries are computed from the fitted adstock-and-saturation exposure basis. They are not raw-spend means. Eligible control summaries are standardised unit means.

The residual unit intercept is integrated out. The likelihood therefore uses one exact Gaussian covariance block per unit. Pointwise log likelihood is unit-block marginal evidence, not an observation-level or future-date score.

The adjustment relaxes the naive random-effects mean-independence restriction only with respect to the declared summary basis. It does not establish causal identification or address omitted time-varying confounding, measurement error, reverse causality, or response-function misspecification.

Data and estimability requirements

The dataset must be a balanced unit-date Cartesian product with one row per unit and date. It must contain enough units to estimate the active centred media and control summaries while retaining at least two residual between-unit degrees of freedom.

AMMM3 rejects:

• non-finite predictors or targets;
• media with no within-unit temporal variation;
• an exactly rank-deficient transformed between-summary design; and
• insufficient between-unit residual degrees of freedom.

It warns about low transformed within-unit variation, high variance inflation factors, and a high condition number. These thresholds are configurable under estimator.estimability. A pass means that the implemented screen found no declared defect. It is not proof of global, posterior-wide, or causal identification.

After fitting, inspect posterior convergence, effective sample size, sampler pathologies, prior sensitivity, the post-fit summary-basis diagnostics, and predictive checks. A CRE coefficient interval containing zero does not prove that a simpler random-effects model is adequate.

Pipeline evidence

A structured CRE run records:

• the resolved estimator contract in 00_run_metadata/estimator_summary.txt and 00_run_metadata/estimator_manifest.yaml;
• the raw structural screen in 10_pre_diagnostics/cre_structural_estimability.json;
• the transformed reference-basis screen in 10_pre_diagnostics/cre_reference_estimability.json and 10_pre_diagnostics/cre_reference_estimability_features.csv;
• the bounded posterior-draw screen in 20_model_fit/cre_postfit_estimability.json; and
• the CRE adjustment and reconciliation outputs under 40_decomposition.

The run manifest is the machine-readable index of these files. A completed pipeline only means that every required stage ran. Review the diagnostic status before interpreting the posterior.

Prediction and persistence

Prediction is conditional on the fitted unit history. Every prediction request must supply all fitted units. Row order may vary, but unseen units and fitted-unit subsets are rejected. Save and load preserve the fitted CRE summary state and validate its unit coordinates before prediction.

Historical and manual scenarios use the same fitted-unit restriction. Manual spend changes the nonlinear media-response path, but AMMM3 does not recompute the fitted training-period Mundlak media or control summaries. This preserves the fitted CRE adjustment rather than redefining confounding context from the planned spend. Scenario outputs are posterior media-contribution estimates, not total-outcome forecasts or causal effects.

Use the YAML and Python examples under data/demo/geo_cre/. Fixed-budget optimisation remains outside the released CRE scenario contract.

Evidence boundary

The release verifies the declared graph, configuration restrictions, estimability evidence, fitted-unit prediction contract and persistence path. It does not promise a fixed point-estimate accuracy, causal validity, or general robustness for arbitrary data. Treat each fitted model as a separate statistical assessment.

For a direct comparison with FE and the aggregate time-series preset, see Choose an Estimator.