Methods and literature

This page maps CausalMediation APIs to the papers that define the estimands, identification conditions, and estimators. Implementations are Julia-native analogues of ideas in the modern mediation literature (including R crumble / medoutcon); they are not line-for-line ports. Full bibliographic entries are in References. Keys such as diaz2020mediation match references.bib in the CDCS book. Engine naming (:interventional, not "RI") is summarised in Naming.

Counterfactual data and mediation

Counterfactual-data designs can provide information beyond ordinary observational and interventional distributions for some nested or path-specific queries. That possibility is relevant to natural direct effects, but identification of the counterfactual query belongs upstream in CausalDynamics. This package currently estimates the mediation functionals supported by its MediationSpec and does not claim a general counterfactual-data identification algorithm. A future bridge should consume an explicit identification certificate rather than infer cross-world information from the mediator data frame.

Interventional (randomised intermediate) effects

Scientific problem. Natural direct and indirect effects require cross-world independence assumptions that fail when a post-treatment variable confounds the mediator–outcome relation (intermediate confounding). Interventional (randomised interventional) effects replace the natural mediator law with a random draw from an interventional mediator distribution, recovering TE / NDE / NIE decompositions under weaker conditions (Vansteelandt & Daniel, 2017; Díaz & Hejazi, 2020; Liu et al., 2024).

Continuous MTP. Treatment shifts follow CausalTargeted ShiftPolicy (z-scale or natural scale, quantile clamps). Nested Monte Carlo draws mediators under shifted treatment; outcome regressions are cross-fitted Super Learners.

Factor treatment. Interventional TE / NDE / NIE also admit a recode MTP on a finite A (DiscreteTreatmentPolicy on both MediationSpec arms; default identity versus recode). Outcome and mediator regressions dummy-code A; treatment density ratios reuse CausalTargeted Díaz–Williams classifiers. Nested Monte Carlo for continuous M is unchanged. Natural / organic / recanting-twin / controlled-direct families, nonempty moc, and run_mediation_grid remain numeric-A only. Mixed ShiftPolicy / discrete arms throw.

Uncertainty contract. Constant discrete treatment arms, empty moc, uniform weights and estimator=:onestep use both outcome and mediator-stage residual corrections. The mediator correction is part of the two-stage EIF; an identity density ratio does not justify dropping it. Check overlap and nuisance-model assumptions before interpreting the resulting intervals. Static factor arms share an ordinary propensity fit, preserving exact zero weights off the assigned arm. Remaining finite-sample undercoverage in the synthetic calibration is documented in the CDCS uncertainty report; these intervals are asymptotic and have not demonstrated nominal coverage throughout the tested small-sample settings.

Other routes retain point estimates but return NaN inferential SEs and limits, with an inference_status explaining the restriction. These include plug-in fits, the current outcome-only :tmle fluctuation, factual-treatment dependent recodes, continuous clamped shifts, intermediate-confounder targets and IPCW fits without a matching joint score. Continuous clamping creates boundary masses. Nonempty moc requires the additional stages of its nested functional, rather than the empty-moc EIF. No estimator or target is silently substituted to supply an interval. Identical arms give an exact zero contrast. mediation_n_mc_sweep diagnoses integration error; it does not measure sampling uncertainty. The existing antithetic draws are retained.

Minimal DAG (no intermediate confounder):

using CausalDynamics, Graphs

g = DiGraph(4)
add_edge!(g, 1, 2); add_edge!(g, 1, 3); add_edge!(g, 1, 4)
add_edge!(g, 2, 3); add_edge!(g, 2, 4); add_edge!(g, 3, 4)
id = identify(
    g, MediationQuery(:A, :Y, [:M]; effect_kind = :interventional);
    node_names = Dict(1 => :W, 2 => :A, 3 => :M, 4 => :Y),
)
(id.strategy, id.adjustment, id.mediators, id.moc)

(:mediation_interventional, [:W], [:M], Symbol[])

With intermediate confounding, CausalDynamics can populate id.moc; estimation must pass those symbols into MediationSpec.

Natural, organic, and controlled direct effects

Natural effects share the identification gate with CausalDynamics: nonempty moc throws. Organic and controlled-direct paths are available for specialised contrasts; interpret them against the cited definitions, not as drop-in replacements for interventional TE/NDE/NIE.

ControlledDirect holds a continuous mediator at the specified value and averages cross-fitted outcome-regression contrasts. Omitting estimator selects :plugin for this effect; explicit :onestep and :tmle throw. A fixed value of a continuous mediator has no ordinary nonparametric influence function, so the treatment-only residual correction is invalid. The returned point estimate depends on the outcome model. Standard errors and confidence limits are NaN until a suitable inference method is implemented. Nonempty moc is refused: its post-treatment distribution would also need to be integrated under each treatment arm.

