---
title: "BioMM: Biological-informed Multi-stage Machine learning framework for phenotype prediction using omics data"
author:
 - name: Junfang Chen and Emanuel Schwarz
   affiliation: Central Institute of Mental Health, Heidelberg University, Germany  
date: "Modified: 28 Aug 2020. Compiled: `r format(Sys.Date(), '%d %b %Y')`"
output: 
  BiocStyle::html_document: 
    toc_float: false
    number_sections: true 
    href: BioMMtutorial.html 

vignette: >
   %\VignetteIndexEntry{BioMMtutorial}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
---

```{r style, echo = FALSE, results = 'asis'}
BiocStyle::markdown()
```
```{r global_options, include=FALSE}  
knitr::opts_chunk$set(message=FALSE, error=FALSE, warning=FALSE, fig.width=8, 
fig.height=8)
options(width=133) 
```


# Overview
## Motivation
The identification of reproducible biological patterns from high-dimensional omics data is a key factor in understanding the biology of complex disease or traits. Incorporating prior biological knowledge into machine learning is an important step in advancing such research.

## Deliverables
We have implemented a biologically informed multi-stage machine learning framework termed __BioMM__ [1] specifically for phenotype prediction using omics-scale data based on prior biological information including gene ontological (GO) and KEGG pathways.   

**Features of BioMM in a nutshell**:   

1. Applicability for various omics data modalities (e.g. methylome, transcriptomics, genomics).   
2. Various biological stratification strategies.    
3. Prioritizing outcome-associated functional patterns.   
4. End-to-end prediction at the individual level based on biological stratified patterns.   
4. Possibility for an extension to machine learning models of interest.   
6. Parallel computing. 

# Getting started  

## Installation and dependencies

*  Install BioMM from Bioconductor (R 4.0):
```{r eval=FALSE}
## Do not execute if you have already installed BioMM.
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
# The following initializes usage of Bioc devel
BiocManager::install(version='devel')
BiocManager::install("BioMM")
```

BioMM installation from Github
```{r eval=FALSE}
install.packages("devtools")
library("devtools")
install_github("transbioZI/BioMM", build_vignettes=TRUE)
``` 

* Load required libraries
```{r loadPkg, eval=TRUE, results="hide"}
library(BioMM)
library(BiocParallel) 
library(ranger)
library(rms)
library(glmnet)
library(e1071)
library(precrec)
library(vioplot)
library(CMplot)
library(imager)
library(topGO)
library(xlsx)
```

# Omics data 
A wide range of omics data is supported for BioMM including whole-genome DNA methylation, transcriptome-wide gene expression and genome-wide SNP data. Other types of omics data that can map into pathways are also encouraging.  
For a better understanding of the BioMM framework, we used two small examplar datasets: one genome-wide DNA methylation data consisting of 20 subjects and 26486 CpGs, and one genome-wide gene expression data comprising of 20 subjects and  15924 genes for demonstration.  

```{r studyData, eval=TRUE}
## DNA methylation data 
methylData <- readRDS(system.file("extdata", "/methylData.rds", package="BioMM"))
# The first column is the label, and the rest are the features (e.g., CpGs) 
head(methylData[,1:4])
# 0: control and 1: patient
table(methylData[,1]) 
dim(methylData)

## Gene expression data
expData <- readRDS(system.file("extdata", "/expData.rds", package="BioMM"))
# The first column is the label, and the rest are the features (e.g., genes) 
head(expData[,1:4])
# 0: control and 1: patient
table(expData[,1]) 
dim(expData)
``` 

# Feature stratification
Features like CpGs, genes or SNPs can be mapped into pathways based on genomic location and pathway annotation, as implemented in the function `omics2pathlist()`. The examples of pathway databases are gene ontology (GO), KEGG and Reactome, which are widely used public repositories. Gene ontological and KEGG pathways are used in this tutorial.

