Explore methylation in a genomic region

Introduction

VariantAnnotation::readVcf() reads VCF records and makes their INFO and FORMAT fields available. methylVCF interprets the caller-specific 5mC fields to place each measurement at its genomic anchor. It uses DRAGEN masks and genotypes to identify measured positions and allele or haplotype slots, and Rastair flags to distinguish reference and de novo CpG contexts. For a DRAGEN reference block, a measured base can be inside the block rather than at its VCF POS. The resulting GRanges can be joined to annotations, and reference measurements can be aligned in a RangedSummarizedExperiment. VariantAnnotation user guide

Suppose you have two samples in a methylation-aware gVCF and want to compare 5mC in a short region. Start by inspecting the coverage at each site. Then align sites across the samples. We use an artificial DRAGEN example from the package. The workflow uses plyranges to manipulate genomic ranges and tidySummarizedExperiment to work with one row per site and sample.

Installation

For the development version, follow the installation instructions. Once methylVCF is available on Bioconductor, install it with its tutorial dependencies.

BiocManager::install("methylVCF", dependencies = TRUE)

Find measurements in the interval

library(methylVCF)
library(tidySummarizedExperiment)
vcf <- system.file("extdata", "dragen-multisample.g.vcf", package = "methylVCF")
region <-
    tibble::tibble(seqnames = "chr21", start = 13204474L, end = 13204520L) |>
    plyranges::as_granges()

calls <- readMethylVcf(vcf, region)
calls |>
    tibble::as_tibble() |>
    dplyr::select(start, sample, scope, fraction, informative_depth)
## # A tibble: 7 × 5
##      start sample   scope     fraction informative_depth
##      <int> <chr>    <chr>        <dbl>             <int>
## 1 13204474 sample_a pooled       0.238                21
## 2 13204474 sample_b pooled       0                     0
## 3 13204515 sample_a pooled       0                     9
## 4 13204520 sample_a haplotype    0.8                   9
## 5 13204520 sample_a haplotype    0                    14
## 6 13204520 sample_b haplotype    0.3                  10
## 7 13204520 sample_b haplotype    0.7                  10

Each row is one reported measurement at a genomic anchor. A site can have several rows, for example one per sample or phased allele. At 13,204,520, each sample has two phased measurements. Leave those rows in the GRanges when inspecting allele-specific methylation.

The coordinates in region are 1-based and inclusive. To check where a measurement came from in the gVCF, inspect record_start and record_end. The query window starts at 13,204,474, inside the reference block that starts at 13,204,471.

Add a feature annotation

Add the name of a small artificial feature using an overlap join. join_overlap_inner() retains the matching measurements as GRanges and adds metadata from the annotation. This example joins one feature to two measurements at its CpG.

features <-
    tibble::tibble(
        seqnames = "chr21",
        start = 13204473L,
        end = 13204476L,
        feature = "example feature"
    ) |> plyranges::as_granges()

annotated <-
    calls |>
    plyranges::join_overlap_inner(features)

annotated |>
    tibble::as_tibble() |>
    dplyr::select(start, feature, sample, coverage_status)
## # A tibble: 2 × 4
##      start feature         sample   coverage_status     
##      <int> <chr>           <chr>    <chr>               
## 1 13204474 example feature sample_a observed            
## 2 13204474 example feature sample_b no_informative_depth

To retain overlapping calls without copying annotation columns, use plyranges::filter_by_overlaps().

covered <-
    calls |>
    plyranges::filter_by_overlaps(features) |>
    dplyr::filter(coverage_status == "observed")

covered |>
    tibble::as_tibble() |>
    dplyr::select(start, sample, fraction, informative_depth)
## # A tibble: 1 × 4
##      start sample   fraction informative_depth
##      <int> <chr>       <dbl>             <int>
## 1 13204474 sample_a    0.238                21

Compare reference sites

Use asMethylExperiment() when the desired unit is a reference site by sample. Build the experiment from the original calls so that zero-depth reports stay available in the reported assays. The two pooled reference sites in the example form a RangedSummarizedExperiment with genomic rows and sample columns.

experiment <- calls |> asMethylExperiment()

With tidySummarizedExperiment loaded, as_tibble() provides a tidy view of the assays and metadata. Keep the observed fraction and the original report side by side to interpret the missing values.

