DNA methylation modulates transcription factor (TF) binding and plays
an important role in regulating gene expression. TF activity is usually
inferred from gene expression or from chromatin accessibility aggregated
over TF binding motifs. methylTFR infers it from DNA
methylation instead. It summarises methylation at the binding sites of
each motif and reports one activity score per TF and sample, rather than
per locus. The result is low-dimensional, interpretable and directly
comparable to accessibility- and expression-based measures.
methylTFR takes CpG-level methylation calls from bulk or
aggregated single-cell experiments, together with a sample annotation
file. For each motif, it compares methylation at the centre of the
binding sites with the flanking regions (the observed
deviation). Because methylation depends on local GC content, it
also computes the deviation expected from the GC content of the motif
and the genome-wide GC distribution (the expected
deviation). The difference between the two is the
bias-corrected deviation score.
The genome-specific annotations (binding sites, motif GC frequency
tables and the genome-wide GC distribution) are provided by the
methylTFRAnnotation packages for hg38 and mm10, or can be
built for any assembly with methylTFRAnnotationBuilder. The
scores can then be used for dimensionality reduction, differential
activity testing, variability analysis and footprint plots, all included
in the package.
The method and its applications are described in the methylTFR preprint.
methylTFR is currently under review for Bioconductor.
Until it is accepted, install the development version from GitHub:
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes")
}
remotes::install_github("EpigenomeInformatics/methylTFR")Once accepted, it will be installable with:
To get started with methylTFR, load the package and its dependencies:
The readMethylome() function is used to import
single-sample DNA methylation data into a GRanges object.
It supports several common file formats, including EPP,
ALLC, BisSNP, bismarkCytosine,
bismarkCov, and ENCODE bedMethyl.
You can optionally filter out low-coverage sites using the
cov_threshold parameter (default = 1), which excludes
positions with insufficient read support.
Below is an example of reading an example EPP-formatted
file provided in the package:
epp_path <- system.file("extdata", "epp.tsv.gz", package = "methylTFR")
epp <- readMethylome(epp_path, "EPP")
epp
#> GRanges object with 6 ranges and 2 metadata columns:
#> seqnames ranges strand | score coverage
#> <Rle> <IRanges> <Rle> | <numeric> <numeric>
#> [1] chr1 3010957-3010958 + | 1.000 27
#> [2] chr1 3010959-3010960 - | 0.500 7
#> [3] chr1 3010971-3010972 + | 1.000 20
#> [4] chr1 3010973-3010974 - | 0.500 20
#> [5] chr1 3011025-3011026 + | 0.814 70
#> [6] chr1 3011027-3011028 - | 0.500 100
#> -------
#> seqinfo: 1 sequence from an unspecified genome; no seqlengthsComputing expected deviations requires precomputed annotations for
the genome of interest: transcription factor binding sites, a
genome-wide GC distribution, and per-motif GC frequency tables. These
are distributed separately from methylTFR, in an annotation
package named after the assembly, for example
methylTFRAnnotationHg38, because the binding sites alone
take several gigabytes for a full motif set.
With the annotation package installed, the three resources are retrieved as follows:
library(methylTFRAnnotationHg38)
tf_bindsites <- getTFbindsites(motifSet = "jaspar2020")
gcfreqs <- getGCfreq(motifSet = "jaspar2020")
gc_dist <- getGenomeGC()To build annotations for a different assembly, motif set, or region
restriction, use methylTFRAnnotationBuilder.
The examples in this vignette instead use a small BATF
subset bundled with methylTFR, so they run without any
annotation package.
methylTFR relies on several precomputed annotation
resources to estimate expected methylation levels at transcription
factor binding sites (TFBS). These annotations include:
gcdist_subset):
Genome-wide GC content distribution in 30-bp windows, used to model
methylation expectations.BATF_gcfreqs): GC
frequency profile specific to the BATF motif across TFBS, used to
correct for sequence composition bias.BATF_tf_bindsites):
A GRanges object containing the genomic coordinates of BATF
binding sites on chromosome 1.example_data): A small subset of methylation
calls, read with readMethylome(), provided for
demonstration purposes.The example methylation data in inst/extdata are derived
from ENCODE whole-genome bisulfite sequencing (ENCSR663MXB, GRCh38).
ENCODE data are released without restrictions. The script that creates
them is inst/scripts/vignette_data.R.
The following code loads these example datasets and displays the first few entries:
load(system.file("extdata", "gcdist_subset.rda", package = "methylTFR"))
load(system.file("extdata", "BATF_gcfreqs.rda", package = "methylTFR"))
load(system.file("extdata", "BATF_tf_bindsites.rda", package = "methylTFR"))
load(system.file("extdata", "example_data.rda", package = "methylTFR"))
head(gcdist)
#> GRanges object with 6 ranges and 2 metadata columns:
#> seqnames ranges strand | GC_bias GC_bin
#> <Rle> <IRanges> <Rle> | <numeric> <integer>
#> [1] chr1 13741-13770 * | 0.700000 5
#> [2] chr1 13801-13830 * | 0.600000 5
#> [3] chr1 47161-47190 * | 0.333333 2
#> [4] chr1 47191-47220 * | 0.333333 2
#> [5] chr1 52231-52260 * | 0.366667 3
#> [6] chr1 52351-52380 * | 0.333333 2
#> -------
#> seqinfo: 24 sequences from an unspecified genome; no seqlengths
head(gcfreqs$BATF[, 1:5])
#> [,1] [,2] [,3] [,4] [,5]
#> [1,] 0.1216832 0.1212626 0.1208012 0.1209724 0.1206374
#> [2,] 0.2540062 0.2544714 0.2551190 0.2541142 0.2549292
#> [3,] 0.1953771 0.1957679 0.1957418 0.1958386 0.1953064
#> [4,] 0.2333033 0.2332140 0.2330019 0.2339583 0.2334522
#> [5,] 0.1956302 0.1952841 0.1953362 0.1951166 0.1956748
head(tf_bindsites)
#> $BATF
#> GRanges object with 21327 ranges and 1 metadata column:
#> seqnames ranges strand | score
#> <Rle> <IRanges> <Rle> | <numeric>
#> [1] chr1 47430-47840 + | 16.7687
#> [2] chr1 57232-57642 + | 13.2598
#> [3] chr1 93216-93626 + | 14.9499
#> [4] chr1 96525-96935 + | 13.6042
#> [5] chr1 99285-99695 + | 13.9006
#> ... ... ... ... . ...
#> [21323] chr1 248685991-248686401 - | 13.2321
#> [21324] chr1 248707209-248707619 - | 13.4153
#> [21325] chr1 248758729-248759139 - | 13.4702
#> [21326] chr1 248773287-248773697 - | 14.1349
#> [21327] chr1 248935661-248936071 - | 13.7639
#> -------
#> seqinfo: 24 sequences from an unspecified genome; no seqlengths
head(msites)
#> GRanges object with 6 ranges and 2 metadata columns:
#> seqnames ranges strand | score coverage
#> <Rle> <IRanges> <Rle> | <numeric> <numeric>
#> [1] chr1 13749-13750 + | 0.8 5
#> [2] chr1 13755-13756 + | 0.8 5
#> [3] chr1 13822-13823 + | 0.6 5
#> [4] chr1 13827-13828 + | 1.0 5
#> [5] chr1 47175-47176 + | 1.0 1
#> [6] chr1 47176-47177 - | 1.0 3
#> -------
#> seqinfo: 195 sequences from an unspecified genome; no seqlengthsThe computeDeviation() function calculates the deviation
score for a specific transcription factor (TF) motif in a single sample.
It compares the observed methylation at TF binding sites (TFBS) to the
expected methylation derived from GC frequency models.
This example uses the BATF motif and the example
methylation dataset loaded earlier. The methylation data must first be
binned by GC content using addGCBinToMethylome() before
computing the deviation.
bin_meth <- addGCBinToMethylome(msites, gcdist, ignoreStrand = TRUE)
bin_meth
#> gcbin avg_mscore
#> [1,] 1 0.5562500
#> [2,] 2 0.7409375
#> [3,] 3 0.8235556
#> [4,] 4 0.7962617
#> [5,] 5 0.7528302
deviation_score <- computeDeviation(
motif = "BATF",
msites = msites,
tf_bindsites = tf_bindsites,
gcfreqs = gcfreqs,
enhancer = NULL,
ignoreStrand = TRUE,
binMsites = bin_meth
)
deviation_score
#> dev exp_dev
#> <num> <num>
#> 1: -0.1167365 0.9992794runMethylTFR() runs the analysis on every sample listed
in a sample annotation file. The file must contain a column (by default
bedFile) with the methylation file names; all its columns
become the colData of the result.
To keep this example self-contained, three small samples are
simulated from the bundled data by resampling the methylated reads at
each CpG, and written to a temporary directory as
bismarkCov files.
sample_dir <- file.path(tempdir(), "methylTFR_vignette")
dir.create(sample_dir, showWarnings = FALSE)
set.seed(1)
sample_files <- paste0("sample_", 1:3, ".cov")
cov <- round(msites$coverage)
keep <- is.finite(msites$score) & msites$score >= 0 &
msites$score <= 1 & is.finite(cov) & cov >= 1
m <- msites[keep]
cov <- cov[keep]
for (f in sample_files) {
n_meth <- rbinom(length(m), cov, m$score)
write.table(
data.frame(
chr = as.character(GenomicRanges::seqnames(m)),
start = GenomicRanges::start(m),
end = GenomicRanges::end(m),
percent = 100 * n_meth / cov,
meth = n_meth,
unmeth = cov - n_meth
),
file.path(sample_dir, f),
sep = "\t", row.names = FALSE, col.names = FALSE, quote = FALSE
)
}
write.table(
data.frame(sampleName = sub(".cov", "", sample_files), bedFile = sample_files),
file.path(sample_dir, "samples.tsv"),
sep = "\t", row.names = FALSE, quote = FALSE
)
devs <- runMethylTFR(
sample_ann = "samples.tsv", # file in sample_dir
sample_dir = sample_dir, # where the methylation files are
sampleColName = "bedFile", # column with the file names
tf_bindsites = tf_bindsites,
gcfreqs = gcfreqs,
gc_dist = gcdist,
filetype = "bismarkCov",
threads = 1,
chunkSize = 10
)
devs
#> class: methylTFRdeviations
#> dim: 1 3
#> metadata(0):
#> assays(3): deviations z expected
#> rownames(1): BATF
#> rowData names(1): motifs
#> colnames(3): sample_1.cov sample_2.cov sample_3.cov
#> colData names(2): sampleName bedFile
deviations(devs)
#> sample_1.cov sample_2.cov sample_3.cov
#> BATF -0.126291 -0.1011316 -0.1371465For a real analysis, the annotation objects come from the annotation package and the per-sample files are your own methylation calls; the call is otherwise the same.
To restrict the analysis to a set of regulatory regions, pass them as
a GRanges through the enhancer argument. Here,
windows of 2 kb around the binding sites stand in for a region set:
regions <- GenomicRanges::reduce(
GenomicRanges::resize(tf_bindsites$BATF, 2000, fix = "center")
)
devsRegions <- runMethylTFR(
sample_ann = "samples.tsv",
sample_dir = sample_dir,
tf_bindsites = tf_bindsites,
gcfreqs = gcfreqs,
gc_dist = gcdist,
filetype = "bismarkCov",
enhancer = regions
)
deviations(devsRegions)
#> sample_1.cov sample_2.cov sample_3.cov
#> BATF -0.126291 -0.1011316 -0.1371465If the methylation data has already been imported and preprocessed
with RnBeads,
there is no need to export per-sample files first.
runMethylTFRFromRnBeads() takes the RnBSet
object directly and returns the same methylTFRdeviations
object as runMethylTFR().
Methylation levels are read one sample column at a time, so
disk-backed sets created with disk.dump.big.matrices = TRUE
are never loaded into memory in full.
A preprocessed set is usually loaded with
RnBeads::load.rnb.set(). Here, a small
RnBiseqSet is built from the bundled data. This chunk runs
only when RnBeads and RnBeads.hg38 are
installed.
library(RnBeads)
old_ids <- rnb.getOption("identifiers.column")
rnb.options(identifiers.column = "sampleName")
ids <- c("sample_1", "sample_2")
meth <- cbind(msites$score, msites$score)
covg <- cbind(msites$coverage, msites$coverage)
dimnames(meth) <- dimnames(covg) <- list(NULL, ids)
rnb_set <- RnBiseqSet(
pheno = data.frame(sampleName = ids),
sites = data.frame(
chr = as.character(GenomicRanges::seqnames(msites)),
start = GenomicRanges::start(msites),
strand = "*"
),
meth = meth,
covg = covg,
assembly = "hg38",
summarize.regions = FALSE
)
devsRnb <- runMethylTFRFromRnBeads(
rnb_set = rnb_set, # preprocessed RnBeads object
tf_bindsites = tf_bindsites,
gcfreqs = gcfreqs,
gc_dist = gcdist,
cov_threshold = 1 # minimum coverage per site
)
deviations(devsRnb)
#> sample_1 sample_2
#> BATF -0.124932 -0.124932Methylation calls are always read at single-cytosine resolution.
Region summaries such as tiling1kb or distal
cannot be used, because a footprint needs base-resolution calls. To
restrict the analysis to a set of regulatory regions, pass them through
the enhancer argument:
devsRnbRegions <- runMethylTFRFromRnBeads(
rnb_set = rnb_set,
tf_bindsites = tf_bindsites,
gcfreqs = gcfreqs,
gc_dist = gcdist,
enhancer = regions
)
deviations(devsRnbRegions)
#> sample_1 sample_2
#> BATF -0.124932 -0.124932
rnb.options(identifiers.column = old_ids)Coverage filtering applies only to sequencing-based sets
(RnBiseqSet), which carry coverage information. Array-based
sets are filtered by detection p-value through
dpval_threshold.
RnBeads is a suggested dependency rather than a required
one, so it is only needed if this entry point is used.
sessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
#> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] parallel grid stats4 stats graphics grDevices utils
#> [8] datasets methods base
#>
#> other attached packages:
#> [1] RnBeads.hg38_1.45.0
#> [2] RnBeads_2.31.4
#> [3] plyr_1.8.9
#> [4] methylumi_2.59.3
#> [5] minfi_1.59.1
#> [6] bumphunter_1.55.1
#> [7] locfit_1.5-9.12
#> [8] iterators_1.0.14
#> [9] foreach_1.5.2
#> [10] Biostrings_2.81.9
#> [11] XVector_0.53.0
#> [12] FDb.InfiniumMethylation.hg19_2.2.0
#> [13] org.Hs.eg.db_3.24.6
#> [14] TxDb.Hsapiens.UCSC.hg19.knownGene_3.24.0
#> [15] GenomicFeatures_1.65.1
#> [16] AnnotationDbi_1.75.2
#> [17] reshape2_1.4.5
#> [18] scales_1.4.0
#> [19] illuminaio_0.55.0
#> [20] limma_3.99.5
#> [21] gridExtra_2.3.1
#> [22] gplots_3.3.0
#> [23] fields_18.0
#> [24] RColorBrewer_1.1-3
#> [25] viridisLite_0.4.3
#> [26] spam_2.11-4
#> [27] ff_4.5.3
#> [28] bit_4.6.0
#> [29] cluster_2.1.8.3
#> [30] MASS_7.3-66
#> [31] circlize_0.4.18
#> [32] ComplexHeatmap_2.29.0
#> [33] ggplot2_4.0.4
#> [34] methylTFR_0.99.12
#> [35] SummarizedExperiment_1.43.0
#> [36] Biobase_2.73.2
#> [37] GenomicRanges_1.65.4
#> [38] Seqinfo_1.3.2
#> [39] IRanges_2.47.5
#> [40] S4Vectors_0.51.10
#> [41] BiocGenerics_0.59.13
#> [42] generics_0.1.4
#> [43] MatrixGenerics_1.25.0
#> [44] matrixStats_1.5.0
#> [45] data.table_1.18.6.1
#> [46] BiocStyle_2.41.0
#>
#> loaded via a namespace (and not attached):
#> [1] splines_4.6.2 BiocIO_1.23.3
#> [3] bitops_1.1-0 tibble_3.3.1
#> [5] R.oo_1.27.1 preprocessCore_1.75.3
#> [7] XML_3.99-0.25 lifecycle_1.0.5
#> [9] doParallel_1.0.17 lattice_0.23-1
#> [11] base64_2.0.2 scrime_1.3.7
#> [13] magrittr_2.0.5 sass_0.4.10
#> [15] rmarkdown_2.32 jquerylib_0.1.4
#> [17] yaml_2.3.12 otel_0.3.0
#> [19] doRNG_1.8.6.3 askpass_1.2.1
#> [21] DBI_1.3.0 buildtools_1.0.0
#> [23] maps_3.4.4 abind_1.4-8
#> [25] quadprog_1.5-8 purrr_1.2.2
#> [27] R.utils_2.13.0 RCurl_1.98-1.20
#> [29] maketools_1.3.2 rentrez_1.2.4
#> [31] genefilter_1.95.0 annotate_1.91.1
#> [33] DelayedMatrixStats_1.35.0 codetools_0.2-20
#> [35] DelayedArray_0.39.8 xml2_1.6.0
#> [37] tidyselect_1.2.1 shape_1.4.6.1
#> [39] UCSC.utils_1.9.1 farver_2.1.2
#> [41] beanplot_1.3.1 GenomicAlignments_1.49.2
#> [43] jsonlite_2.0.0 GetoptLong_1.1.1
#> [45] multtest_2.69.0 survival_3.8-12
#> [47] tools_4.6.2 Rcpp_1.1.2
#> [49] glue_1.8.1 SparseArray_1.13.5
#> [51] BiocBaseUtils_1.15.1 xfun_0.62
#> [53] GenomeInfoDb_1.49.3 dplyr_1.2.1
#> [55] HDF5Array_1.41.8 withr_3.0.3
#> [57] BiocManager_1.30.27 fastmap_1.2.0
#> [59] rhdf5filters_1.25.5 openssl_2.6.0
#> [61] caTools_1.18.4 digest_0.6.39
#> [63] R6_2.6.1 colorspace_2.1-4
#> [65] gtools_3.9.5 RSQLite_3.53.3
#> [67] cigarillo_1.3.1 R.methodsS3_1.8.2
#> [69] h5mread_1.5.7 tidyr_1.3.2
#> [71] rtracklayer_1.73.0 httr_1.4.9
#> [73] S4Arrays_1.13.3 pkgconfig_2.0.3
#> [75] gtable_0.3.6 blob_1.3.0
#> [77] S7_1.0.0 siggenes_1.87.0
#> [79] sys_3.4.3 htmltools_0.5.9
#> [81] dotCall64_1.2 clue_0.3-68
#> [83] png_0.1-9 knitr_1.52
#> [85] tzdb_0.5.0 rjson_0.2.23
#> [87] nlme_3.1-172 curl_8.1.0
#> [89] cachem_1.1.0 rhdf5_2.57.20
#> [91] GlobalOptions_0.1.4 stringr_1.6.0
#> [93] KernSmooth_2.23-27 restfulr_0.0.17
#> [95] GEOquery_2.81.36 pillar_1.11.1
#> [97] logger_0.4.3 reshape_0.8.10
#> [99] vctrs_0.7.3 xtable_1.8-8
#> [101] evaluate_1.0.5 readr_2.2.0
#> [103] cli_3.6.6 compiler_4.6.2
#> [105] Rsamtools_2.29.0 rlang_1.3.0
#> [107] crayon_1.5.3 rngtools_1.5.2
#> [109] labeling_0.4.3 nor1mix_1.3-3
#> [111] mclust_6.1.4 stringi_1.8.9
#> [113] BiocParallel_1.47.0 Matrix_1.7-6
#> [115] hms_1.1.4 sparseMatrixStats_1.25.0
#> [117] bit64_4.8.6 Rhdf5lib_2.1.1
#> [119] KEGGREST_1.53.6 statmod_1.5.2
#> [121] memoise_2.0.1 bslib_0.12.0