SuperAPI AI Directory

mmm-meridian

General & other

View repository

Updated 10-16 08:34

About this skill

Google Meridian (verified against v1.8.0)

Meridian is Google's open-source Bayesian MMM: TensorFlow Probability, geo-hierarchical by default, with media effects parameterised by ROI rather than by coefficient. That last choice is the important one — the prior sits directly on the quantity stakeholders argue about.

Install: pip install google-meridian (Python ≥ 3.10; pulls TensorFlow 2.21 and a pinned tfp-nightly). GPU: google-meridian[and-cuda]. There is also a [jax] extra.


1. When Meridian is the right choice

Choose Meridian when:

  • You have a geo panel with population data. Hierarchical geo pooling is its core strength and the main reason to prefer it.
  • Reach and frequency matter. Meridian is the only major open framework that models RF natively and answers "what frequency should we buy?".
  • You want ROI priors. Calibrating to a geo experiment is a one-line prior change rather than a reverse-engineered coefficient.
  • You need organic media and non-media treatments kept structurally separate from paid media.
  • You want a built-in EDA guardrail that refuses to fit data with critical problems.

Choose something else when:

  • The model is national with no geo dimension — you lose the main advantage and keep the TensorFlow dependency.
  • You need a multiplicative (log-link) model. Meridian's media terms are additive.
  • You need custom likelihoods, arbitrary priors on arbitrary parameters, or a mediation structure. pymc-marketing is a modelling toolkit; Meridian is a well-designed application.
  • You need Fourier seasonality specifically. Meridian uses knots for time effects.

2. Data model

Meridian's InputData distinguishes variable kinds explicitly — the structural feature that stops a price column from acquiring a ROAS.

Slot Dims Meaning
kpi (geo, time) Outcome. kpi_type is "revenue" or "non_revenue"
revenue_per_kpi (geo, time) Value per KPI unit; turns a non-revenue KPI's ROI into money
population (geo,) Required for geo models; enables per-capita scaling
media (geo, media_time, channel) Paid exposure (impressions, GRPs)
media_spend (geo, time, channel) Paid cost
reach, frequency, rf_spend (geo, ·, rf_channel) Reach-and-frequency channels
organic_media (geo, media_time, channel) Unpaid activity with carryover
organic_reach, organic_frequency Organic RF
non_media_treatments (geo, time, channel) Price, promo, distribution
controls (geo, time, variable) Confounders

n_media_times >= n_times: media may extend earlier than the KPI so pre-window exposure drives adstock into the modelled period. This is a genuine advantage — most frameworks lose the first l_max periods to a cold start.

from meridian.data import load

coord_to_columns = load.CoordToColumns(
    time="date", geo="geo", kpi="revenue", population="population",
    revenue_per_kpi=None,
    media=["tv_grps", "yt_impressions"], media_spend=["tv_spend", "yt_spend"],
    reach=["ctv_reach"], frequency=["ctv_frequency"], rf_spend=["ctv_spend"],
    organic_media=["email_sends"],
    non_media_treatments=["price_index", "acv"],
    controls=["competitor_spend", "consumer_confidence"],
)
loader = load.DataFrameDataLoader(
    df=df, kpi_type="revenue", coord_to_columns=coord_to_columns,
    media_to_channel={"tv_grps": "TV", "yt_impressions": "YouTube"},
    media_spend_to_channel={"tv_spend": "TV", "yt_spend": "YouTube"},
)
data = loader.load()

Loaders: DataFrameDataLoader, CsvDataLoader, XrDatasetDataLoader. The panel must be rectangular — every (geo, time) cell present.

National models use a single constant geo. Everything works; the hierarchy is inert.


3. ModelSpec

from meridian.model import spec as model_spec

spec = model_spec.ModelSpec(
    prior=prior,                                   # PriorDistribution
    media_effects_dist="log_normal",               # or "normal"; geo random effects
    hill_before_adstock=False,
    max_lag=8,
    unique_sigma_for_each_geo=False,
    media_prior_type="roi",                        # roi | mroi | contribution | coefficient
    rf_prior_type="roi",
    roi_calibration_period=None,                   # (n_media_times, n_media_channels) bool
    rf_roi_calibration_period=None,
    organic_media_prior_type="contribution",       # contribution | coefficient
    organic_rf_prior_type="contribution",
    non_media_treatments_prior_type="contribution",
    non_media_baseline_values=None,                # float | "min" | "max" per channel
    knots=None,
    baseline_geo=None,
    holdout_id=None,                               # bool mask; excludes KPI, keeps media
    control_population_scaling_id=None,
    non_media_population_scaling_id=None,
    adstock_decay_spec="geometric",                # "geometric" | "binomial" | per-channel map
    saturation_spec="hill",                        # "hill" | "none" | per-channel map
    enable_aks=False,                              # automatic knot selection
)

