mesa

Overview

mesa is an R package for Methylation Enrichment Sequencing Analysis, to investigate sequencing data that has been enriched for regions of CG methylation. This includes both MEDIP-Seq (Methylated DNA immunoprecipitation sequencing) or MBD-seq (methyl-CpG binding domain protein enriched sequencing).

This package builds off the qsea package, using the qseaSet object type defined in that package as the object that holds the data. One of the most useful features of the package is in defining tidyverse verbs to act on a qseaSet, such as filter, mutate and select, but there also includes a range of functionality for other tasks, such as plotting and quality control.

This package has been used in two published papers, in Nature Cancer and Nature Communications.

Development was undertaken internally between September 2022 and March 2024; these commits are now incorporated into this repository. This has involved an extensive rewriting of the package functions, with many function names changing, see the NEWS.md file for all the details.

The package is under active development. It has been submitted to Bioconductor and is under review.

How the package fits together

Sequencing data is read into a qseaSet, which every other part of the package takes as its input. Each box below names the file in R/ that implements it.

mesa architecture. Enriched sequencing data is read by makeQset.R, given coverage and normalisation by buildQset.R, and held as a qseaSet, the class from the qsea package. The qseaSet is consumed by three groups of functions: manipulation (dplyrVerbs.R, alterQset.R, combineQsets.R, mixQsets.R), quality control (sampleQC.R, calculateEnrichment.R, PCA.R with classes.R) and analysis (makeDMRs.R, qseaCNV.R). Results reach the reader through qseaExtra.R, plotting.R and analyseDMRs.R. Packaged reference data and session setup come from utilityFunctions.R, genome.R, the mappability bins in map_hg38.R and ENCODEbadRegions.R.

Install the package

Manual installation:

# 1. Install BiocManager if needed
if (!requireNamespace("BiocManager", quietly = TRUE))
  install.packages("BiocManager")

# 2. Set Bioconductor to the correct version for your R
BiocManager::install(ask = FALSE)

# 3. Install mesa
BiocManager::install("cruk-mi/mesa", dependencies = TRUE)

# 4. Verify everything is consistent
BiocManager::valid()

Development version:

To install the latest development version directly from GitHub:

install.packages("devtools")
devtools::install_github("cruk-mi/mesa")

⚠️ The development version may be unstable. Use the installer script above for a validated installation.

Quick start

mesa ships an example qseaSet, exampleTumourNormal: 10 samples (5 tumours and 5 matched adjacent normals) over a small part of chromosome 7. Everything below runs without any data of your own.

library(mesa)

# A qseaSet holds the sample metadata, counts, windows, CNV and library
# information for an experiment in a single object.
exampleTumourNormal

# The sample table is ordinary sample metadata, one row per sample.
exampleTumourNormal |>
    getSampleTable()

The distinguishing feature of mesa is that tidyverse verbs act on the qseaSet itself, filtering or annotating the sample table while reducing every other part of the object to match, behind the scenes:

lungOnly <- exampleTumourNormal |>
    filter(tissue == "Lung") |>
    mutate(label = paste(patient, type, sep = "_"))

Methylation values come out as tables, either as normalised reads per million or as beta values scaled between 0 (unmethylated) and 1 (methylated):

exampleTumourNormal |>
    getNRPMTable()

exampleTumourNormal |>
    getBetaTable()

Dimensionality reduction is two steps, calculate then plot:

exampleTumourNormal |>
    getPCA(nPC = 3) |>
    plotDimRed(colour = "group")

See the articles below for generating a qseaSet from BAM files, quality control, and calling differentially methylated regions.

Documentation

Full function reference and articles: https://cruk-mi.github.io/mesa/

Article Covers
Introduction to Mesa The qseaSet object, its parts, and the tidyverse verbs that act on it
Generating qseaSets Building a qseaSet from aligned, de-duplicated BAM files
Data Tables and Quality Control Count, NRPM and beta tables, and assessing whether enrichment worked
Dimensionality Reduction - PCAs and UMAPs getPCA(), getUMAP() and plotting the results
Differentially Methylated Regions and Annotation Calling DMRs between groups and annotating them to genomic features

The same articles are available from R once the package is installed, via vignette(package = "mesa").

Citation

mesa underpins the analysis in two published papers. If you use it, please cite whichever is applicable to your work:

Chemi F, Pearce SP, Clipson A, et al. (2022). cfDNA methylome profiling for detection and subtyping of small cell lung cancers. Nature Cancer 3(10), 1260-1270. https://doi.org/10.1038/s43018-022-00415-9

Conway A-M, Pearce SP, Clipson A, et al. (2024). A cfDNA methylation-based tissue-of-origin classifier for cancers of unknown primary. Nature Communications 15, 3292. https://doi.org/10.1038/s41467-024-47195-7

Contributing and support

If you are interested in using the package, we’re happy to hear from you.

mesa is developed at the Cancer Research UK National Biomarker Centre.