Nested units / clustering

When observations nest in clusters, CausalDynamics owns generative nested $U$ (RandomEffectSpec, unroll_hierarchical_dag). CausalTargeted owns sampling hierarchy via cluster= on repeated-outcome / parametric MSM (cluster-robust IF sandwich). CausalMediation should reuse the same missingness stratum rules and, when cluster-robust mediation IF lands, the same cluster= contract — without introducing MixedModels or BLUP estimands here. Hierarchical longitudinal mediation ($A_t$, $M_t$) remains deferred (BOUNDARIES).

Recanting twins and path-specific effects

Recanting-twin (RT) constructions isolate path-specific effects when intermediate confounding blocks natural effects (Vo–Díaz line of work; R crumble effect="RT"). CausalDynamics may suggest moc from graph witnesses; CausalMediation estimates RT contrasts via RecantingTwinMediation.

using CausalMediation, StableRNGs

df, _ = simulate_recanting_twin_mediation(180; rng = StableRNG(11))
first(names(df), 6)

5-element Vector{String}:
 "W"
 "A"
 "M1"
 "M2"
 "Y"

Cross-fitting, Super Learner, and diagnostics

Nuisances reuse CausalTargeted profiles (DEFAULT_SL_LEARNERS, SMALL_N_SL_LEARNERS, …). Fold caches (MediationFoldCache) fit a single CausalTargeted covariate schema on the cleaned analysis frame so string and categorical columns encode consistently across folds.

Missing outcomes and covariates

Mediation runners forward incompleteness to CausalTargeted handle_missing_data. run_mediation_grid, run_mediation_scalar, run_tmle3_nde, and conjugate_mediation_bootstrap (via run_mediation_scalar_ppl) accept handle_missing (:drop default; :ipcw reweights interventional, natural, organic, and recanting-twin influence summaries and the controlled direct plug-in contrast; for the conjugate bootstrap it draws rows with IPCW probabilities; :impute / :ipcw_impute for covariate gaps). Missing mediators are treated as covariates for that policy (complete-case or mean-impute with indicators), not as a separate mediation-specific missingness estimand. Structural MAR/MNAR claims remain CausalDynamics certificates; this package does not invent fills inside the EIF. Full policy catalogue: CausalTargeted Missingness.

Do not pass learners=(:mean,) alone for treatment contrasts.

Use validate_mediation_sweep before archiving a nested-MC stability table. It checks the result-table contract (required columns, positive n_mc, finite estimates and non-negative standard errors); it does not test exchangeability, positivity or other causal assumptions, which remain part of the certificate.

Optional Lux Riesz representers load via weakdep (fit_riesz_representer after using Lux); riesz_available() reports whether the extension is loaded. Riesz nuisances are separate from representation (encoder → codes).

High-dimensional mediators via codes

Raw spectra or images are not MediationSpec mediators. Compress them first with CausalDynamics RepresentationSpec and encode_to_panel, then treat the code columns as mediators:

using CausalDynamics, CausalMediation, CausalTargeted, DataFrames

# S::Matrix (n × p), df has :A, :W, :Y
spec_rep = RepresentationSpec(
    :spectrum, [:z1, :z2], encode;  # encode: n×p → n×2 (Lux CNN/MLP or linear map)
    role = :definitional,           # or :measurement
)
cert = representation_certificate(spec_rep)
wide = encode_to_panel(df, S, spec_rep)

med = MediationSpec(:A, :Y; mediators = [:z1, :z2], covariates = [:W])
# Fit / freeze the encoder on training folds before cross-fitted EIF (DeepMed habit).
# res = run_mediation(med, wide; …)

• :definitional: the estimand is about the codes themselves (M := g_θ(S)).
• :measurement: codes are noisy observations of a latent biological mediator; state that in run metadata via cert.
• Do not expand the Lux Riesz scaffold into a full CNN here; keep Riesz as an optional nuisance for high-dim moc / features already in tabular form.

Executable sketch: CausalDynamics examples/representation_bridge.jl. Application stress (codes → mediation / LMTP): CausalTargeted deepscmestimation_stress.qmd. Additive generative L3 on codes (abduction) lives in CausalDynamics Phase 2b, not in the mediation EIF path.

What we deliberately do not claim

• Full option parity with R crumble / medoutcon / medRCT
• Survival or competing-risks mediation (document as future scope)
• Replacing CausalTargeted for non-mediated LMTP

See Comparison and BOUNDARIES.md.