intra-range-methods: Intra range transformations of a GRanges or GRangesList...
In Bioconductor/GenomicRanges: Representation and manipulation of genomic intervals

intra-range-methods

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 'GenomicRanges'
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 'GenomicRanges'
flank(x, width, start=TRUE, both=FALSE, use.names=TRUE,
      ignore.strand=FALSE)

## S4 method for signature 'GenomicRanges'
promoters(x, upstream=2000, downstream=200, use.names=TRUE)
## S4 method for signature 'GenomicRanges'
terminators(x, upstream=2000, downstream=200, use.names=TRUE)

## S4 method for signature 'GenomicRanges'
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 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.

Details

shift:

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

narrow:

on a GenomicRanges object behaves like on an IntegerRanges object. See ?`intra-range-methods` for the details.

A major difference though is that it returns a GenomicRanges object instead of an IntegerRanges 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:

assumes that the ranges in x represent transcript regions and returns the ranges of the corresponding promoter regions. The result is another GenomicRanges derivative parallel to the input, that is, of the same length as x and with the i-th element in the output corresponding to the i-th element in the input.

The promoter regions extend around the transcription start sites (TSS) which are located at start(x) for ranges on the + or * strand, and at end(x) for ranges on the - strand. The upstream and downstream arguments define the number of nucleotides in the 5' and 3' direction, respectively. More precisely, the output range is defined as

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

for ranges on the + or * strand, and as

    (end(x) - downstream + 1) to (end(x) + upstream)

for ranges on the - strand.

Be aware that the returned object might contain out-of-bound ranges i.e. ranges that start before the first nucleotide position and/or end after the last nucleotide position of the underlying sequence.

The returned object will always have the same class as x, except when x is a GPos object in which case a GRanges instance is returned.

terminators:

like promoters but returns the ranges of the terminator regions. These regions extend around the transcription end sites (TES) which are located at end(x) for ranges on the + or * strand, and at start(x) for ranges on the - strand.

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, V. Obenchain, and H. Pagès

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=8), c("+", "-", "*"))
promoters(gr, 2, 5)
promoters(gr, upstream=0, downstream=1)  # TSS
terminators(gr, 2, 5)
terminators(gr, upstream=0, downstream=1)  # TES

## ---------------------------------------------------------------------
## 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)

Bioconductor/GenomicRanges documentation built on Nov. 17, 2024, 11:43 a.m.