The four prior types

media_prior_type Prior on Use when
"roi" (default) Return per unit spend You have ROI beliefs or experiments. Default choice.
"mroi" Marginal ROI at current spend You care about the next pound, not the average
"contribution" Share of outcome You believe a channel drives ~x% of sales
"coefficient" beta_m directly You are porting a coefficient-parameterised model

roi_calibration_period restricts the ROI prior to the window a test actually covered — essential when a channel was tested in one quarter only.

Knots: the most consequential setting

knots controls the flexibility of time effects, which is Meridian's baseline.

  • knots=None on a geo model means one knot per time period — the most flexible baseline available, able to absorb almost any variation media might otherwise explain.
  • knots=None on a national model means 1 (a constant).
  • knots=k places k equally spaced knots; knots=[0, 25, 51] places them explicitly.
  • enable_aks=True selects the number automatically; it errors if knots is also set.

Never leave knots=None on a geo model without deciding it. Fewer knots means a stiffer baseline and more variance available for media; more knots means the opposite. This is a prior about how much marketing does, expressed as a smoothing parameter. Fit at two settings and compare the media share before choosing.

Adstock and saturation

adstock_decay_spec: "geometric" or "binomial", globally or per channel. There is no delayed/Weibull option — map a delayed request to "binomial", which has a delayed peak, and expect a slightly different carryover shape from an equivalent pymc-marketing model.

saturation_spec: "hill" or "none", globally or per channel. "none" is right for channels genuinely in their linear range.

hill_before_adstock=False (default) applies adstock first. Does not apply to RF channels.


4. Priors

PriorDistribution holds a TFP distribution per parameter family. Defaults verified against 1.8.0:

Parameter Default Meaning
roi_m, roi_rf LogNormal(0.2, 0.9) ROI; median ≈ 1.2, 90% range ≈ 0.3–5.3
mroi_m, mroi_rf LogNormal(0.0, 0.5) Marginal ROI
contribution_m/rf/om/orf Beta(1, 99) Contribution share; mean 1%
contribution_n TruncatedNormal(0, 0.1, -1, 1) Non-media contribution, can be negative
beta_m, beta_rf, beta_om, beta_orf HalfNormal(5) Coefficients (non-negative)
eta_m/rf/om/orf HalfNormal(1) Geo-level random-effect scale
gamma_c, gamma_n Normal(0, 5) Control and non-media coefficients
xi_c, xi_n HalfNormal(5) Their geo random-effect scales
alpha_m/rf/om/orf Uniform(0, 1) Adstock decay
ec_m, ec_om TruncatedNormal(0.8, 0.8, 0.1, 10) Hill half-saturation
ec_rf, ec_orf LogNormal(0.7, 0.4) shifted by 0.1 Hill half-saturation, RF
slope_m, slope_om Deterministic(1.0) Hill slope fixed → concave
slope_rf, slope_orf LogNormal(0.7, 0.4) Hill slope, RF (S-curve allowed)
knot_values Normal(0, 5) Time effects
tau_g_excl_baseline Normal(0, 5) Geo intercepts vs baseline geo
sigma HalfNormal(5) Residual sd

Note slope_m is deterministic at 1.0: paid media gets a concave Hill curve, not an S-curve, unless you override it. RF channels do allow an S-curve, which is the right default given how frequency behaves.

Helpers for stating a prior the way a human would:

from meridian.model import prior_distribution as pd

pd.lognormal_dist_from_range(low=1.0, high=6.0, mass_percent=0.9)   # "ROAS is 1-6, 90% sure"
pd.lognormal_dist_from_mean_std(mean=3.0, std=1.0)
import numpy as np, tensorflow_probability as tfp
tfd = tfp.distributions
# Channel order must match data.media_channel exactly.
prior = pd.PriorDistribution(roi_m=tfd.LogNormal([0.5, 0.2], [0.4, 0.9], name="roi_m"))

5. Fitting

from meridian.model import model

mmm = model.Meridian(input_data=data, model_spec=spec)
mmm.sample_prior(500)
mmm.sample_posterior(n_chains=4, n_adapt=500, n_burnin=500, n_keep=1000, seed=1)
health = mmm.review()          # post-fit health checks -> mmm.health_summary
# or: mmm.sample_posterior_and_review(...)
model.save_mmm(mmm, "model.pkl")

