Package 'RobustMediate'

Description

RobustMediate provides a workflow for causal mediation analysis with continuous treatments using inverse probability weighting (IPW), diagnostic tools, and sensitivity analysis.

Main functions include:

• robustmediate() - Fits treatment, mediator, and outcome models and stores precomputed results for downstream plotting and reporting.

• plot_balance() - Displays covariate balance before and after weighting for both the treatment and mediator pathways using standardized mean differences.

• plot_mediation() - Plots estimated natural direct effects (NDE) and natural indirect effects (NIE) over the treatment range, with pointwise uncertainty bands.

• plot_sensitivity() - Displays a bivariate sensitivity surface based on E-values and sequential ignorability violations parameterized by rho.

• sensitivity_meditcv() - Computes pathway-specific mediation ITCV (medITCV) diagnostics based on Frank's impact threshold for a confounding variable framework.

• plot_meditcv() - Displays pathway-specific medITCV robustness corridors for the a-path and b-path.

• diagnose() - Produces a formatted diagnostic summary of balance, mediation effects, and sensitivity results.

Getting started

library(RobustMediate)

data(sim_mediation)

fit <- robustmediate(
  X ~ Z1 + Z2 + Z3,
  M ~ X + Z1 + Z2 + Z3,
  Y ~ X + M + Z1 + Z2 + Z3,
  data = sim_mediation,
  R = 500
)

plot(fit)
plot(fit, type = "balance")
plot(fit, type = "sensitivity")
plot(fit, type = "meditcv")
diagnose(fit)

Sensitivity interpretation

The E-value x rho surface is a bivariate robustness display rather than a single unified causal model. It is intended to help users examine how large different classes of unmeasured confounding would need to be to attenuate or nullify the estimated indirect effect.

The mediation ITCV (medITCV) is reported separately for the a-path and b-path. The indirect-effect summary is interpreted as a minimum-path robustness bound governed by the weaker pathway.

Author(s)

Maintainer: Subir Hait [email protected] (ORCID)

References

Frank, K. A. (2000). Impact of a confounding variable on a regression coefficient. Sociological Methods & Research, 29(2), 147–194.

Imai, K., Keele, L., & Yamamoto, T. (2010). Identification, inference, and sensitivity analysis for causal mediation effects. Psychological Methods, 15(4), 309–334.

VanderWeele, T. J., & Ding, P. (2017). Sensitivity analysis in observational research: Introducing the E-value. Annals of Internal Medicine, 167(4), 268–274.

See Also

Useful links:

• https://github.com/causalfragility-lab/RobustMediate

• Report bugs at https://github.com/causalfragility-lab/RobustMediate/issues

Description

Convenience accessor returning the NDE/NIE/TE curve data frame.

Usage

## S3 method for class 'robmedfit'
as.data.frame(x, ...)

Arguments

Value

A data frame with columns dose, estimand, estimate, lower, upper.

Description

Returns the original data augmented with IPW weights, fitted mediator values, and fitted outcome values from the pathway models.

Usage

## S3 method for class 'robmedfit'
augment(x, data = NULL, ...)

Arguments

Value

The original data frame with additional columns:

.ipw_weight

Stabilised inverse probability weights.

.fitted_mediator

Predicted mediator values.

.fitted_outcome

Predicted outcome values.

.resid_mediator

Residuals from the mediator model.

.resid_outcome

Residuals from the outcome model.

Examples

fit <- robustmediate(
  treatment_formula = X ~ Z1 + Z2 + Z3,
  mediator_formula  = M ~ X + Z1 + Z2 + Z3,
  outcome_formula   = Y ~ X + M + Z1 + Z2 + Z3,
  data = sim_mediation, R = 50
)
aug <- augment(fit)
hist(aug$.ipw_weight)

Description

Overlays the NDE/NIE/TE curves from two robmedfit objects on the same panel. Useful for sensitivity comparisons (e.g. different spline degrees, trimming thresholds, or model specifications).

