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)
    breakInChunks(totalsize, nchunk, chunksize)

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

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

### Arguments

`width` | A vector of non-negative integers (with no NAs) specifying the widths of the ranges to create.
`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.
`totalsize` | A single non-negative integer. The total size of the object to break.
`nchunk` | A single positive integer. The number of chunks.
`chunksize` | A single positive integer. The size of the chunks (last chunk might be smaller).
`x` | A logical vector for `whichAsIRanges`. An IRanges object for `asNormalIRanges`.
`force` | `TRUE` or `FALSE`. Should `x` be turned into a NormalIRanges object even if `isNormal(x)` is `FALSE`?

### Details

`successiveIRanges` returns an IRanges instance containing the ranges 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`. When `gapwidth=0` and `from=1` (the defaults), the returned IRanges can be seen as a partitioning of the 1:sum(width) interval. See `?Partitioning` for more details on this.

`breakInChunks` returns a PartitioningByEnd object describing the "chunks" that result from breaking a vector-like object of length `totalsize` in the chunks described by `nchunk` or `chunksize`.

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

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)

Hervé Pagès

### See Also

- IRanges objects.

- Partitioning objects.

- `equisplit` for splitting a list-like object into a specified number of partitions.

- intra-range-methods and inter-range-methods for intra range and inter range transformations.

- setops-methods for performing set operations on IRanges objects.

- `solveUserSEW`

- `successiveViews`

### Examples

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

    successiveIRanges(vec)

    breakInChunks(600999, chunksize=50000)  # chunks of size 50000 (last
                                            # chunk is smaller)

    whichAsIRanges(vec >= 5)

    x <- IRanges(start=c(-2L, 6L, 9L, -4L, 1L, 0L, -6L, 10L),
                 width=c( 5L, 0L, 6L,  1L, 4L, 3L,  2L,  3L))
    asNormalIRanges(x)  # 3 non-empty 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 2.22.2 Index]