deconvR

Workflows

Standard Workflow

Map WGBS methylation data to Illumina probe IDs and predict cell-type proportions using a reference atlas.

library(deconvR)
data("HumanCellTypeMethAtlas")
data("IlluminaMethEpicB5ProbeIDs")

# Load WGBS data
load(system.file("extdata", "WGBS_GRanges.rda", package = "deconvR"))

# Map WGBS genomic coordinates to probe IDs
mapped_WGBS_data <- BSmeth2Probe(probe_id_locations = IlluminaMethEpicB5ProbeIDs, 
                                 WGBS_data = WGBS_GRanges,
                                 multipleMapping = TRUE,
                                 cutoff = 10)

# Perform deconvolution
deconvolution <- deconvolute(reference = HumanCellTypeMethAtlas, 
                             bulk = mapped_WGBS_data)
deconvolution$proportions

Input is a GRanges object of WGBS data and a probe ID location reference; output is a dataframe of predicted cell-type proportions.

Atlas Extension And Signature Generation

Extend an existing reference atlas with new sample data or construct tissue-specific CpG/DMP signature matrices.

library(deconvR)
data("HumanCellTypeMethAtlas")

# Simulate new sample data
samples <- simulateCellMix(3, reference = HumanCellTypeMethAtlas)$simulated

# Prepare sample metadata
sampleMeta <- data.table::data.table("Experiment_accession" = colnames(samples)[-1],
                                     "Biosample_term_name" = "new cell type")

# Extend the reference atlas
extended_matrix <- findSignatures(samples = samples, 
                                 sampleMeta = sampleMeta, 
                                 atlas = HumanCellTypeMethAtlas,
                                 IDs = "IDs")

Inputs are a sample matrix, metadata table, and reference atlas; output is an extended reference matrix.

When to Use

• Predicting cell-type proportions from bulk DNA methylation data using deconvolute.
• Mapping WGBS genomic coordinates to Illumina probe IDs using BSmeth2Probe.
• Simulating bulk omic mixtures with known proportions using simulateCellMix.
• Extending a reference atlas or generating tissue-specific CpG/DMP signatures using findSignatures.

When NOT to Use

• For single-cell RNA-seq clustering or cell-type annotation, use Seurat or scran because deconvR is designed for bulk deconvolution.
• For differential methylation locus identification without deconvolution, use methylKit because deconvR focuses on signature-based deconvolution.

Data Requirements

• Reference Atlas: A dataframe of cell types (columns) and CpG loci (rows, e.g., Illumina Probe IDs) containing methylation values between 0 and 1 (e.g., HumanCellTypeMethAtlas).
• Bulk Data: WGBS data as a GRanges object (e.g., WGBS_GRanges) or a methylKit object, or mapped probe-level data.
• Metadata: A data.table or data.frame mapping sample accessions to biosample terms.

Key Parameters

• probe_id_locations: A GRanges object containing probe IDs and genomic coordinates.
• WGBS_data: A GRanges or methylKit object containing methylation values.
• multipleMapping (TRUE): Logical indicating whether to allow multiple mapping in BSmeth2Probe.
• cutoff (10): Minimum coverage cutoff for mapping.
• reference: Reference atlas dataframe used for deconvolution.
• bulk: Mapped bulk methylation data dataframe.
• IDs: Column name containing probe or gene IDs.
• tissueSpecCpGs (FALSE): Logical to construct tissue-based methylation signature matrix.

Best Practices

• Check deconvolution performance by comparing simulated mixtures from simulateCellMix with deconvolute predictions.
• Verify that the reference matrix and bulk samples use the same identifier type (e.g., Illumina Probe IDs or Gene names).
• Use BSmeth2Probe to map WGBS coordinates to probe IDs before running deconvolution.
• Evaluate deconvolution quality using the partial R-squared values returned by deconvolute.

Common Pitfalls

• Mismatching ID column names: Ensure the IDs parameter in findSignatures matches the ID column name of the reference atlas and bulk data.
• Using unmapped WGBS coordinates directly: Map coordinates to probe IDs first using BSmeth2Probe before running deconvolute.
• Setting conflicting signature flags: Ensure only one of tissueSpecCpGs or tissueSpecDMPs is set to TRUE as they cannot be run together.

Alternatives

• methylKit for multi-sample DNA methylation analysis and differential methylation.
• minfi for analyzing Illumina Infinium Methylation Cleanup and normalization.
• Seurat for single-cell level expression analysis and integration.

Citations

• Moss, J. et al. (2018). Comprehensive human cell-type methylation atlas reveals origins of circulating cell-free DNA in health and disease. Nature communications, 9(1), 1-12.

References

• Homepage: bioconductor.org/packages/deconvR
• Vignette: https://bioconductor.org/packages/release/bioc/vignettes/deconvR/inst/doc/deconvR.html