Path-specific (per-mediator) decomposition of an indirect effect

Splits the indirect effect of from on to into a contribution for each mediator, by toggling which mediators are allowed to respond. Two model-based per-mediator quantities are reported:

Usage

path_effects(
  object,
  from,
  to,
  through = NULL,
  by = c("mediator", "component"),
  effect = c("controlled", "natural"),
  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 subset of mediator node names to attribute over (defaults to all mediators between from and to).
by: "mediator" (default) reports the per-mediator inclusion / exclusion split with an interaction_remainder. "component" instead splits each mediator's indirect effect into a mean_channel (the mediator passes only its mean) and one channel per non-mean component (sigma_channel, zi_channel, ... – the drop when that component is frozen at its reference value), plus a component_remainder for the part that does not separate cleanly (the channels are not an exact partition under a nonlinear outcome).
effect: "controlled" (default) gives the model-based per-mediator / per-component decomposition above. "natural" instead reports each mediator's cross-world natural indirect effect (the nie leg when only that mediator is set to its counterfactual world), with an identified column that is FALSE when a recanting witness (another mediator that is a descendant of from and an ancestor of this one) makes the natural path-specific effect non-identified. by is ignored when effect = "natural".
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 with columns from, to, through, mediator, estimand, estimate, conf.low, conf.high. For by = "mediator" the estimand values are total_indirect, inclusion, exclusion, interaction_remainder; for by = "component" they are total_indirect, mean_channel, <component>_channel (one per non-mean component), and component_remainder. The frame also carries an identified column (NA for controlled rows; logical for natural rows).

Details

inclusion – the effect carried by X -> Mj -> Y when only Mj responds (all other mediators held at their observed values): T({Mj}) - direct.
exclusion – Mj's marginal contribution when every other mediator is already active: T(all) - T(all \ Mj).

These coincide only when the mediators act additively (parallel mediators, no downstream nonlinearity, no exposure-mediator or mediator-mediator interaction). The output therefore always includes a total_indirect row and an explicit interaction_remainder = total_indirect - sum(inclusion), which is ~0 in the additive case and non-zero otherwise – the per-mediator effects are never rescaled to force them to sum. This is a model-based decomposition, not a claim of nonparametric path-specific identification; see docs/design/02-effect-calculus.md.

References

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.

Avin C, Shpitser I, Pearl J (2005). “Identifiability of Path-Specific Effects.” In Proceedings of the Nineteenth International Joint Conference on Artificial Intelligence (IJCAI-05), 357–363.

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 (2015). Explanation in Causal Inference: Methods for Mediation and Interaction. Oxford University Press, New York.

Examples

if (FALSE) { # \dontrun{
# per-mediator attribution of temp's indirect effect on survival
path_effects(sem, from = "temp", to = "survival")
# split each mediator's effect into mean vs distributional channels
path_effects(sem, from = "temp", to = "survival", by = "component")
} # }