
Case study: from an HG002 gVCF to a methylation profile
Source:vignettes/dragen-hg002.Rmd
dragen-hg002.RmdIntroduction
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"
)
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