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:
seqnames
ranges
strand
elementMetadata
"seqnames"
, "ranges"
, "strand"
, "seqlengths"
,
"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.
seqnames
ranges
strand
seqlengths
level(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
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
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.
seqlengths(x)
, seqlengths(x) <- value
:
Gets or sets the seqlengths. value
can be a named non-negative
integer or numeric vector.
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:
times
length(x)
, or to repeat the whole vector
if of length 1.length.out
each
x
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
, width
frequency
, 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, Sequence, Ranges, Rle, DataFrame
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)