Usage

compare_fits(
  fit1,
  fit2,
  label1 = "Model 1",
  label2 = "Model 2",
  estimands = c("NDE", "NIE")
)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
fit_a <- robustmediate(X~Z, M~X+Z, Y~X+M+Z, data=dat, spline_df=3, R=200)
fit_b <- robustmediate(X~Z, M~X+Z, Y~X+M+Z, data=dat, spline_df=6, R=200)
compare_fits(fit_a, fit_b, label1="df=3", label2="df=6")

## End(Not run)

Description

Prints a formatted diagnostics report covering balance, mediation effects, and sensitivity robustness. The output is structured so that it can be used directly (or with minimal editing) in the Results section of an applied paper. Returns the underlying results invisibly.

Usage

diagnose(x, ...)

Arguments

Value

Invisibly returns a list with elements balance, effects, sensitivity, meditcv, and meditcv_profile.

Description

Returns a publication-ready table decomposing indirect-effect robustness into pathway-specific components. Columns follow the medITCV reporting convention: pathway, coefficient, SE, t, df, observed partial r, critical r, medITCV, medITCV%, fragility classification, and tipping-point confounder r.

Usage

fragility_table(x, alpha = 0.05)

Arguments

Value

A data frame with three rows (a-path, b-path, indirect effect) and columns pathway, coefficient, SE, t_stat, df, r_obs, r_crit, medITCV, medITCV_pct, fragility, tipping_r_confounder, and bottleneck.

Examples

data(sim_mediation)
  fit <- robustmediate(
    X ~ Z1 + Z2, M ~ X + Z1 + Z2, Y ~ X + M + Z1 + Z2,
    data = sim_mediation, R = 20, verbose = FALSE
  )
fragility_table(fit)

Description

Returns a one-row summary of the fit: sample size, bootstrap reps, reference dose, percentage mediated, and the two tipping-point sensitivity values.

Usage

## S3 method for class 'robmedfit'
glance(x, ...)

Arguments

Value

A one-row data frame.

Examples

fit <- robustmediate(
  treatment_formula = X ~ Z1 + Z2 + Z3,
  mediator_formula  = M ~ X + Z1 + Z2 + Z3,
  outcome_formula   = Y ~ X + M + Z1 + Z2 + Z3,
  data = sim_mediation, R = 50
)
glance(fit)

Description

Produces a publication-ready love plot showing standardised mean differences (SMDs) before and after IPW weighting for both the treatment and mediator pathways — stacked vertically in a single panel. This dual-pathway display is unique to RobustMediate; no other mediation package provides it.

Usage

plot_balance(x, threshold = 0.1, pathways = c("treatment", "mediator"), ...)

Arguments

Value

A ggplot2 object. Add layers or themes as usual.

Examples

## Not run: 
fit <- robustmediate(X ~ Z, M ~ X + Z, Y ~ X + M + Z, data = mydata)
plot_balance(fit)
plot_balance(fit, threshold = 0.05, pathways = "treatment")

## End(Not run)

Description

Three-panel visualisation of dose-varying fragility: (1) effect curve with CI bands and fragility zones, (2) local fragility index, (3) normalised curvature.

Usage

plot_curvature(x, estimand = "NIE", ref_dose = NULL, ...)

Arguments

Value

A ggplot2 object.

Examples

data(sim_mediation)
  fit <- robustmediate(
    X ~ Z1 + Z2, M ~ X + Z1 + Z2, Y ~ X + M + Z1 + Z2,
    data = sim_mediation, R = 20, verbose = FALSE
  )
curv <- sensitivity_curvature(fit)
plot_curvature(curv, ref_dose = fit$meta$ref_dose)

Description

Plots NDE, NIE, and (optionally) total effect as smooth spline curves over the full range of treatment values, with pointwise bootstrap confidence bands. This is the signature visualisation of RobustMediate and is publication-ready out of the box.

