---
title: "ELMER v.2: An R/Bioconductor package to reconstruct gene regulatory networks from DNA methylation and transcriptome profiles"
author: "Tiago Chedraoui Silva [aut], Lijing Yao [aut], Simon Coetzee [aut], Nicole Gull [ctb], Houtan Noushmehr [ctb], Dennis J. Hazelett [ctb], Peggy Farnham [aut], Hui Shen [ctb], Peter Laird [ctb], De-Chen Lin[ctb], Benjamin P. Berman [aut]"
date: "`r Sys.Date()`"
output: 
  html_document:
    self_contained: true
    number_sections: no
    theme: flatly
    highlight: tango
    mathjax: null
    toc: true
    toc_float: true
    toc_depth: 2
    css: style.css
fontsize: 11pt
bibliography: bibliography.bib    
vignette: >
  %\VignetteIndexEntry{"1 - ELMER v.2: An R/Bioconductor package to reconstruct gene regulatory networks from DNA methylation and transcriptome profiles"}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

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

# Introduction
  
DNA methylation can be used to identify functional changes at transcriptional enhancers and other cis-regulatory modules (CRMs) in tumors and other primary disease tissues. Our R/Bioconductor package  `r BiocStyle::Biocpkg("ELMER")` (Enhancer Linking by Methylation/Expression Relationships) provides a systematic approach that reconstructs gene regulatory networks (GRNs) by combining methylation and gene expression data derived from the same set of samples.  `r BiocStyle::Biocpkg("ELMER")` uses methylation changes at CRMs as the central hub of these networks, using correlation analysis to associate them with both upstream master regulator  (MR) transcription factors and downstream target genes.  
  
This package can be easily applied to TCGA public available cancer data sets and custom DNA methylation and gene expression data sets.
  
ELMER analyses have 5 main steps: 
  
  1. Identify distal probes on HM450K or EPIC arrays.
  2. Identify distal probes with significantly different DNA methylation level
  between two groups
  3. Identify putative target genes for differentially methylated distal probes.
  4. Identify enriched motifs for the distalprobes which are significantly 
  differentially methylated and linked to putative target gene.
  5. Identify regulatory TFs whose expression associate with DNA methylation at enriched motifs.
  
# Package workflow
  
The package workflow is showed in the figure below:
  