experiment |>
    tibble::as_tibble() |>
    dplyr::select(start, .sample, fraction, reported_fraction, informative_depth) |>
    dplyr::arrange(start, .sample)
## # A tibble: 4 × 5
##      start .sample  fraction reported_fraction informative_depth
##      <int> <chr>       <dbl>             <dbl>             <int>
## 1 13204474 sample_a    0.238             0.238                21
## 2 13204474 sample_b   NA                 0                     0
## 3 13204515 sample_a    0                 0                     9
## 4 13204515 sample_b   NA                NA                    NA

At 13,204,474, the reported zero for sample_b has zero depth. At 13,204,515, sample_b has no measurement. Both analytical fractions are missing. The recorded depth distinguishes them. The zero at 13,204,515 in sample_a is an observed fraction supported by nine reads.

The same projection can take a named list of imports when each file contains a different sample. Select one VCF sample in each import, and use a common caller format and reference assembly. The list names become the output sample names. The importer keeps declared assemblies in seqinfo(calls). Confirm the reference assembly for files that omit it. See the input guide for reader settings and format details.

Session information

utils::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] stats4    stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
##  [1] ggplot2_4.0.4                   tidyr_1.3.2                    
##  [3] dplyr_1.2.1                     tidySummarizedExperiment_1.23.2
##  [5] ttservice_0.5.3                 SummarizedExperiment_1.43.0    
##  [7] Biobase_2.73.2                  GenomicRanges_1.65.4           
##  [9] Seqinfo_1.3.2                   IRanges_2.47.5                 
## [11] S4Vectors_0.51.10               BiocGenerics_0.59.13           
## [13] generics_0.1.4                  MatrixGenerics_1.25.0          
## [15] matrixStats_1.5.0               methylVCF_0.99.0               
## [17] BiocStyle_2.41.0               
## 
## loaded via a namespace (and not attached):
##  [1] tidyselect_1.2.1         viridisLite_0.4.3        farver_2.1.2            
##  [4] Biostrings_2.81.9        S7_1.0.0                 bitops_1.1-0            
##  [7] fastmap_1.2.0            RCurl_1.98-1.20          GenomicAlignments_1.49.2
## [10] XML_3.99-0.25            digest_0.6.39            lifecycle_1.0.5         
## [13] ellipsis_0.3.3           plyranges_1.33.2         magrittr_2.0.5          
## [16] compiler_4.6.2           rlang_1.3.0              sass_0.5.0              
## [19] tools_4.6.2              utf8_1.2.6               yaml_2.3.12             
## [22] data.table_1.18.6.1      rtracklayer_1.73.0       knitr_1.52              
## [25] S4Arrays_1.13.3          htmlwidgets_1.6.4        curl_8.1.0              
## [28] DelayedArray_0.39.8      RColorBrewer_1.1-3       tidyprint_1.1.1         
## [31] abind_1.4-8              BiocParallel_1.47.0      withr_3.0.3             
## [34] purrr_1.2.2              sys_3.4.3                grid_4.6.2              
## [37] fansi_1.0.7              scales_1.4.0             cli_3.6.6               
## [40] rmarkdown_2.32           crayon_1.5.3             otel_0.3.0              
## [43] httr_1.4.9               rjson_0.2.23             BiocBaseUtils_1.15.1    
## [46] cachem_1.1.0             stringr_1.6.0            parallel_4.6.2          
## [49] BiocManager_1.30.27      XVector_0.53.0           restfulr_0.0.17         
## [52] vctrs_0.7.3              Matrix_1.7-6             jsonlite_2.0.0          
## [55] maketools_1.3.2          plotly_4.12.1            jquerylib_0.1.4         
## [58] glue_1.8.1               codetools_0.2-20         stringi_1.8.9           
## [61] gtable_0.3.6             BiocIO_1.23.3            tibble_3.3.1            
## [64] pillar_1.11.1            htmltools_0.5.9          R6_2.6.1                
## [67] evaluate_1.0.5           lattice_0.23-1           Rsamtools_2.29.0        
## [70] cigarillo_1.3.1          bslib_0.12.0             SparseArray_1.13.5      
## [73] xfun_0.62                buildtools_1.0.0         pkgconfig_2.0.3