IRanges-utils {Biostrings} | R Documentation

## IRanges utility functions

### Description

Utility functions for creating or modifying IRanges objects.

### Usage

      ## Create an IRanges object
      intToRanges(x, use.names=TRUE)
      intToAdjacentRanges(x, use.names=TRUE)
      toNormalIRanges(x)

      ## Modify an IRanges object
      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)

### Arguments

`x` | A vector of integers for `intToRanges` and `intToAdjacentRanges`. An IRanges object for `shift`, `restrict`, `reduce`, `toNormalIRanges` and `gaps`. An IRanges object or an integer vector for `narrow`.
`use.names` | `TRUE` or `FALSE`. Should names be preserved?
`shift` | A single integer.
`start` | A single integer or `NA`.
`end` | A single integer or `NA`.
`keep.all.ranges` | `TRUE` or `FALSE`. Should ranges that become "out of limits" after restriction be kept?
`width` | A single number or `NA`.
`with.inframe.attrib` | `TRUE` or `FALSE`. For internal use.

### Details

`intToRanges` returns an IRanges object of the same length as `x` where each integer in `x` has been converted into the range that starts at 1 and ends at that integer.

`intToAdjacentRanges` returns an IRanges object of the same length as `x` where the ranges are adjacent and have the width of the corresponding integer in `x`. The first range in the returned IRanges object starts at 1.

`toNormalIRanges` first reduces `x`, then removes the empty ranges. The final result is returned as a NormalIRanges object.

`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`. This subrange is determined by the `start`, `end` and `width` arguments. At least one of `start`, `end` and `width` must be `NA` and the other ones must be single numeric values. If at least two of them are `NA`s, then `start=NA` means that the starts are unchanged and `end=NA` means that the ends are unchanged. A positive `start` or `end` is interpreted relatively to the start of the original range whereas a negative `start` or `end` is interpreted relatively to its end. Note that, if `width` is `NA`, then `start=NA` is equivalent to `start=1` and `end=NA` is equivalent to `end=-1`. Finally, if `width` is not `NA`, then `start` and `end` cannot be both `NA`s.

`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.

### Author(s)

H. Pages

### See Also

IRanges-class, MaskCollection-class, `reverse` `coverage`

### Examples

      intToRanges(c(19, 5, 0, 8, 5))
      x <- intToAdjacentRanges(c(19, 5, 0, 8, 5))
      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)

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

[Package Biostrings version 2.8.18 Index]