--- title: "DMRs identification with mCSEA package" author: - name: Jordi Martorell-Marugán affiliation: - Bioinformatics Unit. GENYO, Centre for Genomics and Oncological Research - name: Pedro Carmona-Sáez affiliation: - Bioinformatics Unit. GENYO, Centre for Genomics and Oncological Research email: pedro.carmona@genyo.es package: mCSEA date: "`r doc_date()`" abstract: > mCSEA (methylathed CpGs Set Enrichment Analysis) searches Differentially Methylated Regions (DMRs) between conditions using methylation data from Illumina's 450k or EPIC microarrays. The evaluated DMRs are predefined regions (promoters, gene bodies, CpG Islands and user-defined regions). This package contains functions to rank the CpG probes, to apply a GSEA analysis for DMRs identification, to plot the results and to integrate them with expression data. output: BiocStyle::pdf_document vignette: > %\VignetteIndexEntry{Predefined DMRs identification with mCSEA package} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} references: - id: du10 title: "Comparison of Beta-value and M-value methods for quantifying methylation levels by microarray analysis" author: - family: Du given: P - family: Zhang given: X - family: Huang given: C - family: Jafari given: N - family: Kibbe given: WA - family: Hou given: L - family: Lin given: SM container-title: BMC Bioinformatics issued: year: 2010 volume: 11 issue: 587 - id: jones12 title: "Functions of DNA Methylation: islands, start sites, gene bodies and beyond" author: - family: Jones given: Peter A. container-title: Nature Reviews Genetics issued: year: 2012 volume: 13 issue: 7 --- # Previous steps This package is not intended to process raw methylation data. The input of mCSEA is tipically a matrix with the processed $\beta$-values for each probe and sample. If you start from the raw methylation files (like .idat files) you should first preprocess the data with any of the available packages for that purpose (e.g. `r Biocpkg("minfi")` or `r Biocpkg("ChAMP")`). Minfi includes functions to get a matrix of $\beta$-values (_getBeta()_) or M-values (_getM()_). ChAMP output class depends on the type of analysis performed. For instance, _champ.norm()_ function returns a matrix, while _champ.load()_ returns a list of results, and one of them is a $\beta$-values matrix. So mCSEA is totally compatible with minfi and ChAMP outputs as long as a matrix with the methylation values is obtained. # Step 1: Ranking CpGs probes To run a mCSEA analysis, you must rank all the evaluated CpGs probes with some metric (e.g. t-statistic, Fold-Change...). You can use _rankProbes()_ function for that aim, or prepare a ranked list with the same structure as the _rankProbes()_ output. We load sample data to show how _rankProbes()_ works: ```{r, message = FALSE, results='hide'} library(mCSEA) data(mcseadata) ``` We loaded to our R environment **betaTest** and **phenoTest** objects, in addition to **exprTest**, annotation objects and association objects (we will talk about these after). **betaTest** is a matrix with the $\beta$-values of 10000 EPIC probes for 20 samples. **phenoTest** is a dataframe with the explanatory variable and covariates associated to the samples. When you load your own data, the structure of your objects should be similar. ```{r} head(betaTest, 3) print(phenoTest) ``` _rankProbes()_ function uses these two objects as input and apply a linear model with `r Biocpkg("limma")` package. By default, _rankProbes()_ considers the first column of the phenotypes table as the explanatory variable in the model (e.g. cases and controls) and does not take into account any covariate to adjust the models. You can change this behaviour modifying **explanatory** and **covariates** options. By default, _rankProbes()_ assumes that the methylation data object contains $\beta$-values and transform them to M-values before calculating the linear models. If your methylation data object contains M-values, you must specify it (typeInput = "M"). You can also use $\beta$-values for models calculation (typeAnalysis = "beta"), although we do not recommend it due to it has been proven that M-values better accomplish the statistical assumptions of limma analysis (@du10). ```{r} myRank <- rankProbes(betaTest, phenoTest, refGroup = "Control") ``` **myRank** is a named vector with the t-values for each CpG probe. ```{r} head(myRank) ``` You can also supply _rankProbes()_ function with a SummarizedExperiment object. In that case, if you don't specify a **pheno** object, phenotypes will be extracted from the SummarizedExperiment object with _colData()_ function. ## Paired analysis It is possible to take into account paired samples in _rankProbes()_ analysis. For that aim, you should use paired = TRUE parameter and specify the column in pheno containing pairing information (pairColumn parameter). # Step 2: Searching DMRs in predefined regions Once you calculated a score for each CpG, you can perform the mCSEA analysis. For that purpose, you should use _mCSEATest()_ function. This function takes as input the vector generated in the previous step, the methylation data and the phenotype information. By default, it searches for differentially methylated promoters, gene bodies and CpG Islands. You can specify the regions you want to test with _regionsTypes_ option. _minCpGs_ option specifies the minimum amount of CpGs in a region to be considered in the analysis (5 by default). You can increase the number of processors to use with _nproc_ option (recommended if you have enough computational resources). By default, mCSEA performs 10000 permutations to calculate P-values, but you can change that with _nperm_ option. Finally, you should specify if the array platform is 450k or EPIC with the _platform_ option. Note that _mCSEATest()_ performs permutations to get the P-values, so each time it is executed, the results are not exactly the same. To avoid that, we recommend to include a _set.seed()_ in order to get reproducible results. ```{r, warning=FALSE} set.seed(123) myResults <- mCSEATest(myRank, betaTest, phenoTest, regionsTypes = "promoters", platform = "EPIC") ``` _mCSEATest()_ returns a list with the GSEA results and the association objects for each region type analyzed, in addition to the input data (methylation, phenotype and platform). ```{r} ls(myResults) ``` **promoters** is a data frame with the following columns (partially extracted from `r Biocpkg("fgsea")` help): * *pval:* Estimated P-value. * *padj:* P-value adjusted by BH method. * *ES:* Enrichment score. * *NES:* Normalized enrichment score by number of CpGs associated to the feature. * *nMoreExtreme:* Number of times a random gene set had a more extreme enrichment score value. * *size:* Number of CpGs associated to the feature. * *leadingEdge:* Leading edge CpGs which drive the enrichment. ```{r} head(myResults[["promoters"]][,-7]) ``` On the other hand, **promoters_association** is a list with the CpG probes associated to each feature: ```{r} head(myResults[["promoters_association"]], 3) ``` You can also provide a custom association object between CpG probes and regions (_customAnnotation_ option). This object should be a list with a structure similar to this: ```{r} head(assocGenes450k, 3) ``` # Step 3: Plotting the results Once you found some DMRs, you can make a plot with the genomic context of the interesting ones. For that, you must provide _mCSEAPlot()_ function with the _mCSEATest()_ results, and you must specify which type of region you want to plot and the name of the DMR to be plotted (e.g. gene name). There are some graphical parameters you can adjust (see _mCSEAPlot()_ help). Take into account that this function connects to some online servers in order to get genomic information. For that reason, this function could take some minutes to finish the plot, specially the first time it is executed. ```{r, message = FALSE, results='hide'} mCSEAPlot(myResults, regionType = "promoters", dmrName = "CLIC6", transcriptAnnotation = "symbol", makePDF = FALSE) ``` You can also plot the GSEA results for a DMR with _mCSEAPlotGSEA()_ function. ```{r} mCSEAPlotGSEA(myRank, myResults, regionType = "promoters", dmrName = "CLIC6") ``` # Integrating methylation and expression data If you have both methylation and expression data for the same samples, you can integrate them in order to discover significant associations between methylation changes in a DMR and an expression alterations in a close gene. _mCSEAIntegrate()_ considers the DMRs identified by _mCSEATest()_ passing a P-value threshold (0.05 by default). It calculates the mean methylation for each condition using the leading edge CpGs and performs a correlation test between this mean DMR methylation and the expression of close genes. This function automatically finds the genes located within a determined distance (1.5 kb) from the DMR. Only correlations passing thresholds (0.5 for correlation value and 0.05 por P-value by default) are returned. For promoters, only negative correlations are returned due to this kind of relationship between promoters methylation and gene expression has been largely observed (@jones12). On the contrary, only positive correlations between gene bodies methylation and gene expression are returned, due to this is a common relationship observed (@jones12). For CpG islands and custom regions, both positive and negative correlations are returned, due to they can be located in both promoters and gene bodies. To test this function, we extracted a subset of 100 genes expression from bone marrows of 10 healthy and 10 leukemia patients (**exprTest**). Data was extracted from `r Biocpkg("leukemiasEset")` package. ```{r} # Explore expression data head(exprTest, 3) # Run mCSEAIntegrate function resultsInt <- mCSEAIntegrate(myResults, exprTest, "promoters", "ENSEMBL") resultsInt ``` It is very important to specify the correct gene identifiers used in the expression data (_geneIDs_ parameter). _mCSEAIntegrate()_ automatically generates correlation plots for the significant results and save them in the directory specified by _folder_ parameter (current directory by default). ![Integration plot for GATA2 promoter methylation and ENSG00000179348 expression. Note that, actually, both names refers to the same gene, but SYMBOL was used to analyze promoters methylation and ENSEMBL ID was used as gene identifiers in the expression data.](GATA2_ENSG00000179348_promoters.pdf) # Session info ```{r sessionInfo, echo=FALSE} sessionInfo() ``` # References