Interpret 5mC fields from DRAGEN and Rastair and retain evidence supplied by the file, including explicit missing slots and zero fractions. The query filters observations by their reported anchors after decoding.
Arguments
- file
Path to a local text VCF or gVCF, optionally compressed with gzip or BGZF.
- which
A
GRangeswith 1-based inclusive regions to query. The reader combines overlapping regions and ignores strand in the query.- format
The producer's format,
"dragen"(default) or"rastair". Use theformatreported byinspectMethylVcf()when identified.- samples
Character vector of VCF sample names to return, or
NULLto retain all samples.- on_problem
"error"stops at the first unsupported or invalid record, sample, or measurement."report"retains readable observations and records omissions in the result metadata. Header, file, and index errors always stop the import.
Value
A GRanges with one row per reported measurement slot and a
one-base range at its reported anchor. Metadata columns include the
sample, context, scope, fraction, informative and modified read depths,
genotype, optional haplotype and phase-set identifiers, allele index
(0 for REF and 1 for the first ALT), and the source record coordinates.
allele_offset is the zero-based offset within the allele sequence or
reference block. In a gVCF block, allele gives the sequence at the
record's anchor only. methylation_mask retains the original DRAGEN
INFO/M5mC string in REF/ALT order when present.
The Seqinfo retains all contigs, lengths and assembly tags declared in
the VCF header. Queried contigs absent from the header have unknown
lengths and assemblies.
Details
DRAGEN support includes reference blocks with INFO/END, diploid
SNVs including multiallelic sites, and measurements on mappable alleles
of complex records. When REF and ALT differ in length, projection is
limited to their shared leading anchor. Rastair reference and biallelic
single-base contexts use their producer-specific order. When both
CPG and CPGnovo are set, values must be separable by context.
Rastair 2.2.0 can emit a single slot for such records. The reader
reports that representation as unsupported.
A Rastair slot with more modified reads (ADM5mC) than informative
reads (DPM5mC) is invalid when both depths are available.
scope is "pooled", "allele", "haplotype", or "context". A DRAGEN
phased homozygote with one measurement per site has pooled scope and a
missing haplotype. A Rastair allele assignment identifies a local
sequence allele to which the CpG context can be attributed. Its haplotype
is missing. If multiple local alleles could anchor the context, the
reader retains the measurement with a missing allele index and
unspecified strand. Unreported measurements remain missing. The file-level
metadata include the chosen format, selected sample IDs (even for
samples without calls), and available header provenance.
coverage_status is "observed" for a reported fraction with positive
informative depth. "no_informative_depth" takes precedence when the
depth is zero. "missing_fraction" indicates a missing fraction and
"unknown_depth" indicates a reported fraction with missing depth.
fraction retains the producer's value.
The reader uses Rsamtools for BGZF files with a companion TBI or CSI index, preferring CSI when both are present. Otherwise it scans the input sequentially in chunks. Indexed queries retrieve the requested intervals and decode a source record only in its first overlapping interval, keeping all measurements within the query. Anchors include the start of a collapsed CpG dyad. Retained rows preserve source order within each record.
Import diagnostics
S4Vectors::metadata(result)$diagnostics contains one row per import
issue, with chrom, pos, sample when known, type ("invalid" or
"unsupported"), allele_index, allele_offset, and value_index
when available, and reason. In "error" mode, the first such issue
signals a methylVCF_import_error condition with those fields. In
"report" mode, a single methylVCF_import_warning condition carries the
total issue count in n_issues.
See also
inspectMethylVcf() for checking the header and index,
asMethylExperiment() for comparing reference sites across samples,
and vignette("methylVCF") for the complete workflow.
Examples
file <- system.file("extdata", "dragen-example.g.vcf", package = "methylVCF")
region <- GenomicRanges::GRanges("chr21", IRanges::IRanges(13204474L))
result <- readMethylVcf(file, region, format = "dragen")
result
#> GRanges object with 1 range and 22 metadata columns:
#> seqnames ranges strand | context modification scope
#> <Rle> <IRanges> <Rle> | <character> <character> <character>
#> [1] chr21 13204474 * | CG 5mC pooled
#> fraction informative_depth modified_depth allele_index haplotype
#> <numeric> <integer> <integer> <integer> <integer>
#> [1] 0.2381 21 <NA> 0 <NA>
#> motif_origin value_index allele_offset coverage_status sample
#> <character> <integer> <integer> <character> <character>
#> [1] reference 1 3 observed dragen_demo
#> genotype phase_set allele record_start record_end ref
#> <character> <character> <character> <integer> <integer> <character>
#> [1] 0/0 <NA> <NA> 13204471 13204512 A
#> alt filter methylation_mask
#> <character> <character> <character>
#> [1] <NON_REF> PASS ...Z..................
#> -------
#> seqinfo: 1 sequence from an unspecified genome
