Response-scale direct (controlled) effect of a predictor on a node

The controlled direct effect holds all mediators at their observed values and changes only from, so only the arrow(s) from from directly into to operate. Reported as the population-average change in the chosen target functional of to for a one-SD (numeric) or first-to-second-level (factor) change in from. The fitted direct coefficients are attached as a coefficients attribute.

Usage

direct_effects(
  object,
  from,
  to,
  component = 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,
  draw = NULL,
  n_sim = NULL,
  ...
)

Arguments

object: A drm_sem object.
from: Predictor variable or node name.
to: Endogenous target node.
component: Optional component filter for the attached coefficient table.
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). Non-mean targets simulate the outcome from its family (OQ-11) — most useful when a path moves only sigma/zi/nu, which can shift a tail probability or quantile while leaving the mean nearly unchanged.
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.
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 data frame (from, to, scale, target, estimate, conf.low, conf.high) with a coefficients attribute.

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.

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)
# Controlled direct effect of temp on abundance, with parametric uncertainty.
direct_effects(sem, from = "temp", to = "abundance",
               uncertainty = "parametric", nsim = 50)
} # }