---
title: "CPBayes (Bayesian meta analysis for studying cross-phenotype genetic associations) package"
author: "Arunabha Majumdar, Tanushree Haldar, John Witte"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    fig_width: 7
    fig_height: 6
vignette: >
  %\VignetteIndexEntry{CPBayes (Bayesian meta analysis for studying cross-phenotype genetic associations) package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
# Introduction
Simultaneous analysis of genetic associations with multiple phenotypes may reveal shared genetic susceptibility across traits (pleiotropy). CPBayes is a Bayesian meta analysis method for studying cross-phenotype genetic associations. It uses summary-level data across multiple phenotypes to simultaneously measure the evidence of aggregate-level pleiotropic association and estimate an optimal subset of traits associated with the risk locus. CPBayes model is based on a spike and slab prior. 

This R-package consists of following functions: 

1. analytic_locFDR_BF_uncor: This function analytically computes the local FDR & Bayes factor (BF) that quantifies the evidence of aggregate-level pleiotropic association for uncorrelated summary statistics.
1. cpbayes_uncor: It implements CPBayes for uncorrelated summary statistics to figure out the optimal subset of non-null traits underlying a pleiotropic signal and other insights. The summary statistics across traits/studies are uncorrelated when the studies have no overlapping subjects.
1. analytic_locFDR_BF_cor: This function analytically computes the local FDR & Bayes factor (BF) that quantifies the evidence of aggregate-level pleiotropic association for correlated summary statistics.
1. cpbayes_cor: It implements CPBayes for correlated summary statistics to figure out the optimal subset of non-null traits underlying a pleiotropic signal and other insights. The summary statistics across traits/studies are correlated when the studies have overlapping subjects or the phenotypes were measured in a cohort study. 
1. post\_summaries: It summarizes the MCMC data produced by cpbayes\_uncor or cpbayes\_cor. It computes additional summaries to provide a better insight into a pleiotropic signal. It works in the same way for both cpbayes\_uncor and cpbayes\_cor.
1. forest\_cpbayes: It creates a forest plot presenting the pleiotropy result obtained by cpbayes\_uncor or cpbayes\_cor. It works in the same way for both cpbayes\_uncor and cpbayes\_cor.
1. estimate\_corln: It computes an approximate correlation matrix of the beta-hat vector for multiple overlapping case-control studies using the sample-overlap matrices.

# Installation

You can install CPBayes from CRAN.

```{r install_package, eval=FALSE, collapse = TRUE}
install.packages("CPBayes")
library("CPBayes")
```

# How to run CPBayes for uncorrelated summary statistics. 

Load the example data.

```{r load_Beta, collapse = TRUE}
library("CPBayes")
# Load the beta hat vector
BetaHatfile <- system.file("extdata", "BetaHat.rda", package = "CPBayes")
load(BetaHatfile)
BetaHat
```

BetaHat contains an example data of the main genetic effect (beta/log odds ratio) estimates for a single nucleotide polymorphism (SNP) obtained from 10 separate case-control studies for 10 different diseases. In each case-control study comprising a distinct set of 7000 cases and 10000 controls, we fit a logistic regression of the case-control status on the genotype coded as the minor allele count for all the individuals in the sample. One can also include various covariates, such as, age, gender, principal components (PCs) of ancestries in the logistic regression. From each logistic regression for a disease, we obtain the estimate of the main genetic association parameter (beta/logodds ratio) along with the corresponding standard error. Since the studies do not have any overlapping subject, beta-hat across the diseases are uncorrelated.  

```{r load_SE, collapse = TRUE}
# Load the standard error vector
SEfile <- system.file("extdata", "SE.rda", package = "CPBayes")
load(SEfile)
SE
```

SE contains the standard errors corresponding to the above beta hat vector across 10 separate case-control studies. 

Next we specify the name of the diseases/phenotypes and the genetic variant.
```{r names, collapse = TRUE}
# Specify the name of the traits and the genetic variant.
traitNames <- paste("Disease", 1:10, sep = "")
SNP1 <- "rs1234"
traitNames
SNP1
```

Now, since the studies are non-overlapping, the summary statistics across traits are uncorrelated. Here we run the analytic_locFDR_BF_uncor function for this example data.
  
```{r example_analytic_calculation_uncor, collapse = TRUE}
#Run analytic_locFDR_BF_uncor function to analytically compute locFDR and log10BF for uncorrelated summary statistics.
result <- analytic_locFDR_BF_uncor(BetaHat, SE)
str(result)
```
So, locFDR [result\$locFDR] was analytically computed as 3.43*10^(-6) and log10(Bayes factor) [result\$log10_BF] was estimated as 3.93 indicating an aggregate-level pleiotropic association. While analytically computing locFDR (BF), a fixed value of slab variance is considered.   

Next we implement CPBayes for this example data. Since the studies are non-overlapping, the summary statistics across traits are uncorrelated. Hence we run the cpbayes\_uncor function.
  
```{r uncor_example, collapse = TRUE}
# Run the uncorrelated version of CPBayes (based on MCMC).
result <- cpbayes_uncor(BetaHat, SE, Phenotypes = traitNames, Variant = SNP1, MCMCiter = 5500, Burnin = 500)
```

There are more options of arguments to pass into the function (see the Arguments section of cpbayes\_uncor in the CPBayes manual). After running cpbayes\_uncor, it prints the list of important traits for which the trait-specific posterior probability of association (PPAj) > 20%. However, the printed output is only a part of 'result' which is a list that constitutes of various components. An overall summary of 'result' can be seen by using the str() function (as shown below). 

```{r result_structure, collapse= TRUE}
# Overall summary of the primary results produced by cpbayes_uncor.
str(result)
```

Here, result\$variantName returns the name of the genetic variant specified by the user. Here, it is 'rs1234'. Estimated based on the MCMC posterior sample, result\$log10\_BF provides the log10(Bayes factor) and result\$locFDR provides the local false discovery rate (posterior probability of null association) evaluating the aggregate-level pleiotropic association. These values were different from that obtained by the analytical version (above). The main reason is that the locFDR (log10BF) obtained by cpbayes\_uncor() function are estimated based on MCMC sample and a range of slab variance is considered. We recommend using the locFDR (log10BF) value obtained from the analytical version. Next, result\$subset provides the optimal subset of associated/non-null traits selected by CPBayes. CPBayes selected Disease7, Disease9, and Disease10 as associated/non-null. It also gives a list of important traits (important\_traits) comprising phenotypes having PPAj > 20%. Even if a phenotype is not selected in the optimal subset of non-null traits, it can produce a non-negligible value of trait-specific posterior probability of association (PPAj) and can be promising to be pleiotropic. For example, Disease8 had a PPAj of 21% and was listed in important\_traits, but was not included in the optimal subset. A detailed interpretation of all the outputs are described in the Value section of cpbayes\_uncor in the CPBayes manual.

The post\_summaries function provides important insights into an obseved pleiotropic signal, e.g. the direction of associations, trait-specific posterior probability of associations (PPAj), posterior mean/median and 95\% credible interval (Bayesian analog of the confidence interval) of the unknown true genetic effect (beta/odds ratio) on each trait, etc.

```{r post_summary, collapse= TRUE}
# Post summary of the MCMC data produced by cpbayes_uncor.
PleioSumm <- post_summaries(result, level = 0.05)  
str(PleioSumm)
```

So we have to pass the list 'result' returned by cpbayes\_uncor as the first argument and the 'level' as the second argument into the post\_summaries function. If 'level' is not specified, the default value is 0.05. Note that post\_summaries computes (1-level)\% credible interval of the unknown true genetic effect (beta/odds ratio) on each trait. It estimates the direction of association with the important traits, the vector of trait-specific posterior probability of association (PPAj), etc. For detailed description of different outputs provided by this function, see the Value section of post_summaries in the CPBayes manual.

Next we run the forest\_cpbayes function to create a forest plot that presents the pleiotropy result produced by cpbayes\_uncor.

```{r forest_plot, eval = FALSE, collapse= TRUE}
# Forest plot for the pleiotropy result obtained by cpbayes_uncor.
forest_cpbayes(result, level = 0.05)
```

Similarly as for the post\_summaries function, we need to pass the same list `result' returned by cpbayes\_uncor as the first argument into the function. Second argument is the level whose default value is 0.05. In the forest plot, (1-level)% confidence interval of the beta/log odds ratio parameter is plotted for each trait. For more details, please see the section of forest_cpbayes function in the CPBayes manual.

# How to run CPBayes for correlated summary statistics.

Next we demonstrate how to run CPBayes for correlated summary statistics. Get the path to the data.

```{r load_cBeta, collapse = TRUE}
# Load the beta-hat vector
datafile <- system.file("extdata", "cBetaHat.rda", package = "CPBayes")
load(datafile)
cBetaHat
```

Here, 'c' in cBetaHat stands for correlated case. cBetaHat contains an example data of the main genetic association parameter (beta/log odds ratio) estimates for a SNP across 10 overlapping case-control studies for 10 different diseases. Each of the 10 studies has a distinct set of 7000 cases and a common set of 10000 controls shared across all the studies. In each case-control study, we fit a logistic regression of the case-control status on the genotype coded as the minor allele count for all the individuals in the sample. One can also include various covariates, such as, age, gender, principal components (PCs) of ancestries in the logistic regression. From each logistic regression for a disease, we obtain the estimate of the main genetic effect (beta/log odds ratio) along with the corresponding standard error. Since the studies have overlapping subjects, beta-hat across the diseases are correlated.  

```{r load_cSE, collapse = TRUE}
# Load the standard error vector
datafile <- system.file("extdata", "cSE.rda", package = "CPBayes")
load(datafile)
cSE
```

cSE contains the standard errors corresponding to the above beta hat vector across 10 overlapping case-control studies. 

```{r load_cor, collapse = TRUE}
# Load the correlation matrix of the beta-hat vector (cBetaHat)
datafile <- system.file("extdata", "cor.rda", package = "CPBayes")
load(datafile)
cor
```

Since the summary statistics across traits are correlated, we run the the analytic_locFDR_BF_cor function for this example data.

```{r example_analytic_calculation_cor, collapse = TRUE}
# Run analytic_locFDR_BF_cor function to analytically compute locFDR and log10BF for correlated summary statistics.
result <- analytic_locFDR_BF_cor(cBetaHat, cSE, cor)
str(result)
```

So the locFDR [result\$locFDR] was analytically computed as 3.54*10^(-10) and log10(Bayes factor) [result\$log10_BF] was estimated as 9.18 indicating an aggregate-level pleiotropic association.   

The correlation matrix of the beta-hat vector (cBetaHat) is given by 'cor' which we estimated by employing the estimate_corln function (demonstrated later in this tutorial) using the sample-overlap matrices (explained later in this tutorial). Next we run the correlated version of CPBayes based on MCMC for this example data.

```{r cor_example, collapse = TRUE}
# Run the correlated version of CPBayes.
result <- cpbayes_cor(cBetaHat, cSE, cor, Phenotypes = traitNames, Variant = SNP1, MCMCiter = 5500, Burnin = 500)
```

There are more options of arguments to pass into the function (see the Arguments section of cpbayes\_cor in the CPBayes manual). After running cpbayes\_cor, it prints the list of important traits for which the trait-specific posterior probability of association (PPAj) > 20%. However, the printed outputs are only a part of 'result' which is a list that constitutes of various components. An overall summary of 'result' can be seen by using the str() function (as shown below). 

```{r result_structure_cor, collapse= TRUE}
# Overall summary of the primary results produced by cpbayes_cor.
str(result)
```

Here, result\$variantName returns the name of the genetic variant specified by the user. Here, it is 'rs1234'. Estimated based on the MCMC sample, result\$log10\_BF provides the log10(Bayes factor) and result\$locFDR provides the local false discovery rate (posterior probability of null association) measuring the evidence of aggregate-level pleiotropic association. Again, these values were different from that obtained by the analytical version. The main reason is that the locFDR (log10BF) obtained by cpbayes\_cor() function are estimated based on MCMC sample and a range of slab variance is considered. We recommend using the locFDR (log10BF) value obtained from the analytical version. However, for large number of traits (say > 25), analytic_locFDR_BF_cor may be slow to run. Next, result\$subset provides the optimal subset of associated traits selected by CPBayes. A detailed interpretation of all the outputs are described in the Value section of cpbayes\_cor in the CPBayes manual. 

The post\_summaries function provides important insights into an observed pleiotropic signal, e.g., the direction of associations, trait-specific posterior probability of associations (PPAj), posterior mean/median and 95\% credible interval (Bayesian analog of the confidence interval) of the unknown true genetic effect (beta/odds ratio) on each trait, etc.

```{r post_summary_cor, collapse= TRUE}
# Post summary of the MCMC data produced by cpbayes_cor.
PleioSumm <- post_summaries(result, level = 0.05)  
str(PleioSumm)
```

Note that, post\_summaries works exactly in the same way for both cpbayes\_cor and cpbayes\_uncor. For detailed description of different outputs provided by post\_summaries, see the Value section of post_summaries in the CPBayes manual.

Next we run the forest\_cpbayes function to create a forest plot that presents the pleiotropy result produced by cpbayes\_cor.

```{r forest_plot_cor, eval=FALSE, collapse= TRUE}
# Forest plot for the pleiotropy result obtained by cpbayes_cor.
forest_cpbayes(result, level = 0.05)
```

Note that, forest\_cpbayes works exactly in the same way for both cpbayes_cor and cpbayes_uncor. For more details, see the section of forest_cpbayes function in the CPBayes manual.

# How to run estimate_corln.
The function estimate\_corln estimates the correlation matrix of the beta-hat vector for multiple overlapping case-control studies using the sample-overlap matrices which describe the number of cases or controls shared between studies/traits, and the number of subjects who are case for one study/trait but control for another study/trait. For a cohort study, the phenotypic correlation matrix should be a reasonable substitute of this correlation matrix. 

```{r corln_estimation_example, collapse = TRUE}
# Example data of sample-overlap matrices
SampleOverlapMatrixFile <- system.file("extdata", "SampleOverlapMatrix.rda", package = "CPBayes")
load(SampleOverlapMatrixFile)
SampleOverlapMatrix
```

SampleOverlapMatrix is a list that contains an example of the sample overlap matrices for five different diseases in the Kaiser GERA cohort (a real data). The list constitutes of three matrices as follows. SampleOverlapMatrix\$n11 provides the number of cases shared between all possible pairs of studies/traits. SampleOverlapMatrix\$n00 provides the number of controls shared between all possible pairs of studies/traits. SampleOverlapMatrix\$n10 provides the number of subjects who are case for one study/trait and control for another study/trait. For more detailed explanation, see the Arguments section of estimate\_corln in the CPBayes manual. 

```{r run_corln_estimation, collapse = TRUE}
# Estimate the correlation matrix of correlated beta-hat vector
n11 <- SampleOverlapMatrix$n11
n00 <- SampleOverlapMatrix$n00
n10 <- SampleOverlapMatrix$n10
cor <- estimate_corln(n11, n00, n10)
cor
```

 The function estimate\_corln computes an approximate correlation matrix of the correlated beta-hat vector obtained from multiple overlapping case-control studies using the sample-overlap matrices. Note that for a cohort study, the phenotypic correlation matrix should be a reasonable substitute of this correlation matrix. These approximations of the correlation structure are accurate when none of the diseases/traits is associated with the environmental covariates and genetic variant. While demonstrating cpbayes\_cor, we used simulated data for 10 overlapping case-control studies with each study having a distinct set of 7000 cases and a common set of 10000 controls shared across all the studies. We used the estimate\_corln function to estimate the correlation matrix of the correlated beta-hat vector using the sample-overlap matrices.  
 
 ***Important note on the estimation of correlation structure of correlated beta-hat vector:*** In general, environmental covariates are expected to be present in a study and associated with the phenotypes of interest. Also, a small proportion of genome-wide genetic variants are expected to be associated. Hence the above approximations of the correlation matrix may not be accurate. So in general, we recommend an alternative strategy to estimate the correlation matrix using the genome-wide summary statistics data across traits as follows. First, extract all the SNPs for each of which the trait-specific univariate association p-value across all the traits are > 0.1. The trait-specific univariate association p-values are obtained using the beta-hat and standard error for each trait. Each of the SNPs selected in this way is either weakly or not associated with any of the phenotypes (null SNP). Next, select a set of independent null SNPs from the initial set of null SNPs by using a threshold of r^2 < 0.01 (r: the correlation between the genotypes at a pair of SNPs). In the absence of in-sample linkage disequilibrium (LD) information, one can use the reference panel LD information for this screening. Finally, compute the correlation matrix of the effect estimates (beta-hat vector) as the sample correlation matrix of the beta-hat vector across all the selected independent null SNPs. This strategy is more general and applicable to a cohort study or multiple overlapping studies for binary or quantitative traits with arbitrary distributions. It is also useful when the beta-hat vector for multiple non-overlapping studies become correlated due to genetically related individuals across studies. Misspecification of the correlation structure can affect the results produced by CPBayes to some extent. Hence, if genome-wide summary statistics data across traits is available, we recommend this alternative strategy to estimate the correlation matrix of the beta-hat vector. 
 
See our paper for more details: Majumdar A, Haldar T, Bhattacharya S, Witte JS (2018) An efficient Bayesian meta analysis approach for studying cross-phenotype genetic associations. PLoS Genet 14(2): e1007139.
