Causal Inference 03: Structural Mediation

Veranda Home's CMO believes something no flat MMM can even express: TV doesn't sell patio sets this week — it builds awareness, awareness feeds consideration, and consideration converts to sales over months. Notebook 02 ended with a warning: conditioning on a funnel variable amputates the effect flowing through it. The fix is not to ignore the funnel — it's to model it. This guide mirrors nbs/causal/causal_03_structural_mediation.ipynb: the brand-funnel world is posited as a structural causal model and fit jointly against binomial and Likert survey data with StructuralNestedMMM — then every structural claim is graded against the world's sealed answer key.

1 — The world: spend, sales, and two surveys

The brand-funnel world (make_brand_funnel in src/mmm_framework/synth/dgp.py) ships the standard dashboard — 156 weeks, four channels, sales, price — plus the two survey tracks a real brand team would run. The structure the sealed key encodes:

• TV → awareness. An AR(1) latent state on the logit scale (persistence ρ = 0.85 — brand stock decays slowly), observed through a weekly binary tracker: aware_count out of n respondents. The tracker is realistically imperfect: only 115 of 156 weeks observed (~26% missing) with weekly sample sizes swinging from 152 to 599. A binomial measurement model turns that varying n into varying precision instead of pretending every week is equally trustworthy.
• Display + Social + awareness + price + demand → consideration. A latent index observed through a 5-point Likert survey (ordered category counts, 122 of 156 weeks).
• Consideration + Search (+ demand, price) → sales. Search is a pure direct-response channel; TV, Display and Social are fully mediated — the sealed mediated share is 1.0 for the brand channels and exactly 0.0 for Search.
• A latent demand trend confounds consideration and sales — and has no survey of its own.

The awareness state equation, in the model's own terms: \( z_t = \mu + \rho\,(z_{t-1} - \mu) + \beta_{\mathrm{TV}}\, f(s_t) + \varepsilon_t \), with the tracker observing \( \mathrm{count}_t \sim \mathrm{Binomial}(n_t,\, \sigma(z_t)) \). Persistence ρ is the parameter a media planner actually wants: the implied brand-stock half-life is \( t_{1/2} = \ln 0.5 / \ln \rho \).

2 — The wrong model first: a flat MMM

Hand this world to the standard four-channel MMM (surveys ignored — a flat model has nowhere to put them). Two honest observations, both measured in the notebook run:

1. The flat model's totals are not crazy. Mediation by itself doesn't bias a total-effect estimate — the effect still flows from spend to sales. Graded against the sealed key, the flat contribution errors are TV +27%, Display −25%, Social +39%, Search −0%, and all four truths land inside their 90% intervals. (The latent demand confounder does the damage here, mildly.)
2. The flat model has no opinion about anything the CMO actually asked. How long does brand stock last? Which funnel stage does each channel move? What is a survey point worth? Those aren't parameters it has.

3 — Positing the structure

Now say what we believe, as a graph. StructuralNestedMMM takes the funnel as configuration: each mediator declares its drivers (channels, parent mediators, controls, latent factors), its state dynamics, and its measurement — binomial for the awareness tracker, cumulative-logit ordered for the Likert. The latent demand factor is declared with no measurement of its own: it is identified purely by the co-movement it induces between consideration and sales.

from mmm_framework.mmm_extensions import (
    StructuralNestedConfig,
    binary_survey_mediator,
    likert_mediator,
    latent_demand_factor,
)

cfg = StructuralNestedConfig(
    mediators=(
        binary_survey_mediator(
            "awareness", ["TV"], persistence="high", affects_outcome=False
        ),
        likert_mediator(
            "consideration",
            ["Display", "Social"],
            parents=["awareness"],
            controls=["Price"],
            latent_factors=["demand"],
            n_categories=5,
        ),
    ),
    latent_factors=(latent_demand_factor("demand"),),
)

