Total effect of a predictor on a node by simulation

Propagates a do()-style change in from through the whole DAG (all mediators respond) and reports the population-average change in the chosen target functional of to. With method = "simulate", mediators pass realized draws from their families, so effects flowing through a mediator's scale, zero-inflation, or shape (distribution-mediated paths) are included; with method = "gcomp" only the mediator means propagate.

Usage

total_effects(
  object,
  from,
  to,
  method = NULL,
  target = c("mean", "p_gt", "p_zero", "var", "quantile"),
  threshold = 0,
  prob = 0.5,
  functional = c("simulate", "analytic"),
  at = NULL,
  B = 200L,
  uncertainty = NULL,
  nsim = NULL,
  population = NULL,
  level = 0.95,
  seed = NULL,
  mediation = NULL,
  draw = NULL,
  n_sim = NULL,
  ...
)

Arguments

object: A drm_sem object.
from: Predictor variable or node name.
to: Endogenous target node.
method: "gcomp" (mean mediation: deterministic g-computation on mediator expectations, the default) or "simulate" (mediators pass realized draws from their fitted families, capturing distribution-mediated paths).
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).
functional: How a non-mean target is evaluated: "simulate" (default; draw the outcome from its family and summarize) or "analytic" (a closed-form functional of the predicted parameters — no Monte-Carlo noise). Analytic forms are offered for the gaussian and poisson families (others abort with a pointer to "simulate"), and require mean mediation (method = "gcomp") so the outcome parameters are deterministic.
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.
mediation: Deprecated alias for method ("mean" maps to "gcomp", "distribution" to "simulate"); supplying it emits a deprecation warning.
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 one-row drm_effect data frame.

Details

Feedback SEMs. When the model declares a feedback motif (see drm_cycle()), the total effect is the system's equilibrium response, computed by iterating the mean-propagation map to its fixed point rather than by a single topological sweep. Only target = "mean" is supported (the equilibrium is on the deterministic mean map), the mediation column reads "equilibrium", and if the feedback diverges (no stable equilibrium, spectral radius >= 1) the estimate is reported as NA with a warning — never a fabricated number. The mean/distribution decomposition through a cycle is out of scope, so indirect_effects() / path_effects() refuse a feedback SEM. See docs/design/10-cyclic-feedback.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.

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{
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)
# Total effect of temp on abundance, mediators allowed to respond by simulation.
total_effects(sem, from = "temp", to = "abundance",
              method = "simulate", uncertainty = "parametric", nsim = 50)
} # }