---
title: "recountmethylation User's Guide"
author:
- Sean K. Maden
- Reid F. Thompson
- Kasper D. Hansen
- Abhinav Nellore
date: "`r format(Sys.time(), '%d %B, %Y')`"
bibliography: bibliography.bib
csl: cell-numeric.csl
package: recountmethylation
output:
  BiocStyle::html_document:
    code_folding: show
    toc: yes
    tocfloat: yes
  BiocStyle::pdf_document: 
    toc: yes
    toc_depth: 2
vignette: > 
  %\VignetteIndexEntry{recountmethylation User's Guide}
  %\VignetteDepends{RCurl}
  %\usepackage[UTF-8]{inputenc} 
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---

```{r setup, echo = FALSE, warning = FALSE}
suppressMessages(library(knitr))
suppressMessages(library(GenomicRanges))
suppressMessages(library(limma))
suppressMessages(library(minfi))
suppressMessages(library(ExperimentHub))
suppressMessages(library(recountmethylation))
knitr::opts_chunk$set(echo = TRUE, eval = TRUE, warning = FALSE, 
  message = FALSE)
```

# Introduction and overview

The `recountmethylation` package provides access to databases of DNA 
methylation (DNAm) data from over 62,000 cumulative sample records with 
IDATs in the Gene Expression Omnibus (GEO, available by November, 2020). 
Samples were run using either of 2 Illumina BeadArray platform types, 
either the older HM450K platform or the newer EPIC/HM850K platform. The
database compilation files include mined, mapped, and model-based sample 
metadata, and DNAm data in the form of either raw/unnormalized red and 
green signals, raw/unnormalized methylated and unmethylated signals, or 
normalized DNAm fractions (a.k.a. "Beta-values") @maden_human_2020. 
Normalization was performed using the out-of-band signal correction (a.k.a. 
"noob") method, a type of within-sample normalization @triche_low-level_2013.

This User's Guide shows how to use the `recountmethylation` package to obtain, 
load, and query the DNAm databases with 2 small example files. Background about 
DNAm arrays, DNAm measurement, `SummarizedExperiment` objects, database file 
types, and samples metadata is also provided. Further analysis examples are 
contained in the `data_analyses` vignette.

## Disclaimer

Databases accessed with `recountmethylation` contain data from GEO 
(ncbi.nlm.nih.gov/geo/), a live public database where alterations to 
online records can cause discrepancies with stored data over time. 
We cannot guarantee the accuracy of stored data, and advise users 
cross-check their findings with latest available records.

## Database files and access

Database compilation file download and access is managed by the `get_db` 
functions, where the DNAm array platform type using the `platform` argument
(see `?get_db` for details). Both HM450K and EPIC/HM850K platforms are 
currently supported (see below for platform details). Note you will need 
between 50-180 Gb of disk space to store a single database file. Files pair 
sample metadata and assay data in various formats, including `HDF5-SummarizedExperiment` database directories, and `HDF5` database files 
with the `.h5` extension. 

The databases are located at 
[https://methylation.recount.bio/](https://methylation.recount.bio/), 
and file details are viewable as follows:

```{r, echo = TRUE, message = TRUE}
sm <- as.data.frame(smfilt(get_servermatrix()))
if(is(sm, "data.frame")){knitr::kable(sm, align = "c")}
```

## ExperimentHub integration

The DNAm array database files are indexed on `ExperimentHub`, and are 
viewable as follows. Note, the cache needs to be set with `R_user_dir()` per instructions [here](https://bioconductor.org/packages/devel/bioc/vignettes/ExperimentHub/inst/doc/ExperimentHub.html#default-caching-location-update).

```{r, eval = F}
cache.path <- tools::R_user_dir("recountmethylation")
setExperimentHubOption("CACHE", cache.path)
hub <- ExperimentHub::ExperimentHub()                    # connect to the hubs
rmdat <- AnnotationHub::query(hub, "recountmethylation") # query the hubs
```

In addition to using the `getdb` functions, the `HDF5` (".h5"" extension) 
files may be downloaded from the hubs.

```{r, eval = F}
fpath <- rmdat[["EH3778"]] # download with default caching
rhdf5::h5ls(fpath)         # load the h5 file
```

Note that whether downloads use the hubs or `getdb` functions, caching 
is implemented to check for previously downloaded database files.

# Background

This section includes essential background about DNAm array platforms, assays 
and file types, and sample metadata.

## DNAm arrays

Databases include human samples run on the Illumina Infinium HM450K BeadArray 
platform. HM450K is a popular 2-channel platform that probes over 480,000 CpG 
loci genome-wide, with enriched coverage at CG islands, genes, and enhancers 
@sandoval_validation_2011. The more recently released EPIC/HM850K platform 
contains an expanded probe set targeting over 850,000 CpGs, including 
more than 90% of the HM450K probes, with greater coverage of potential intergenic 
regulatory regions @pidsley_critical_2016.

Array processing generates 2 intensity files (IDATs) per sample, one each for 
the red and green color channels. These raw files also contain control signals 
useful for quality evaluations @noauthor_illumina_2010. The BeadArray probes use 
either of 2 bead technologies, known as Type I and Type II, where the majority 
(72%) of probes use the latter. For Type II probes, a single bead assay informs 
a single probe, while Type I probes use 2 beads each. Practically, this means 
the bead-specific matrices found in `RGChannelSet` objects are larger than the 
probe-specific matrices found in derived object types (e.g. for HM450K samples, 
622,399 assays for red/green signal matrices versus 485,512 assays for 
methylated/unmethylated signal, DNAm fractions matrices, see below).

## `SummarizedExperiment` object classes

DNAm array sample IDATs can be read into an R session as an object of class 
`RGChannelSet`, a type of `SummarizedExperiment`. These objects support 
analyses of high-throughput genomics datasets, and they include slots for 
assay matrices, sample metadata, and experiment metadata. During a typical 
workflow, normalization and preprocessing convert `RGChannelSet` objects into 
new types like `MethylSet` and `RatioSet`. While not all IDAT information is 
accessible from every object type (e.g. only `RGChannelSet`s can contain 
control assays), derived objects like `MethylSet`s and `RatioSet`s may be 
smaller and/or faster to access.

Three `SummarizedExperiment` databases are provided as 
`HDF5-SummarizedExperiment` files, including an unnormalized `RGChannelSet` 
(red/green signals), an unnormalized `MethylSet` (methylated/unmethylated 
signals) and a normalized `GenomicRatioSet` (DNAm fractions). For the latter, 
DNAm fractions (logit2 Beta-values, or M-values) were normalized using the 
out-of-band signal or "noob" method, an effective within-sample normalization 
that removes signal artifacts @triche_low-level_2013.

## Database file types

Database files are stored as either `HDF5` or `HDF5-SummarizedExperiment`. For 
most R users, the latter files will be most convenient to work with. `HDF5`, or 
hierarchical data format 5, combines compression and chunking for convenient 
handling of large datasets. `HDF5-SummarizedExperiment` files combine the 
benefits of `HDF5` and `SummarizedExperiment` entities using a 
DelayedArray-powered backend. Once an `HDF5-SummarizedExperiment` file is 
loaded, it can be treated similarly to a `SummarizedExperiment` object in 
active memory. That is, summary and subset operations execute rapidly, and 
realization of large data chunks in active memory is delayed until called for 
by the script (see examples).

## Sample metadata

Sample metadata are included with DNAm assays in the database files. Currently, 
metadata variables include GEO record IDs for samples (GSM) and studies (GSE), 
sample record titles, learned labels for tissue and disease, sample type 
predictions from the MetaSRA-pipeline, and DNAm model-based predictions for 
age, sex, and blood cell types. Access sample metadata from 
`SummarizedExperiment` objects using the `pData` minfi function (see examples). 
Examples in the `data_analyses` vignette illustrate some ways to utilize the 
provided sample metadata.

Provided metadata derives from the GSE-specific SOFT files, which contain 
experiment, sample, and platform metadata. Considerable efforts were made to 
learn, harmonize, and predict metadata labels. Certain types of info lacking 
in the `recountmethylation` metadata may be available in the SOFT files, 
especially if it is sample non-specific (e.g. methods text, PubMed ID, etc.) 
or redundant with DNAm-derived metrics (e.g. DNAm summaries, predicted sex, 
etc.).

It is good practice to validate the harmonized metadata with original metadata 
records, especially where labels are ambiguous or there is insufficient 
information for a given query. GEO GSM and GSE records can be viewed from a 
browser, or SOFT files may be downloaded directly. Packages like GEOmetadb and 
GEOquery are also useful to query and summarize GEO metadata.

# `HDF5-SummarizedExperiment` example

This example shows basic handling for `HDF5-SummarizedExperiment` (a.k.a. 
"h5se") files. For these files, the `getdb` function returns the loaded file. 
Thanks to a `DelayedArray` backend, even full-sized `h5se` databases can be 
treated as if they were fully loaded into active memory.

## Obtain the test database

The test `h5se` dataset includes sample metadata and noob-normalized 
DNAm fractions (Beta-values) for chromosome 22 probes for 2 samples. 
Datasets can be downloaded using the `getdb` series of functions 
(see `?getdb` for details), where the `dfp` argument specifies the 
download destination. The test `h5se` file is included in the package 
"inst" directory, and can be loaded as follows.

```{r}
dn <- "remethdb-h5se_gr-test_0-0-1_1590090412"
path <- system.file("extdata", dn, package = "recountmethylation")
h5se.test <- HDF5Array::loadHDF5SummarizedExperiment(path)
```

## Inspect and summarize the database

Common characterization functions can be used on the dataset after it has been 
loaded. These include functions for `SummarizedExperiment`-like objects, such 
as the `getBeta`, `pData`, and `getAnnotation` minfi functions. First, inspect 
the dataset using standard functions like `class`, `dim`, and `summary` as 
follows.

```{r}
class(h5se.test) # inspect object class
```

```{r}
dim(h5se.test) # get object dimensions
```

```{r}
summary(h5se.test) # summarize dataset components
```

Access the sample metadata for the 2 available samples using `pData`. 

```{r}
h5se.md <- minfi::pData(h5se.test) # get sample metadata
dim(h5se.md)                       # get metadata dimensions
```
```{r}
colnames(h5se.md) # get metadata column names
```

Next get CpG probe-specific DNAm fractions, or "Beta-values", with `getBeta` 
(rows are probes, columns are samples).

```{r}
h5se.bm <- minfi::getBeta(h5se.test) # get dnam fractions
dim(h5se.bm)                         # get dnam fraction dimensions
```
```{r}
colnames(h5se.bm) <- h5se.test$gsm       # assign sample ids to dnam fractions
knitr::kable(head(h5se.bm), align = "c") # show table of dnam fractions 
```

Access manifest information for probes with `getAnnotation`. This includes the 
bead addresses, probe type, and genome coordinates and regions. For full details 
about the probe annotations, consult the minfi and Illumina platform documentation.

```{r}
an <- minfi::getAnnotation(h5se.test) # get platform annotation
dim(an)                               # get annotation dimensions
```

```{r}
colnames(an) # get annotation column names
```

```{r}
ant <- as.matrix(t(an[c(1:4), c(1:3, 5:6, 9, 19, 24, 26)])) # subset annotation
knitr::kable(ant, align = "c")                              # show annotation table
```

# `HDF5` database and example

To provide more workflow options, bead-specific red and green signal data have 
been provided with sample metadata in an `HDF5`/`h5` file. This example shows 
how to handle objects of this type with `recountmethylation`.

## Obtain the test database

The test `h5` file includes metadata and bead-specific signals from 
chromosome 22 for the same 2 samples as in the `h5se` test file. 
Note `getdb` functions for `h5` files simply return the database path.
Since the test `h5` file has also been included in the package "inst" folder,
get the path to load the file as follows.

```{r}
dn <- "remethdb-h5_rg-test_0-0-1_1590090412.h5"     # get the h5se directory name
h5.test <- system.file("extdata", "h5test", dn, 
                    package = "recountmethylation") # get the h5se dir path
```

## Inspect and summarize the database

Use the file path to read data into an `RGChannelSet` with the `getrg` 
function. Setting `all.gsm = TRUE` obtains data for all samples in the
database files, while passing a vector of GSM IDs to `gsmv` argument 
will query a subset of available samples. Signals from all available 
probes are retrieved by default, and probe subsets can be obtained by 
passing a vector of valid bead addresses to the `cgv` argument.

```{r}
h5.rg <- getrg(dbn = h5.test, all.gsm = TRUE) # get red/grn signals from an h5 db
```

To avoid exhausting active memory with the full-sized `h5` dataset, provide 
either `gsmv` or `cgv` to `getrg`, and set either `all.cg` or `all.gsm` to 
FALSE (see `?getrg` for details).

As in the previous example, use `pData` and `getAnnotation` to get sample 
metadata and array manifest information, respectively. Access the green and 
red signal matrices in the `RGChannelSet` with the `getRed` and `getGreen` 
minfi functions.

```{r}
h5.red <- minfi::getRed(h5.rg)     # get red signal matrix
h5.green <- minfi::getGreen(h5.rg) # get grn signal matrix
dim(h5.red)                        # get dimensions of red signal matrix
``` 
```{r}
knitr::kable(head(h5.red), align = "c") # show first rows of red signal matrix
```
```{r}
knitr::kable(head(h5.green), align = "c") # show first rows of grn signal matrix
```
```{r}
identical(rownames(h5.red), rownames(h5.green)) # check cpg probe names identical
```

Rows in these signal matrices map to bead addresses rather than probe IDs. 
These matrices have more rows than the `h5se` test Beta-value matrix because 
any type I probes use data from 2 beads each.

# Validate DNAm datasets

This section demonstrates validation using the test databases. Full code
to reproduce this section is provided but not evaluated, as it involves a 
download from the GEO servers. As the disclaimer notes, it is good practice
to validate data against the latest available GEO files. This step may be 
most useful for newer samples published close to the end compilation date 
(through November 7, 2020 for current version), which may be more prone to 
revisions at initial publication.

## Download and read IDATs from the GEO database server

Use the `gds_idat2rg` function to download IDATs for the 2 test samples 
and load these into a new `RGChannelSet` object. Do this by passing a vector
of GSM IDs to `gsmv` and the download destination to `dfp`. (note, chunks in
this section are fully executable, but not evaluated for this vignette).

```{r, eval = FALSE}
# download from GEO
dlpath <- tempdir()                                     # get a temp dir path
gsmv <- c("GSM1038308", "GSM1038309")                   # set sample ids to identify
geo.rg <- gds_idat2rg(gsmv, dfp = dlpath)               # load sample idats into rgset
colnames(geo.rg) <- gsub("\\_.*", "", colnames(geo.rg)) # assign sample ids to columns
```

## Compare DNAm signals

Extract the red and green signal matrices from `geo.rg`.

```{r, eval = FALSE}
geo.red <- minfi::getRed(geo.rg)      # get red signal matrix
geo.green <- minfi::getGreen(geo.rg)  # get grn signal matrix
```

Match indices and labels between the GEO and `h5` test signal matrices.

```{r, eval = FALSE}
int.addr <- intersect(rownames(geo.red), rownames(h5.red)) # get probe address ids
geo.red <- geo.red[int.addr,]                              # subset geo rgset red signal
geo.green <- geo.green[int.addr,]                          # subset gro rgset grn signal
geo.red <- geo.red[order(match(rownames(geo.red), rownames(h5.red))),]
geo.green <- geo.green[order(match(rownames(geo.green), rownames(h5.green))),]
identical(rownames(geo.red), rownames(h5.red))             # check identical addresses, red
identical(rownames(geo.green), rownames(h5.green))         # check identical addresses, grn
class(h5.red) <- "integer"; class(h5.green) <- "integer"   # set matrix data classes to integer
```

Finally, compare the signal matrix data.

```{r, eval = FALSE}
identical(geo.red, h5.red) # compare matrix signals, red
```
```{r, eval = FALSE}
identical(geo.green, h5.green) # compare matrix signals, grn
```

## Compare DNAm Beta-values

Before comparing the GEO-downloaded data to data from the `h5se.test` database, 
normalize the data using the same out-of-band or "noob" normalization technique 
that was used to generate data in the `h5se` database.

```{r, eval = FALSE}
geo.gr <- minfi::preprocessNoob(geo.rg) # get normalized se data
```

Next, extract the Beta-values.

```{r, eval = FALSE}
geo.bm <- as.matrix(minfi::getBeta(geo.gr)) # get normalized dnam fractions matrix
```

Now match row and column labels and indices.

```{r, eval = FALSE}
h5se.bm <- as.matrix(h5se.bm) # set dnam fractions to matrix
int.cg <- intersect(rownames(geo.bm), rownames(h5se.bm))
geo.bm <- geo.bm[int.cg,]     # subset fractions on shared probe ids
geo.bm <- geo.bm[order(match(rownames(geo.bm), rownames(h5se.bm))),]
```

Finally, compare the two datasets.

```{r, eval = FALSE}
identical(summary(geo.bm), summary(h5se.bm)) # check identical summary values
```
```{r, eval = FALSE}
identical(rownames(geo.bm), rownames(h5se.bm)) # check identical probe ids
```

# Troubleshooting and tips

This section describes how to address potential issues with accessing the
database files or working with the `DelayedArray` based objects locally.

## Issue: large file downloads don't complete

If repeated attempts to download the database compilation files fail, you
may try the following:

* First ensure your internet connection is stable and there is sufficient 
space at the download destination for the database file. 

* Second, try increasing your timeout duration beyond the default before 
repeating the download attempt with `getdb`. Check the current timeout 
for an R session with `getOptions('timeout')`, then manually increase 
the timeout duration with `options(timeout = new.time)`.

* Finally, you may attempt to download a server file using command line 
calls to your system terminal or console. For instance, on a Mac you 
might try `wget -r <file_url>`. If this doesn't work, you can again 
attempt to increase the timeout duration and repeat the download attempt.

## Issue: unexpected function behaviors for `DelayedArray` inputs

Unexpected function behaviors may arise when using `DelayedArray`-based inputs.
These essentially arise from lacking interoperativity between normal matrices 
and the `DelayedArray`-based matrices. Known examples include:

* `minfi::detectionP()`: 

Throws error for specific subsets of data, such as for queries of exactly 
50 samples. 

```{r, eval = FALSE}
detectionP(rg[,1:50]) # get detection pvalues from rgset
"Error in .local(Red, Green, locusNames, controlIdx, TypeI.Red, TypeI.Green, dim(Red_grid) == dim(detP_sink_grid) are not all TRUE"
```

* `minfi::preprocessFunnorm()`: 

Throws error when called for an `RGChannelSet` of type `HDF5-SummarizedExperiment`.

```{r, eval = FALSE}
preprocessFunnorm(rg) # get noob-normalized data
"Error: 'preprocessFunnorm()' only supports matrix-backed minfi objects.""
```

These and other related errors may be addressed by instantiating the data query, 
or the data chunk, as a new non-`DelayedArray` object. For example, remake a 
subset of the full `h5se` dataset, `rg`, as follows.

```{r, eval = FALSE}
rg.h5se <- loadHDF5SummarizedExperiment(rg.path)        # full h5se RGChannelSet
rg.sub <- rg.h5se[,c(1:20)]                             # subset samples of interest
rg.new <- RGChannelSet(Red = getRed(rg.sub), 
                       Green = getGreen(rg.sub),
                       annotation = annotation(rg.sub)) # re-make as non-DA object
gr <- preprocessFunnorm(rg.new)                         # repeat preprocessing
```

Alternatively, non-`DelayedArray` `RGChannelSet` objects can be readily generated from
the full `h5` `RGChannelSet` database with the provided function `getrg()`.

# Get more help

Consult the Data Analyses [vignette](link.url) and main [manuscript](link.url) 
for analysis examples and details about data compilations.

# Session info

```{r get_sessioninfo}
sessionInfo()
```

# Works Cited