Everything — media effects, funnel edges, survey measurement, latent demand, sales — becomes one PyMC graph, so survey information flows backwards to discipline the media coefficients, and uncertainty flows forward from the surveys into every causal claim:

from mmm_framework.mmm_extensions import StructuralNestedMMM
from mmm_framework.synth.dgp import make_brand_funnel

world = make_brand_funnel()               # sealed answer key in world.notes
funnel = StructuralNestedMMM(
    world.spend.to_numpy(float), world.y.to_numpy(float),
    world.channels, cfg,
    mediator_data={"awareness": world.notes["awareness_counts"],
                   "consideration": world.notes["consideration_counts"]},
    mediator_trials={"awareness": world.notes["awareness_trials"]},
    X_controls=world.controls.to_numpy(float), control_names=["Price"],
    index=world.weeks,
)
funnel.fit(draws=500, tune=1000, chains=4, nuts_sampler="numpyro")

mediation = funnel.get_mediation_effects()   # exact posterior counterfactuals
pathways = funnel.get_pathway_effects()      # per-path decomposition
roas = funnel.get_channel_roas()

4 — The joint fit, graded parameter by parameter

This is the one genuinely expensive fit of the series: full NUTS, 4 chains × 500 draws after 1,000 tuning steps — 741 seconds (~12 minutes) in the notebook run, max r-hat 1.067, under the 1.1 bar the framework's own recovery test pins. (Approximate methods like MAP are documented-unstable for latent-state models; the series never uses them here.) Here is what a flat MMM could never produce — the mechanism itself, graded against the sealed key:

Measured — posterior mean and 90% interval per structural parameter vs the sealed true value (near-black tick). ρ = 0.854 vs 0.85 true; TV→awareness 1.00 vs 0.9; awareness→consideration 1.99 vs 2.5; price→consideration −0.98 vs −0.8; demand→consideration 0.59 vs 0.6. All five truths inside their 90% intervals. Numbers: nbs/artifacts/causal_03_mediation_recovery.json.

The persistence posterior is the headline for the media plan: ρ = 0.854 implies a brand-stock half-life of ≈ 4.4 weeks (sealed truth: ρ = 0.85 ⇒ 4.3 weeks). That single number — how fast the awareness a TV flight builds decays to half — is a flighting-cadence decision no flat MMM could have produced, recovered here from a noisy, gappy survey.

5 — Three unobserved series, recovered through their footprints

The model also had to infer three time series it never observed directly: the true awareness probability (through the binomial tracker — corr with truth 0.985), the latent consideration level (through the Likert counts — corr 0.995), and — hardest — the latent demand factor, which has no survey at all and is identified only by the co-movement it induces between consideration and sales (|corr| 0.951):

Measured — the recovered latent demand series (posterior mean, 90% band) against the true series from the sealed key, aligned for display (a latent with no measurement is identified up to sign/scale). Correlation with truth: 0.951. The awareness and consideration states recover even more tightly (0.985, 0.995); the notebook plots all three.

6 — The mediation decomposition

The headline for the CMO: how much of each channel's effect flows through the funnel? These are exact posterior counterfactuals — the model re-runs its own world with each channel off, holding the inferred shocks fixed — not back-of-envelope path products.

Measured — direct vs through-the-funnel contribution per channel (KPI units, notebook run). Estimated proportion mediated: TV 1.26, Display 0.69, Social 0.78, Search −0.00 — against sealed truths of 1.0, 1.0, 1.0, 0.0. TV's direct effect is −78.7k ± 57.5k: indistinguishable from zero, so its mediated-share posterior brackets 1.0. Search shows exactly no funnel path.

The funnel story survives grading: the brand channels flow through the funnel; Search doesn't. This is also the design-review guard the framework itself tests — mediated totals must be genuinely nonzero for brand channels (an in-graph centering bug would make them identically zero), and Search's mediated share must sit at ~0.

7 — What the structure bought (and what it didn't)