---
title: "Random effects meta-analysis for correlated test statistics"
author:
- name: "[Gabriel Hoffman](http://gabrielhoffman.github.io)"
  affiliation: | 
    Icahn School of Medicine at Mount Sinai, New York

output:
  rmarkdown::html_document:
    highlight: pygments
    toc: false
    toc_depth: 3
    fig_width: 5
bibliography: ../inst/REFERENCES.bib
vignette: >
  %\VignetteIndexEntry{remaCor: Random effects meta-analysis for correlated test statistics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\usepackage[utf8]{inputenc}
---

```{r setup, echo=FALSE, results="hide"}
knitr::opts_chunk$set(tidy=FALSE, cache=TRUE,
                      dev="png",
                      package.startup.message = FALSE,
                      message=FALSE, error=FALSE, warning=TRUE)
```	

<style>
body {
text-align: justify}
</style>

Standard approaches to meta-analysis assumes that effect sizes are statistically independent.  Here we provide methods for fixed and random effects meta-analysis when the correlation between effect sizes are known.

### Fixed effects meta-analysis

`LS()` implements fixed effect meta-analysis for correlated test statistics using method of @lin2009meta.  By default, correlation is set to identity matrix to for independent test statistics.  

### Random effects  meta-analysis

`RE2C()` implements random effect meta-analysis for correlated test statistics that jointly tests deviation of the mean from zero as well as effect size heterogenity.  This method uses the RE2 method of @han2011random, or RE2 for correlated test statistics from @han2016general.   By default, correlation is set to identity matrix to for independent test statistics.  (In addition, this function computes the two step RE2C method of @lee2017increasing to further test for heterogenity in effect size after applying a fixed effect test.)


  * `stat1`: statistic testing effect mean

  * `stat2`: statistic testing effect heterogeneity

  * `RE2Cp`: RE2 p-value accounting for correlelation between tests. (This is the p-value appropriate for most questions)

  * `RE2Cp.twoStep`: two step RE2C test after fixed effect test.
            Only evaluated if `twoStep==TRUE`.  (not typically used)

  * `QE`: test statistic for the test of (residual) heterogeneity

  * `QEp`: p-value for the test of (residual) heterogeneity

  * `Isq`: I^2 statistic

    `QE`, `QEp` and `Isq` are only evaluted if correlation is diagonal



### Examples
```{r rema}
library(remaCor)
library(metafor)
library(mvtnorm)
library(clusterGeneration )

# sample size
n = 30

# number of response variables
m = 2

# Error covariance
Sigma = genPositiveDefMat(m)$Sigma

# regression parameters
beta = matrix(0, 1, m)

# covariates
X = matrix(rnorm(n), ncol=1)

# Simulate response variables
Y = X %*% beta + rmvnorm(n, sigma = Sigma)

# Multivariate regression
fit = lm(Y ~ X)

# Correlation between residuals
C = cor(residuals(fit))

# Extract effect sizes and standard errors from model fit
df = lapply(coef(summary(fit)), function(a) 
  data.frame(beta = a["X", 1], se = a["X", 2]))
df = do.call(rbind, df)

# Standard fixed effects meta-analysis
# of independent effects with metafor pacakge
rma( df$beta, sei=df$se, method="FE")

# Standard random effects meta-analysis
# of independent effects with metafor pacakge
rma( df$beta, sei=df$se, method="REML")

# Run fixed effects meta-analysis, assume identity correlation  
# Use Lin-Sullivan method
LS( df$beta, df$se)

# Run fixed effects meta-analysis, accounting for correlation  
# Use Lin-Sullivan method
LS( df$beta, df$se, C)

# Run random effects meta-analysis, assume identity correlation  
RE2C( df$beta, df$se)

# Run random effects meta-analysis, accounting for correlation 
RE2C( df$beta, df$se, C)
```

```{r out, echo=FALSE}
RE2C( df$beta, df$se, C)
```





# Session info
<details>
```{r sessionInfo}
sessionInfo()
```
</details>

## References