RangesList-class           package: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

