Ranges-utils {IRanges}R Documentation

Ranges utility functions

Description

Utility functions for modifying Ranges objects.

Usage

flank(x, width, start=TRUE, both=FALSE, use.names=TRUE)
narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
reflect(x, bounds, use.names=TRUE)
resize(x, width, fix="start", use.names=TRUE, ...)
restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
shift(x, shift, use.names=TRUE)

## S4 method for signature 'Ranges':
range(x, ..., na.rm = FALSE)
## S4 method for signature 'Ranges':
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L,
       with.inframe.attrib=FALSE)

threebands(x, start=NA, end=NA, width=NA)

Arguments

x An Ranges object.
width For narrow and threebands, a vector of integers, eventually with NAs. See the SEW (Start/End/Width) interface for the details (?solveUserSEW).

For resize and flank, the width of the resized or flanking regions. Note that if both is TRUE, this is effectively doubled. Recycled as necessary so that each element corresponds to a range in x.

start, end A single integer or NA for all functions except narrow, threebands, and flank.

For narrow and threebands, the supplied start and end arguments must be vectors of integers, eventually with NAs, that contain coordinates relative to the current ranges. See the Details section below.

For flank, start is a logical 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.

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?
bounds An IRanges object to serve as the reference bounds for the reflection, see below.
fix For resize, a character vector or character Rle of length 1 or length(x) 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 IRanges object.
shift A single integer.
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 Ranges to consider.
na.rm Ignored

Details

flank generates flanking ranges for each range in x. If start is TRUE for a given range, the flanking occurs at the start, otherwise the end. The widths of the flanks are given by the width parameter. The widths can be negative, in which case the flanking region is reversed so that it represents a prefix or suffix of the range in x. The flank operation is illustrated below for a call of the form flank(x, 3, TRUE), where x indicates a range in x and - indicates the resulting flanking region:

    ---xxxxxxx
  
If start were FALSE:
       xxxxxxx---
  
For negative width, i.e. flank(x, -3, FALSE), where * indicates the overlap between x and the result:
       xxxx***
  
If both is TRUE, then, for all ranges in x, the flanking regions are extended into (or out of, if width is negative) the range, so that the result straddles the given endpoint and has twice the width given by width. This is illustrated below for flank(x, 3, both=TRUE):
    ---***xxxx
  

narrow narrows the ranges in x i.e. each range in the returned Ranges object is a subrange of the corresponding range in x. The supplied start/end/width values are solved by a call to solveUserSEW(width(x), start=start, end=end, width=width) and therefore must be compliant with the rules of the SEW (Start/End/Width) interface (see ?solveUserSEW for the details). Then each subrange is derived from the original range according to the solved start/end/width values for this range. Note that those solved values are interpreted relatively to the original range.

reflect "reflects" or reverses each range in x relative to the corresponding range in bounds, which is recycled as necessary. Reflection preserves the width of a range, but shifts it such the distance from the left bound to the start of the range becomes the distance from the end of the range to the right bound. This is illustrated below, where x represents a range in x and [ and ] indicate the bounds:

    [..xxx.....]
    becomes
    [.....xxx..]
  

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

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

shift shifts all the ranges in x.

range returns an IRanges instance with a single range, from the minimum start to the maximum end in the combined ranges of x and the arguments in ....

reduce first orders the ranges in x from left to right, then merges the overlapping or adjacent ones.

threebands extends the capability of narrow by returning the 3 ranges objects associated to the narrowing operation. The returned value y is a list of 3 ranges objects named "left", "middle" and "right". The middle component is obtained by calling narrow with the same arguments (except that names are dropped). The left and right components are also instances of the same class as x and they contain what has been removed on the left and right sides (respectively) of the original ranges during the narrowing.

Note that original object x can be reconstructed from the left and right bands with punion(y$left, y$right, fill.gap=TRUE).

Author(s)

H. Pages, M. Lawrence, P. Aboyoun

See Also

threebands could be described as a parallel variant of disjoin.

Ranges-class, IRanges-setops, solveUserSEW

Examples

  vec <- as.integer(c(19, 5, 0, 8, 5))
  x <- successiveIRanges(vec)
  x

  shift(x, -3)

  restrict(x, start=12, end=34)
  restrict(x, start=20)
  restrict(x, start=21)
  restrict(x, start=21, keep.all.ranges=TRUE)

  y <- x[width(x) != 0]
  narrow(y, start=4, end=-2)
  narrow(y, start=-4, end=-2)
  narrow(y, end=5, width=3)
  narrow(y, start = c(3, 4, 2, 3), end = c(12, 5, 7, 4))

  resize(y, width = 200)
  resize(y, width = 2, fix = "end")

  z <- threebands(y, start=4, end=-2)
  y0 <- punion(z$left, z$right, fill.gap=TRUE)
  identical(y, y0)  # TRUE
  threebands(y, start=-5)

  x <- IRanges(start=c(-2, 6, 9, -4, 1, 0, -6, 3, 10),
               width=c( 5, 0, 6,  1, 4, 3,  2, 0,  3))
  reduce(x)
  reduce(x, drop.empty.ranges=TRUE)

  ir1 <- IRanges(c(2,5,1), c(3,7,3))

  bounds <- IRanges(c(0, 5, 3), c(10, 6, 9))
  reflect(ir1, bounds)

  flank(ir1, 2)
  flank(ir1, 2, FALSE)
  flank(ir1, 2, c(FALSE, TRUE, FALSE))
  flank(ir1, c(2, -2, 2))
  flank(ir1, 2, both = TRUE)
  flank(ir1, 2, FALSE, TRUE)
  flank(ir1, -2, FALSE, TRUE)

[Package IRanges version 1.6.16 Index]