| GRanges-class {GenomicRanges} | R Documentation |
The GRanges class is a container for the genomic locations and their associated annotations.
The GRanges class stores the sequences of genomic locations and associated annotations. Each element in the sequence is comprised of a sequence name, an interval, a strand, and optional element metadata (e.g. score, GC content, etc.). This information is stored in four slots:
seqnamesrangesstrandelementMetadata"seqnames", "ranges", "strand",
"seqlengths", "isCircular",
"start", "end", "width", or "element".
GRanges(seqnames = Rle(), ranges = IRanges(),
strand = Rle("*", length(seqnames)),
...,
seqlengths =
structure(rep(NA_integer_, length(levels(seqnames))),
names = levels(seqnames))):
Creates a GRanges object.
seqnamesrangesstrandseqlengthslevel(seqnames)....elementMetadata slot. These columns cannot be named
"start", "end", "width", or "element".
In the code snippets below, x is a GRanges object.
as(from, "GRanges"):
Creates a GRanges object from a RangedData or RangesList object.
as(from, "RangedData"):
Creates a RangedData object from a GRanges
object. The strand and the values become columns in the
result. The seqlengths(from) and isCircular(from)
vectors are stored in the element metadata of ranges(rd).
as(from, "RangesList"):
Creates a RangesList object from a GRanges
object. The strand and values become element metadata on the
ranges. The seqlengths(from) and isCircular(from)
vectors are stored in the element metadata.
as.data.frame(x, row.names = NULL, optional = FALSE):
Creates a data.frame with columns seqnames (factor),
start (integer), end (integer), width (integer),
strand (factor), as well as the additional columns stored in
elementMetadata(x).
In the following code snippets, x is a GRanges object.
seqnames(x), seqnames(x) <- value:
Gets or sets the sequence names. value can be an Rle object,
character vector, or factor.
ranges(x), ranges(x) <- value:
Gets or sets the ranges. value can be a Ranges object.
strand(x), strand(x) <- value:
Gets or sets the strand. value can be an Rle object, character
vector, or factor.
seqinfo(x):
Returns a Seqinfo object containing information about
the underlying sequences.
seqlengths(x), seqlengths(x) <- value:
Gets or sets the seqlengths. seqlengths(x) is formally
equivalent to seqlengths(seqinfo(x)).
value can be a named non-negative integer or numeric vector.
isCircular(x):
Formally equivalent to isCircular(seqinfo(x)).
isCircularWithKnownLength(x):
Formally equivalent to isCircularWithKnownLength(seqinfo(x)).
elementMetadata(x), elementMetadata(x) <- value:
Gets or sets the optional data columns. value can be a DataFrame,
data.frame object, or NULL.
values(x), values(x) <- value:
Alternative to elementMetadata functions.
names(x), names(x) <- value:
Gets or sets the names of the elements.
length(x):
Gets the number of elements.
In the following code snippets, x is a GRanges object.
start(x), start(x) <- value:
Gets or sets start(ranges(x)).
end(x), end(x) <- value:
Gets or sets end(ranges(x)).
width(x), width(x) <- value:
Gets or sets width(ranges(x)).
flank(x, width, start = TRUE, both = FALSE, use.names = TRUE):
Returns a new GRanges object containing intervals of width width
that flank the intervals in x.
The start argument takes a logical indicating whether x
should be flanked at the "start" (TRUE) or the "end"
(FALSE), which for strand(x) != "-" is start(x) and
end(x) respectively and for strand(x) == "-" is
codeend(x) and start(x) respectively.
The both argument takes a single logical value indicating whether
the flanking region width positions extends into the range.
If both = TRUE, the resulting range thus straddles the end point,
with width positions on either side.
resize(x, width, use.names = TRUE):
Returns a new GRanges object containing intervals that have been
resized to width width based on the strand(x) values.
Elements where strand(x) == "+" are anchored at start(x),
elements where strand(x) == "-" are anchored at the end(x),
and elements where strand = "*" are anchored at
(end(x) - start(x))%/%2. The use.names argument
determines whether or not to keep the names on the ranges.
shift(x, shift, use.names = TRUE):
Returns a new GRanges object containing intervals with start and
end values that have been shifted by integer vector shift.
The use.names argument determines whether or not to
keep the names on the ranges.
disjoin(x):
Returns a new GRanges object containing disjoint ranges for each
distinct (seqname, strand) pairing. The names (names(x)) and
the columns in x are dropped.
gaps(x, start = 1L, end = seqlengths(x)):
Returns a new GRanges object containing complemented ranges for each
distinct (seqname, strand) pairing. The names (names(x)) and
the columns in x are dropped. See
?gaps for more information
about range complements and for a description of the optional arguments.
range(x, ...):
Returns a new GRanges object containing range bounds for each
distinct (seqname, strand) pairing. The names (names(x)) and
the columns in x are dropped.
reduce(x, drop.empty.ranges = FALSE, min.gapwidth = 1L):
Returns a new GRanges object containing reduced ranges for each
distinct (seqname, strand) pairing. The names (names(x)) and
the columns in x are dropped. See
?reduce for more information
about range reduction and for a description of the optional arguments.
coverage(x, shift = list(0L), width = as.list(seqlengths(x)), weight = list(1L)):
Returns a named RleList object with one element
('integer' Rle) per unique sequence name representing how many
times each position in the sequence is covered by the intervals in
x. The shift, width, and weight arguments
take list arguments, possibly named by the unique sequence names in
x, whose elements are passed into the coverage method for
IRanges object. See ?coverage for more
information on these optional arguments.
In the code snippets below, x is a GRanges object.
append(x, values, after = length(x)):
Inserts the values into x at the position given by
after, where x and values are of the same
class.
c(x, ...):
Combines x and the GRanges objects in ... together.
Any object in ... must belong to the same class as x,
or to one of its subclasses, or must be NULL.
The result is an object of the same class as x.
split(x, f = seq_len(length(x)), drop = FALSE):
Splits x into a GRangesList, according to f,
dropping elements corresponding to unrepresented levels if drop
is TRUE. Split factor f defaults to splitting each
element of x into a separate element in the resulting
GRangesList object.
In the code snippets below, x is a GRanges object.
x[i, j], x[i, j] <- value:
Gets or sets elements i with optional elementMetadata columns
elementMetadata(x)[,j], where i can be missing; an NA-free
logical, numeric, or character vector; or a 'logical' Rle object.
x[i,j] <- value:
Replaces elements i and optional elementMetadata columns j
with value.
head(x, n = 6L):
If n is non-negative, returns the first n elements of the
GRanges object.
If n is negative, returns all but the last abs(n) elements
of the GRanges object.
rep(x, times, length.out, each):
Repeats the values in x through one of the following conventions:
timeslength(x), or to repeat the whole vector
if of length 1.length.outeachx is
repeated each times.rev(x):
Returns a new object of the same class as x made of the original
elements in the reverse order.
seqselect(x, start=NULL, end=NULL, width=NULL):
Similar to window, except that multiple consecutive subsequences
can be requested for concatenation. As such two of the three start,
end, and width arguments can be used to specify the
consecutive subsequences. Alternatively, start can take a Ranges
object or something that can be converted to a Ranges object like an
integer vector, logical vector or logical Rle. If the concatenation of
the consecutive subsequences is undesirable, consider using
Views.
seqselect(x, start=NULL, end=NULL, width=NULL) <- value:
Similar to window<-, except that multiple consecutive subsequences
can be replaced by a value whose length is a divisor of the number
of elements it is replacing. As such two of the three start,
end, and width arguments can be used to specify the
consecutive subsequences. Alternatively, start can take a Ranges
object or something that can be converted to a Ranges object like an
integer vector, logical vector or logical Rle.
subset(x, subset):
Returns a new object of the same class as x made of the subset
using logical vector subset, where missing values are taken as
FALSE.
tail(x, n = 6L):
If n is non-negative, returns the last n elements of the
GRanges object.
If n is negative, returns all but the first abs(n) elements
of the GRanges object.
window(x, start = NA, end = NA, width = NA, frequency = NULL, delta = NULL, ...):
Extracts the subsequence window from the GRanges object using:
start, end, widthfrequency, delta"[" operator.
window(x, start = NA, end = NA, width = NA, keepLength = TRUE) <- value:
Replaces the subsequence window specified on the left (i.e. the subsequence
in x specified by start, end and width)
by value.
value must either be of class class(x), belong to a subclass
of class(x), be coercible to class(x), or be NULL.
If keepLength is TRUE, the elements of value are
repeated to create a GRanges object with the same number of elements
as the width of the subsequence window it is replacing.
If keepLength is FALSE, this replacement method can modify
the length of x, depending on how the length of the left
subsequence window compares to the length of value.
P. Aboyoun
GRangesList-class, Seqinfo-class, Sequence-class, Ranges-class, Rle-class, DataFrame-class
gr <-
GRanges(seqnames =
Rle(c("chr1", "chr2", "chr1", "chr3"), c(1, 3, 2, 4)),
ranges =
IRanges(1:10, width = 10:1, names = head(letters,10)),
strand =
Rle(strand(c("-", "+", "*", "+", "-")),
c(1, 2, 2, 3, 2)),
score = 1:10,
GC = seq(1, 0, length=10))
gr
# Summarizing elements
table(seqnames(gr))
sum(width(gr))
summary(elementMetadata(gr)[,"score"]) # or values(gr)
coverage(gr)
# Changing sequence name
unique(seqnames(gr))
seqnames(gr) <- sub("chr", "Chrom", seqnames(gr))
gr
# Intra-interval operations
flank(gr, 10)
resize(gr, 10)
shift(gr, 1)
# Inter-interval operations
disjoin(gr)
gaps(gr, start = 1, end = 10)
range(gr)
reduce(gr)