medRCT

medRCT: Causal mediation analysis estimating interventional effects mapped to a target trial in R - Published in JOSS (2025)

https://github.com/t0ngchen/medrct

Keywords

Scientific Fields

Repository

📦R package medRCT

README.Rmd

---
output: github_document
bibliography: "inst/references.bib"
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# medRCT 


[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)
[![R-CMD-check](https://github.com/T0ngChen/medRCT/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/T0ngChen/medRCT/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/T0ngChen/medRCT/graph/badge.svg)](https://app.codecov.io/gh/T0ngChen/medRCT)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.08063/status.svg)](https://doi.org/10.21105/joss.08063)


> Causal mediation analysis estimating interventional effects mapped to a target trial

The R package `medRCT` for causal mediation analysis supports the estimation of interventional effects [@vanderweele2014effect], specifically interventional effects that are defined such that they map explicitly to a "target trial" [@hernan2016using], as recently proposed by @Moreno2021Mediation. In the target trial, the treatment strategies are specified to reflect hypothetical interventions targeting and thus shifting the joint distribution of the mediators. `medRCT` can accommodate any number of potentially correlated mediators, including mediators that are not of primary interest but that are intermediate (exposure-induced) mediator-outcome confounders.  

## Statement of need:

Causal mediation analysis generally seeks to investigate the extent to which the causal effect of an exposure on an outcome is mediated through intermediate variables. Natural (in)direct effects [@Robins1992; @Pearl2001] were initially proposed as the estimands of interest in these analyses. Natural effects are defined based on cross-world counterfactuals [@Robins2011] and their identifiability relies on a cross-world independence assumption. Given their reliance on cross-world counterfactuals, these effects have been criticized for not capturing the effects of interventions or policy measures that could be conducted in the real world [@Naimi2014Mediation]. Further, the independence assumption required can never be guaranteed, even in an experiment [@Robins2011; @Didelez2006], and it renders the estimands unidentifiable in the common settings of exposure-induced mediator-outcome confounding and multiple mediators [@Avin2005; @vanderweele2014effect; @Vansteelandt2012Natural]. However, in the context of multiple mediators, certain path-specific natural effects, also defined in terms of cross-world counterfactuals, can still be identified and may be of substantive interest [@VanderWeele2014].

Interventional effects have been proposed as an alternative to address these limitations. Firstly, these effects can be shown to map to a hypothetical randomized trial that evaluates the impact of hypothetical interventions shifting the distribution of the mediators [@MorenoBetancur2018]. Secondly, interventional effects remain identifiable in the presence of exposure-induced mediator-outcome confounding and multiple interrelated mediators of interest.

The `medRCT` package implements the estimation of interventional effects that are defined explicitly as effects in a hypothetical randomized trial (the target trial) , as proposed by @Moreno2021Mediation. This assists with clarifying the research question and ensuring that the study findings are meaningful and relevant to policy and practice. In the target trial, the treatment strategies are specified to reflect hypothetical interventions targeting and thus shifting the joint mediator distribution.  The `medRCT` package implements the estimation of interventional effects that correspond to effects of hypothetical interventions which:

1. shift the joint distribution of all mediators under exposure to that under no exposure,

2. shift the distribution of a specific mediator under exposure, given confounders, to match the corresponding distribution under no exposure, independent of and without considering flow-on effects on other mediators, 

3. shift the distribution of a specific mediator under exposure, given confounders, to match the corresponding distribution under no exposure, while considering flow-on effects on causally descendant mediators.

`medRCT` estimates these interventional effects using a Monte Carlo simulation-based g-computation approach. It should be noted that this method can be computationally intensive and is sensitive to model misspecification, as all nuisance parameters are estimated via restrictive parametric models.

Researchers should consider using `medRCT` when their ultimate goal for conducting mediation analysis is to examine the effects of hypothetical interventions targeting multiple, potentially interdependent mediators.


## Installation

The `medRCT` package is not yet available on CRAN. You can install the latest stable version from [GitHub](https://github.com/T0ngChen/medRCT) using the following command:

``` r
remotes::install_github("T0ngChen/medRCT")
```

## Example

Using a simulated dataset based on a published case study from the Longitudinal Study of Australian Children [@Goldfeld2023], we illustrate how to use `medRCT` to estimate the interventional effects that emulate a target trial. Specifically, we aim to estimate the difference in expected outcome (risk of child mental health problems) under exposure (low family socioeconomic position) with versus without a hypothetical intervention that individually shifts the distribution of each mediator (parental mental health and preschool attendance) to the levels in the unexposed (high family socioeconomic position), while accounting for baseline confounders, an intermediate (exposure-induced) mediator-outcome confounder (family stressful life events), and correlations amongst mediators. 

We begin by loading the library and dataset, and defining the confounder vector.
```{r eg, warning=FALSE, message=FALSE}
# Load the medRCT package
library(medRCT)

# Set a seed for reproducibility
set.seed(2025)

# Display the first few rows of the dataset
head(LSACdata)

# Define confounders for the analysis
confounders <- c("child_sex", "child_atsi", "mat_cob", "mat_engl", "mat_age")
```
Next we run the analyses, estimating interventional effects for a hypothetical intervention that shifts the distribution of each mediator individually. 
**Note 1:** the dataset has missing data. Incomplete records are by default deleted before the analysis. 
**Note 2:** It is recommended to perform the analysis with at least 200 Monte Carlo simulations by setting `mcsim = 200`. For illustration purposes, we use `mcsim = 50`, which takes approximately 90 seconds to run.

```{r}
# Estimate interventional effects for a hypothetical intervention
# that shifts the distribution of each mediator individually
med_res <- medRCT(
  dat = LSACdata,                      
  exposure = "sep",                    
  outcome = "child_mh",                
  mediators = c("parent_mh", "preschool_att"), 
  intermediate_confs = "fam_stress",  # intermediate confounders 
  confounders = confounders,           
  bootstrap = TRUE,                    
  intervention_type = "shift_k",       
  mcsim = 50                          
)

# Summarise the results
summary(med_res)
```

Based on the estimated interventional effect (IIE_1), a hypothetical intervention improving the mental health of parents of children from families with low socioeconomic position to the levels of those from families with high socioeconomic position could potentially prevent 1 per 100 cases of child mental health problems. Meanwhile, the effect of a hypothetical intervention on preschool attendance (IIE_2) is negligible. 

For detailed guidance on using the package to handle more complex scenarios, please refer to the [vignette](https://t0ngchen.github.io/medRCT/articles/intro.html).

## Citation

For work involving the `medRCT` R package, please cite the following:

    @article{Chen2025medRCT,
      author = {Tong Chen and S. Ghazaleh Dashti and Margarita Moreno-Betancur},
      title = {{medRCT}: Causal mediation analysis estimating interventional effects mapped to a target trial in {R}},
      year = {2025},
      doi = {10.21105/joss.08063},
      url = {https://doi.org/10.21105/joss.08063},
      journal = {Journal of Open Source Software},
      volume = {10},
      number = {110},
      pages = {8063},
      publisher = {The Open Journal}
    }
    @article{Moreno2021Mediation,
       author={Margarita Moreno-Betancur and Paul Moran and Denise Becker and George C Patton and John B Carlin},
       title={Mediation effects that emulate a target randomised trial: Simulation-based evaluation of ill-defined interventions on multiple mediators},
       journal={Statistical Methods in Medical Research},
       volume={30},
       number={6},
       pages={1395--1412},
       year={2021},
       URL={https://doi.org/10.1177/0962280221998409},
       doi={10.1177/0962280221998409},
       publisher={SAGE Publications Ltd}
    }

## References

Owner

JOSS Publication

medRCT: Causal mediation analysis estimating interventional effects mapped to a target trial in R

Published

June 27, 2025

DOI

10.21105/joss.08063

Volume 10, Issue 110, Page 8063

Authors

Tong Chen
Clinical Epidemiology and Biostatistics Unit, Murdoch Children’s Research Institute, Australia, Melbourne Dental School, University of Melbourne, Australia

S. Ghazaleh Dashti
Clinical Epidemiology and Biostatistics Unit, Murdoch Children’s Research Institute, Australia, Department of Paediatrics, University of Melbourne, Australia

Margarita Moreno-Betancur
Clinical Epidemiology and Biostatistics Unit, Murdoch Children’s Research Institute, Australia, Department of Paediatrics, University of Melbourne, Australia

Editor

Fabian Scheipl

Tags

causal inference mediation analysis interventional effect target trial

View PDF Review Thread Software Archive

GitHub Events

Issues and Pull Requests

Last synced: 4 months ago