GRangesList-class {GenomicRanges}R Documentation

GRangesList objects

Description

The GRangesList class is a container for storing a collection of GRanges objects.

Constructor

GRangesList(...): Creates a GRangesList object using GRanges objects supplied in ....

Coercion

In the code snippets below, x is a GRangesList object.

as.data.frame(x, row.names = NULL, optional = FALSE): Creates a data.frame with columns element (character), seqnames (factor), start (integer), end (integer), width (integer), strand (factor), as well as the additional columns stored in elementMetadata(unlist(x)).
as.list(x, use.names = TRUE): Creates a list containing the elements of x.
as(x, "IRangesList"): Turns x into an IRangesList object.
as(from, "GRangesList"): Creates a GRangesList object from a RangedDataList object.

Accessors

In the following code snippets, x is a GRanges object.

seqnames(x), seqnames(x) <- value: Gets or sets the sequence names in the form of an RleList. value can be an RleList or CharacterList.
ranges(x), ranges(x) <- value: Gets or sets the ranges in the form of a CompressedIRangesList. value can be a RangesList object.
strand(x), strand(x) <- value: Gets or sets the strand in the form of an RleList. value can be an RleList or CharacterList object.
elementMetadata(x), elementMetadata(x) <- value: Gets or sets the optional data columns for the GRangesList elements. value can be a DataFrame, data.frame object, or NULL.
values(x), values(x) <- value: Alternative to elementMetadata functions.
seqinfo(x), seqinfo(x) <- value: Gets or sets the information about the underlying sequences. value must be a Seqinfo object.
seqlevels(x), seqlevels(x) <- value: Gets or sets the sequence levels. seqlevels(x) is equivalent to seqlevels(seqinfo(x)) or to levels(seqnames(x)), those 2 expressions being guaranteed to return indentical character vectors on a GRangesList object. value must be a character vector with no NAs.
seqlengths(x), seqlengths(x) <- value: Gets or sets the sequence lengths. seqlengths(x) is equivalent to seqlengths(seqinfo(x)). value can be a named non-negative integer or numeric vector eventually with NAs.
isCircular(x), isCircular(x) <- value: Gets or sets the circularity flags. isCircular(x) is equivalent to isCircular(seqinfo(x)). value must be a named logical vector eventually with NAs.

List methods

In the following code snippets, x is a GRangesList object.

length(x): Gets the number of elements.
names(x), names(x) <- value: Gets or sets the names of the elements.
elementLengths(x): Gets the length of each of the elements.
isEmpty(x): Returns a logical indicating either if the GRangesList has no elements or if all its elements are empty.

RangesList methods

In the following code snippets, x is a GRangesList 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)).
shift(x, shift, use.names=TRUE): Returns a new GRangesList 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.
coverage(x, shift=0L, width=NULL, weight=1L): Equivalent to coverage(unlist(x), shift, width, weight).

Combining

In the code snippets below, x is a GRangesList 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 GRangesList 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.
unlist(x, recursive = TRUE, use.names = TRUE): Concatenates the elements of x into a single GRanges object.

Subsetting

In the following code snippets, x is a GRangesList object.

x[i, j], x[i, j] <- value: Gets or sets elements i with optional values columns values(x)[,j], where i can be missing; an NA-free logical, numeric, or character vector; a 'logical' Rle object, or an AtomicList object.
x[[i]], x[[i]] <- value: Gets or sets element i, where i is a numeric or character vector of length 1.
x$name, x$name <- value: Gets or sets element name, where name is a name or character vector of length 1.
head(x, n = 6L): If n is non-negative, returns the first n elements of the GRangesList object. If n is negative, returns all but the last abs(n) elements of the GRangesList object.
rep(x, times, length.out, each): Repeats the values in x through one of the following conventions:
times
Vector giving the number of times to repeat each element if of length length(x), or to repeat the whole vector if of length 1.
length.out
Non-negative integer. The desired length of the output vector.
each
Non-negative integer. Each element of x is repeated each times.
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
The start, end, or width of the window. Two of the three are required.
frequency, delta
Optional arguments that specify the sampling frequency and increment within the window.
In general, this is more efficient than using "[" 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.

