R: RangesList utility functions

RangesList-utils {IRanges}

R Documentation

RangesList utility functions

Description

Utility functions for manipulating RangesList objects.

Usage

# Intra-interval operations
## S4 method for signature 'RangesList'
flank(x, width, start=TRUE, both=FALSE, use.names=TRUE)
## S4 method for signature 'RangesList'
narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
## S4 method for signature 'RangesList'
resize(x, width, fix="start", use.names=TRUE)
## S4 method for signature 'RangesList'
restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
## S4 method for signature 'RangesList'
shift(x, shift, use.names=TRUE)

# Inter-interval operations
## S4 method for signature 'RangesList'
disjoin(x)
## S4 method for signature 'RangesList'
gaps(x, start=NA, end=NA)
## S4 method for signature 'RangesList'
range(x, ..., na.rm = FALSE)
## S4 method for signature 'RangesList'
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L,
                              with.inframe.attrib=FALSE)

# Set operations
## S4 method for signature 'RangesList,RangesList'
union(x, y)
## S4 method for signature 'RangesList,RangesList'
intersect(x, y)
## S4 method for signature 'RangesList,RangesList'
setdiff(x, y)

Arguments

`x, y`	A `RangesList`
`start, end`	For `flank`, `start` must be either a logical vector or a LogicalList object indicating whether `x` should be flanked at the start (`TRUE`) or the end (`FALSE`). Recycled as necessary so that each element corresponds to a range in `x`. For `narrow`, `start` and `end` must be either an integer vector or a IntegerList object containing coordinates relative to the current ranges. For `restrict`, `start` and `end` must be either a single integer or `NA`. For `gaps`, `start` and `end` must be an integer vector containing the coordinate bounds for each RangesList element.
`width`	For `flank` and `resize`, either an integer vector or an IntegerList object containing the width of the flanking or resized regions. Recycled as necessary so that each element corresponds to a range in `x`. (Note for `flank`: if `both` is `TRUE`, this is effectively doubled.) For `narrow`, either an integer vector or a IntegerList object containing the widths to narrow to. See the SEW (Start/End/Width) interface for the details (`?solveUserSEW`).
`both`	If `TRUE`, extends the flanking region `width` positions into the range. The resulting range thus straddles the end point, with `width` positions on either side.
`use.names`	`TRUE` or `FALSE`. Should names be preserved?
`fix`	For `resize`, a character vector of length 1, a CharacterList object, or a 'character' RleList object containing the values `"start"`, `"end"`, and `"center"` denoting what to use as an anchor for each element in `x`.
`keep.all.ranges`	`TRUE` or `FALSE`. Should ranges that don't overlap with the interval specified by `start` and `end` be kept? Note that "don't overlap" means that they end strictly before `start - 1` or start strictly after `end + 1`. Ranges that end at `start - 1` or start at `end + 1` are always kept and their width is set to zero in the returned RangesList object.
`shift`	Either an integer vector or a IntegerList object containing the shift information. Recycled as necessary so that each element corresponds to a range in `x`.
`drop.empty.ranges`	`TRUE` or `FALSE`. Should empty ranges be dropped?
`min.gapwidth`	Ranges separated by a gap of at least `min.gapwidth` positions won't be merged in the Ranges object returned by `reduce`. Otherwise, they will.
`with.inframe.attrib`	`TRUE` or `FALSE`. For internal use.
`...`	For `range`, additional `RangesList` to consider.
`na.rm`	Ignored

Details

The flank method generates flanking ranges for each range in x.

The narrow method narrows the ranges in x i.e. each range in the returned RangesList object is a subrange of the corresponding range in x.

The resize method resizes the ranges to the specified width where either the start or end is used as an anchor.

The restrict method restricts the ranges in x to the interval specified by the start and end arguments.

The shift method shifts all the ranges in x.

The disjoin method returns disjoint ranges by finding the within element union of the end points of x.

The gaps method takes the complement (via gaps) of each element in the list and returns the result as a RangesList.

range finds the range, i.e. a Ranges with one range, from the minimum start to the maximum end, on each element in x and returns the result as a RangesList. If there are additional RangesList objects in ..., they are merged into x by name, if all objects have names, otherwise, if they are all of the same length, by position. Else, an exception is thrown.

The reduce method merges (via reduce) each of the elements in the list and returns the result as a RangesList.

The union method performs elementwise union operations for two RangesList objects.

The intersect method performs elementwise intersect operations for two RangesList objects.

The setdiff method performs elementwise setdiff operations for two RangesList objects.

Value

A RangesList object. For flank, narrow, resize, restrict, and shift, the length is the same as that of x.

Author(s)

Michael Lawrence, H. Pages, P. Aboyoun

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))
  range3 <- IRanges(start=c(-2,6,7), width=c(8,0,0))  # with empty ranges
  collection <- RangesList(one = range1, range2, range3)

  shift(collection, shift=5)
  restrict(collection, start=2, end=8)
  resize(collection, width=200)
  flank(collection, width=10)
  disjoin(collection)

  # these three are the same
  reduce(collection)
  RangesList(one = reduce(range1), reduce(range2), reduce(range3))
  do.call(RangesList, lapply(collection, reduce))

  # drop empty ranges
  reduce(collection, drop.empty.ranges=TRUE)

  # these three are the same
  gaps(collection)
  RangesList(one = gaps(range1), gaps(range2), gaps(range3))
  do.call(RangesList, lapply(collection, gaps))

  # 'range'
  rl <- RangesList(a = IRanges(c(1,2),c(4,3)), b = IRanges(c(4,6),c(10,7)))
  rl2 <- RangesList(c = IRanges(c(0,2),c(4,5)), a = IRanges(c(4,5),c(6,7)))
  range(rl, rl2) # matched by names
  names(rl2) <- NULL
  range(rl, rl2) # now by position

  # set operations
  union(rl, rl2)
  intersect(rl, rl2)
  setdiff(rl, rl2)

[Package IRanges version 1.12.6 Index]