n_chains accepts a list (e.g. [2, 2]) to split sampling into separate calls and cap memory. posterior_thinning() reduces a large posterior for downstream analysis.

The EDA guardrail. Meridian runs its own checks before fitting and refuses to proceed on critical findings. Check types: PAIRWISE_CORRELATION, STANDARD_DEVIATION, MULTICOLLINEARITY, KPI_INVARIABILITY, COST_PER_MEDIA_UNIT, VARIABLE_GEO_TIME_COLLINEARITY, POPULATION_CORRELATION, PRIOR_PROBABILITY, DATA_ADEQUACY. Read mmm.eda_outcomes rather than working around a refusal — the checks map closely onto the problems that produce confidently wrong MMMs.


6. Analysis

from meridian.analysis import analyzer, optimizer, summarizer, visualizer

an = analyzer.Analyzer(mmm)
an.rhat_summary(bad_rhat_threshold=1.2)
an.predictive_accuracy()
an.summary_metrics()                    # ROI, mROI, CPIK, contribution, effectiveness
an.baseline_summary_metrics()
an.negative_baseline_probability()      # check this before believing any ROI
an.incremental_outcome(...)
an.roi(); an.marginal_roi(); an.cpik()
an.response_curves(spend_multipliers=np.linspace(0, 2, 20))
an.adstock_decay(); an.hill_curves()
an.optimal_freq()                       # RF channels only
an.expected_vs_actual_data(split_by_holdout_id=True)

negative_baseline_probability() exists because the failure is common: a negative baseline means the model is borrowing from an impossible counterfactual to pay media, and every ROI downstream is inflated.

CPIK (cost per incremental KPI) is the non-revenue counterpart of ROI — the right headline metric when the KPI is signups or policies.

opt = optimizer.BudgetOptimizer(mmm)
res = opt.optimize(fixed_budget=True, budget=1_000_000,
                   spend_constraint_lower=0.3, spend_constraint_upper=0.3,
                   use_optimal_frequency=True)
res.output_optimization_summary("optimization.html", ".")

summarizer.Summarizer(mmm).output_model_results_summary("summary.html", ".")

Scenarios: fixed_budget=True (reallocate a fixed pot), fixed_budget=False with target_roi or target_mroi (flexible budget to a return threshold). The second is the more useful question and the one most teams never ask.

Visualizers: ModelDiagnostics, ModelFit, MediaEffects, MediaSummary, ReachAndFrequency — each produces Altair charts and the DataFrames behind them.


7. Meridian ↔ pymc-marketing

Concept Meridian pymc-marketing
Geo panel native, population-weighted dims=("geo",)
Media prior ROI / mROI / contribution / coefficient coefficient (saturation_beta)
Adstock geometric, binomial geometric, delayed, Weibull CDF/PDF, binomial
Saturation Hill (slope fixed at 1 for paid media) logistic, Hill, MM, tanh, root, log
Time effects knots Fourier, LinearTrend, HSGP
Reach & frequency native + optimal frequency not modelled
Organic media own slot channel_columns + role discipline
Non-media treatments own slot control_columns
Experiment calibration ROI prior + roi_calibration_period add_lift_test_measurements (likelihood)
Link function additive only identity or log
Pre-period media n_media_times > n_times not supported
Custom priors fixed parameter families any Prior on any parameter
Backend TensorFlow Probability PyMC / PyTensor

Porting caveats. A delayed adstock has no exact Meridian equivalent; Fourier seasonality has no equivalent at all; a log-link model cannot be ported. Expect different numbers, and reconcile on the decision (which channels to grow) rather than on the point estimates.

agent_mmm.backends.get_backend("meridian").translate(spec, priors=...) generates the code and lists every spec feature Meridian cannot express.


8. Common failures

Symptom Cause
Fit refused before sampling EDA guardrail found a critical issue — read mmm.eda_outcomes
Baseline absorbs almost everything knots=None on a geo model; set an explicit number
ROI posterior ≈ ROI prior The channel is not identified (flat spend, collinearity). Widen, or test
negative_baseline_probability is high Missing driver; every ROI is inflated
Loader errors on shape Panel is not rectangular, or media/KPI time axes disagree
ROI in KPI units, not money Non-revenue KPI without revenue_per_kpi
A price variable appears with a ROI It was loaded as media instead of non_media_treatments
Frequency recommendation missing Channel loaded as media rather than reach/frequency