---
title: "Comparing Confidence Interval Methods in RMediation"
author: "RMediation Development Team"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Comparing Confidence Interval Methods in RMediation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(RMediation)
```

## Introduction

This vignette compares the different confidence interval methods available in the RMediation package. Understanding the differences between methods is important for selecting the most appropriate approach for your mediation analysis.

## Overview of Methods

RMediation provides several methods for computing confidence intervals for indirect effects:

- **Distribution of Product (DOP)**: Exact method for the product of two normal random variables
- **Monte Carlo (MC)**: Simulation-based approach using random sampling
- **Asymptotic Normal**: Traditional approach based on normal theory (e.g., Sobel test)
- **MBCO (Model-Based Constrained Optimization)**: Advanced frequentist method for hypothesis testing

## Method Comparison

Let's compare different methods using the same example:

```{r method-comparison}
# Same example parameters
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

# Compare all methods
results <- medci(
  mu.x = mu.x, mu.y = mu.y,
  se.x = se.x, se.y = se.y,
  rho = rho,
  type = "all",  # This gives results for all methods
  plot = FALSE
)

# Print results
for(method_name in names(results)) {
  cat("\n", method_name, ":\n")
  # Display the structure of each result
  str(results[[method_name]])
}
```

## Performance and Accuracy Comparison

Different methods have different strengths and weaknesses:

```{r performance-comparison}
# Example of comparing results across different parameter values

# Define parameter values to test
param_sets <- list(
  list(mu.x = 0.5, mu.y = 0.6, se.x = 0.08, se.y = 0.04),
  list(mu.x = 0.3, mu.y = 0.4, se.x = 0.10, se.y = 0.05),
  list(mu.x = 0.1, mu.y = 0.2, se.x = 0.05, se.y = 0.03)
)

for(i in seq_along(param_sets)) {
  params <- param_sets[[i]]
  cat("\nParameter set", i, ":\n")
  cat("Effect sizes: a =", params$mu.x, ", b =", params$mu.y, "\n")

  results_subset <- medci(
    mu.x = params$mu.x, mu.y = params$mu.y,
    se.x = params$se.x, se.y = params$se.y,
    rho = 0,
    type = "all",
    plot = FALSE
  )

  # Print confidence intervals from each method
  for(method_name in names(results_subset)) {
    ci_values <- results_subset[[method_name]][[1]]  # Extract CI values
    cat(sprintf("%-25s: [%.3f, %.3f]\n", method_name, ci_values[1], ci_values[2]))
  }
}
```

## When to Use Each Method

### Distribution of Product (DOP)

- **Best for:** Small samples where normality assumptions may not hold
- **Advantages:** Exact method for product of two normals, maintains Type I error rates
- **Disadvantages:** Computationally intensive for complex models

```{r dop-example}
# Example using DOP method
result_dop <- medci(
  mu.x = 0.5, mu.y = 0.6,
  se.x = 0.08, se.y = 0.04,
  rho = 0,
  type = "dop"
)

cat("DOP Method Results:\n")
str(result_dop)
```

### Monte Carlo (MC)

- **Best for:** Complex models with multiple mediators
- **Advantages:** Flexible, works with complex functions of parameters
- **Disadvantages:** Requires large sample sizes for stability

```{r mc-example}
# Example using MC method
result_mc <- medci(
  mu.x = 0.5, mu.y = 0.6,
  se.x = 0.08, se.y = 0.04,
  rho = 0,
  type = "mc",
  n.mc = 1e5  # Specify Monte Carlo sample size
)

cat("Monte Carlo Method Results:\n")
str(result_mc)
```

### Asymptotic Normal

- **Best for:** Large samples with well-behaved distributions
- **Advantages:** Computationally fast
- **Disadvantages:** Can have poor Type I error control in small samples

```{r asymptotic-example}
# Example using asymptotic method
result_asymp <- medci(
  mu.x = 0.5, mu.y = 0.6,
  se.x = 0.08, se.y = 0.04,
  rho = 0,
  type = "asymp"
)

cat("Asymptotic Method Results:\n")
str(result_asymp)
```

## Working with S7 Classes

The modern S7 implementation provides method-specific functionality:

```{r s7-example, eval = FALSE}
# Create a ProductNormal object (represents distribution of product)
pn <- ProductNormal(
  mu = c(0.5, 0.6),  # Means of the two variables
  Sigma = matrix(c(0.0064, 0, 0, 0.0016), 2, 2)  # Covariance matrix (se.x^2, 0, 0, se.y^2)
)

# Compute cumulative distribution function
cat("CDF at 0.1:", cdf(pn, q = 0.1), "\n")
cat("CDF at 0.3:", cdf(pn, q = 0.3), "\n")

# Compute quantiles
cat("2.5% quantile:", quantile(pn, p = 0.025), "\n")
cat("97.5% quantile:", quantile(pn, p = 0.975), "\n")

# Compute confidence interval
ci_result <- ci(pn, level = 0.95)
cat("95% Confidence Interval:", ci_result, "\n")

# Print and summary methods
show(pn)  # Use show instead of print
summary(pn)  # This should work as it's a different S7 method
```

## Practical Recommendations

Based on simulation research and statistical theory, here are practical recommendations:

1. **For simple mediation models with two paths:** Use DOP method as it provides the most accurate confidence intervals.

2. **For complex models:** Use Monte Carlo methods which are more flexible and extend to higher-order products.

3. **For hypothesis testing:** Consider using the MBCO procedure which provides better Type I error control.

4. **For publication:** When possible, report results from multiple methods to show robustness.

## Conclusion

The choice of confidence interval method can significantly impact your conclusions about mediation effects. The RMediation package provides multiple rigorous methods that account for the non-normal distribution of the indirect effect, unlike simpler normal-theory approaches. Using the appropriate method for your specific situation will lead to more reliable inferences in mediation analysis.

For more information about the statistical methods, see the package documentation and references.