GenomicRanges (version 1.24.1)

intra-range-methods: 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

"shift"(x, shift=0L, use.names=TRUE)
"shift"(x, shift=0L, use.names=TRUE)
"narrow"(x, start=NA, end=NA, width=NA, use.names=TRUE)
"resize"(x, width, fix="start", use.names=TRUE, ignore.strand=FALSE)
"resize"(x, width, fix="start", use.names=TRUE, ignore.strand=FALSE)
"flank"(x, width, start=TRUE, both=FALSE, use.names=TRUE, ignore.strand=FALSE)
"flank"(x, width, start=TRUE, both=FALSE, use.names=TRUE, ignore.strand=FALSE)
"promoters"(x, upstream=2000, downstream=200, ...)
"promoters"(x, upstream=2000, downstream=200, ...)
"restrict"(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
"restrict"(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
"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.

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)