Usage

plot_mediation(
  x,
  estimands = c("NDE", "NIE"),
  show_total = FALSE,
  facet = FALSE,
  ...
)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
fit <- robustmediate(X ~ Z, M ~ X + Z, Y ~ X + M + Z, data = mydata)
plot_mediation(fit)
plot_mediation(fit, estimands = c("NDE","NIE","TE"), facet = TRUE)

## End(Not run)

Description

Produces a two-panel pathway-specific robustness corridor plot showing the observed partial correlation, critical partial correlation threshold, medITCV corridor, and benchmark confounder impacts for each pathway.

Usage

plot_meditcv(x, ...)

Arguments

Value

A ggplot2 object.

Examples

data(sim_mediation)
  fit <- robustmediate(
    X ~ Z1 + Z2, M ~ X + Z1 + Z2, Y ~ X + M + Z1 + Z2,
    data = sim_mediation, R = 20, verbose = FALSE
  )
med <- sensitivity_meditcv(fit)
plot_meditcv(med)

Description

Visualises how each pathway's partial correlation is attenuated as confounding impact delta increases, with tipping points and a fragility zone marked.

Usage

plot_meditcv_profile(x, ...)

Arguments

Value

A ggplot2 object.

Examples

data(sim_mediation)
  fit <- robustmediate(
    X ~ Z1 + Z2, M ~ X + Z1 + Z2, Y ~ X + M + Z1 + Z2,
    data = sim_mediation, R = 20, verbose = FALSE
  )
mp  <- sensitivity_meditcv_profile(fit)
plot_meditcv_profile(mp)

Description

Renders the novel bivariate robustness map unique to RobustMediate: a 2-D heatmap where the x-axis is the E-value (VanderWeele-style unmeasured treatment–outcome confounding) and the y-axis is Imai's sequential-ignorability violation parameter rho. Contour lines show where the mediation effect crosses zero, so readers can judge robustness to two different sensitivity dimensions simultaneously.

This visualisation does not exist elsewhere in the R ecosystem. The correct interpretation is as a bivariate robustness display, not a joint causal model — see the package paper for theoretical justification.

Usage

plot_sensitivity(
  x,
  annotate_zero = TRUE,
  n_breaks = 12,
  palette = "RdYlGn",
  ...
)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
fit <- robustmediate(X ~ Z, M ~ X + Z, Y ~ X + M + Z, data = mydata)
plot_sensitivity(fit)
plot_sensitivity(fit, annotate_zero = FALSE, palette = "PuOr")

## End(Not run)

Description

Dispatches to the appropriate plot function based on type.

Usage

## S3 method for class 'robmedfit'
plot(
  x,
  type = c("mediation", "balance", "sensitivity", "meditcv", "meditcv_profile",
    "curvature"),
  ...
)

Arguments

Value

A ggplot2 object.

Description

Print a meditcv object

Usage

## S3 method for class 'meditcv'
print(x, ...)

Arguments

Value

The input object, invisibly. Called for its side effect of printing a formatted medITCV report to the console.

Description

Print a meditcv_profile object

Usage

## S3 method for class 'meditcv_profile'
print(x, ...)

Arguments

Value

The input object, invisibly. Called for its side effect of printing a formatted medITCV robustness profile to the console.

Description

Print a robmedfit object

Usage

## S3 method for class 'robmedfit'
print(x, ...)

Arguments

Value

The input object, invisibly.

Description

Fits treatment, mediator, and outcome models for causal mediation analysis with continuous treatments using inverse probability weighting (IPW), and returns a precomputed robmedfit object for plotting and diagnostics.

Usage

