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.
For the development version, follow the installation instructions. Once methylVCF is available on Bioconductor, install it with its tutorial dependencies.
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 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
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.
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.
## 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