```{r annotationFile, eval=TRUE}
## Load feature annotation data
featureAnno <- readRDS(system.file("extdata", "cpgAnno.rds", package="BioMM"))
# The mapping between CpGs and genes (i.e. entrezID or gene symbol)
head(featureAnno)
# total number of CpGs under investigation
str(unique(featureAnno[,1]))

## Reprocessed Gene ontological pathway annotation with 10 and 200 genes for each pathway
golist <- readRDS(system.file("extdata", "goDB.rds", package="BioMM")) 
## Number of investigated biological processes
length(golist)
str(golist[1:3])

## Reprocessed KEGG pathway annotation with 10 and 200 genes for each pathway
kegglist <- readRDS(system.file("extdata", "keggDB.rds", package="BioMM"))  
## Number of investigated KEGG pathways 
length(kegglist)
str(kegglist[1:3]) 

``` 

To annotate pathways, we demonstrate the usage of `omics2pathlist()` function based on two different pathway databases and two data modalities as follows.

```{r pathlist, eval=TRUE} 
## Feature annotation to pathways 
## Use 100 pathways to reduce the runtime for the downstream analysis. But if possible, please make sure to use all.
numPath <- 100

# GO pathway mapping using DNA methylation data
golistSub <- golist[seq_len(numPath)]
methylGOlist <- omics2pathlist(data=methylData, pathlistDB=golistSub, 
                               featureAnno=featureAnno, 
                               restrictUp=200, restrictDown=10, minPathSize=10) 
# KEGG pathway mapping using DNA methylation data
kegglistSub <- kegglist[seq_len(numPath)]
methylKEGGlist <- omics2pathlist(data=methylData, pathlistDB=kegglistSub, 
                                 featureAnno=featureAnno, 
                                 restrictUp=200, restrictDown=10, minPathSize=10) 

# GO pathway mapping using gene expression data
golistSub <- golist[seq_len(numPath)]
expGOlist <- omics2pathlist(data=expData, pathlistDB=golistSub, 
                            featureAnno=NULL, 
                            restrictUp=200, restrictDown=10, minPathSize=10) 
# KEGG pathway mapping using gene expression data
kegglistSub <- kegglist[seq_len(numPath)]
expKEGGlist <- omics2pathlist(data=expData, pathlistDB=kegglistSub, 
                              featureAnno=NULL, 
                              restrictUp=200, restrictDown=10, minPathSize=10) 

``` 

# BioMM framework
## Recapitulation
Briefly, the BioMM framework consists of two learning stages [1]. During the first stage, biological meta-information is used to 'compress' the variables of the original dataset into pathway-level 'latent variables' (henceforth called stage-2 data) using either supervised or unsupervised learning models (stage-1 models). In the second stage, a supervised model (stage-2 model) is built using the stage-2 data with non-negative outcome-associated features for final prediction. 

### Interface to machine learning models 
The end-to-end prediction is performed using `BioMM()` function. Both supervised and unsupervised learning are implemented in the BioMM framework, which is indicated by the argument `supervisedStage1=TRUE` or `supervisedStage1=FALSE`. Commonly used supervised classifiers: generalized regression models with lasso, ridge or elastic net regularization (GLM) [4], support vector machine (SVM) [3] and random forest [2] are included. For the unsupervised method, regular or sparse constrained principal component analysis (PCA) [5] is used. `predMode` indicates the prediction type. In the case of classification setting, the "probability" or "classification" mode can be used. Generic resampling methods include cross-validation (CV) and bootstrapping (BS) procedures as the argument `resample1="CV"` or `resample1="BS"`. Stage-2 data is reconstructed using either resampling methods during machine learning prediction or independent test set prediction if the argument `testData` is provided. For more details, please check `BioMM()` in the manual.

#### BioMM with Random Forest  
To apply BioMM with the Random Forest model, we use the argument `supervisedStage1=TRUE` and `classifier=randForest` in `BioMM()`. DNA methylation data mapping to GO pathways is used.