robustmediate(
  treatment_formula,
  mediator_formula,
  outcome_formula,
  data,
  ref_dose = NULL,
  dose_grid = NULL,
  R = 500,
  alpha = 0.05,
  covariates = NULL,
  cluster_var = NULL,
  family_treatment = stats::gaussian(),
  family_mediator = stats::gaussian(),
  family_outcome = stats::gaussian(),
  spline_df = 4,
  evalue_seq = seq(1, 10, by = 0.25),
  rho_seq = seq(-1, 1, by = 0.05),
  verbose = TRUE
)

Arguments

Value

An object of class "robmedfit" containing:

models

Fitted treatment, mediator, and outcome models.

balance

Balance statistics before and after weighting.

effects

Dose-response summaries for NDE, NIE, and TE, including bootstrap intervals.

sensitivity

Bivariate E-value and rho sensitivity surface.

meditcv

Pathway-specific medITCV object from sensitivity_meditcv().

meditcv_profile

medITCV robustness profile from sensitivity_meditcv_profile().

cluster

Cluster information, or NULL if clustering was not used.

meta

Call, variable names, dose settings, bootstrap settings, and sample information.

Examples

n <- 400
Z1 <- rnorm(n)
Z2 <- rbinom(n, 1, 0.5)
X  <- 0.5 * Z1 + 0.3 * Z2 + rnorm(n)
M  <- 0.4 * X + 0.2 * Z1 + rnorm(n)
Y  <- 0.3 * X + 0.5 * M + 0.1 * Z1 + rnorm(n)
dat <- data.frame(Y, X, M, Z1, Z2)

fit <- robustmediate(
  treatment_formula = X ~ Z1 + Z2,
  mediator_formula = M ~ X + Z1 + Z2,
  outcome_formula = Y ~ X + M + Z1 + Z2,
  data = dat,
  R = 100
)

print(fit)

Description

Computes the fragility curvature of the mediation effect across the full treatment dose grid. Returns local fragility index, numerical curvature of the effect curve, and a fragility zone flag at each dose value.

Usage

sensitivity_curvature(x, estimand = c("NIE", "NDE", "TE"))

Arguments

Value

A data frame with columns dose, estimate, lower, upper, se_approx, frag_local, curvature, and in_fragility_zone.

See Also

plot_curvature(), sensitivity_meditcv_profile()

Examples

data(sim_mediation)
  fit <- robustmediate(
    X ~ Z1 + Z2, M ~ X + Z1 + Z2, Y ~ X + M + Z1 + Z2,
    data = sim_mediation, R = 20, verbose = FALSE
  )
curv <- sensitivity_curvature(fit, estimand = "NIE")
plot_curvature(curv)

Description

Computes a mediation-specific extension of Kenneth Frank's (2000) Impact Threshold for a Confounding Variable (ITCV) for both pathways of a mediation model:

• a-path: treatment -> mediator

• b-path: mediator -> outcome (controlling for treatment)

The mediation ITCV (medITCV) quantifies how strong an unmeasured confounder would need to be, in terms of the product $r_{XC} \cdot r_{YC}$, to invalidate inference for each pathway.

Usage

sensitivity_meditcv(x, alpha = 0.05)

Arguments

Value

An object of class "meditcv": a named list with elements a_path, b_path, indirect, and alpha. Each pathway element contains the observed partial correlation, critical partial correlation, medITCV value, and benchmark confounder impacts.

References

Frank, K. A. (2000). Impact of a confounding variable on a regression coefficient. Sociological Methods & Research, 29(2), 147–194.

See Also

plot_meditcv(), print.meditcv()

Examples

data(sim_mediation)
  fit <- robustmediate(
    X ~ Z1 + Z2, M ~ X + Z1 + Z2, Y ~ X + M + Z1 + Z2,
    data = sim_mediation, R = 20, verbose = FALSE
  )
med <- sensitivity_meditcv(fit)
print(med)
plot_meditcv(med)

Description

Implements the medITCV robustness profile, a formal extension of Frank's ITCV to causal mediation. Computes pathway-specific fragility thresholds, applies the minimum robustness principle, and identifies the bottleneck pathway that governs indirect-effect fragility.

