Indirect effect of a predictor on a node, with a distributional decomposition

The indirect effect is the simulation-based total path effect (mediators in through allowed to respond) minus the controlled direct effect. It is decomposed into a mean-mediated part (mediator means propagate) and a distribution-mediated part (the extra effect that appears when mediators pass realized draws, i.e. flowing through mediator scale / zero-inflation / shape).

Usage

indirect_effects(
  object,
  from,
  to,
  through = NULL,
  effect = c("controlled", "natural"),
  target = c("mean", "p_gt", "p_zero", "var", "quantile"),
  threshold = 0,
  prob = 0.5,
  at = NULL,
  B = 200L,
  uncertainty = NULL,
  nsim = NULL,
  population = NULL,
  level = 0.95,
  seed = NULL,
  draw = NULL,
  n_sim = NULL,
  ...
)

Arguments

object: A drm_sem object.
from: Predictor variable or node name.
to: Endogenous target node.
through: Optional set of mediator node names to route through. Defaults to all mediators between from and to.
effect: "controlled" (default) decomposes the total into a controlled direct effect (mediators at observed values) plus mean-mediated and distribution-mediated parts. "natural" reports the cross-world natural direct/indirect effects (Pearl/Imai), holding the mediators at their predicted M(x0) / M(x1) distributions; see docs/design/02-effect-calculus.md.
target: Functional of the outcome distribution to report the effect on: "mean" (default), "p_gt" (Pr(Y > threshold)), "p_zero" (Pr(Y = 0)), "var" (Var(Y)), or "quantile" (the prob-quantile). Distributional targets simulate the outcome from its family (OQ-11); see docs/design/02-effect-calculus.md. For a feedback SEM only "mean" (the equilibrium response) is defined.
threshold: Cutoff for target = "p_gt".
prob: Probability for target = "quantile" (default 0.5, the median).
at: Optional length-2 contrast values for from.
B: Number of uncertainty replicates (coefficient draws) used when uncertainty = "parametric".
uncertainty: How to propagate parameter uncertainty: "parametric" (draw coefficients from MVN(coef, vcov), the default), "none" (MLE point estimate, no interval), or "bootstrap" (refit per replicate; not yet implemented, OQ-10).
nsim: Inner distributional realizations per uncertainty draw (used for non-mean targets).
population: "conditional" (random effects held at zero, the default) or "marginal" (integrate over the fitted random-effect distribution; not yet implemented, OQ-9).
level: Confidence level for the Monte-Carlo interval.
seed: Optional RNG seed.
draw, n_sim: Deprecated aliases for uncertainty (draw = TRUE/FALSE maps to "parametric"/"none") and nsim; supplying either emits a deprecation warning.
...: Unused.

Value

A drm_effect data frame. For effect = "controlled", rows total_path, direct, indirect, mean_mediated, distribution_mediated and a target column naming the reported functional. For effect = "natural", rows total_path, natural_direct, natural_indirect, mediated_interaction.

Details

The controlled and natural direct/indirect estimands and their identification under the counterfactual framework are due to Pearl (2001), Robins & Greenland (1992), Imai et al. (2010), and VanderWeele (2015); the four-way decomposition under exposure–mediator interaction is VanderWeele (2014); the interventional estimand for multi-mediator settings is Vansteelandt & Daniel (2017). The distribution-mediated row reported here is a drmSEM construction: it isolates the Jensen-gap part of an indirect effect that flows through a mediator's higher-moment components (sigma, zi, nu), with no coefficient-product analogue. The construction sits on top of the cited mediation framework — it does not replace any of these estimands.

indirect_effects() does not take a method argument: the controlled decomposition is formed from both the mean-mediated and distribution-mediated legs, and the natural decomposition always uses distribution mediation, so neither has a single mean/distribution choice to make. The shared uncertainty, nsim, and population controls apply as elsewhere.

A non-mean target (OQ-11) is supported for effect = "controlled": every leg then reports the contrast on that functional of the outcome (e.g. the indirect change in Pr(Y = 0) or a tail quantile routed through the mediators), and the mean-/distribution-mediated split still closes (indirect = mean_mediated + distribution_mediated). effect = "natural" supports only target = "mean" (the cross-world functional contrast is open, OQ-8/OQ-11).

References

Robins JM, Greenland S (1992). “Identifiability and Exchangeability for Direct and Indirect Effects.” Epidemiology, 3(2), 143–155. doi:10.1097/00001648-199203000-00013 .

Pearl J (2001). “Direct and Indirect Effects.” In Proceedings of the Seventeenth Conference on Uncertainty in Artificial Intelligence (UAI), 411–420.

Pearl J (2009). Causality: Models, Reasoning, and Inference, 2nd edition. Cambridge University Press, Cambridge.

Imai K, Keele L, Yamamoto T (2010). “Identification, Inference and Sensitivity Analysis for Causal Mediation Effects.” Statistical Science, 25(1), 51–71. doi:10.1214/10-STS321 .

VanderWeele TJ (2014). “A Unification of Mediation and Interaction: A 4-Way Decomposition.” Epidemiology, 25(5), 749–761. doi:10.1097/EDE.0000000000000121 .

VanderWeele TJ (2015). Explanation in Causal Inference: Methods for Mediation and Interaction. Oxford University Press, New York.

Vansteelandt S, Daniel RM (2017). “Interventional Effects for Mediation Analysis with Multiple Mediators.” Epidemiology, 28(2), 258–265. doi:10.1097/EDE.0000000000000596 .

Examples

if (FALSE) { # \dontrun{
sem <- drm_sem(
  size = drm_node(drmTMB::bf(size ~ temp + habitat, sigma ~ temp),
                  family = stats::gaussian()),
  abundance = drm_node(drmTMB::bf(abundance ~ size + temp, zi ~ habitat),
                       family = drmTMB::nbinom2()),
  data = dat)
# Indirect effect of temp on abundance routed through size.
indirect_effects(sem, from = "temp", to = "abundance", through = "size",
                 uncertainty = "parametric", nsim = 50)
} # }