intra-range-methods {GenomicRanges} | R Documentation

## Intra range transformations of a GRanges or GRangesList object

### Description

This man page documents intra range transformations of a GenomicRanges object (i.e. of an object that belongs to the GenomicRanges class or one of its subclasses, this includes for example GRanges objects), or a GRangesList object.

See `?`intra-range-methods`` and `?`inter-range-methods`` in the IRanges package for a quick introduction to intra range and inter range transformations.

Intra range methods for GAlignments and GAlignmentsList objects are defined and documented in the GenomicAlignments package.

See `?`inter-range-methods`` for inter range transformations of a GenomicRanges or GRangesList object.

### Usage

    ## S4 method for signature 'GenomicRanges'
    shift(x, shift=0L, use.names=TRUE)
    ## S4 method for signature 'GRangesList'
    shift(x, shift=0L, use.names=TRUE)
    ## S4 method for signature 'GenomicRangesList'
    shift(x, shift=0L, use.names=TRUE)

    ## S4 method for signature 'GenomicRanges'
    narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
    ## S4 method for signature 'GRangesList'
    narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
    ## S4 method for signature 'GenomicRangesList'
    narrow(x, start=NA, end=NA, width=NA,
           use.names=TRUE)

    ## S4 method for signature 'GenomicRanges'
    resize(x, width, fix="start", use.names=TRUE,
           ignore.strand=FALSE)
    ## S4 method for signature 'GRangesList'
    resize(x, width, fix="start", use.names=TRUE,
           ignore.strand=FALSE)
    ## S4 method for signature 'GenomicRangesList'
    resize(x, width, fix="start", use.names=TRUE,
           ignore.strand=FALSE)

    ## S4 method for signature 'GenomicRanges'
    flank(x, width, start=TRUE, both=FALSE,
          use.names=TRUE, ignore.strand=FALSE)
    ## S4 method for signature 'GRangesList'
    flank(x, width, start=TRUE, both=FALSE,
          use.names=TRUE, ignore.strand=FALSE)
    ## S4 method for signature 'GenomicRangesList'
    flank(x, width, start=TRUE, both=FALSE,
          use.names=TRUE, ignore.strand=FALSE)

    ## S4 method for signature 'GenomicRanges'
    promoters(x, upstream=2000, downstream=200)
    ## S4 method for signature 'GRangesList'
    promoters(x, upstream=2000, downstream=200)
    ## S4 method for signature 'GenomicRangesList'
    promoters(x, upstream=2000, downstream=200)

    ## S4 method for signature 'GenomicRanges'
    restrict(x, start=NA, end=NA, keep.all.ranges=FALSE,
             use.names=TRUE)
    ## S4 method for signature 'GRangesList'
    restrict(x, start=NA, end=NA, keep.all.ranges=FALSE,
             use.names=TRUE)
    ## S4 method for signature 'GenomicRangesList'
    restrict(x, start=NA, end=NA,
          keep.all.ranges=FALSE, use.names=TRUE)

    ## S4 method for signature 'GenomicRanges'
    trim(x, use.names=TRUE)

### Arguments

`x` | A GenomicRanges or GRangesList object.
`shift, use.names, start, end, width, both, fix, keep.all.ranges, upstream, downstream` | See `?`intra-range-methods``.
`ignore.strand` | `TRUE` or `FALSE`. Whether the strand of the input ranges should be ignored or not. See details below.
`...` | Additional arguments to methods.

### Details

- `shift` behaves like the `shift` method for Ranges objects. See `?`intra-range-methods`` for the details.

- ()`narrow` on a GenomicRanges object behaves like on a Ranges object. See `?`intra-range-methods`` for the details.

  A major difference though is that it returns a GenomicRanges object instead of a Ranges object. The returned object is parallel (i.e. same length and names) to the original object `x`.