Usage

sensitivity_meditcv_profile(
  x,
  alpha = 0.05,
  delta_grid = seq(0, 0.5, by = 0.01)
)

Arguments

Value

An object of class "meditcv_profile": a named list with elements a_path, b_path, meditcv_indirect, bottleneck, robustness_profile, fragility_ratio, meditcv_detail, and alpha.

References

Frank, K. A. (2000). Impact of a confounding variable on a regression coefficient. Sociological Methods & Research, 29(2), 147–194.

See Also

sensitivity_meditcv(), plot_meditcv_profile(), sensitivity_curvature()

Examples

data(sim_mediation)
  fit <- robustmediate(
    X ~ Z1 + Z2, M ~ X + Z1 + Z2, Y ~ X + M + Z1 + Z2,
    data = sim_mediation, R = 20, verbose = FALSE
  )
mp  <- sensitivity_meditcv_profile(fit)
print(mp)
plot_meditcv_profile(mp)

Description

A synthetic dataset mimicking a clustered education study with a continuous treatment (tutoring hours), a continuous mediator (mid-year test score), and a continuous outcome (end-of-year test score). Designed to illustrate RobustMediate with realistic effect sizes and non-trivial confounding.

Usage

sim_mediation

Format

A data frame with 600 rows (30 schools x 20 students) and 7 columns:

school

Factor. School identifier (30 levels). Use as cluster_var.

Y

Numeric. End-of-year test score (outcome).

X

Numeric. Tutoring hours received (continuous treatment, >= 0).

M

Numeric. Mid-year test score (mediator).

Z1

Numeric. Prior achievement (continuous covariate).

Z2

Integer (0/1). Free-lunch status (binary covariate).

Z3

Numeric. Parental education index (continuous covariate).

True parameter targets

The data-generating process sets:

• NDE (X → Y direct path) ~= 0.25

• NIE (X → M → Y path) ~= 0.35

• TE ~= 0.60

• % mediated ~= 58%

Use these as a ground truth to assess estimation accuracy.

Source

Generated via data-raw/generate_sim_data.R. See that script for the full data-generating process.

Examples

data(sim_mediation)
str(sim_mediation)
summary(sim_mediation[, c("Y","X","M")])

## Not run: 
fit <- robustmediate(
  treatment_formula = X ~ Z1 + Z2 + Z3,
  mediator_formula  = M ~ X + Z1 + Z2 + Z3,
  outcome_formula   = Y ~ X + M + Z1 + Z2 + Z3,
  data        = sim_mediation,
  cluster_var = "school",
  R           = 500
)
diagnose(fit)

## End(Not run)

Description

Summary method for robmedfit objects

Usage

## S3 method for class 'robmedfit'
summary(object, ...)

Arguments

Value

A list with effect, balance, and sensitivity summaries, invisibly.

Description

Returns a tidy data frame of the mediation effect estimates (NDE, NIE, TE) at the reference dose, with confidence intervals. Compatible with broom::tidy() and the broader tidymodels ecosystem.

Usage

## S3 method for class 'robmedfit'
tidy(x, conf.int = TRUE, ...)

Arguments

Value

A data frame with columns term, estimate, conf.low, conf.high, and ref_dose.

Examples

fit <- robustmediate(
  treatment_formula = X ~ Z1 + Z2 + Z3,
  mediator_formula  = M ~ X + Z1 + Z2 + Z3,
  outcome_formula   = Y ~ X + M + Z1 + Z2 + Z3,
  data = sim_mediation, R = 50
)
tidy(fit)

Description

Returns a formatted data frame of sensitivity tipping points: the minimum E-value and minimum |rho| required to nullify the NIE. Designed for direct insertion into a table in a manuscript.

Usage

tipping_table(x)

Arguments

Value

A data frame with columns parameter, tipping_value, interpretation.