IRanges (version 2.0.1)

intra-range-methods: Intra range transformations of a Ranges, Views, RangesList, or MaskCollection object

Description

Except for threebands(), all the transformations described in this man page are endomorphisms that operate on a single "range-based" object, that is, they transform the ranges contained in the input object and return them in an object of the same class as the input object.

Range-based endomorphisms are grouped in 2 categories:

1. Intra range transformations like shift() that transform each range individually (and independently of the other ranges) and return an object of the same length as the input object. Those transformations are described in this man page.
2. Inter range transformations like reduce() that transform all the ranges together as a set to produce a new set of ranges and return an object not necessarily of the same length as the input object. Those transformations are described in the inter-range-methods man page (see ?`inter-range-methods`).

Usage

## shift()
shift(x, shift=0L, use.names=TRUE)
## narrow()
narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
## resize()
resize(x, width, fix="start", use.names=TRUE, ...)
## flank()
flank(x, width, start=TRUE, both=FALSE, use.names=TRUE, ...)
## promoters()
promoters(x, upstream=2000, downstream=200, ...)
## reflect()
reflect(x, bounds, use.names=TRUE)
## restrict()
restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
## threebands()
threebands(x, start=NA, end=NA, width=NA)

Arguments

x

A Ranges, Views, RangesList, or MaskCollection object.

shift

An integer vector containing the shift information. Recycled as necessary so that each element corresponds to a range in x. It can also be an IntegerList object if x is a RangesList object.

use.names

TRUE or FALSE. Should names be preserved?

start, end

