API overview

InterventionalMean(trt, outcome, adjustment, shift)

Modified treatment policy contrast vs natural policy (LMTP TE grid).

MediationContrast(trt, outcome, adjustment, mediators, shift)

Interventional NDE / NIE / TE grid under shifted exposure.

LongitudinalPolicy(trt, outcome, adjustment, shift, treat_lag, outcome_lag)

Pathway exposure at treat_lag on AUC outcome at outcome_lag (temporal ID).

DiscreteTreatmentPolicy

Modified treatment policy on a finite exposure. Recode maps, a static do(A = a*), or a user function (a, wrow) -> a' (R lmtp shift). mtp=true when the rule depends on the natural value of A.

DiscreteInterventionalMean(trt, outcome, adjustment, policy)

L2 mean under a DiscreteTreatmentPolicy, contrasted with the natural policy.

msm_contrast(result, i, j) -> NamedTuple

Wald inference for $\tau_i - \tau_j$ using the joint covariance in result.

msm_contrast(result, c) -> NamedTuple

Wald inference for the linear form $c^\top\tau$ with $\mathrm{Var}=c^\top\Sigma c$.

suggest_family_outcome(y) -> Symbol

Return :binomial when all non-missing values lie in $\{0, 1\}$; :negbin or :poisson for nonnegative integer counts (overdispersion heuristic); otherwise :gaussian. Use with recommend_run_options(...; outcome=) or pass the result as family_outcome on LMTP runners (#34, #36).

IdentificationCertificate

Application-layer certificate wrapping CausalDynamics.IdentificationResult with column symbols.

identification_certificate(result, trt, outcome; adjustment, mediators, source, temporal_lags) -> IdentificationCertificate

certificate_dict(cert) -> Dict{String, Any}

CausalTargeted

Cross-fitted targeted inference: LMTP, Super Learner, certificates, and grid execution. Identification is delegated to CausalDynamics.jl. Mediation EIF / TE / NDE / NIE live in CausalMediation.jl (using CausalMediation).

Small-n profiles, positivity atlases, and sensitivity helpers target conservation and other low-sample causal applications.

Documentation

• Methods ↔ literature: docs/src/methods.md
• Full bibliography (DOIs / BibTeX keys): docs/src/references.md
• Small-n checklist: docs/src/small_n.md

Canonical papers: Díaz et al. (2023) LMTP; van der Laan & Rose (2011) TMLE; Cinelli & Hazlett (2020) sensitivity. For mediation, see CausalMediation (Díaz & Hejazi 2020; Liu et al. 2024).

recommend_run_options(n; engine, n_mediators, rich) -> NamedTuple

Kwargs suitable for run_lmtp_grid / run_mediation_grid / execute_estimand under a small-n-first policy. Pass outcome= (a column vector) to add family_outcome via suggest_family_outcome.

* Parallel remains off by default for memory safety; set parallel=true explicitly.

run_lmtp_grid(data, trt, outcome; baseline, kwargs...) -> DataFrame

Cross-fitted SuperLearner LMTP TMLE grid matching R run_lmtp_grid() (shift_scale = "z").

Uses clamp-aware hybrid targeting: when many observations hit clamp bounds, the TMLE fluctuation is down-weighted toward g-computation.

Defaults:

• density_ratio = :gaussian (stable at sheep n; use :hybrid / :classification for large n)
• cv_trunc = false (prespecified trunc; opt-in variance heuristic is not cross-validation)
• estimator = :tmle (score-solving; pass :sdr / :eif / :itmle as needed)
• epochs = 1 (do not inherit mediation-grid epochs=30)
• simultaneous = true adds multiplier-bootstrap simultaneous bands
• parallel = true when Threads.nthreads() > 1
• cache_nuisances = true reuses fold outcome / exposure models across δ

Quantile clamping creates boundary masses under a continuous treatment law. Finite score-based limits are therefore labelled :approximate_clamped_policy, not claimed as regular nonparametric EIF intervals. Overlap, truncation and weakened targeting require empirical calibration for the selected target.

run_repeated_outcome_msm(df, treatment, outcomes; baseline, strata, propensity,
                         folds, learners, rng, handle_missing, estimator, cluster)
    -> NamedTuple

Estimate $\tau(t)$ for binary point treatment and several outcomes with a joint influence-function covariance.

Returns (estimates, se, covariance, ic, outcomes, n, positivity, missingness, …). Use msm_contrast for linear forms $c^\top\tau$ (e.g. $\tau(t_3)-\tau(t_2)$).

Missingness uses a shared sample across times (complete-profile $R$). estimator=:tmle (default) applies a per-fold clever-covariate fluctuation; :eif is the untargeted AIPW one-step.

strata may be one Symbol or a vector of symbols. Nuisance models are still fit on the full eligible sample, with these columns added to baseline, while targeting and Hajek standardisation are conditional on each joint stratum. propensity may be a known scalar, column symbol, or input-row-aligned vector; known values bypass treatment fitting but retain positivity diagnostics.

cluster may be a column Symbol in df or a length-nrow(df) id vector. When set, $\widehat{\Sigma}$ is cluster-robust (sampling hierarchy). This does not change the estimand to BLUP / partial pooling.

run_parametric_repeated_msm(df, treatment, outcomes; baseline, design, target, ...)
    -> NamedTuple

Estimate a parametric MSM by GLS projection of the unstructured repeated-outcome IF estimates from run_repeated_outcome_msm.

strata and propensity are passed through to the unstructured fit. A stratified projection requires an explicit K*T × p design for target=:tau or 2*K*T × p for target=:mean; symbolic T-row designs are rejected.

Returns (coefficients, se, covariance, coef_names, fitted_tau, design, target, outcomes, n, positivity, missingness, …).

positivity_report(data, trt; deltas, stratify_by, lower_q, upper_q, shift_scale, kwargs...) -> DataFrame

Tidy atlas of support / clamp diagnostics across the δ-grid and strata.

Uses support_diagnostics and additive_clamp_diagnostics. Statuses: ok, weak_support, unsupported_shift.

sensitivity_report(est, se; n, alpha, r2_grid) -> DataFrame

One-row tipping point plus a small grid of partial-R² calibrations.

SequentialPolicy(treatments, outcome, baseline; time_vary, shift, policies)

Time-ordered treatments A_1,…,A_T, baseline covariates L_0, and optional time-varying covariates time_vary[t] observed before A_t.

Empty policies selects the numeric additive-shift path. A nonempty vector of DiscreteTreatmentPolicy (length T, or length 1 broadcast to every time) selects dummy-coded factor recodes. Mixed continuous and categorical A_t is not supported.

estimand_from_query(query::CausalQuery, adjustment; mediators, shift, policies, treatments, time_vary) -> Estimand

Map a CausalDynamics query to a typed estimand.

• TotalEffectQuery → InterventionalMean
• MediationQuery → MediationContrast
• InterventionalPolicyQuery → DiscreteInterventionalMean when query.shift or policies is a DiscreteTreatmentPolicy; otherwise InterventionalMean
• TemporalEffectQuery → LongitudinalPolicy by default (single lagged column). Pass nonempty policies and wide treatments (:A1, :A2, …) for SequentialPolicy.

nested_sl_candidate(learners; name=:esl, metalearner=:nnls) -> NestedSLCandidate

Build a nested ensemble candidate for metalearner=:cv_selector.

has_makie() -> Bool

Return true when the optional CausalTargetedMakieExt plotting extension is loaded. Loading a Makie backend such as CairoMakie loads Makie and activates the extension.

mtp_curve!(ax, shift, estimate, lower, upper;
    clamp=nothing, estimand=nothing, panel_mode=false,
    ribbon_alpha=0.18, strip_gap_fraction=0.020,
    strip_height_fraction=0.055)

Draw already-estimated modified-treatment-policy (MTP) effects into an existing Makie Axis. This function performs no causal estimation.

The four required vectors contain shift values, point estimates, and lower and upper interval limits. estimand may contain TE, NDE, and NIE labels and defaults to TE for every row. clamp contains optional proportions clamped by the treatment policy; finite values are squished to [0, 1]. Missing or non-finite clamp values are omitted. Required numeric values must be finite, lower <= upper, and all vectors must have equal lengths.

Rows are copied and sorted by shift within the stable estimand order TE, NDE, NIE. Clamp values repeated across estimands must agree at each shift. The returned named tuple contains plot handles plus series and clamp_geometry metadata, making the result composable and inspectable without mutating inputs.

Keywords

• panel_mode=false: use compact line and marker sizes suitable for a manually composed faceted layout when true.
• ribbon_alpha=0.18: interval-ribbon opacity.
• strip_gap_fraction=0.020: gap below the effect range as a fraction of its y span.
• strip_height_fraction=0.055: clamp-strip height as a fraction of its y span.

plot_mtp_curve(shift, estimate, lower, upper;
    clamp=nothing, estimand=nothing, title=nothing,
    xlabel="Shift (SD units)", ylabel="Estimated effect (95% CI)",
    figure_size=(8.5, 4.5), base_size=12,
    ribbon_alpha=0.18, strip_gap_fraction=0.020,
    strip_height_fraction=0.055) -> Figure, Axis

Create one complete Makie MTP effect-curve figure and return (figure, axis). The function visualises supplied estimates and intervals; it does not estimate causal effects. Intervals may be pointwise or simultaneous—the configurable ylabel should describe whichever interval the caller supplied.

figure_size is measured in inches. The default physical canvas is 8.5 × 4.5 inches, represented internally at 120 Makie layout units per inch. title is left aligned. The remaining data and strip keywords have the same meaning and validation as mtp_curve!. If no finite clamp values are supplied, the clamp strip and colourbar are omitted. Only estimands present in the data appear in the top legend, ordered TE, NDE, NIE.

Export at exact physical size

For a returned fig, PDF uses pt_per_unit = 72 / 120; 320-dpi PNG uses px_per_unit = 320 / 120:

save("mtp_curve.pdf", fig; pt_per_unit = 72 / 120)
save("mtp_curve.png", fig; px_per_unit = 320 / 120)

plot_mtp_curve(df;
    shift=:delta, estimate=:est, lower=:lwr, upper=:upr,
    clamp=:clamp, estimand=:estimand, kwargs...) -> Figure, Axis

DataFrame convenience interface for plot_mtp_curve. Its defaults match the output of run_lmtp_grid, so plot_mtp_curve(grid) works directly. Required column selectors are shift, estimate, lower, and upper. The estimand column is optional and defaults to TE when absent or when estimand=nothing; the optional clamp column is similarly ignored when absent or disabled. A single error lists every missing required column. Column vectors are never mutated.

Load a Makie backend such as CairoMakie to activate this method. Other keywords, including title, xlabel, ylabel, and figure_size, are forwarded to the vector API. To plot simultaneous bands returned by run_lmtp_grid, pass lower=:lwr_sim, upper=:upr_sim, and an appropriate ylabel.