Data Requirements & Runtime

The Input Format: One Long Table

All data enters the framework as a single Master Flat File (MFF)—a long-format table with one row per period (and optionally geography, product, campaign, outlet, creative) per variable.

Instead of one column per metric, the MFF uses two columns—VariableName says which series a row belongs to (the KPI, a media channel, a control), and VariableValue holds its value. The same file therefore carries national and geo-level series side by side, and adding a channel means adding rows, not redesigning a schema. This matches the definition in the glossary. Data is loaded with MFFLoader (or the one-call load_mff()), which validates the file against a declared MFFConfig before anything is fit. If your data lives in the more common wide format (one column per metric), mff_from_wide_format() converts it.

Column Dictionary

Eight columns. All eight must exist in the file—the loader raises MFFValidationError: Missing required columns otherwise code-enforced. But the five extra dimension columns may be left blank for data that doesn't use them: the loader treats a dimension as active only when it has more than one distinct non-null value. Column names are remappable via MFFColumnConfig; the defaults are shown.

Frequency. MFFConfig.frequency accepts exactly "W" (weekly, aligned to weeks ending Sunday), "D" (daily), or "M" (monthly, month-start) code-enforced. Weekly is the default and the frequency all of the framework's published benchmarks and pressure tests use.

Gaps. Missing media values are filled with 0.0 by default (no record of spend = no spend); missing control values are forward-filled by default. Both behaviors are configurable (fill_missing_media, fill_missing_controls) code-enforced.

Worked Example

Two weeks of a small national model—one KPI (Sales), two media channels, one price control. Note the dimension columns sit empty for national data; a geo-level KPI would simply repeat the Sales rows once per region with Geography filled in.

That TV = 0 week is not a data error—it's information. Dark weeks are what let the model see what sales look like without TV (see media variation below).

How Variables Are Declared

The file alone doesn't say which series is the KPI, which are media, and which are controls. That's declared in an MFFConfig: one required KPIConfig, a list of MediaChannelConfigs (each carrying its own adstock, saturation, and coefficient-prior settings), and a list of ControlVariableConfigs (sign constraints, shrinkage, and an optional causal role—declared mediators and colliders are refused as controls at model-construction time). Each variable also declares its DimensionTypes (PERIOD, GEOGRAPHY, PRODUCT, CAMPAIGN, OUTLET, CREATIVE), and the loader checks the data actually has the dimensions you claimed code-enforced. National media is automatically allocated down to a geo-level KPI (population weights by default; configurable).

import pandas as pd
from mmm_framework import MFFConfigBuilder, load_mff

# Declare what each VariableName means
mff_config = (
    MFFConfigBuilder()
    .with_kpi_name("Sales")
    .add_national_media("TV", adstock_lmax=8)
    .add_national_media("Paid_Search", adstock_lmax=2)
    .add_price_control("Price_Index")   # control allowed a negative sign
    .build()
)

# Load + validate in one call -> aligned panel, ready to fit
panel = load_mff(pd.read_csv("weekly_mff.csv"), mff_config)
print(panel.summary())

Minimum Data Requirements

The loader enforces structure, not statistical sufficiency. The thresholds below are guidance—the same checklist the Modeling Guide uses—not hard gates. A model will fit on less; its intervals will just be honest about how little it learned.

The variation requirements are not hypothetical: the framework's own pressure-testing worlds include a synchronized-flighting scenario and a near-collinear channel pair built precisely to demonstrate what happens when they're violated—the model's job in those worlds is to report wide intervals, not to invent a split. See Variable Selection for how collinearity is handled and when only an experiment can break the tie.

Spend or Impressions?

Either works as the media input. Internally each channel is scaled by its own maximum after adstock code-enforced , so units don't affect the fit—the response curve is learned on a normalized scale either way. Prefer spend when you want ROI and budget-allocation readouts directly: contributions-per-dollar require dollars in the denominator. Use impressions (or GRPs) when CPMs shifted materially over the window and you want the response curve in exposure units—then convert to ROI with your own cost data. The framework applies that conversion for you: set the per-channel measurement_unit to "impressions" (or "clicks") on MediaChannelConfig and give it a cost source—a cpm/cpc constant or a spend_column pointing at a separate dollar series—and it reports ROI/marginal-ROAS internally (cpm → (impressions/1000)×cpm; cpc → clicks×cpc). With no cost declared it instead reports an efficiency metric (contribution per 1,000 impressions / per click, break-even reference 0). See technical-docs/impression-level-roi.md. guidance

