RangesList-class {IRanges} | R Documentation

## List of Ranges

### Description

An extension of `AnnotatedList` 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 an `AnnotatedList`, `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)`: Get the starts of the ranges.
  `end(x)`: Get the ends of the ranges.
  `width(x)`: Get the widths of the ranges.
  `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 `TypedList`, 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 `overlap` 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 `as.data.frame(unlist(x))`.
  `as(from, "RangedData")`: Coerces `from` to a `RangedData` with zero columns and the same ranges as in `from`.
  `as(from, "IRangesList")`: Coerces `from`, to an `IRangesList`, 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).

### 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

      # 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.2.3 Index]