Getting Started with mediationverse

Introduction

The mediationverse is a collection of R packages for mediation analysis. It provides a unified ecosystem for model fitting, effect size computation, confidence interval estimation, sensitivity analysis, and simulation studies.

This vignette introduces the core concepts and shows how to get started with the mediationverse ecosystem.

Installation

Install the mediationverse meta-package from GitHub:

# Install with pak (recommended)
pak::pak("data-wise/mediationverse")

# Or with remotes
remotes::install_github("data-wise/mediationverse")

This will install all core packages:

medfit - Infrastructure (S7 classes, model fitting, extraction, bootstrap)
probmed - Probabilistic effect size (P_med)
RMediation - Confidence intervals (Distribution of Product, MBCO)
medrobust - Sensitivity analysis (bounds, falsification)
medsim - Simulation infrastructure

Loading the Ecosystem

The mediationverse uses selective loading: only the foundation package (medfit) is loaded by default. This keeps your namespace clean and lets you load only what you need.

library(mediationverse)

This attaches medfit and displays helpful information:

── Attaching mediationverse 0.0.0.9000 ──
✔ medfit 0.1.0 (foundation package)
ℹ Use library(probmed) for P_med effect size
ℹ Use library(RMediation) for DOP/MBCO inference
ℹ Use library(medrobust) for sensitivity analysis
ℹ Use library(medsim) for simulation utilities
──────────────────────────────────────────

Load additional packages as needed for your analysis:

# Load packages you need
library(probmed)      # For probabilistic effect sizes
library(RMediation)   # For confidence intervals
library(medrobust)    # For sensitivity analysis
library(medsim)       # For simulation studies (if needed)

Why selective loading?

Clean namespace: Avoids function name conflicts
Explicit: You control which packages are loaded
Foundation always available: medfit is loaded automatically since all other packages depend on it

Package Management

The mediationverse provides utility functions to manage the ecosystem:

Check Installed Versions

# List all mediationverse packages with versions and status
mediationverse_packages()

Update Packages

# Update all packages from GitHub/CRAN
mediationverse_update()

Check for Conflicts

# Show function name conflicts between packages
mediationverse_conflicts()

Core Workflow

The mediationverse follows a consistent workflow for mediation analysis.

First, load the packages you need (medfit is already loaded via mediationverse):

library(probmed)      # For this example
library(RMediation)   # For this example

1. Fit Models

Using medfit (already loaded), fit your mediator and outcome models:

# Fit models
fit_m <- lm(M ~ X + C, data = mydata)
fit_y <- lm(Y ~ X + M + C, data = mydata)

2. Extract Mediation Structure

Extract path coefficients and covariance matrix:

med_data <- extract_mediation(
  fit_m,
  model_y = fit_y,
  treatment = "X",
  mediator = "M"
)

# View the extracted structure
print(med_data)

3. Choose Your Analysis

Once you have a MediationData object, you can use any of the ecosystem packages:

Confidence Intervals (RMediation)

# Distribution of Product method
ci_dop <- ci(med_data, type = "dop")

# Monte Carlo method
ci_mc <- ci(med_data, type = "MC", n.mc = 10000)

Probabilistic Effect Size (probmed)

# Compute P_med
pmed_result <- compute_pmed(med_data)

Sensitivity Analysis (medrobust)

# Bounds for unmeasured confounding
bounds <- sensitivity_bounds(med_data)

Bootstrap Inference (medfit)

# Nonparametric bootstrap
boot_result <- bootstrap_mediation(med_data, n_boot = 2000)

Ecosystem Design

The mediationverse follows several design principles:

Foundation Package

medfit serves as the foundation, providing:

S7 classes (MediationData, SerialMediationData, BootstrapResult)
Model extraction methods
Bootstrap infrastructure
Common utilities

Specialized Packages

Each package focuses on one methodological contribution:

Package	Focus	Key Functions
probmed	Effect sizes	`compute_pmed()`, `pmed()`
RMediation	Confidence intervals	`ci()`, `medci()`, `mbco()`
medrobust	Sensitivity	`sensitivity_bounds()`
medsim	Simulation	`run_simulation()`

Type Safety

All packages use S7 classes for type safety and validation:

# MediationData validates input
med_data <- MediationData(
  a_path = 0.5,
  b_path = 0.4,
  c_prime = 0.1,
  estimates = c(a = 0.5, b = 0.4, c_prime = 0.1),
  vcov = matrix(c(0.01, 0, 0, 0, 0.01, 0, 0, 0, 0.01), 3, 3)
)

Next Steps

Read the mediationverse Workflow article for a complete analysis example
Explore individual package documentation:
- medfit
- probmed
- RMediation
- medrobust
- medsim

Session Info

sessionInfo()

R version 4.6.0 (2026-04-24)
Platform: x86_64-pc-linux-gnu
Running under: Ubuntu 24.04.4 LTS

Matrix products: default
BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0

locale:
 [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
 [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
 [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
 [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
 [9] LC_ADDRESS=C               LC_TELEPHONE=C            
[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       

time zone: Etc/UTC
tzcode source: system (glibc)

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

loaded via a namespace (and not attached):
 [1] compiler_4.6.0   fastmap_1.2.0    cli_3.6.6        htmltools_0.5.9 
 [5] tools_4.6.0      otel_0.2.0       yaml_2.3.12      maketools_1.3.2 
 [9] buildtools_1.0.0 rmarkdown_2.31   knitr_1.51       jsonlite_2.0.0  
[13] digest_0.6.39    xfun_0.58        rlang_1.2.0      sys_3.4.3       
[17] evaluate_1.0.5