Data and fitted-model lifecycle

Supply complete, finite observations with explicit labels. AMMM4 rejects invalid observations rather than choosing aggregation or imputation rules for you.

Features and targets

For a DataFrame, each (date_column, *dims) key must occur exactly once. Include every configured channel, control and panel dimension, with a complete panel grid. Duplicate rows are invalid even if their values match. Zero spend is an observation; a missing outcome is not evidence of zero sales.

Use timezone-naive dates or parseable date strings. Numeric dates, missing dates and irregular spacing are rejected. Ordinary models allow regular calendar frequencies; frequency inference needs at least three dates. Time-varying models require constant positive whole-day spacing and at least two dates. The implementation cannot tell that an apparently regular fortnightly series was meant to contain weekly rows, so audit the intended calendar yourself.

NumPy targets follow DataFrame row order. Ordinary pandas indices must match the feature index. DatetimeIndex, MultiIndex and coordinate-labelled xarray targets align by labels and require identical label sets. Sorting is applied consistently before positional carryover transforms.

For xarray features, use media or _channel with dimensions ("date", *dims, "channel"); optional _control uses a control axis. An embedded target or _target has dimensions ("date", *dims). Configured channel/control labels must match exactly. Supply either an embedded target or a separate target. The canonical stored date coordinate is date.

Build, calibrate and fit

Continue the Python quickstart with unchanged X, y and model.

model.build_model(X, y)
model.add_original_scale_contribution_variable(["y", "channel_contribution"])
model.sample_prior_predictive(X, y, samples=100, random_seed=42)
# Add compatible calibration here, before fitting.
model.fit(X, y, nuts_sampler="pymc", random_seed=42)

Fitting an existing graph requires exact equality of canonical observations and live graph data. Copies of the same values and labels are valid; changed data require build_model again. Rebuilding clears inference state and calibration, so re-register required deterministics and calibration before refitting. Invalid input is checked before replacement, but arbitrary graph-construction errors do not guarantee transactional rollback.

Supplying real targets during prior prediction avoids a prior-only placeholder. If you omit targets, rebuild with observed targets before fitting, even when they happen to equal the placeholder values. Data-derived placeholder scaling uses one; explicit fixed scaling remains in force.

Predictions may omit targets but must include all fitted panel labels. The default clone_model=True leaves training graph data intact; prediction with clone_model=False can invalidate subsequent fitting and saving until rebuilding and refitting.

Save and reload

model.save("sandbox/model.nc")
restored = type(model).load("sandbox/model.nc")

Choose a fresh path when preserving evidence. fit_data retains canonical _channel, _target, optional _control and required auxiliary xarray variables. Unused DataFrame columns are not retained as observations.

Supported lift and cost-per-target calibration records are copied, ordered and saved with their required inputs. Loading rebuilds the graph and replays those records. Arbitrary manual graph edits are outside this guarantee. Refit after adding calibration to an already fitted model before saving it.

Use the originating AMMM4 release when loading a saved model. Persistence format 1 requires canonical training data and a calibration manifest, including an empty one for uncalibrated models. Incomplete or older records are rejected even with check=False; reconstruct and refit rather than guessing missing calibration. There is no AMMM3 saved-model compatibility promise.

Avoid partial groups selection unless you understand the persistence contract. Retain posterior, training observations, observed data, all calibration groups and any effect-specific state. The supported Zarr writer uses format 2 and needs its backend installed. Loading materialises saved arrays and closes the file, so memory must accommodate the full saved inference data.

Prepare a named target

A named pandas Series must match target_column; an unnamed Series is accepted. For a model configured with target_column="revenue", prepare inputs as follows:

# Continue with your validated input DataFrame named data.
y = data["revenue"].rename("revenue")
X = data.drop(columns="revenue")

A mismatch raises y has name 'revenue' but the model's target_column is 'y'. Set the constructor’s target name or rename the Series intentionally; do not change labels to conceal a different outcome (src/ammm/mmm/_mmm_graph.py:42). For a complete long-panel example, see specification.

Implementation reference at 7cb7f20: src/ammm/mmm/data_conversion.py:1, src/ammm/mmm/mmm.py:1709, src/ammm/mmm/persistence.py:1.