R: List of Ranges

RangesList-class {IRanges} | R Documentation

## List of Ranges

### Description

An extension of `Sequence` that holds only `Ranges` objects. Useful for storing ranges over a set of spaces (e.g. chromosomes), each of which requires a separate `Ranges` object. As a `Sequence`, `RangesList` may be annotated with its universe identifier (e.g. a genome) in which all of its spaces exist.

### Accessors

In the code snippets below, `x` is a `RangesList` object.

All of these accessors collapse over the spaces:

  `start(x), start(x) <- value`: Get or set the starts of the ranges. When setting the starts, `value` can be an integer vector of `length(sum(elementLengths(x)))` or an IntegerList object of length `length(x)` and names `names(x)`.
  `end(x), end(x) <- value`: Get or set the ends of the ranges. When setting the starts, `value` can be an integer vector of `length(sum(elementLengths(x)))` or an IntegerList object of length `length(x)` and names `names(x)`.
  `width(x), width(x) <- value`: Get or set the widths of the ranges. When setting the starts, `value` can be an integer vector of `length(sum(elementLengths(x)))` or an IntegerList object of length `length(x)` and names `names(x)`.
  `space(x)`: Gets the spaces of the ranges as a character vector. This is equivalent to `names(x)`, except each name is repeated according to the length of its element.

These accessors are for the `universe` identifier:

  `universe(x)`: gets the name of the universe as a single string, if one has been specified, `NULL` otherwise.
  `universe(x) <- value`: sets the name of the universe to `value`, a single string or `NULL`.

### Constructor

  `RangesList(..., universe = NULL)`: Each `Ranges` in `...` becomes an element in the new `RangesList`, in the same order. This is analogous to the `list` constructor, except every argument in `...` must be derived from `Ranges`. The universe is specified by the `universe` parameter, which should be a single string or NULL, to leave unspecified.

### Subsetting

In the code snippets below, `x` is a `RangesList` object.

  `x[i]`: Subset `x` by index `i`, with the same semantics as a basic `Sequence`, except `i` may itself be a `RangesList`, in which case only the ranges in `x` that overlap with those in `i` are kept. See the `findOverlaps` method for more details.

### Coercion

In the code snippets below, `x` and `from` are a `RangesList` object.

  `as.data.frame(x, row.names = NULL, optional = FALSE)`: Coerces `x` to a `data.frame`. Essentially the same as calling `data.frame(space=rep(names(x), elementLengths(x)), as.data.frame(unlist(x, use.names=FALSE)))`.
  `as(from, "RangedData")`: Coerces `from` to a `RangedData` with zero columns and the same ranges as in `from`.
  `as(from, "SimpleIRangesList")`: Coerces `from`, to a `SimpleIRangesList`, requiring that all `Ranges` elements are coerced to internal `IRanges` elements. This is a convenient way to ensure that all `Ranges` have been imported into R (and that there is no unwanted overhead when accessing them).
  `as(from, "CompressedIRangesList")`: Coerces `from`, to a `CompressedIRangesList`, requiring that all `Ranges` elements are coerced to internal `IRanges` elements. This is a convenient way to ensure that all `Ranges` have been imported into R (and that there is no unwanted overhead when accessing them).
  `as(from, "SimpleNormalIRangesList")`: Coerces `from`, to a `SimpleNormalIRangesList`, requiring that all `Ranges` elements are coerced to internal `NormalIRanges` elements.
  `as(from, "CompressedNormalIRangesList")`: Coerces `from`, to a `CompressedNormalIRangesList`, requiring that all `Ranges` elements are coerced to internal `NormalIRanges` elements.

### Arithmetic Operations

Any arithmetic operation, such as `x + y`, `x * y`, etc, where `x` is a `RangesList`, is performed identically on each element. Currently, `Ranges` supports only the `*` operator, which zooms the ranges by a numeric factor.

### Author(s)

Michael Lawrence

### Examples

      range1 <- IRanges(start=c(1,2,3), end=c(5,2,8))
      range2 <- IRanges(start=c(15,45,20,1), end=c(15,100,80,5))
      named <- RangesList(one = range1, two = range2)
      length(named) # 2
      start(named) # same as start(c(range1, range2))
      names(named) # "one" and "two"
      named[[1]] # range1
      unnamed <- RangesList(range1, range2)
      names(unnamed) # NULL

      # edit the width of the ranges in the list
      edited <- named
      width(edited) <- rep(c(3,2), elementLengths(named))
      edited

      # subset by RangesList
      range1 <- IRanges(start=c(1,2,3), end=c(5,2,8))
      range2 <- IRanges(start=c(1,15,20,45), end=c(5,15,100,80))
      collection <- RangesList(one = range1, range2)
      collection[RangesList()] # empty elements
      collection[RangesList(IRanges(4, 6), IRanges(50, 70))]
      collection[RangesList(IRanges(50, 70), one=IRanges(4, 6))]

      # same as list(range1, range2)
      as.list(RangesList(range1, range2))

      # coerce to data.frame
      as.data.frame(named)

      # set the universe
      universe(named) <- "hg18"
      universe(named)
      RangesList(range1, range2, universe = "hg18")

      ## zoom in 2X
      collection * 2

[Package IRanges version 1.6.17 Index]