The VRanges class is a container for variant calls, including SNVs and
indels. It extends GRanges to provide
special semantics on top of a simple vector of genomic locations. While
it is not as expressive as the VCF object, it is
a simpler alternative that may be convenient for variant
calling/filtering and similar exercises.
Details
VRanges extends GRanges to store the following components. Except
where noted, the components are considered columns in the dataset,
i.e., their lengths match the number of variants. Many columns can be
stored as either an atomic vector or an Rle.
ref
(character), the reference
allele. The range (start/end/width) should always correspond to
this sequence.
alt
(character/Rle),
the alternative allele (NA allowed). By convention there is only
a single alt allele per element (row) of the VRanges. Many methods,
like match, make this assumption.
refCount
(integer/Rle), read count for the
reference allele (NA allowed)
altCount
(integer/Rle), read count for the
alternative allele (NA allowed)
totalCount
(integer/Rle), total read count at the
position, must be at least refCount+altCount (NA allowed)
sampleNames
(factor/Rle), name of the sample -
results from multiple samplse can be combined into the same object
(NA allowed)
softFilterMatrix
(matrix/FilterMatrix),
variant by filter matrix, TRUE where variant passed the
filter; use a FilterMatrix to store the
actual FilterRules object that was applied
hardFilters
(FilterRules) record of hard
filters applied, i.e., only the variants that passed the filters
are present in this object; this is the only component that is not
a column, i.e., its length does not match the number of variants
Except in the special circumstances described here, a VRanges
may be treated like a GRanges. The range should span the
sequence in ref. Indels are typically represented by the VCF
convention, i.e., the start position is one upstream of the event. The
strand is always constrained to be positive (+).
Indels, by convention, should be encoded VCF-style, with the upstream
reference base prepended to the indel sequence. The ref/alt for a
deletion of GCGT before A might be AGCGT/A and for an insertion might
be A/AGCGT. Since the range always matches the ref sequence,
this means a deletion will be the width of the deletion + 1, and an
insertion is always of width 1.
VRanges and the VCF class:
The VRanges and VCF classes encode different types of information and
are semantically incompatible. While methods exist for converting
a VCF object to a VRanges and vice versa, information is lost in the
transformation. There is no way to collapse multiple rows of a VRanges
at the same genomic position and accurately represent missing data.
For this reason, it is not reasonable to assume that an object resulting
from multiple conversions (VRanges -> VCF -> VRanges) will be equivalent to
the original.
Rle object, character vector, or factor
containing the sequence names.
ranges
IRanges object containing the ranges.
ref
character vector, containing the reference allele.
alt
character vector/Rle,
containing the alternative allele (NA allowed).
totalDepth
integer vector/Rle, containing the
total read depth (NA allowed).
refDepth
integer vector/Rle, containing the
reference read depth (NA allowed).
altDepth
integer vector/Rle, containing the
reference read depth (NA allowed).
...
Arguments passed to the GRanges
constructor.
sampleNames
character/factor vector/Rle, containing the
sample names (NA allowed).
softFilterMatrix
a matrix (typically
a FilterMatrix) of dimension variant by
filter, with logical values indicating whether a variant
passed the filter.
hardFilters
a FilterRules,
containing the filters that have already been applied to
subset the object to its current state.
makeVRangesFromGRanges(gr,
ref.field="ref",
alt.field="alt",
totalDepth.field="totalDepth",
refDepth.field="refDepth",
altDepth.field="altDepth",
sampleNames.field="sampleNames",
keep.extra.columns=TRUE):
Creates a VRanges object from a GRanges.
gr
A GenomicRanges object.
ref.field
The character(1) name of the GRanges metadata column to be
used as the VRanges ref field.
alt.field
The character(1) name of the GRanges metadata column to be
used as the VRanges alt field.
totalDepth.field
The character(1) name of the GRanges metadata column to be
used as the VRanges totalDepth field.
refDepth.field
The character(1) name of the GRanges metadata column to be
used as the VRanges refDepth field.
altDepth.field
The character(1) name of the GRanges metadata column to be
used as the VRanges altDepth field.
sampleNames.field
The character(1) name of the GRanges metadata column to be
used as the VRanges sampleNames field.
keep.extra.columns
TRUE (the default) or FALSE.
If TRUE, then the columns in gr that are not used to
form the VRanges are retained as metadata columns. Otherwise, they
will be ignored.
Coercion
These functions/methods coerce objects to and from VRanges:
asVCF(x, info = character(), filter = character(), meta =
character()): Creates a VCF object from a VRanges object. The
following gives the mapping from VRanges components to VCF:
seqnames(x)
CHROM column
start(x)
POS column
names(x)
ID column
ref(x)
REF column
alt(x)
ALT column
totalDepth(x)
DP in FORMAT column
altDepth(x), refDepth(x)
AD in FORMAT column
sampleNames(x)
Names the sample columns
softFilterMatrix(x)
FT in FORMAT column, except filters
named in filter argument, which are considered
per-position and placed in the FILTER column
hardFilters(x)
Not yet exported
mcols(x)
Become fields in the FORMAT column; unless they
are named in the info argument, in which case they
are considered per-position and placed in the INFO column
metadata(x)
If named in the meta argument, output
in the VCF header; a component is required to be coercible to
a character vector of length one.
Note that identical(x, as(as(x, "VCF"), "VRanges"))
generally return FALSE. During coercion to VCF, the "geno"
components are reshaped into matrix form, with NAs filling the
empty cells. The reverse coercion will not drop the NA values, so
rows are added to the new VRanges. All logical values will become
integers in VCF, and there is no automatic way of regenerating the
logical column with the reverse coercion. There are many other
cases of irreversibility.
as(from, "VCF"): Like calling asVCF(from).
as(from, "VRanges"):
When from is a VCF this coercion is essentially
the inverse of asVCF. Information missing in the VCF
is imputed as NA.
When from is a GRanges, metadata columns of
ref, alt, refDepth, altDepth,
totalDepth and sampleNames are transfered to
the VRanges object. Additional metadata columns in
the GRanges can be retained or dropped with
keep.extra.columns. See also makeVRangesFromGRanges.
Accessors
In addition to all of the GRanges accessors, VRanges
provides the following, where x is a VRanges object.
alt(x), alt(x) <- value: Get or set the alt allele (character).
ref(x), ref(x) <- value: Get or set the ref allele (character).
altDepth(x), altDepth(x) <- value: Get or set the alt allele
read depth (integer).
refDepth(x), refDepth(x) <- value: Get or set the ref
allele read depth (integer).
totalDepth(x), totalDepth(x) <- value: Get or set the total
read depth (integer).
sampleNames(x), sampleNames(x) <- value: Get or set the
sample names (character/factor).
softFilterMatrix(x), softFilterMatrix(x) <- value: Gets or
sets the soft filter matrix (any matrix, but ideally a
FilterMatrix).
resetFilter(x): Removes all columns from softFilterMatrix.
called(x): Returns whether all filter results in
softFilterMatrix(x) are TRUE for each variant.
hardFilters(x), hardFilters(x) <- value: Gets or
sets the hard filters (those applied to yield the current subset).
Utilities and Conveniences
match(x): Like GRanges match, except matches on the
combination of chromosome, start, width, and alt.
tabulate(bin): Finds unique(bin) and counts how many
times each unique element occurs in bin. The result is
stored in mcols(bin)$sample.count.
softFilter(x, filters, ...): applies the FilterRules
in filters to x, storing the results in
softFilterMatrix.
Input/Output to/from VCF
writeVcf(obj, filename, ...): coerces to a VCF object and
writes it to a file; see writeVcf.
readVcfAsVRanges(x, genome, param = ScanVcfParam(), ...):
Reads a VCF x directly into a VRanges;
see readVcf for details on the arguments.
readVcfAsVRanges is an alternative syntax to
as(readVcf(), "VRanges")
NOTE: By default all INFO and FORMAT fields are read in with
ScanVcfParam(). The minimal information needed to create
the VRanges can be specified as follows:
ScanVcfParam(fixed = "ALT", info = NA, geno = "AD"))
Variant Type
Functions to identify variant type include isSNV,
isInsertion, isDeletion, isIndel,
isSubstitution and isTransition. See the ?isSNV
man page for details.
Author(s)
Michael Lawrence. makeVRangesFromGRanges was contributed
by Thomas Sandmann.
See Also
VRangesList, a list of VRanges; bam_tally in the
gmapR package, which generates a VRanges.