How Many Channels? How Many Geographies?

Channels. The framework's synthetic evaluation worlds use 4 channels (the clean and violation worlds) to 7 (the “realistic” world, which deliberately includes a near-collinear Radio/Print pair) , and the runtime benchmark sweeps 3–7. Nothing caps the channel count, but identification degrades before runtime does: every added channel is another response curve competing to explain the same KPI variance, and collinearity risk grows with count. Past roughly this range, consider grouping minor channels under a parent_channel hierarchy or letting shrinkage-based selection do the pruning. guidance

Geographies. Hierarchical geo models need at least 2 geographies code-enforced; the synthetic geo worlds use 4 . The binding constraint is not the count but per-geo spend variation: the built-in diagnostic (validation.geo_spend_variation_diagnostic) computes each channel's coefficient of variation of spend across geos and flags channels below a 0.15 default threshold as too uniform to carry geo-level identifying information . It also ships with a caveat worth repeating verbatim in spirit: cross-geo variation identifies effects only if geo-level spend is exogenous—not the result of targeting higher-demand markets.

Cost to Run: Measured Runtimes

These are measured numbers, not vendor estimates—every row below comes from nbs/validation/runtime_benchmark.ipynb, run on an Apple M3 laptop (8 cores, 16 GB RAM; Python 3.12, PyMC 6.0.1, PyTensor 3.0, ArviZ 1.2, NumPyro 0.19, JAX 0.8). The honest caveat: the ratios transfer to other hardware; the absolute seconds don't (and run-to-run variance is ~15%).

Fit Budgets

What this means for a working day:

The production figure is extrapolated from the measured draws-scaling line (500 → 1000 draws cost 1.32×; per-draw cost ≈ 9 ms on this hardware), not measured directly—treat it as an order of magnitude, not a quote. The practical point survives any hardware change: a full Bayesian MMM refit is a coffee break, not an overnight job, which is what makes the closed measurement loop (refit after every experiment) economically viable.

Even faster during exploration: for model-checking — catching bad priors, broken geometry, or pathological saturation/adstock before paying for a full sample — fit(method="map"|"laplace"|"advi"|"fullrank_advi"|"pathfinder") (builder .with_fit_method(…) / agent fit_mmm_model(method=…)) returns an approximate posterior in seconds, faster than the ≈ 10–15 s NUTS fit, and works on the extension models too (shared run_approximate_fit engine). The catch: R-hat/ESS are unavailable and the uncertainty is not calibrated, so re-fit with NUTS before reporting numbers or making decisions. (A second exact sampler, fit(method="smc"), exists for a different job — confirming multimodal posteriors and computing model evidence; see troubleshooting.)

What Happens to Bad Data

Two lines of defense, both before any model is fit:

The loader refuses structural errors code-enforced. MFFLoader raises MFFValidationError for missing required columns, declared variables absent from the file, dates that don't parse under the configured format, and variables whose actual dimensions contradict their declared ones. It warns (rather than fails) on undeclared extra variables—which are ignored—and on null values in VariableValue. Nothing silently reshapes your data into something fittable.

The EDA module screens statistical problems. mmm_framework.eda is the pre-fit sibling of the post-fit validation suite: load_eda_panel builds the panel view, validate_dataset runs the automated rule checks, missingness_matrix maps gaps, and detect_outliers flags anomalies and pairs them with recommended treatments (recommend_treatments / apply_treatments)—plus collinearity_analysis for the channel-separation problem above. The design stance is the same throughout: flag and explain, never silently fix. Outlier remediation is proposed, reviewed, and applied explicitly—not baked invisibly into the fit.

Data-ready checklist

Before you fit, walk this list. Building the MFF from raw platform exports? The Data-Prep Cookbook is the step-by-step code version.

• ☐  Data is in MFF long format — Period, dimension columns, and a VariableName/VariableValue pair.
• ☐  Every variable shares one weekly (or daily/monthly) anchor; the KPI has no missing periods.
• ☐  Media values are non-negative; a dark week is a real zero, not a blank.
• ☐  Confounding controls are present — anything that moves spend and sales (price, promotions, seasonality drivers, distribution).
• ☐  You have enough history (≈ two years of weekly data for a national model).
• ☐  Each channel is modeled on the right variable — spend, or impressions/clicks with a spend column for dollar ROI.
• ☐  The EDA screen is clean — validate_dataset and detect_outliers raise nothing you haven't reviewed.
• ☐  The MFF loads without validation errors or contiguity warnings.