IRanges-utils {IRanges}R Documentation

IRanges utility functions

Description

Utility functions for creating or modifying IRanges objects.

Usage

  ## Create an IRanges instance:
  successiveIRanges(width, gapwidth=0, from=1)

  ## Turn a logical vector into a set of ranges:
  whichAsIRanges(x)

  ## Modify an IRanges object (endomorphisms):
  shift(x, shift, use.names=TRUE)
  restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
  narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
  reduce(x, with.inframe.attrib=FALSE)
  gaps(x, start=NA, end=NA)

  ## Coercion:
  asNormalIRanges(x, force=TRUE)

Arguments

width For successiveIRanges, must be a vector of non-negative integers (with no NAs) specifying the widths of the ranges to create.
For narrow, a vector of integers, eventually with NAs. See the SEW (Start/End/Width) interface for the details (?solveUserSEW).
gapwidth A single integer or an integer vector with one less element than the width vector specifying the widths of the gaps separating one range from the next one.
from A single integer specifying the starting position of the first range.
x A logical vector for whichAsIRanges.
An IRanges object for shift, restrict, narrow, reduce, gaps and asNormalIRanges.
shift A single integer.
use.names TRUE or FALSE. Should names be preserved?
start, end A single integer or NA for all functions except narrow.
For narrow, 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.
keep.all.ranges TRUE or FALSE. Should ranges that become "out of limits" after restriction be kept?
with.inframe.attrib TRUE or FALSE. For internal use.
force TRUE or FALSE. Should x be turned into a NormalIRanges object even if isNormal(x) is FALSE?

Details

successiveIRanges returns an IRanges object containing the ranges on subject that have the widths specified in the width vector and are separated by the gaps specified in gapwidth. The first range starts at position from.

whichAsIRanges returns an IRanges object containing all of the ranges where x is TRUE.

shift shifts all the ranges in x.

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

narrow narrows the ranges in x i.e. each range in the returned IRanges 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.

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

gaps returns the normal IRanges object describing the set of integers obtained by removing the set of integers described by x from the interval specified by the start and end arguments.

If force=TRUE (the default), then asNormalIRanges will turn x into a NormalIRanges instance by reordering and reducing the set of ranges if necessary (i.e. only if isNormal(x) is FALSE, otherwise the set of ranges will be untouched). If force=FALSE, then asNormalIRanges will turn x into a NormalIRanges instance only if isNormal(x) is TRUE, otherwise it will raise an error. Note that when force=FALSE, the returned object is guaranteed to contain exactly the same set of ranges than x. as(x, "NormalIRanges") is equivalent to asNormalIRanges(x, force=TRUE).

Author(s)

H. Pages

See Also

Ranges-class, IRanges-class, IRanges-setops, solveUserSEW, successiveViews

Examples

  vec <- as.integer(c(19, 5, 0, 8, 5))
  whichAsIRanges(vec >= 5)
  x <- successiveIRanges(vec)
  x
  shift(x, -3)
  restrict(x, start=12, end=34)
  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))

  x <- IRanges(start=c(-2L, 6L, 9L, -4L, 1L, 0L, -6L, 10L),
               width=c( 5L, 0L, 6L,  1L, 4L, 3L,  2L,  3L))
  reduce(x)
  gaps(x)
  gaps(x, start=-6, end=20)  # Regions of the -6:20 range that are not masked by 'x'.
  asNormalIRanges(x)   # 3 ranges ordered from left to right and separated by
                       # gaps of width >= 1.

  ## More on normality:
  example(`IRanges-class`)
  isNormal(x16)                        # FALSE
  if (interactive())
      x16 <- asNormalIRanges(x16)      # Error!
  whichFirstNotNormal(x16)             # 57
  isNormal(x16[1:56])                  # TRUE
  xx <- asNormalIRanges(x16[1:56])
  class(xx)
  max(xx)
  min(xx)

[Package IRanges version 1.0.16 Index]