```{r BioMMrandForest4methylGO, eval=TRUE}
## To reduce the runtime, only use a subset of DNA methylation data
## However, if possible, subsetting the data is not suggested.
trainData <- methylData[,1:3000]  
trainDataY <- trainData[,1]
testData <- NULL

## Model parameters
supervisedStage1=TRUE
classifier <- "randForest"
predMode <- "probability"
paramlist <- list(ntree=100, nthreads=20)   
core <- MulticoreParam(workers = 10) 

set.seed(123)
result <- BioMM(trainData=trainData, testData=NULL, 
                pathlistDB=golistSub, featureAnno, 
                restrictUp=200, restrictDown=10, minPathSize=10, 
                supervisedStage1, typePCA="regular", 
                resample1="BS", resample2="CV", dataMode="allTrain",
                repeatA1=50, repeatA2=1, repeatB1=10, repeatB2=1, 
                nfolds=10, FSmethod1=NULL, FSmethod2=NULL, 
                cutP1=0.05, cutP2=0.05, fdr2=NULL, 
                FScore=MulticoreParam(workers = 1), 
                classifier, predMode, paramlist, innerCore=core)

if (is.null(testData)) {
    metricCV <- getMetrics(dataY = trainDataY, predY = result)
    message("Cross-validation prediction performance:")
    print(metricCV)
} else if (!is.null(testData)){
    testDataY <- testData[,1]  
    metricCV <- getMetrics(dataY = trainDataY, cvYscore = result[[1]])
    metricTest <- getMetrics(dataY = testDataY, testYscore = result[[2]])
    message("Cross-validation performance:")
    print(metricCV)
    message("Test set prediction performance:")
    print(metricTest)
}

``` 

Other machine learning models can be employed with the following respective parameter settings. For the classifier `"SVM"`, parameters can be tuned using an internal cross-validation if `tuneP=TRUE`. For generalized regression model `glmnet`, elastic net is specified by the input argument `alpha=0.5`. Alternatively, `alpha=1` is for the lasso and `alpha=0` is the ridge. For the unsupervised learning `supervisedStage1=FALSE`, regular PCA `typePCA="regular"` is applied and followed with random forest classification `classifier2=TRUE`.

### Interface to biological stratification

For the stratification of predictors using biological information, various strategies can be applied. In this tutorial, `BioMM()` integrates GO and KEGG pathway based stratification, which not only accounts for epistasis between stage-1 features within the functional category, but also considers the interaction between pathway-level features. Therefore, this may provide more value-relevant information on biological insight into the underlying phenotype.  
 
#### BioMM with KEGG pathways

To apply BioMM with the random forest model, we use the argument `supervisedStage1=TRUE` and `classifier=randForest` in `BioMM()`. Gene expression data mapping to KEGG pathways is demonstrated.

```{r BioMMrandForest4expKEGG, eval=TRUE}
## to reduce the runtime, only use a subset of gene expression data
## However, if possible, subsetting the data is not suggested.
trainData <- expData[,1:3000] 
trainDataY <- trainData[,1] 
testData <- NULL 
## Only for gene expression data
featureAnno=NULL
## Model parameters
supervisedStage1=TRUE
classifier <- "randForest"
predMode <- "probability"
paramlist <- list(ntree=100, nthreads=20)   
core <- MulticoreParam(workers = 10) 

set.seed(123)
result <- BioMM(trainData=trainData, testData=NULL, 
                pathlistDB=kegglistSub, featureAnno, 
                restrictUp=200, restrictDown=10, minPathSize=10, 
                supervisedStage1, typePCA="regular", 
                resample1="BS", resample2="CV", dataMode="allTrain",
                repeatA1=50, repeatA2=1, repeatB1=10, repeatB2=1, 
                nfolds=10, FSmethod1=NULL, FSmethod2=NULL, 
                cutP1=0.05, cutP2=0.05, fdr2=NULL, 
                FScore=MulticoreParam(workers = 1), 
                classifier, predMode, paramlist, innerCore=core)

## Cross-validation is applied on the training data, therefore 'result' only returns the CV predicted score.
metricCV <- getMetrics(dataY = trainDataY, predY = result)
message("Cross-validation prediction performance:")
print(metricCV)
``` 


