methylTFR: DNA Methylation Signatures in TFBS

Introduction

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.

Installation

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:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}

BiocManager::install("methylTFR")

Getting Started

To get started with methylTFR, load the package and its dependencies:

library(methylTFR)

Read a Sample File

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 seqlengths

Annotation Resources

Computing 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.

Input Data

methylTFR relies on several precomputed annotation resources to estimate expected methylation levels at transcription factor binding sites (TFBS). These annotations include:

  • GC distribution (gcdist_subset): Genome-wide GC content distribution in 30-bp windows, used to model methylation expectations.
  • Motif GC frequency (BATF_gcfreqs): GC frequency profile specific to the BATF motif across TFBS, used to correct for sequence composition bias.
  • TF binding sites (BATF_tf_bindsites): A GRanges object containing the genomic coordinates of BATF binding sites on chromosome 1.
  • Example methylation data (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 seqlengths

Compute Deviation Score for a Single Sample and Single Motif

The 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.9992794

Run methylTFR on multiple samples and motifs

runMethylTFR() 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.1371465

For 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.1371465

Run methylTFR directly on an RnBeads object

If 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.124932

Methylation 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.

Session Information

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