Author: RMediation Development Team

# Getting Started with RMediation

#### RMediation Development Team

## Introduction

The RMediation package provides rigorous statistical methods for mediation analysis in observational and experimental designs. It addresses the known limitations of normal-theory confidence intervals (e.g., Sobel test) by implementing advanced methods that account for the non-normal distribution of the indirect effect.

## Basic Usage

### Single Mediator Analysis

To compute a confidence interval for a single mediator using summary statistics:

    # Example: Single mediator with known coefficients and standard errors
    result <- medci(
      mu.x = 0.5, # Effect of X on M
      mu.y = 0.6, # Effect of M on Y (controlling for X)
      se.x = 0.08, # Standard error of a path
      se.y = 0.04, # Standard error of b path
      rho = 0, # Correlation between a and b (often 0 for experimental X)
      type = "dop" # Distribution of the product method
    )

    # Display the structure of the result
    str(result)
    #> List of 3
    #>  $ 95% CI  : num [1:2] 0.201 0.405
    #>  $ Estimate: num 0.3
    #>  $ SE      : num 0.0521

    # Or access specific components
    cat("Confidence Interval:", result$`95% CI`, "\n")
    #> Confidence Interval: 0.2010806 0.4053619
    cat("Estimate:", result$Estimate, "\n")
    #> Estimate: 0.3
    cat("Standard Error:", result$SE, "\n")
    #> Standard Error: 0.05209837

### Multiple Mediators

For more complex mediation models with multiple mediators:

    # Example: Two sequential mediators
    result2 <- ci(
      c(b1 = 1, b2 = .7, b3 = .6, b4 = .45),
      Sigma = c(.05, 0, 0, 0, .05, 0, 0, .03, 0, .03),
      quant = ~ b1 * b2 * b3 * b4,
      type = "MC",
      plot = FALSE # Set to TRUE to see visualization
    )

    str(result2)
    #> List of 5
    #>  $         : Named num [1:2] 0.0237 0.5002
    #>   ..- attr(*, "names")= chr [1:2] "2.5 %" "97.5 %"
    #>  $ Estimate: num 0.19
    #>  $ SE      : num 0.125
    #>  $ MCError : num 1.25e-06
    #>  $ p       : num 0.0121
    #>  - attr(*, "quant")=Class 'formula'  language ~b1 * b2 * b3 * b4
    #>   .. ..- attr(*, ".Environment")=<environment: R_GlobalEnv>

### Three-Variable Indirect Effects (ProductNormal3)

For sequential indirect effects of the form `a1 * a2 * b` (e.g., X → M1 → M2 → Y), use the `ProductNormal3` S7 class and its exact `pprodnormal3()` CDF engine:

    # Path coefficients (a1, a2, b) and their joint covariance
    mu3 <- c(a1 = 0.5, a2 = 0.4, b = 0.6)
    Sigma3 <- diag(c(0.01, 0.01, 0.01)) # independent paths

    # Create the distribution object and compute 95% CI
    pn3 <- ProductNormal3(mu = mu3, Sigma = Sigma3)
    ci(pn3, level = 0.95)

    # Direct CDF query: P(a1*a2*b <= 0)
    pprodnormal3(q = 0, mean = mu3, cov = Sigma3)

### Using S7 Classes

The package includes modern S7 object-oriented classes:

    # Create a ProductNormal distribution object
    pn <- ProductNormal(
      mu = c(0.5, 0.3), # Means of the two normal variables
      Sigma = matrix(c(0.01, 0.002, 0.002, 0.01), 2, 2) # Covariance matrix
    )

    # Compute confidence interval
    ci_result <- ci(pn, level = 0.95)

    show(pn) # Use show instead of print
    str(ci_result) # Use str to show structure

## Available Methods

RMediation offers several methods for computing confidence intervals:

- `"dop"`: Distribution of the product (default for medci)
- `"MC"`: Monte Carlo method
- `"asymp"`: Asymptotic normal approach
- `"all"`: All methods

    # Compare different methods
    comparison <- medci(
      mu.x = 0.5,
      mu.y = 0.6,
      se.x = 0.08,
      se.y = 0.04,
      rho = 0,
      type = "all",
      plot = FALSE
    )

    # Show comparison
    str(comparison)
    #> List of 3
    #>  $ Distribution of Product:List of 3
    #>   ..$ 95% CI  : num [1:2] 0.201 0.405
    #>   ..$ Estimate: num 0.3
    #>   ..$ SE      : num 0.0521
    #>  $ Monte Carlo            :List of 4
    #>   ..$ 95% CI  : num [1:2] 0.201 0.405
    #>   ..$ Estimate: num 0.3
    #>   ..$ SE      : num 0.0521
    #>   ..$ MC.Error: num 5.21e-07
    #>  $ Asymptotic Normal      :List of 3
    #>   ..$ 95% CI  : num [1:2] 0.198 0.402
    #>   ..$ Estimate: num 0.3
    #>   ..$ SE      : num 0.0521

## Integration with Structural Equation Modeling

RMediation integrates seamlessly with popular SEM packages:

    library(lavaan)

    # Define a simple mediation model
    model <- "
      # Direct effect
      Y ~ c*X

      # Mediator
      M ~ a*X
      Y ~ b*M

      # Indirect effect
      ab := a*b
      # Total effect
      total := c + (a*b)
    "
    # Simulate data
    set.seed(123)
    n <- 1000
    X <- rnorm(n)
    M <- 0.5 * X + rnorm(n)
    Y <- 0.3 * M + 0.2 * X + rnorm(n)
    df <- data.frame(X, M, Y)

    # This would be fitted with your data
    fit <- sem(model, data = df)

    # Automatically compute CI for defined parameters
    ci(fit) # This would auto-detect 'ab' parameter

## Validation and Error Handling

The package includes robust validation for inputs:

    # These would throw helpful error messages:
    # medci(mu.x = 0.5, mu.y = 0.6, se.x = -0.1, se.y = 0.04)  # Invalid negative SE
    # ci(mu = c(0.5), Sigma = matrix(1), quant = ~ b1)  # Dimension mismatch

## Conclusion

RMediation provides a comprehensive solution for mediation analysis with proper statistical inference. The package offers multiple methods for computing confidence intervals, seamless SEM integration, and robust error handling.

For more advanced usage and method comparisons, see our other vignettes.