---
title: "Getting Started with mediationverse"
format: html
vignette: >
  %\VignetteIndexEntry{Getting Started with mediationverse}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
execute:
  eval: false
---

## 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:

```{r}
#| label: install
# 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.

```{r}
#| label: load
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:

```{r}
#| label: load-more
# 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

```{r}
#| label: packages
# List all mediationverse packages with versions and status
mediationverse_packages()
```

### Update Packages

```{r}
#| label: update
# Update all packages from GitHub/CRAN
mediationverse_update()
```

### Check for Conflicts

```{r}
#| label: 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):

```{r}
#| label: setup-workflow
library(probmed)      # For this example
library(RMediation)   # For this example
```

### 1. Fit Models

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

```{r}
#| label: fit
# 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:

```{r}
#| label: extract
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)

```{r}
#| label: ci
# 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)

```{r}
#| label: pmed
# Compute P_med
pmed_result <- compute_pmed(med_data)
```

#### Sensitivity Analysis (medrobust)

```{r}
#| label: robust
# Bounds for unmeasured confounding
bounds <- sensitivity_bounds(med_data)
```

#### Bootstrap Inference (medfit)

```{r}
#| label: bootstrap
# 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:

```{r}
#| label: s7
# 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](mediationverse-workflow.html) article for
  a complete analysis example
- Explore individual package documentation:
  - [medfit](https://data-wise.github.io/medfit/)
  - [probmed](https://data-wise.github.io/probmed/)
  - [RMediation](https://data-wise.github.io/rmediation/)
  - [medrobust](https://data-wise.github.io/medrobust/)
  - [medsim](https://data-wise.github.io/medsim/)

## Session Info

```{r}
#| label: session
#| eval: true
sessionInfo()
```