medsim provides standardized infrastructure for conducting Monte Carlo simulation studies in mediation analysis. Eliminate the need to repeatedly implement parallel processing, progress reporting, result analysis, and visualization across different research projects.
- Environment-Aware Execution: Automatically detects local machine vs HPC cluster
- Three Execution Modes: test (~30s), local (~15min), cluster (hours)
- Parallel Processing: Built-in parallelization with progress bars
- Ground Truth Caching: Avoid expensive recomputation
- Automated Analysis: Summary statistics, accuracy metrics, coverage rates
- Publication-Ready Output: Figures and LaTeX tables with one function call
medsim is part of the mediationverse ecosystem for mediation analysis in R:
| Package | Purpose | Role |
|---|---|---|
| medfit | Model fitting, extraction, bootstrap | Foundation |
| probmed | Probabilistic effect size (P_med) | Application |
| RMediation | Confidence intervals (DOP, MBCO) | Application |
| medrobust | Sensitivity analysis | Application |
| medsim (this) | Simulation infrastructure | Support |
See Ecosystem Coordination for version compatibility and development guidelines.
Install the development version from GitHub:
# install.packages("pak")
pak::pak("data-wise/medsim")library(medsim)
# 1. Define your estimation method
my_method <- function(data, params) {
fit_m <- lm(M ~ X, data = data)
fit_y <- lm(Y ~ X + M, data = data)
a <- coef(fit_m)["X"]
b <- coef(fit_y)["M"]
list(indirect = a * b, a = a, b = b)
}
# 2. Configure and run simulation
config <- medsim_config("local")
scenarios <- medsim_scenarios_mediation()
results <- medsim_run(
method = my_method,
scenarios = scenarios,
config = config
)
# 3. Generate analysis and output
medsim_workflow(results, output_dir = "results")Output: Complete simulation results with figures and tables in results/
Three modes optimized for different use cases:
| Mode | Replications | Runtime | Use Case |
|---|---|---|---|
test |
20 | ~30s | Quick validation |
local |
100 | ~15m | Development |
cluster |
1000+ | hours | Production runs |
# Auto-detect environment
config <- medsim_config(mode = "auto")
# Or specify explicitly
config_test <- medsim_config(mode = "test") # Quick check
config_local <- medsim_config(mode = "local") # Development
config_cluster <- medsim_config(mode = "cluster") # ProductionSix standard mediation scenarios covering common data-generating patterns:
scenarios <- medsim_scenarios_mediation()
# 1. Independent paths (ρ = 0)
# 2. Moderate correlation (ρ = 0.3)
# 3. High correlation (ρ = 0.7)
# 4. Suppression (mixed signs)
# 5. Non-zero direct effect
# 6. Unequal variances
# View scenario details
print(scenarios[[1]])
# Generate data from a scenario
data <- scenarios[[1]]$data_generator(n = 200)Define custom data-generating processes:
my_scenario <- medsim_scenario(
name = "Large Effects",
description = "Both paths have large effects (a = b = 0.7)",
data_generator = function(n = 200) {
X <- rnorm(n)
M <- 0.7 * X + rnorm(n)
Y <- 0.7 * M + rnorm(n)
data.frame(X = X, M = M, Y = Y)
},
params = list(
a = 0.7,
b = 0.7,
indirect = 0.49
)
)
# Combine with standard scenarios
all_scenarios <- c(medsim_scenarios_mediation(), list(my_scenario))Full pipeline from simulation to manuscript-ready output:
# Run simulation
results <- medsim_run(
method = my_method,
scenarios = scenarios,
config = medsim_config("local")
)
# Analyze results
analysis <- medsim_analyze(results)
coverage <- medsim_analyze_coverage(results)
power <- medsim_analyze_power(results)
# Create publication-ready figures
medsim_plot_coverage(coverage, output_file = "figures/coverage.pdf")
medsim_plot_error_boxplot(results, output_file = "figures/errors.pdf")
# Generate LaTeX tables
medsim_tables_workflow(results, output_dir = "tables")Generates:
- Summary statistics and accuracy metrics
- Publication-ready PDF figures
- LaTeX tables ready for manuscript inclusion
Automatic detection of SLURM, PBS, and LSF job schedulers:
#!/bin/bash
#SBATCH --job-name=medsim
#SBATCH --nodes=1
#SBATCH --cpus-per-task=20
#SBATCH --time=24:00:00
module load R/4.3.0
Rscript run_simulation.R# run_simulation.R
library(medsim)
# Auto-detects cluster and uses all allocated cores
config <- medsim_config(mode = "auto")
results <- medsim_run(
method = my_method,
scenarios = scenarios,
config = config
)Designed to work seamlessly with other mediationverse packages:
library(medsim)
library(medfit)
library(probmed)
# Simulate P_med coverage
pmed_method <- function(data, params) {
fit_m <- lm(M ~ X, data = data)
fit_y <- lm(Y ~ X + M, data = data)
med_data <- medfit::extract_mediation(
fit_m, model_y = fit_y,
treatment = "X", mediator = "M"
)
p_med <- probmed::compute_pmed(med_data)
# Bootstrap CI
boot <- medfit::bootstrap_mediation(
med_data,
statistic = probmed::compute_pmed,
n_boot = 1000
)
list(
estimate = p_med,
ci_lower = boot@ci_lower,
ci_upper = boot@ci_upper,
truth = params$true_pmed
)
}
results <- medsim_run(pmed_method, scenarios, config)
coverage <- medsim_analyze_coverage(results)Compare performance across different estimation approaches:
methods <- list(
pmed = function(data, params) {
# Compute P_med with bootstrap CI
},
dop = function(data, params) {
# Distribution of Product CI
},
bounds = function(data, params) {
# Sensitivity analysis bounds
}
)
results <- medsim_compare_methods(
methods = methods,
scenarios = scenarios,
config = config
)
# Generate comparison table
medsim_comparison_table(results)
#> Accuracy Coverage Power Runtime
#> P_med 0.95 0.948 0.82 3.2s
#> DOP CI 0.94 0.952 0.81 0.1s
#> Bounds 0.93 0.945 0.78 1.5sInspired by simulation infrastructure in successful R packages and academic projects:
- Configuration Over Repetition: Write simulation logic once, run in multiple modes
- Environment Awareness: Seamlessly scale from laptop to HPC cluster
- Reproducibility by Design: Automatic seed management, session tracking
- Publication Ready: One function generates manuscript-ready output
- Getting Started - Step-by-step tutorial
- Function Reference - Complete API documentation
- Package Website - Comprehensive guides and examples
If you use medsim in your research, please cite:
citation("medsim")- GitHub Issues - Bug reports and feature requests
- Documentation - Comprehensive guides
- Discussions - Questions and community support
This project is released with a Contributor Code of Conduct. By contributing, you agree to abide by its terms.
GPL (>= 3)
Maintainer: Davood Tofighi (dtofighi@gmail.com) ORCID: 0000-0001-8523-7776