API overview

CausalMediation

Cross-fitted mediation estimation for the CDCS stack: interventional (RI), natural, organic, controlled direct, and recanting-twin path-specific effects.

Depends on CausalDynamics for identification certificates and CausalTargeted for Super Learner, ShiftPolicy, fold helpers, and MTP density ratios.

Entry points

• MediationSpec / run_mediation — typed estimate
• run_mediation_grid — δ-grid DataFrame API
• plan_mediation / spec_from_identification — ID bridge
• decompose — TE / NDE / NIE (or path) extraction

Documentation

• Documenter site: https://simonab.github.io/CausalMediation.jl/dev/
• Design: DESIGN.md · Boundaries: BOUNDARIES.md · Naming: NAMING.md

MediationEffect

Supertype for mediation estimand families (interventional, natural, organic, recanting-twin, controlled direct).

Interventional (randomised intermediate) mediation — RI / Vansteelandt–Daniel.

Natural direct/indirect effects (Pearl / Robins–Greenland); requires empty moc.

Organic direct/indirect effects (Lok 2015).

Recanting-twin / path-specific effects (Vo–Díaz).

Controlled direct effect with mediators fixed at m.

MediationSpec(treatment, outcome; mediators, covariates, moc, policy_d0, policy_d1, effect)

Typed mediation estimand: treatment, outcome, mediators, baseline covariates, intermediate confounders (moc), shift policies, and effect family.

Arguments

• mediators: mediator column symbols (required)
• covariates: baseline adjustment set (often from IdentificationResult.adjustment)
• moc: intermediate confounders; must be empty for NaturalMediation
• policy_d0 / policy_d1: CausalTargeted ShiftPolicy for the two arms
• effect: InterventionalMediation() by default

See also plan_mediation, run_mediation, assumptions.

MediationResult

Point estimates, SEs, influence curves, and diagnostics for a mediation run.

Fields include estimates / se (typically :te, :nde, :nie), a full δ-grid table (DataFrame), and diagnostics (n_mc, estimator, …). Use decompose for a compact TE/NDE/NIE (or path) NamedTuple.

assumptions(spec) -> NamedTuple

Named assumption checklist shared by identify gates and run_mediation.

assert_natural_admissible!(spec)

Refuse natural effects when intermediate confounders (moc) are present.

assert_moc_for_ri!(spec)

Document that interventional effects admit moc (no-op gate for API symmetry).

decompose(result) -> NamedTuple

Extract TE / NDE / NIE (or path-specific components) from a MediationResult.

plan_mediation(spec, id_result; shift) -> MediationSpec

Certificate-first planning: merge adjustment / mediators / moc from a CausalDynamics IdentificationResult into a concrete MediationSpec (mirrors CausalTargeted plan_mtp).

Empty fields on spec are filled from the certificate; nonempty fields are kept. Optional shift replaces both policy_d0 and policy_d1.

spec_from_identification(id_result; effect, policy_d0, policy_d1) -> MediationSpec

Build a MediationSpec from an IdentificationResult whose query is a CausalDynamics MediationQuery.

Uses id_result.adjustment, .mediators, and .moc. When effect is the default :interventional and the query carries a different effect_kind, that kind is preferred.

run_mediation(spec, data; folds, learners, estimator, deltas, n_mc, kwargs...) -> MediationResult

Canonical mediation entry point. Dispatches on spec.effect and returns a MediationResult whose table is the δ-grid from run_mediation_grid.

Keyword arguments

• estimator: :plugin, :onestep (default), or :tmle
• deltas: MTP shift grid (defaults to CausalTargeted default_deltas())
• n_mc: nested mediator Monte Carlo draws per unit (default 32)
• folds, learners, parallel, cache_nuisances: Super Learner / cross-fit controls from CausalTargeted

Natural effects with nonempty spec.moc are refused by assert_natural_admissible!.

run_mediation_grid(data, trt, outcome; covar, mediators, moc, deltas, estimator, effect, kwargs...) -> DataFrame

Mediation δ-grid as a DataFrame (rows for TE / NDE / NIE × δ × stratum). Supports optional moc intermediate confounders and estimator ∈ (:plugin, :onestep, :tmle).

Prefer run_mediation with a MediationSpec when you already have an identification certificate. Pass effect to select natural / organic / RT / controlled-direct families (default InterventionalMediation()).