## Stage-2 data exploration 
### Generation of stage-2 data
Here we use BioMM with the Random Forest method on gene expression data incorporating KEGG pathways to create stage-2 pathway-level data.

```{r stage2dataAprep, eval=TRUE} 
## Define the omics type 
# omicsType <- "methylation"
omicsType <- "expression"
pathType <- "GO"
pathType <- "KEGG"
if (omicsType == "methylation" & pathType == "GO"){
    studylist <- methylGOlist
} else if (omicsType == "methylation" & pathType == "KEGG"){
    studylist <- methylKEGGlist
} else if (omicsType == "expression" & pathType == "GO"){
    studylist <- expGOlist
} else if (omicsType == "expression" & pathType == "KEGG"){
    studylist <- expKEGGlist
} else {
    stop("Wrong specified omicsType and pathType!")
} 

length(studylist)

## Model parameters 
classifier <- "randForest"
predMode <- "probability"
paramlist <- list(ntree=100, nthreads=20)   
core <- MulticoreParam(workers = 10) 

set.seed(123)
stage2dataA <- reconBySupervised(trainDataList=studylist, 
                   testDataList=NULL,
                   resample="BS", dataMode="allTrain",
                   repeatA=50, repeatB=1, nfolds=10,
                   FSmethod=NULL, cutP=0.05, fdr=NULL, 
                   FScore=MulticoreParam(workers = 1),
                   classifier, predMode, paramlist,
                   innerCore=core, outFileA=NULL, outFileB=NULL)
## Check stage-2 data
dim(stage2dataA)
print(table(stage2dataA[,1]))
head(stage2dataA[,1:4])

``` 

### Feature Visualization
#### Explained variation of stage-2 data
The distribution of the proportion of variance explained for the individual generated feature of stage-2 data for the classification task is illustrated `plotVarExplained()` below. Nagelkerke pseudo R-squared measure is used to compute the explained variance. The argument `posF=TRUE` indicates that only positively outcome-associated features are plotted since negative associations likely reflect random effects in the underlying data [6].

``` {r stage2dataViz, eval=TRUE}
core <- MulticoreParam(workers = 10)   
fileName <- paste0(omicsType,"_", pathType, "_featuresVarExplained.png")
plotVarExplained(data=stage2dataA, posF=TRUE, binarize=FALSE, core=core, 
                 pathTitle=paste0(pathType, " pathways"), fileName)

plot(load.image(fileName)) 

``` 

#### Prioritization of outcome-associated functional patterns 
`plotRankedFeature()` is employed to rank and visualize the outcome-associated features from stage-2 data. The argument `topF=10` and `posF=TRUE` are used to define the top 10 positively outcome-associated features. The negative log P value using logistic regression is utilized to evaluate the importance of the ranked features as indicated by the argument `rankMetric="negPlogit"`. Other metrics including Nagelkerke pseudo R-squared "R2", and Z score "Zscore" measure are also available (see `plotRankedFeature` in the manual for details). The size of the respective pathway is pictured as the argument `colorMetric="size"`. 

``` {r topPathFeatures, eval=TRUE, fig.show="hold"} 
core <- MulticoreParam(workers = 1)   
rankMetric <- "negPlogit" 
filePrefix <- paste0(omicsType, "_", pathType, "_topPath_", rankMetric)
topPath <- plotRankedFeature(data=stage2dataA, 
                             posF=TRUE, topF=10, binarize=FALSE, 
                             blocklist=studylist,  
                             rankMetric=rankMetric, 
                             colorMetric="size",  core, 
                             pathTitle=paste0(pathType, " pathways"), 
                             fileName=paste0(filePrefix, ".png"))
plot(load.image(paste0(filePrefix, ".png")))   

``` 

