Skip to contents

Introduction

This case study starts with a small indexed DRAGEN example included in the package. It then shows the same workflow on HG002 and explains how coverage and phase affect the interpretation of the resulting methylation profile.

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)

Query a bundled DRAGEN file with Tabix

Compress the artificial gVCF and create a TBI index in the temporary directory. Inspect the indexed file and pass the detected format to the reader. The query starts inside a gVCF reference block, so the measurement anchor and the source record start differ.

library(methylVCF)

fixture <- system.file("extdata", "dragen-example.g.vcf", package = "methylVCF")
indexed_file <- tempfile(fileext = ".g.vcf.gz")
invisible(Rsamtools::bgzip(fixture, dest = indexed_file))
index <- Rsamtools::indexTabix(indexed_file, format = "vcf")

info <- inspectMethylVcf(indexed_file)
info$index[c("type", "status")]
## $type
## [1] "TBI"
## 
## $status
## [1] "readable"
site <- GenomicRanges::GRanges("chr21", IRanges::IRanges(13204474L))
local_calls <- readMethylVcf(indexed_file, site, format = info$format)
S4Vectors::metadata(local_calls)$access
## [1] "tabix"
as.data.frame(local_calls)[c("start", "record_start", "fraction", "informative_depth")]
##      start record_start fraction informative_depth
## 1 13204474     13204471   0.2381                21

Query an HG002 region

Can we inspect reference methylation and phase evidence in a single DRAGEN gVCF? Here we query a 190 kb window on chromosome 1 (chr1:10000–200000, GRCh38). The input comes from Illumina’s 5-Base DNA Prep demo for HG002 (NA24385, Sample40, DRAGEN 4.4.6). The example results use a local indexed excerpt of that file. Demo files · Validation and provenance

To run the code, download Demo-5base-gDNA-Sample40-NA24385-50ng-B-C02.hard-filtered.gvcf.gz and keep its matching .tbi beside it. An indexed excerpt also works if it contains the header and all overlapping records. Set the local path before running this article from a checkout with methylVCF installed. The worked example uses plyranges to select genomic regions and tidySummarizedExperiment to view the reference assays. Leave the variable unset to build the article with the recorded results.

Sys.setenv(METHYLVCF_HG002 = "/path/to/HG002.gvcf.gz")
rmarkdown::render("vignettes/dragen-hg002.Rmd")
library(tidySummarizedExperiment)

info <- inspectMethylVcf(hg002, format = "dragen")
info$index[c("type", "status")]

region <-
    tibble::tibble(seqnames = "chr1", start = 10000L, end = 200000L) |>
    plyranges::as_granges()

calls <- readMethylVcf(hg002, region, format = info$format, on_problem = "report")
calls |>
    tibble::as_tibble() |>
    dplyr::count(scope, coverage_status)

nrow(S4Vectors::metadata(calls)$diagnostics)

The interval returned 1,992 measurements. Of these, 1,135 had observed fractions and 857 had zero informative depth. There were 1,969 pooled, 20 allele-level and 3 haplotype-level measurements. No import diagnostics were recorded. The uncompressed version of the same excerpt yielded identical rows by sequential access.

Plot the reference methylation profile

Project the pooled reference measurements onto a common set of reference sites. The resulting experiment has 1,771 sites in one sample, with 1,055 coverage-backed fractions. Plot the observed fractions along the chromosome. Each dot is one measured CpG anchor. Omitted positions include sites with zero informative depth.

experiment <- asMethylExperiment(calls)
profile <-
    experiment |>
    tibble::as_tibble() |>
    dplyr::filter(!is.na(fraction)) |>
    dplyr::mutate(position_kb = start / 1000)

graphics::plot(
    fraction ~ position_kb, data = profile, ylim = c(0, 1),
    pch = 16, cex = 0.55, col = "#247A78", bty = "l",
    xlab = "chr1 position (kb)", ylab = "Reference 5mC fraction"
)

Reference CpG methylation fractions along the HG002 interval.

Inspect what one measurement means

Use the original ranges to inspect allele assignment. The cases below cover one block and several variant or coverage situations.

anchors <-
    tibble::tibble(
        seqnames = "chr1",
        start = c(10493L, 10816L, 28692L, 94011L, 171535L),
        width = 1L
    ) |> plyranges::as_granges()

calls |>
    plyranges::filter_by_overlaps(anchors) |>
    tibble::as_tibble() |>
    dplyr::select(
        start,
        record_start,
        genotype,
        allele_index,
        haplotype,
        scope,
        fraction,
        informative_depth
    )
Anchor What the call represents Fraction Reads
10,493 REF CpG inside the block starting at 10,486 0.4839 31
10,816 Pooled REF with no informative reads 0 0
28,692 REF on phased slot 1 0 14
94,011 ALT in an unphased heterozygote 0.9286 14
171,535 ALT pooled across both copies of a phased homozygote 0.7692 13

The zero at 28,692 is backed by 14 reads. The zero at 10,816 is the caller-reported value at zero depth. The ALT measurements at 94,011 and 171,535 both have haplotype = NA, for different reasons: the first genotype is unphased and the second measurement pools both copies.

A phased or heterozygous genotype alone does not establish a REF/ALT methylation comparison. In the larger validation excerpt (chr1:9998–8007476), 6,924 heterozygous PASS SNVs with one real ALT allele were checked. Of those, 768 had an active REF mask only, 498 had an active ALT mask only, and 5,658 had neither. The excerpt provided no SNV with measurements on both alleles at the same anchor. Check sequence context before interpreting a missing mask as CpG gain or loss. DRAGEN methylation fields

For an overview of these objects and how to annotate them, start with the regional tutorial.

Session information

utils::sessionInfo()
## R version 4.6.1 (2026-06-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 24.04.5 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.26.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: UTC
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] methylVCF_0.99.0 BiocStyle_2.41.0
## 
## loaded via a namespace (and not attached):
##  [1] jsonlite_2.0.0       crayon_1.5.3         compiler_4.6.1      
##  [4] BiocManager_1.30.27  Rsamtools_2.29.0     GenomicRanges_1.65.4
##  [7] bitops_1.1-0         Biostrings_2.81.9    parallel_4.6.1      
## [10] jquerylib_0.1.4      systemfonts_1.3.2    IRanges_2.47.5      
## [13] Seqinfo_1.3.2        textshaping_1.0.5    BiocParallel_1.47.0 
## [16] yaml_2.3.12          fastmap_1.2.0        R6_2.6.1            
## [19] XVector_0.53.0       generics_0.1.4       knitr_1.52          
## [22] BiocGenerics_0.59.13 htmlwidgets_1.6.4    bookdown_0.48       
## [25] desc_1.4.3           bslib_0.12.0         rlang_1.3.0         
## [28] cachem_1.1.0         xfun_0.62            fs_2.1.0            
## [31] sass_0.4.10          otel_0.2.0           cli_3.6.6           
## [34] pkgdown_2.2.1        digest_0.6.39        lifecycle_1.0.5     
## [37] S4Vectors_0.51.10    evaluate_1.0.5       codetools_0.2-20    
## [40] ragg_1.5.2           stats4_4.6.1         rmarkdown_2.32      
## [43] tools_4.6.1          htmltools_0.5.9