Choose an Estimator

PanelMMM provides three released named estimator presets:

time_series for one aggregate time series
fe for a one-unit fixed-effects panel
cre for a one-unit correlated-random-effects panel

The re declaration is typed but release-gated. It is not a runnable estimator.

Release support matrix

Preset	Status in 3.1.0	Data contract	Identifying variation	Important operation boundary
`time_series`	Released	One aggregate observation per date	Aggregate temporal variation	Uses the supported ordinary `PanelMMM` workflow
`fe`	Released	One balanced unit-date panel	Within-unit temporal variation	Prediction and historical/manual scenarios require all fitted units; calibration and fixed-budget optimisation are unavailable
`cre`	Released	One balanced unit-date panel	Within-unit variation conditional on the declared transformed between-unit summary adjustment	Prediction and historical/manual scenarios require all fitted units and frozen fitted CRE summaries; calibration and fixed-budget optimisation are unavailable
`re`	Gated; not released	Declaration only	Not applicable until release	Graph construction fails closed with `EstimatorReleaseGateError`

The support status is a software release boundary, not evidence that a preset is appropriate for a particular dataset or causal question.

Compare the released presets

Question	`time_series`	`fe`	`cre`
Data structure	One observation per date	Balanced unit-date panel	Balanced unit-date panel
Unit effects	Not applicable	Absorbed unit intercepts	Gaussian random unit intercept
Identifying variation for shared slopes	Aggregate temporal variation	Within-unit temporal variation	Within-unit temporal variation, conditional on the declared between-unit summary adjustment
Media slopes	Shared	Shared across units	Shared across units
Adstock and saturation	Shared	Shared across units	Shared across units
Persistent unit differences	Not represented	Removed from the slope likelihood	Modelled through the random intercept and declared CRE summaries
Common categorical time effects	Not an estimator option	Not supported	Not supported
Calibration	Available through the ordinary `PanelMMM` surface	Not supported	Not supported
Historical and manual scenarios	Supported	Supported for all fitted units	Supported for all fitted units with frozen fitted CRE summaries
Fixed-budget optimisation	Supported	Not supported	Not supported

All three presets combine likelihood information with the declared priors. None of them turns observational marketing data into a causal design.

Use the time-series preset

Use time_series when the modelling unit is one aggregate market, brand, or business series and each date occurs once.

estimator:
  type: time_series

Do not use it to disguise panel observations as independent aggregate rows. Aggregate the data deliberately or use a panel estimator.

Use FE

Use fe when the target question concerns changes within units over time and you want time-invariant unit characteristics removed from the shared-slope likelihood.

estimator:
  type: fe
  unit: geo

FE is appropriate only when the transformed media and controls have enough within-unit temporal variation. It cannot estimate coefficients for predictors that are constant within every unit. It also does not remove time-varying confounding or common shocks.

See Fixed-effects Estimator for the exact likelihood and estimability checks.

Use CRE

Use cre when persistent unit differences may be associated with the declared predictors and you need an explicit within-between panel specification.

estimator:
  type: cre
  unit: geo

CRE augments the shared-slope random-intercept model with centred unit summaries. Media summaries use the fitted adstock-and-saturation exposure basis rather than raw-spend means. The adjustment is limited to the declared basis. It does not correct arbitrary omitted confounding.

CRE needs both usable within-unit media variation and enough independent between-unit information for its active summaries. Prediction is limited to the complete set of fitted units.

See Correlated-random-effects Estimator for the exact likelihood, summary basis, estimability checks, and prediction boundary.

Do not choose from fit statistics alone

The presets answer different statistical questions. Do not select one only because it has the best in-sample fit, lowest information criterion, or the most favourable media coefficient.

Before fitting:

State the unit and time structure of the business question.
State which persistent and time-varying confounding paths remain plausible.
Check whether the proposed identifying variation exists after media transformation.
Choose the estimator contract and priors before inspecting the preferred result.

After fitting, inspect the estimator-specific estimability evidence, MCMC diagnostics, posterior predictive checks, prior sensitivity, and any predeclared holdout evidence supported by that estimator. A passed screen means that AMMM3 did not detect the specified defect. It is not proof of causal or global identification.

Run the bundled recipes

From the repository root:

python3 runme.py --demo timeseries
python3 runme.py --demo geo_fe
python3 runme.py --demo geo_cre

The demo sampling settings are evidence-oriented and may take time. Command-line overrides can reduce the budget for an installation or workflow check. Do not interpret a reduced run as final statistical evidence.