• If x is a Ranges or Views object: A vector of integers for all functions except for flank. For restrict, the supplied start and end arguments must be vectors of integers, eventually with NAs, that specify the restriction interval(s). Recycled as necessary so that each element corresponds to a range in x. Same thing for narrow and threebands, except that here start and end must contain coordinates relative to the ranges in x. See the Details section below. For flank, start is a logical indicating whether x should be flanked at the start (TRUE) or the end (FALSE). Recycled as necessary so that each element corresponds to a range in x.
• If x is a RangesList object: For flank, start must be either a logical vector or a LogicalList object indicating whether x should be flanked at the start (TRUE) or the end (FALSE). Recycled as necessary so that each element corresponds to a range in x. For narrow, start and end must be either an integer vector or an IntegerList object containing coordinates relative to the current ranges. For restrict, start and end must be either an integer vector or an IntegerList object (possibly containing NA's).

width

• If x is a Ranges or Views object: For narrow and threebands, a vector of integers, eventually with NAs. See the SEW (Start/End/Width) interface for the details (?solveUserSEW). For resize and flank, the width of the resized or flanking regions. Note that if both is TRUE, this is effectively doubled. Recycled as necessary so that each element corresponds to a range in x.
• If x is a RangesList object: For resize and flank, either an integer vector or an IntegerList object containing the width of the flanking or resized regions. Recycled as necessary so that each element corresponds to a range in x. (Note for flank: if both is TRUE, this is effectively doubled.) For narrow, either an integer vector or a IntegerList object containing the widths to narrow to. See the SEW (Start/End/Width) interface for the details (?solveUserSEW).

both

If TRUE, extends the flanking region width positions into the range. The resulting range thus straddles the end point, with width positions on either side.

bounds

An IRanges object to serve as the reference bounds for the reflection, see below.

fix

• If x is a Ranges or Views object: A character vector or character-Rle of length 1 or length(x) containing the values "start", "end", and "center" denoting what to use as an anchor for each element in x.
• If x is a RangesList object: A character vector of length 1, a CharacterList object, or a character-RleList object containing the values "start", "end", and "center" denoting what to use as an anchor for each element in x.

upstream, downstream

Single integer values >= 0L. upstream defines the number of nucleotides toward the 5' end and downstream defines the number toward the 3' end, relative to the transcription start site. Promoter regions are formed by merging the upstream and downstream ranges.

Default values for upstream and downstream were chosen based on our current understanding of gene regulation. On average, promoter regions in the mammalian genome are 5000 bp upstream and downstream of the transcription start site.

keep.all.ranges

TRUE or FALSE. Should ranges that don't overlap with the restriction interval(s) be kept? Note that "don't overlap" means that they end strictly before start - 1 or start strictly after end + 1. Ranges that end at start - 1 or start at end + 1 are always kept and their width is set to zero in the returned IRanges object.

...

Additional arguments for methods.

Details

Here we start by describing how each transformation operates on a Ranges object x.

shift shifts all the ranges in x by the amount specified by the shift argument.

narrow narrows the ranges in x i.e. each range in the returned Ranges object is a subrange of the corresponding range in x. The supplied start/end/width values are solved by a call to solveUserSEW(width(x), start=start, end=end, width=width) and therefore must be compliant with the rules of the SEW (Start/End/Width) interface (see ?solveUserSEW for the details). Then each subrange is derived from the original range according to the solved start/end/width values for this range. Note that those solved values are interpreted relatively to the original range.

resize resizes the ranges to the specified width where either the start, end, or center is used as an anchor.

flank generates flanking ranges for each range in x. If start is TRUE for a given range, the flanking occurs at the start, otherwise the end. The widths of the flanks are given by the width parameter. The widths can be negative, in which case the flanking region is reversed so that it represents a prefix or suffix of the range in x. The flank operation is illustrated below for a call of the form flank(x, 3, TRUE), where x indicates a range in x and - indicates the resulting flanking region:

    ---xxxxxxx
  

If start were FALSE:

       xxxxxxx---
  

For negative width, i.e. flank(x, -3, FALSE), where * indicates the overlap between x and the result:

       xxxx***
  

If both is TRUE, then, for all ranges in x, the flanking regions are extended into (or out of, if width is negative) the range, so that the result straddles the given endpoint and has twice the width given by width. This is illustrated below for flank(x, 3, both=TRUE):

    ---***xxxx
  

promoters generates promoter ranges for each range in x relative to the transcription start site (TSS), where TSS is start(x). The promoter range is expanded around the TSS according to the upsteam and downstream arguments. upstream represents the number of nucleotides in the 5' direction and downstream the number in the 3' direction. The full range is defined as, (start(x) - upstream) to (start(x) + downstream - 1). For documentation for using promoters on GenomicRanges objects see ?"promoters,GRanges-method".

reflect "reflects" or reverses each range in x relative to the corresponding range in bounds, which is recycled as necessary. Reflection preserves the width of a range, but shifts it such the distance from the left bound to the start of the range becomes the distance from the end of the range to the right bound. This is illustrated below, where x represents a range in x and [ and ] indicate the bounds:

    [..xxx.....]
    becomes
    [.....xxx..]
  

restrict restricts the ranges in x to the interval(s) specified by the start and end arguments.

threebands extends the capability of narrow by returning the 3 ranges objects associated to the narrowing operation. The returned value y is a list of 3 ranges objects named "left", "middle" and "right". The middle component is obtained by calling narrow with the same arguments (except that names are dropped). The left and right components are also instances of the same class as x and they contain what has been removed on the left and right sides (respectively) of the original ranges during the narrowing.

Note that original object x can be reconstructed from the left and right bands with punion(y$left, y$right, fill.gap=TRUE).

When x in a RangesList object, doing any of the transformation above is equivalent to applying the transformation to each RangesList top-level element separately.

See Also

• inter-range-methods for inter range transformations.
• The Ranges, Views, RangesList, and MaskCollection classes.
• The intra-range-methods man page in the XVector package for methods that operate on XVectorList objects.
• The intra-range-methods man page in the GenomicRanges package for methods that operate on GenomicRanges and other objects.
• setops-methods for set operations on IRanges objects.
• solveUserSEW for the SEW (Start/End/Width) interface.

Examples

## ---------------------------------------------------------------------
## shift()
## ---------------------------------------------------------------------

## On a Ranges object
ir1 <- successiveIRanges(c(19, 5, 0, 8, 5))
ir1
shift(ir1, shift=-3)

## On a RangesList object
range1 <- IRanges(start=c(1, 2, 3), end=c(5, 2, 8))
range2 <- IRanges(start=c(15, 45, 20, 1), end=c(15, 100, 80, 5))
range3 <- IRanges(start=c(-2, 6, 7), width=c(8, 0, 0))  # with empty ranges
collection <- IRangesList(one=range1, range2, range3)
shift(collection, shift=5)

## ---------------------------------------------------------------------
## narrow()
## ---------------------------------------------------------------------

## On a Ranges object
ir2 <- ir1[width(ir1) != 0]
narrow(ir2, start=4, end=-2)
narrow(ir2, start=-4, end=-2)
narrow(ir2, end=5, width=3)
narrow(ir2, start=c(3, 4, 2, 3), end=c(12, 5, 7, 4))

## On a RangesList object
narrow(collection[-3], start=2)
narrow(collection[-3], end=-2)

## On a MaskCollection object
mask1 <- Mask(mask.width=29, start=c(11, 25, 28), width=c(5, 2, 2))
mask2 <- Mask(mask.width=29, start=c(3, 10, 27), width=c(5, 8, 1))
mask3 <- Mask(mask.width=29, start=c(7, 12), width=c(2, 4))
mymasks <- append(append(mask1, mask2), mask3)
mymasks
narrow(mymasks, start=8)

## ---------------------------------------------------------------------
## resize()
## ---------------------------------------------------------------------

## On a Ranges object
resize(ir2, 200)
resize(ir2, 2, fix="end")

## On a RangesList object
resize(collection, width=200)

## ---------------------------------------------------------------------
## flank()
## ---------------------------------------------------------------------

## On a Ranges object
ir3 <- IRanges(c(2,5,1), c(3,7,3))
flank(ir3, 2)
flank(ir3, 2, start=FALSE)
flank(ir3, 2, start=c(FALSE, TRUE, FALSE))
flank(ir3, c(2, -2, 2))
flank(ir3, 2, both = TRUE)
flank(ir3, 2, start=FALSE, both=TRUE)
flank(ir3, -2, start=FALSE, both=TRUE)

## On a RangesList object
flank(collection, width=10)

## ---------------------------------------------------------------------
## promoters()
## ---------------------------------------------------------------------

## On a Ranges object
ir4 <- IRanges(20:23, width=3)
promoters(ir4, upstream=0, downstream=0) ## no change
promoters(ir4, upstream=0, downstream=1) ## start value only
promoters(ir4, upstream=1, downstream=0) ## single upstream nucleotide 

## On a RangesList object
promoters(collection, upstream=5, downstream=2)

## ---------------------------------------------------------------------
## reflect()
## ---------------------------------------------------------------------

## On a Ranges object
bounds <- IRanges(c(0, 5, 3), c(10, 6, 9))
reflect(ir3, bounds)

## reflect() does not yet support RangesList objects!

## ---------------------------------------------------------------------
## restrict()
## ---------------------------------------------------------------------

## On a Ranges object
restrict(ir1, start=12, end=34)
restrict(ir1, start=20)
restrict(ir1, start=21)
restrict(ir1, start=21, keep.all.ranges=TRUE)

## On a RangesList object
restrict(collection, start=2, end=8)

## ---------------------------------------------------------------------
## threebands()
## ---------------------------------------------------------------------

## On a Ranges object
z <- threebands(ir2, start=4, end=-2)
ir2b <- punion(z$left, z$right, fill.gap=TRUE)
stopifnot(identical(ir2, ir2b))
threebands(ir2, start=-5)

## threebands() does not support RangesList objects.