Skip to contents

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.

Usage

readMethylVcf(
  file,
  which,
  format = c("dragen", "rastair"),
  samples = NULL,
  on_problem = c("error", "report")
)

Arguments

file

Path to a local text VCF or gVCF, optionally compressed with gzip or BGZF.

which

A GRanges with 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 the format reported by inspectMethylVcf() when identified.

samples

Character vector of VCF sample names to return, or NULL to 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