- `resize` returns an object of the same type and length as `x` containing intervals that have been resized to width `width` based on the `strand(x)` values. Elements where `strand(x) == "+"` or `strand(x) == "*"` are anchored at `start(x)` and elements where `strand(x) == "-"` are anchored at the `end(x)`. The `use.names` argument determines whether or not to keep the names on the ranges.

- `flank` returns an object of the same type and length as `x` containing intervals of width `width` that flank the intervals in `x`. The `start` argument takes a logical indicating whether `x` should be flanked at the "start" (`TRUE`) or the "end" (`FALSE`), which for `strand(x) != "-"` is `start(x)` and `end(x)` respectively and for `strand(x) == "-"` is `end(x)` and `start(x)` respectively. The `both` argument takes a single logical value indicating whether the flanking region `width` positions extends into the range. If `both=TRUE`, the resulting range thus straddles the end point, with `width` positions on either side.

- `promoters` returns an object of the same type and length as `x` containing promoter ranges. Promoter ranges extend around the transcription start site (TSS) which is defined as `start(x)`. The `upsteam` and `downstream` arguments define the number of nucleotides in the 5' and 3' direction, respectively. The full range is defined as,

  (start(x) - upstream) to (start(x) + downstream - 1).

  Ranges on the `*` strand are treated the same as those on the `+` strand. When no seqlengths are present in `x`, it is possible to have non-positive start values in the promoter ranges. This occurs when (TSS - `upstream`) < 1. In the equal but opposite case, the `end` values of the ranges may extend beyond the chromosome end when (TSS + `downstream` + 1) > 'chromosome end'. When `seqlengths` are not `NA` the promoter ranges are kept within the bounds of the defined `seqlengths`.

- `restrict` returns an object of the same type and length as `x` containing restricted ranges for distinct seqnames. The `start` and `end` arguments can be a named numeric vector of seqnames for the ranges to be resticted or a numeric vector or length 1 if the restriction operation is to be applied to all the sequences in `x`. See `?`intra-range-methods`` for more information about range restriction and for a description of the optional arguments.

- `trim` trims out-of-bound ranges located on non-circular sequences whose length is not NA.

### Author(s)

P. Aboyoun and V. Obenchain <vobencha@fhcrc.org>

### See Also

- GenomicRanges, GRanges, and GRangesList objects.

- The intra-range-methods man page in the IRanges package.

- The Ranges class in the IRanges package.

- `endoapply` in the S4Vectors package.

### Examples

    ## ---------------------------------------------------------------------
    ## A. ON A GRanges OBJECT
    ## ---------------------------------------------------------------------
    gr <- GRanges(
            seqnames=Rle(paste("chr", c(1, 2, 1, 3), sep=""), c(1, 3, 2, 4)),
            ranges=IRanges(1:10, width=10:1, names=letters[1:10]),
            strand=Rle(strand(c("-", "+", "*", "+", "-")), c(1, 2, 2, 3, 2)),
            score=1:10,
            GC=seq(1, 0, length=10)
          )
    gr

    shift(gr, 1)
    narrow(gr[-10], start=2, end=-2)
    resize(gr, width=10)
    flank(gr, width=10)
    restrict(gr, start=3, end=7)

    gr <- GRanges("chr1", IRanges(rep(10, 3), width=6), c("+", "-", "*"))
    promoters(gr, 2, 2)

    ## ---------------------------------------------------------------------
    ## B. ON A GRangesList OBJECT
    ## ---------------------------------------------------------------------
    gr1 <- GRanges("chr2", IRanges(3, 6))
    gr2 <- GRanges(c("chr1", "chr1"), IRanges(c(7,13), width=3),
                   strand=c("+", "-"))
    gr3 <- GRanges(c("chr1", "chr2"), IRanges(c(1, 4), c(3, 9)),
                   strand="-")
    grl <- GRangesList(gr1= gr1, gr2=gr2, gr3=gr3)
    grl

    resize(grl, width=20)
    flank(grl, width=20)
    restrict(grl, start=3)

[Package GenomicRanges version 1.30.3 Index]