The statistical metrics and descriptions of these above top pathways are shown below:

``` {r reportTopPath, eval=TRUE} 
## Report the top pathways
if (pathType == "GO"){
    
  goterms = unlist(Term(GOTERM))  
  topGOID = gsub("\\.", ":", rownames(topPath))
  subTerm = goterms[is.element(names(goterms), topGOID)] 
  topIDmatch = subTerm[match(topGOID, names(subTerm))]  
  topPath <- data.frame(topPath, Description=topIDmatch)
  
} else if (pathType == "KEGG"){
  ## A matching list between KEGG ID and names. Data freezes on Aug 2020
  keggID2name <- readRDS(system.file("extdata", "/keggID2name202008.rds", 
                                     package="BioMM"))  
  keggSub <- keggID2name[is.element(keggID2name[,"ID"], rownames(topPath)),]
  topIDmatch <- keggSub[match(rownames(topPath), keggSub[,"ID"]),] 
  topPath <- data.frame(topPath, Description=topIDmatch[,"name"])
}

print(topPath) 
write.xlsx(topPath,file=paste0(filePrefix, ".xlsx"))
# write.table(topPath,file=paste0(filePrefix, ".txt"), sep="\t")

``` 

#### The significance of CpGs in pathways of interest
`cirPlot4pathway()` illustrates the significance of the individual CpGs (for DNA methylation data) or genes (for gene expression data) falling into a set of pathways. Here the top 10 outcome-associated pathways are investigated. Negative log P value is used to define the significance of each CpG or genes within these pathways.

``` {r cirPlot, eval=TRUE, fig.show="hold"}  
core <- MulticoreParam(workers = 10)   
pathID <- gsub("\\.", ":", rownames(topPath))
## The number of top pathways must be bigger than overall investigated pathways
pathSet <- studylist[is.element(names(studylist), pathID)]
pathMatch <- pathSet[match(pathID, names(pathSet))]
fileName <- paste0(omicsType, "_", pathType, "_SigRankBy_", rankMetric)

cirPlot4pathway(datalist=pathMatch, topPathID=names(pathMatch), core, fileName)


``` 

## Computational consideration
BioMM with supervised models at both stages incorporating pathway based stratification method will take longer to run than unsupervised approaches. But the prediction is more powerful. Therefore, we suggest the former even if the computation is more demanding, as the adoption of the next-generation technology (e.g., 5G) is pushing advances in computational storage and speed. 

Furthermore, the stability of BioMM prediction is often facilitated with the increasing number of resampling repetitions and some other related model parameters such as the number of trees used in the Random Forest model. Finally, parallel computing is implemented and recommended for such a scenario. In this vignette, due to the runtime, we only showcased the smaller examples and models with less computation. 


# Session information

``` {r sessioninfo, eval=TRUE} 
sessionInfo()
```  

# References

[1] NIPS ML4H submission: Chen, J. and Schwarz, E., 2017. BioMM: 
Biologically-informed Multi-stage Machine learning for identification of 
epigenetic fingerprints. arXiv preprint arXiv:1712.00336. 

[2] Breiman, L. (2001). "Random forests." Machine learning 45(1): 5-32.

[3] Cortes, C., & Vapnik, V. (1995). "Support-vector networks." 
Machine learning 20(3): 273-297.

[4] Friedman, J., Hastie, T., & Tibshirani, R. (2010). "Regularization paths 
for generalized linear models via coordinate descent." 
Journal of statistical software 33(1): 1.

[5] Wold, S., Esbensen, K., & Geladi, P. (1987). "Principal component 
analysis." Chemometrics and intelligent laboratory systems 2(1-3): 37-52.

[6] Claudia Perlich and Grzegorz Swirszcz. On cross-validation and stacking: 
Building seemingly predictive models on random data. ACM SIGKDD Explorations 
Newsletter, 12(2):11-15, 2011. 