run_mediation_scalar(data, trt, outcome; mediators, covar, moc, kwargs...) -> DataFrame

Binary contrast d0=0 vs d1=1 with NDE / NIE / TE rows.

run_mediation_scalar_ppl(data, trt, outcome; mediators, covar, method, kwargs...) -> DataFrame

Scalar mediation via :eif (default, run_mediation_scalar) or :conjugate_bootstrap.

run_tmle3_nde(data, treatment, outcome; baseline, mediators, folds, rng) -> DataFrame

Cross-fitted SuperLearner interventional NDE with one-step TMLE targeting.

eif_psi_interventional(Q̄, Q_at_M, Q_obs, y, H_at, H_am, ρ_am) -> Vector

Uncentred EIF contributions for ψ(at, am).

mediator_density_ratio_vs_obs(m_obs, μ_pol, μ_obs, σ; trunc) -> Vector

g(M|a_pol,·) / g(M|A_obs,·) under independent Gaussian mediator conditionals.

decompose_mediation_eif(ic10, ic00, ic11) -> NamedTuple

Map ψ EIF vectors to NDE / NIE / TE uncentred influence contributions.

MediationFoldCache

Per-fold SuperLearner fits reused across δ values. Policy-specific predictions still depend on a_nat / a_shift.

build_mediation_fold_cache(df, outcome, trt, covar, mediators, folds, rng; learners, moc) -> MediationFoldCache

Cross-fit Super Learner fits for outcome, mediators, optional moc, and exposure, reused across δ values on a mediation grid.

mediation_n_mc_sweep(data, trt, outcome; covar, mediators, n_mc_values, delta, kwargs...) -> DataFrame

Re-fit mediation NDE/NIE/TE at a single delta for each n_mc in n_mc_values. Useful for checking whether nested-MC noise dominates inference.

mediation_stability_summary(sweep::DataFrame; central_estimands=("TE", "NDE", "NIE")) -> NamedTuple

Summarise a mediation_n_mc_sweep table: SE vs n_mc, and whether signs of central estimates are stable across Monte Carlo depths.

mediation_stability_markdown(sweep; title) -> String

Render a Markdown table of TE SEs and sign-stability from a mediation_n_mc_sweep result (via mediation_stability_summary).

simulate_mediation(n; ...) -> (df, truth)

Binary-A linear mediation DGP (same as CausalTargeted).

simulate_continuous_mtp_mediation(n; ...) -> (df, truth)

Continuous-exposure mediation DGP for MTP δ-grids (forwards to CausalTargeted).

simulate_intermediate_confounding_mediation(n; ...) -> (df, truth)

Mediation DGP with a post-treatment intermediate confounder L (moc).

simulate_recanting_twin_mediation(n; ...) -> (df, truth)

Two-mediator DGP with a recanting structure: A → M1 → M2 → Y and A → M2, so natural effects are not identified without path-specific (RT) assumptions.

TargetTrialMediation

High-level constructor over interventional (RI) effects with trial-style policy language (Moreno-Betancur et al. 2021 / medRCT semantics).

target_trial_mediation(...) -> MediationSpec

Build an interventional MediationSpec from target-trial contrasts. Policies use raw additive shifts of intervention_d0 / intervention_d1 (SD-scale via ShiftPolicy).

fit_riesz_representer(X, y; kwargs...) -> Any

Fit a Riesz representer for high-dimensional mediators / moc. Requires using Lux so the weakdep extension loads. Without Lux, throws.

riesz_available() -> Bool

Return true when the Lux extension is loaded.

prepare_ppl_mediation_spec(g, treatment, outcome, data, covar, mediators; node_names) -> NamedTuple
prepare_ppl_mediation_spec(treatment, outcome, data, covar, mediators; kwargs...) -> NamedTuple

Prepare a NamedTuple for PPL / RxInfer-style mediation workflows. With a graph and node_names, delegates to CausalDynamics prepare_for_rxinfer when available; otherwise returns a generic identifiable spec.

conjugate_mediation_bootstrap(df, trt, outcome, covar, mediators; n_boot, rng) -> DataFrame

Linear-Gaussian bootstrap NDE / NIE / TE (pedagogical / sensitivity check, not the main EIF path).