![ELMER workflow: ELMER receives as input a DNA methylation object, a gene expression object (both can be either a matrix or a SummarizedExperiment object) and a Genomic Ranges (GRanges) object with distal probes to be used as a filter which can be retrieved using the `get.feature.probe` function. The function `createMAE`  will create a Multi Assay Experiment object keeping only samples that have both DNA methylation and gene expression data. Genes will be mapped to genomic position and annotated using ENSEMBL database, while for probes it will add annotation from (http://zwdzwd.github.io/InfiniumAnnotation). This MAE object will be used as input to the next analysis functions. First, it identifies differentially methylated probes followed by the identification of their nearest genes (10 upstream and 10 downstream) through the  `get.diff.meth` and  `GetNearGenes` functions respectively. For each probe, it will verify if any of the nearby genes were affected by its change in the DNA methylation level and a list of  gene and probes pairs will be outputted from `get.pair` function. For the probes in those pairs, it will search for enriched regulatory Transcription Factors motifs with the  `get.enriched.motif` function. Finally, the  enriched motifs will be correlated with the level of the transcription factor through the `get.TFs` function. In the figure green Boxes represent user input data, blue boxes represent output object, orange boxes represent auxiliary pre-computed data and gray boxes are functions. ](figures/workflow.png)
  
# Main differences between ELMER v2 vs ELMER v1

## Summary table

|                                |                 ELMER Version 1                |                            ELMER Version 2                           |
|--------------------------------|:----------------------------------------------|:--------------------------------------------------------------------|
| Primary data structure         | mee object (custom data structure)             | MAE object (Bioconductor data structure)                             |
| Auxiliary data                 | Manually created                               | Programmatically created                                             |
| Number of human TFs            | 1,982                                          | 1,639 (curated list from Lambert, Samuel A., et al.)                 |
| Number of TF motifs            | 91                                             | 771  (HOCOMOCO v11 database)                                         |
| TF classification              | 78 families                                    | 82 families and 331 subfamilies \newline(TFClass database, HOCOMOCO) |
| Analysis performed             | Normal vs tumor samples                        | Group 1 vs group 2                                                   |
| Statistical grouping           | **Unsupervised** only                              | **Unsupervised** or **supervised** using labeled groups                      |
| TCGA data source               | The Cancer Genome Atlas (TCGA) (not available) | The NCI's Genomic Data Commons (GDC)                                 |
| Genome of reference            | GRCh37 (hg19)                                  | GRCh37 (hg19)/GRCh38 (hg38)                                          |
| DNA methylation platforms      | HM450                                          | EPIC and HM450                                                       |
| Graphical User Interface (GUI) | None                                           | TCGAbiolinksGUI                                                      |
| Automatic report               | None                                           | HTML summarizing results                                             |
| Annotations                    | None                                           | StateHub                                                             |

## Supervised vs Unsupervised mode

In ELMER v2 we introduce a new concept, the algorithm `mode` that can be either `supervised` or `unsupervised`. 
In the unsupervised mode (described in ELMER v1), it is assumed that one of the two groups is a heterogeneous mix of different (sometimes unknown) molecular phenotypes. For instance, in the example of Breast Cancer, normal breast tissues (Group A) are relatively homogenous, whereas Breast tumors fall into multiple molecular subtypes.

The assumption of the Unsupervised mode is that methylation changes may be restricted to a subset of one or more molecular subtypes, and thus only be present in a fraction of the samples in the test group. For instance, methylation changes related to estrogen signaling may only be present in LuminalA or LuminalB subtypes. 

When this structure is unknown, the Unsupervised mode is the appropriate model, since it only requires changes in a subset of samples (by default, 20%). In contrast, in the Supervised mode, it is assumed that each group represents a more homogenous molecular phenotype, and thus we compare all samples in Group A vs. all samples in Group B. This can be used in the case of direct comparison of tumor subtypes (i.e. Luminal vs. Basal-like tumors), but can also be used in numerous other situations, including sorted cells of different types, or treated vs. untreated samples in perturbation experiments.

# Installing and loading ELMER
  
To install this package from github (development version), start R and enter:
  
```{r, eval = FALSE}
devtools::install_github(repo = "tiagochst/ELMER.data")
devtools::install_github(repo = "tiagochst/ELMER")
```
  
To install this package from Bioconductor start R and enter:
  
```{r, eval = FALSE}
if (!requireNamespace("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("ELMER")
```
  
Then, to load ELMER enter:
  
```{r, fig.height=6,echo=FALSE, message=FALSE, warning=FALSE, include=TRUE}
library(ELMER, quietly = TRUE)
```

# Citing this work

If you used ELMER package or its results, please cite:

* Yao, L., Shen, H., Laird, P. W., Farnham, P. J., & Berman, B. P. "Inferring regulatory element landscapes and transcription factor networks from cancer methylomes." Genome Biol 16 (2015): 105.
* Yao, Lijing, Benjamin P. Berman, and Peggy J. Farnham. "Demystifying the secret mission of enhancers: linking distal regulatory elements to target genes." Critical reviews in biochemistry and molecular biology 50.6 (2015): 550-573. 
* Tiago C Silva, Simon G Coetzee, Nicole Gull, Lijing Yao, Dennis J Hazelett, Houtan Noushmehr, De-Chen Lin, Benjamin P Berman; ELMER v.2: An R/Bioconductor package to reconstruct gene regulatory networks from DNA methylation and transcriptome profiles, Bioinformatics, , bty902, https://doi.org/10.1093/bioinformatics/bty902

If you get TCGA data using `getTCGA` function, please cite TCGAbiolinks package: 

* Colaprico A, Silva TC, Olsen C, Garofano L, Cava C, Garolini D, Sabedot T, Malta TM, Pagnotta SM, Castiglioni I, Ceccarelli M, Bontempi G and Noushmehr H. "TCGAbiolinks: an R/Bioconductor package for integrative analysis of TCGA data." Nucleic acids research (2015): gkv1507.
* Silva, TC, A Colaprico, C Olsen, F D’Angelo, G Bontempi, M Ceccarelli, and H Noushmehr. 2016. “TCGA Workflow: Analyze Cancer Genomics and Epigenomics Data Using Bioconductor Packages [Version 2; Referees: 1 Approved, 1 Approved with Reservations].” F1000Research 5 (1542). doi:10.12688/f1000research.8923.2.

* Grossman, Robert L., et al. "Toward a shared vision for cancer genomic data." New England Journal of Medicine 375.12 (2016): 1109-1112.

If you get use the Graphical user interface, please cite `TCGAbiolinksGUI` package: 

* Silva, Tiago C. and Colaprico, Antonio and Olsen, Catharina and Bontempi, Gianluca and Ceccarelli, Michele and Berman, Benjamin P. and Noushmehr, Houtan. "TCGAbiolinksGUI: A graphical user interface to analyze cancer molecular and clinical data" (bioRxiv 147496; doi: https://doi.org/10.1101/147496)

# Bugs and questions 

If you have questions, wants to report a bug, please use our github repository: http://www.github.com/tiagochst/ELMER

# Paper supplemental material

TCGA-BRCA reports  (paper supplemental material) can be found at https://tiagochst.github.io/ELMER_supplemental/

# Session Info

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