Skip to contents
Chapters and reference

Complete canonical API text; task articles explain the workflows. Usage guide

VariantAnnotation reads local VCF text (including gzip). Files ending in .bcf or .bcf.gz first use pysam/HTSlib in the explicitly selected Python environment to transcode to temporary VCF. No parser is installed or run at plot time. This is an in-memory adapter for selected local files, not an indexed chromosome-scale query or variant caller.

Usage

R · Example code
read_vcf(
  file = NULL,
  files = NULL,
  structural = FALSE,
  python = "python3",
  source_file = FALSE
)

Arguments

file

Optional local path vector or glob patterns, before files.

files

Optional additional VCF/BCF paths or patterns.

structural

Logical. Explicitly request optional structural decoding, default FALSE. Duplicate record IDs fail in this mode because mates would be ambiguous. All source records remain accessible in the default mode.

python

Existing interpreter with optional pysam for BCF only. Ignored for VCF text; default "python3". No environment is modified.

source_file

Add .source_file to returned table rows, default FALSE.

Value

A list with features$variant (reference allele spans), breakends, links and report. The report retains each complete parsed VCF object, source record text, original headers/IDs, decoder versions, warnings and sequence dictionaries with unknown lengths preserved. Original INFO and genotype evidence stays in report$records; no caller-specific support field is silently promoted to a universal count. Table .source_input and .source_record refer to the report file and its record order, never an invented biological observation ID. BCF text is decoder output rather than original binary bytes; no physical BCF line numbers are assigned.

Details

Each placed source record remains one row, including multiallelic records. Variant features show the reference allele span at POS, including its padding base; they are not claimed to be the inserted sequence or a symbolic SV footprint. Original IDs, REF, ALT lists, QUAL, FILTER, INFO and sample/genotype arrays are retained. Missing IDs stay missing. No alleles or samples are combined, filtered, phased or normalised. No support, Identity or full lengths are inferred from positions. Header length entries that are missing remain NA. Telomeric or out-of-bounds reference spans remain in the complete parsed source and report$records[[i]]$unplaced_features rather than being clipped into invented reference features. Empty VCFs return empty feature tables.

Explicit structural decoding uses optional StructuralVariantAnnotation, with missing-mate inference disabled and positional uncertainty retained. Each reciprocal decoded pair produces one link, with both source record indices; single and unpaired records remain in the source/report. Breakend orientation describes derivative sequence, not homology or feature strand. Links retain ascending confidence intervals and separate orientation fields; no pident, relative Orientation or connection to an absent mate is invented. Decoder-derived metadata is labelled separately from original evidence. Breakends outside known bounds have .plottable = FALSE; affected pairs stay in the report's unplaced_links instead of being clipped to exact boundaries.

Examples

R · Example code
# \donttest{
# Optional Bioconductor decoder loading can take several seconds.
if (requireNamespace("VariantAnnotation", quietly = TRUE)) {
  path <- system.file("extdata", "chr22.vcf.gz", package = "VariantAnnotation")
  # Preserve the original headers and first three observed records.
  con <- gzfile(path, "rt")
  lines <- character()
  records <- 0L
  while (records < 3L) {
    line <- readLines(con, n = 1L)
    if (!length(line)) break
    lines <- c(lines, line)
    if (!startsWith(line, "#")) records <- records + 1L
  }
  close(con)
  input <- tempfile(fileext = ".vcf")
  writeLines(lines, input)
  variants <- read_vcf(input)
  print(variants$features$variant[c("accver", "start", "end", "feature_id")])
  unlink(input)
}
#>   accver    start      end  feature_id
#> 1     22 50300078 50300078   rs7410291
#> 2     22 50300086 50300086 rs147922003
#> 3     22 50300101 50300101 rs114143073
# }

Search documentation

↑ ↓ select · Enter open · Esc close; or browse by task. API and functions