Read your DRAGEN or Rastair files

Introduction

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.

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)

Inspect the file

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.

library(methylVCF)
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
info$samples
## [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.

Set up a regional query

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").

Read a phased DRAGEN variant

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

Read a Rastair CpG context

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

Diagnose an incomplete import

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.
calls |>
    tibble::as_tibble() |>
    dplyr::select(start, motif_origin, fraction, informative_depth)
## # 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
S4Vectors::metadata(calls)$diagnostics |>
    tibble::as_tibble() |>
    dplyr::select(pos, type, reason)
## # 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.

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] 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