This guide takes a local DRAGEN or Rastair file from header inspection to a regional query. It shows how to choose a sample and interpret measurements when the callers use different allele or CpG context slots.
For the development version, follow the installation instructions. Once methylVCF is available on Bioconductor, install it with its tutorial dependencies.
Use inspectMethylVcf() before choosing a region. It
reports the caller, samples, contigs and declared methylation fields
from the header. The function recognizes DRAGEN and Rastair from their
header declarations. Supply format = "dragen" or
format = "rastair" if the caller cannot be identified.
dragen_file <- system.file("extdata", "dragen-multisample.g.vcf", package = "methylVCF")
info <- inspectMethylVcf(dragen_file)
info##
## ── Methylation VCF inspection ──────────────────────────────────────────────────
##
## File: 'dragen-multisample.g.vcf'
## Caller: DRAGEN (version not declared)
## VCF version: "4.5"
## Reference: not declared
## Samples (2): sample_a, sample_b
## Contigs (1): chr21 (46,709,983 bp)
##
## ── Declared methylation fields ──
##
## INFO/M5mC: Allele masks
## FORMAT/M5mC: Methylation fraction
## FORMAT/DPM5mC: Informative depth
##
## ── Diagnostics ──
##
## ℹ Access: sequential (no index found)
## ✔ Header checks: passed
## [1] "sample_a" "sample_b"
The printed summary is a quick overview. Use
info$seqinfo to get the declared contigs, lengths and
assemblies, info$fields for the field declarations and
info$checks for the header checks.
By default, the inspector tries to open the index it finds.
info$index$status distinguishes "absent",
"readable" and "unreadable". With
check_index = FALSE, a sidecar found on disk is reported as
"detected". The bundled gVCF has no index. When both
sidecars are present, CSI takes precedence even if it is unreadable. A
readable index can still belong to a different file. Use the matching
sidecar when you query. The inspection reads only the header and
optionally opens the index.
Choose a local file, an interval on the VCF’s reference assembly, and
the caller’s format. Use the contig name as it appears in the header
(for example, chr21 or 21). The region uses
1-based inclusive coordinates. By default the reader returns all
samples. Use samples to request specific VCF sample
IDs.
Pass info$format to readMethylVcf() after
identifying the caller. If info$format is NA,
supply the known format to inspectMethylVcf() first.
Omitting format from readMethylVcf() selects
DRAGEN.
region <-
tibble::tibble(seqnames = "chr21", start = 13204474L, end = 13204520L) |>
plyranges::as_granges()
calls <- readMethylVcf(
dragen_file, region, format = info$format, samples = info$samples[[1L]]
)
as.data.frame(calls)[c("start", "sample", "scope", "fraction")]## start sample scope fraction
## 1 13204474 sample_a pooled 0.2381
## 2 13204515 sample_a pooled 0.0000
## 3 13204520 sample_a haplotype 0.8000
## 4 13204520 sample_a haplotype 0.0000
For indexed access, place the matching index beside the BGZF file,
for example sample.g.vcf.gz.tbi. CSI (.csi) is
also supported and takes precedence if both indices exist. Plain text
and unindexed gzip inputs are scanned sequentially. Check the chosen
path in S4Vectors::metadata(calls)$access
("tabix" or "sequential").
To read a variant, ask for its coordinate just as you would for a reference site. The example below includes both orders of a phased heterozygous genotype.
variant <-
tibble::tibble(seqnames = "chr21", start = 13204520L, width = 1L) |>
plyranges::as_granges()
calls <- readMethylVcf(dragen_file, variant, format = info$format)
calls |>
tibble::as_tibble() |>
dplyr::select(
sample,
genotype,
allele_index,
haplotype,
phase_set,
fraction,
informative_depth
)## # A tibble: 4 × 7
## sample genotype allele_index haplotype phase_set fraction informative_depth
## <chr> <chr> <int> <int> <chr> <dbl> <int>
## 1 sample_a 1|0 1 1 13204520 0.8 9
## 2 sample_a 1|0 0 2 13204520 0 14
## 3 sample_b 0|1 0 1 13204520 0.3 10
## 4 sample_b 0|1 1 2 13204520 0.7 10
In sample_a, 1|0 puts ALT first, so
fraction 0.8 is assigned to ALT and fraction 0 to REF. In
sample_b, 0|1 puts REF first. Read
allele_index as 0 for REF, 1 for the first ALT, and so on.
Read haplotype as the slot in the phased genotype. It is
meaningful within a sample, contig and phase set. A pooled call has no
per-copy assignment. DRAGEN
methylation fields
Rastair indicates whether a call comes from a reference CpG
(CPG) or a newly formed CpG (CPGnovo). The
bundled example follows the 2.3.0-rc1 layout with separate slots for the
reported contexts.
file <- system.file("extdata", "rastair-example.vcf", package = "methylVCF")
info <- inspectMethylVcf(file)
region <-
tibble::tibble(seqnames = "chr19", start = 6105744L, end = 6105760L) |>
plyranges::as_granges()
calls <- readMethylVcf(file, region, format = info$format)
calls |>
tibble::as_tibble() |>
dplyr::select(
start,
strand,
motif_origin,
allele_index,
fraction,
informative_depth
)## # A tibble: 5 × 6
## start strand motif_origin allele_index fraction informative_depth
## <int> <fct> <chr> <int> <dbl> <int>
## 1 6105744 + reference 0 0.8 10
## 2 6105745 - reference 0 0.5 14
## 3 6105750 + reference 0 NA 0
## 4 6105750 - de_novo 1 1 5
## 5 6105760 * de_novo NA 0.6 5
At 6,105,750 the two contexts have distinct slots. At 6,105,760 a reported de novo context could be anchored to multiple local alleles. The fraction and depth remain available, with an unspecified strand and allele index. This layout encodes context and local allele information. Rastair VCF format
Use the default on_problem = "error" for strict import.
To inspect what can be recovered, use on_problem = "report"
and read the diagnostics. File, header and index errors still stop
either mode. For Rastair, a slot with ADM5mC greater than
DPM5mC is invalid. Report mode records the affected slot
and retains valid measurements.
Rastair 2.2.0 can report one slot for a record carrying both CpG flags. The package includes an example generated by Rastair on artificial reads. The following query returns the readable rows and warns about the unsupported record at position 302.
file <- system.file("extdata", "rastair-2.2.0-synthetic.vcf", package = "methylVCF")
region <-
tibble::tibble(seqnames = "synthetic", start = 300L, end = 320L) |>
plyranges::as_granges()
calls <- readMethylVcf(file, region, format = "rastair", on_problem = "report")## Warning: The import reported 1 issue. See metadata(result)$diagnostics.
## # A tibble: 2 × 4
## start motif_origin fraction informative_depth
## <int> <chr> <dbl> <int>
## 1 301 de_novo 0.5 12
## 2 303 reference 0 0
## # A tibble: 1 × 3
## pos type reason
## <int> <chr> <chr>
## 1 302 unsupported Rastair reports a single methylation slot for two CpG conte…
For caller versions, fixture provenance and comparisons with raw records, see the validation report. Rastair software attribution is Copyright © 2025, University of Oxford. For aligned reference measurements, see the regional workflow.
## 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] 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] utf8_1.2.6 sass_0.5.0 generics_0.1.4
## [4] bitops_1.1-0 digest_0.6.39 magrittr_2.0.5
## [7] evaluate_1.0.5 fastmap_1.2.0 jsonlite_2.0.0
## [10] cigarillo_1.3.1 restfulr_0.0.17 BiocManager_1.30.27
## [13] httr_1.4.9 plyranges_1.33.2 XML_3.99-0.25
## [16] Biostrings_2.81.9 codetools_0.2-20 jquerylib_0.1.4
## [19] cli_3.6.6 rlang_1.3.0 crayon_1.5.3
## [22] XVector_0.53.0 withr_3.0.3 cachem_1.1.0
## [25] yaml_2.3.12 BiocBaseUtils_1.15.1 otel_0.3.0
## [28] tools_4.6.2 parallel_4.6.2 BiocParallel_1.47.0
## [31] dplyr_1.2.1 Rsamtools_2.29.0 BiocGenerics_0.59.13
## [34] curl_8.1.0 buildtools_1.0.0 vctrs_0.7.3
## [37] R6_2.6.1 BiocIO_1.23.3 stats4_4.6.2
## [40] lifecycle_1.0.5 rtracklayer_1.73.0 Seqinfo_1.3.2
## [43] S4Vectors_0.51.10 IRanges_2.47.5 pkgconfig_2.0.3
## [46] bslib_0.12.0 pillar_1.11.1 glue_1.8.1
## [49] xfun_0.62 tibble_3.3.1 GenomicAlignments_1.49.2
## [52] GenomicRanges_1.65.4 tidyselect_1.2.1 sys_3.4.3
## [55] knitr_1.52 rjson_0.2.23 htmltools_0.5.9
## [58] rmarkdown_2.32 maketools_1.3.2 compiler_4.6.2
## [61] RCurl_1.98-1.20