Looping

In the code snippets below, x is a GRangesList object.

endoapply(X, FUN, ...): Similar to lapply, but performs an endomorphism, i.e. returns an object of class(X).
lapply(X, FUN, ...): Like the standard lapply function defined in the base package, the lapply method for GRangesList objects returns a list of the same length as X, with each element being the result of applying FUN to the corresponding element of X.
Map(f, ...): Applies a function to the corresponding elements of given GRangesList objects.
mapply(FUN, ..., MoreArgs = NULL, SIMPLIFY = TRUE, USE.NAMES = TRUE): Like the standard mapply function defined in the base package, the mapply method for GRangesList objects is a multivariate version of sapply.
mendoapply(FUN, ..., MoreArgs = NULL): Similar to mapply, but performs an endomorphism across multiple objects, i.e. returns an object of class(list(...)[[1]]).
Reduce(f, x, init, right = FALSE, accumulate = FALSE): Uses a binary function to successively combine the elements of x and a possibly given initial value.
f
A binary argument function.
init
An R object of the same kind as the elements of x.
right
A logical indicating whether to proceed from left to right (default) or from right to left.
nomatch
The value to be returned in the case when "no match" (no element satisfying the predicate) is found.
sapply(X, FUN, ..., simplify=TRUE, USE.NAMES=TRUE): Like the standard sapply function defined in the base package, the sapply method for GRangesList objects is a user-friendly version of lapply by default returning a vector or matrix if appropriate.

The "range" and "reduce" methods

In the code snippets below, x is a GRangesList object. The methods in this section are isomorphisms, that is, they are endomorphisms (i.e. they preserve the class of x) who also preserve the length & names & elementMetadata of x. In addition, the seqinfo is preserved too.

range(x): Applies range to each element in x. More precisely, it is equivalent to endoapply(x, range).
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L): Applies reduce to each element in x. More precisely, it is equivalent to endoapply(x, reduce, drop.empty.ranges=drop.empty.ranges, min.gapwidth=min.gapwidth).

Author(s)

P. Aboyoun & H. Pages

See Also

GRanges-class, Seqinfo-class Vector-class, RangesList-class, RleList-class, DataFrameList-class

Examples

  ## Construction using GRangesList
  gr1 <-
    GRanges(seqnames = "chr2", ranges = IRanges(3, 6),
            strand = "+", score = 5L, GC = 0.45)
  gr2 <-
    GRanges(seqnames = c("chr1", "chr1"),
            ranges = IRanges(c(7,13), width = 3),
            strand = c("+", "-"), score = 3:4, GC = c(0.3, 0.5))
  gr3 <-
    GRanges(seqnames = c("chr1", "chr2"),
            ranges = IRanges(c(1, 4), c(3, 9)),
            strand = c("-", "-"), score = c(6L, 2L), GC = c(0.4, 0.1))
  grl <- GRangesList("gr1" = gr1, "gr2" = gr2, "gr3" = gr3)
  grl

  # Summarizing elements
  elementLengths(grl)
  table(seqnames(grl))
  coverage(grl)

  # Extracting subsets
  grl[seqnames(grl) == "chr1", ]
  grl[seqnames(grl) == "chr1" & strand(grl) == "+", ]

  # Renaming the underlying sequences
  seqlevels(grl)
  seqlevels(grl) <- sub("chr", "Chrom", seqlevels(grl))
  grl

  # range() and reduce():
  range(grl)
  reduce(grl)  # Doesn't really reduce anything but note the reordering
               # of the inner elements in the 3rd top-level element: the
               # ranges are reordered by sequence name first (the order of
               # the sequence names is dictated by the sequence levels),
               # and then by strand.

  # Coerce to IRangesList (seqnames and strand information are lost)
  as(grl, "IRangesList")

[Package GenomicRanges version 1.4.6 Index]