--- 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.