Lists of Atomic Vectors in Natural and Rle Form

Description

An extension of List that holds only atomic vectors in either a natural or run-length encoded form.

Details

The lists of atomic vectors are LogicalList , IntegerList , NumericList , ComplexList , CharacterList , and RawList . There is also an RleList class for run-length encoded versions of these atomic vector types.

Each of the above mentioned classes is virtual with Compressed and Simple non-virtual representations.

Seealso

• AtomicList-utils for common operations on AtomicList objects.

• List objects in the S4Vectors package for the parent class.

Author

P. Aboyoun

Examples

int1 <- c(1L,2L,3L,5L,2L,8L)
int2 <- c(15L,45L,20L,1L,15L,100L,80L,5L)
collection <- IntegerList(int1, int2)

## names
names(collection) <- c("one", "two")
names(collection)
names(collection) <- NULL # clear names
names(collection)
names(collection) <- "one"
names(collection) # c("one", NA)

## extraction
collection[[1]] # range1
collection[["1"]] # NULL, does not exist
collection[["one"]] # range1
collection[[NA_integer_]] # NULL

## subsetting
collection[numeric()] # empty
collection[NULL] # empty
collection[] # identity
collection[c(TRUE, FALSE)] # first element
collection[2] # second element
collection[c(2,1)] # reversed
collection[-1] # drop first
collection$one

## replacement
collection$one <- int2
collection[[2]] <- int1

## concatenating
col1 <- IntegerList(one = int1, int2)
col2 <- IntegerList(two = int2, one = int1)
col3 <- IntegerList(int2)
append(col1, col2)
append(col1, col2, 0)
col123 <- c(col1, col2, col3)
col123

## revElements
revElements(col123)
revElements(col123, 4:5)

Common operations on AtomicList objects

Description

Common operations on AtomicList objects.

Seealso

• AtomicList objects.

Author

P. Aboyoun

Examples

## group generics
int1 <- c(1L,2L,3L,5L,2L,8L)
int2 <- c(15L,45L,20L,1L,15L,100L,80L,5L)
col1 <- IntegerList(one = int1, int2)
2 * col1
col1 + col1
col1 > 2
sum(col1)  # equivalent to (but faster than) 'sapply(col1, sum)'
mean(col1)  # equivalent to 'sapply(col1, mean)'

CompressedHitsList objects

Description

An efficient representation of HitsList objects. See ? for more information about HitsList objects.

Seealso

HitsList objects.

Note

This class is highly experimental. It has not been well tested and may disappear at any time.

Author

Michael Lawrence

CompressedList objects

Description

Like the SimpleList class defined in the S4Vectors package, the CompressedList class extends the List virtual class.

Details

Unlike the SimpleList class, CompressedList is virtual, that is, it cannot be instantiated. Many concrete (i.e. non-virtual) CompressedList subclasses are defined and documented in this package (e.g. CompressedIntegerList , CompressedCharacterList , CompressedRleList , etc...), as well as in other packages (e.g. GRangesList in the GenomicRanges package, GAlignmentsList in the GenomicAlignments package, etc...). It's easy for developers to extend CompressedList to create a new CompressedList subclass and there is generally very little work involved to make this new subclass fully operational.

In a CompressedList object the list elements are concatenated together in a single vector-like object. The partitioning of this single vector-like object (i.e. the information about where each original list element starts and ends) is also kept in the CompressedList object. This internal representation is generally more memory efficient than SimpleList , especially if the object has many list elements (e.g. thousands or millions). Also it makes it possible to implement many basic list operations very efficiently.

Many objects like LogicalList , IntegerList , CharacterList , RleList , etc... exist in 2 flavors: CompressedList and SimpleList . Each flavor is incarnated by a concrete subclass: CompressedLogicalList and SimpleLogicalList for virtual class LogicalList , CompressedIntegerList and SimpleIntegerList for virtual class IntegerList , etc... It's easy to switch from one representation to the other with as(x, "CompressedList") and as(x, "SimpleList") . Also the constructor function for those virtual classes have a switch that lets the user choose the representation at construction time e.g. CharacterList(..., compress=TRUE) or CharacterList(..., compress=FALSE) . See below for more information.

Seealso

• The List class defined and documented in the S4Vectors package for the parent class.

• The SimpleList class defined and documented in the S4Vectors package for an alternative to CompressedList.

• The CompressedIntegerList class for a CompressedList subclass example.

Examples

## Displaying a CompressedList object:
x <- IntegerList(11:12, integer(0), 3:-2, compress=TRUE)
class(x)

## The "Simple" prefix is removed from the real class name of the
## object:
x

## This is controlled by internal helper classNameForDisplay():
classNameForDisplay(x)

List of DataFrames

Description

Represents a list of DataFrame objects. The SplitDataFrameList class contains the additional restriction that all the columns be of the same name and type. Internally it is stored as a list of DataFrame objects and extends List .

Seealso

DataFrame

Author

Michael Lawrence

Common operations on DataFrame objects

Description

Common operations on DataFrame objects.

Seealso

DataTable and Vector

Author

Michael Lawrence

Examples

## split

sw <- DataFrame(swiss)
swsplit <- split(sw, sw[["Education"]])

## rbind

do.call(rbind, as.list(swsplit))

## cbind

cbind(DataFrame(score), DataFrame(counts))

Grouping objects

Description

We call list("grouping") an arbitrary mapping from a collection of NO objects to a collection of NG groups, or, more formally, a bipartite graph between integer sets [1, NO] and [1, NG]. Objects mapped to a given group are said to belong to, or to be assigned to, or to be in that group. Additionally, the objects in each group are ordered. So for example the 2 following groupings are considered different: list(" ", " Grouping 1: NG = 3, NO = 5 ", " group objects ", " 1 : 4, 2 ", " 2 : ", " 3 : 4 ", " ", " Grouping 2: NG = 3, NO = 5 ", " group objects ", " 1 : 2, 4 ", " 2 : ", " 3 : 4 ") There are no restriction on the mapping e.g. any object can be mapped to 0, 1, or more groups, and can be mapped twice to the same group. Also some or all the groups can be empty.

The Grouping class is a virtual class that formalizes the most general kind of grouping. More specific groupings (e.g. list("many-to-one groupings") or list("block-groupings") ) are formalized via specific Grouping subclasses.

This man page documents the core Grouping API, and 3 important Grouping subclasses: ManyToOneGrouping, GroupingRanges, and Partitioning (the last one deriving from the 2 first).

Seealso

IntegerList-class , IntegerRanges-class , IRanges-class , successiveIRanges , cumsum , diff

Author

Hervé Pagès, Michael Lawrence

Examples

showClass("Grouping")  # shows (some of) the known subclasses

## ---------------------------------------------------------------------
## A. H2LGrouping OBJECTS
## ---------------------------------------------------------------------
high2low <- c(NA, NA, 2, 2, NA, NA, NA, 6, NA, 1, 2, NA, 6, NA, NA, 2)
h2l <- H2LGrouping(high2low)
h2l

## The core Grouping API:
length(h2l)
nobj(h2l)  # same as 'length(h2l)' for H2LGrouping objects
h2l[[1]]
h2l[[2]]
h2l[[3]]
h2l[[4]]
h2l[[5]]
grouplengths(h2l)  # same as 'unname(sapply(h2l, length))'
grouplengths(h2l, 5:2)
members(h2l, 5:2)  # all the members are put together and sorted
togroup(h2l)
togroup(h2l, 5:2)
togrouplength(h2l)  # same as 'grouplengths(h2l, togroup(h2l))'
togrouplength(h2l, 5:2)

## The List API:
as.list(h2l)
sapply(h2l, length)

## ---------------------------------------------------------------------
## B. Dups OBJECTS
## ---------------------------------------------------------------------
dups1 <- as(h2l, "Dups")
dups1
duplicated(dups1)  # same as 'duplicated(togroup(dups1))'

### The purpose of a Dups object is to describe the groups of duplicated
### elements in a vector-like object:
x <- c(2, 77, 4, 4, 7, 2, 8, 8, 4, 99)
x_high2low <- high2low(x)
x_high2low  # same length as 'x'
dups2 <- Dups(x_high2low)
dups2
togroup(dups2)
duplicated(dups2)
togrouplength(dups2)  # frequency for each element
table(x)

## ---------------------------------------------------------------------
## C. Partitioning OBJECTS
## ---------------------------------------------------------------------
pbe1 <- PartitioningByEnd(c(4, 7, 7, 8, 15), names=LETTERS[1:5])
pbe1  # the 3rd partition is empty

## The core Grouping API:
length(pbe1)
nobj(pbe1)
pbe1[[1]]
pbe1[[2]]
pbe1[[3]]
grouplengths(pbe1)  # same as 'unname(sapply(pbe1, length))'
# and 'width(pbe1)'
togroup(pbe1)
togrouplength(pbe1)  # same as 'grouplengths(pbe1, togroup(pbe1))'
names(pbe1)

## The IntegerRanges core API:
start(pbe1)
end(pbe1)
width(pbe1)

## The List API:
as.list(pbe1)
sapply(pbe1, length)

## Replacing the names:
names(pbe1)[3] <- "empty partition"
pbe1

## Coercion to an IRanges object:
as(pbe1, "IRanges")

## Other examples:
PartitioningByEnd(c(0, 0, 19), names=LETTERS[1:3])
PartitioningByEnd()  # no partition
PartitioningByEnd(integer(9))  # all partitions are empty
x <- c(1L, 5L, 5L, 6L, 8L)
pbe2 <- PartitioningByEnd(x, NG=10L)
stopifnot(identical(togroup(pbe2), x))
pbw2 <- PartitioningByWidth(x, NG=10L)
stopifnot(identical(togroup(pbw2), x))

## ---------------------------------------------------------------------
## D. RELATIONSHIP BETWEEN Partitioning OBJECTS AND successiveIRanges()
## ---------------------------------------------------------------------
mywidths <- c(4, 3, 0, 1, 7)

## The 3 following calls produce the same ranges:
ir <- successiveIRanges(mywidths)  # IRanges instance.
pbe <- PartitioningByEnd(cumsum(mywidths))  # PartitioningByEnd instance.
pbw <- PartitioningByWidth(mywidths)  # PartitioningByWidth instance.
stopifnot(identical(as(ir, "PartitioningByEnd"), pbe))
stopifnot(identical(as(ir, "PartitioningByWidth"), pbw))

Examples of basic manipulation of Hits objects

Description

IMPORTANT NOTE - 4/29/2014: This man page is being refactored. Most of the things that used to be documented here have been moved to the man page for Hits objects located in the S4Vectors package.

Details

The as.data.frame method coerces a Hits object to a two column data.frame with one row for each hit, where the value in the first column is the index of an element in the query and the value in the second column is the index of an element in the subject.

Seealso

The Hits class defined and documented in the S4Vectors package.

Examples

query <- IRanges(c(1, 4, 9), c(5, 7, 10))
subject <- IRanges(c(2, 2, 10), c(2, 3, 12))
hits <- findOverlaps(query, subject)

as.matrix(hits)
as.data.frame(hits)

as.table(hits) # hits per query
as.table(t(hits)) # hits per subject

## Turn a Hits object into an IntegerList object with one list element
## per element in the original query.
as(hits, "IntegerList")
as(hits, "List")  # same as as(hits, "IntegerList")

## Turn a Hits object into a PartitioningByEnd object that describes
## the grouping of hits by query.
as(hits, "PartitioningByEnd")
as(hits, "Partitioning")  # same as as(hits, "PartitioningByEnd")

## ---------------------------------------------------------------------
## remapHits()
## ---------------------------------------------------------------------

hits2 <- remapHits(hits,
Rnodes.remapping=factor(c("e", "e", "d"), letters[1:5]))
hits2

hits3 <- remapHits(hits,
Rnodes.remapping=c(5, 5, 4), new.nRnode=5)
hits3
stopifnot(identical(hits2, hits3))

IPosRanges objects

Description

The IPosRanges virtual class is a general container for storing a vector of ranges of integer positions.

Details

An IPosRanges object is a vector-like object where each element describes a "range of integer positions".

A "range of integer values" is a finite set of consecutive integer values. Each range can be fully described with exactly 2 integer values which can be arbitrarily picked up among the 3 following values: its "start" i.e. its smallest (or first, or leftmost) value; its "end" i.e. its greatest (or last, or rightmost) value; and its "width" i.e. the number of integer values in the range. For example the set of integer values that are greater than or equal to -20 and less than or equal to 400 is the range that starts at -20 and has a width of 421. In other words, a range is a closed, one-dimensional interval with integer end points and on the domain of integers.

The starting point (or "start") of a range can be any integer (see start below) but its "width" must be a non-negative integer (see width below). The ending point (or "end") of a range is equal to its "start" plus its "width" minus one (see end below). An "empty" range is a range that contains no value i.e. a range that has a null width. Depending on the context, it can be interpreted either as just the empty set of integers or, more precisely, as the position between its "end" and its "start" (note that for an empty range, the "end" equals the "start" minus one).

The length of an IPosRanges object is the number of ranges in it, not the number of integer values in its ranges.

An IPosRanges object is considered empty iff all its ranges are empty.

IPosRanges objects have a vector-like semantic i.e. they only support single subscript subsetting (unlike, for example, standard R data frames which can be subsetted by row and by column).

The IPosRanges class itself is a virtual class. The following classes derive directly from it: IRanges , IPos , NCList , and GroupingRanges .

Seealso

• IRanges objects ( NormalIRanges objects are documented in the same man page).

• The IPos class, a memory-efficient IPosRanges derivative for representing integer positions (i.e. integer ranges of width 1).

• IPosRanges-comparison for comparing and ordering ranges.

• findOverlaps-methods for finding/counting overlapping ranges.

• intra-range-methods and inter-range-methods for intra range and inter range transformations of IntegerRanges derivatives.

• coverage-methods for computing the coverage of a set of ranges.

• setops-methods for set operations on ranges.

• nearest-methods for finding the nearest range neighbor.

Author

H. Pagès and M. Lawrence

Examples

## ---------------------------------------------------------------------
## Basic manipulation
## ---------------------------------------------------------------------
x <- IRanges(start=c(2:-1, 13:15), width=c(0:3, 2:0))
x
length(x)
start(x)
width(x)
end(x)
isEmpty(x)
as.matrix(x)
as.data.frame(x)

## Subsetting:
x[4:2]                  # 3 ranges
x[-1]                   # 6 ranges
x[FALSE]                # 0 range
x0 <- x[width(x) == 0]  # 2 ranges
isEmpty(x0)

## Use the replacement methods to resize the ranges:
width(x) <- width(x) * 2 + 1
x
end(x) <- start(x)            # equivalent to width(x) <- 0
x
width(x) <- c(2, 0, 4)
x
start(x)[3] <- end(x)[3] - 2  # resize the 3rd range
x

## Name the elements:
names(x)
names(x) <- c("range1", "range2")
x
x[is.na(names(x))]  # 5 ranges
x[!is.na(names(x))]  # 2 ranges

ir <- IRanges(c(1,5), c(3,10))
ir*1 # no change
ir*c(1,2) # zoom second range by 2X
ir*-2 # zoom out 2X

Comparing and ordering ranges

Description

Methods for comparing and/or ordering the ranges in IPosRanges derivatives (e.g. IRanges , IPos , or NCList objects).

Usage

## match() & selfmatch()
## ---------------------
list(list("match"), list("IPosRanges,IPosRanges"))(x, table, nomatch=NA_integer_, incomparables=NULL,
      method=c("auto", "quick", "hash"))
list(list("selfmatch"), list("IPosRanges"))(x, method=c("auto", "quick", "hash"))
## order() and related methods
## ----------------------------
list(list("is.unsorted"), list("IPosRanges"))(x, na.rm=FALSE, strictly=FALSE)
list(list("order"), list("IPosRanges"))(..., na.last=TRUE, decreasing=FALSE,
           method=c("auto", "shell", "radix"))
## Generalized parallel comparison of 2 IPosRanges derivatives
## -----------------------------------------------------------
list(list("pcompare"), list("IPosRanges,IPosRanges"))(x, y)
rangeComparisonCodeToLetter(code)

Arguments

Details

Two ranges of an IPosRanges derivative are considered equal iff they share the same start and width. duplicated() and unique() on an IPosRanges derivative are conforming to this.

Note that with this definition, 2 empty ranges are generally not equal (they need to share the same start to be considered equal). This means that, when it comes to comparing ranges, an empty range is interpreted as a position between its end and start. For example, a typical usecase is comparison of insertion points defined along a string (like a DNA sequence) and represented as empty ranges.

The "natural order" for the elements of an IPosRanges derivative is to order them (a) first by start and (b) then by width. This way, the space of integer ranges is totally ordered.

pcompare() , == , != , <= , >= , < and > on IPosRanges derivatives behave accordingly to this "natural order".

is.unsorted() , order() , sort() , rank() on IPosRanges derivatives also behave accordingly to this "natural order".

Finally, note that some list("inter range transformations") like reduce or disjoin also use this "natural order" implicitly when operating on IPosRanges derivatives.

list(" ", " ", list(list(), list(" ", " ", list("pcompare(x, y)"), ": ", " Performs element-wise (aka "parallel") comparison of 2 ", " ", list("IPosRanges"), " objects of ", list("x"), " and ", list("y"), ", that is, ", " returns an integer vector where the i-th element is a code describing ", " how ", list("x[i]"), " is qualitatively positioned with respect to ", list("y[i]"), ". ", " ", " Here is a summary of the 13 predefined codes (and their letter ",

"      equivalents) and their meanings:

", " ", list(" ", " -6 a: x[i]: .oooo....... 6 m: x[i]: .......oooo. ", " y[i]: .......oooo. y[i]: .oooo....... ", " ", " -5 b: x[i]: ..oooo...... 5 l: x[i]: ......oooo.. ", " y[i]: ......oooo.. y[i]: ..oooo...... ", " ", " -4 c: x[i]: ...oooo..... 4 k: x[i]: .....oooo... ", " y[i]: .....oooo... y[i]: ...oooo..... ", " ", " -3 d: x[i]: ...oooooo... 3 j: x[i]: .....oooo... ",

    "            y[i]: .....oooo...              y[i]: ...oooooo...

", " ", " -2 e: x[i]: ..oooooooo.. 2 i: x[i]: ....oooo.... ", " y[i]: ....oooo.... y[i]: ..oooooooo.. ", " ", " -1 f: x[i]: ...oooo..... 1 h: x[i]: ...oooooo... ", " y[i]: ...oooooo... y[i]: ...oooo..... ", " ", " 0 g: x[i]: ...oooooo... ", " y[i]: ...oooooo... ", " "), " ", " ", " Note that this way of comparing ranges is a refinement over the ",

"      standard ranges comparison defined by the ", list("=="), ", ", list("!="), ",

", " ", list("<="), ", ", list(">="), ", ", list("<"), " and ", list(">"), " operators. In particular ", " a code that is ", list("< 0"), ", ", list("= 0"), ", or ", list("> 0"), ", corresponds to ", " ", list("x[i] < y[i]"), ", ", list("x[i] == y[i]"), ", or ", list("x[i] > y[i]"), ", ", " respectively. ", " ", " The ", list("pcompare"), " method for ", list("IPosRanges"), " derivatives is ",

"      guaranteed to return predefined codes only but methods for other

", " objects (e.g. for ", list("GenomicRanges"), " objects) can ", " return non-predefined codes. Like for the predefined codes, the sign ", " of any non-predefined code must tell whether ", list("x[i]"), " is less than, ", " or greater than ", list("y[i]"), ". ", " ")), " ", " ", list(list(), list(" ", " ", list("rangeComparisonCodeToLetter(x)"), ": ", " Translate the codes returned by ",

list("pcompare"), ". The 13 predefined

", " codes are translated as follow: -6 -> a; -5 -> b; -4 -> c; -3 -> d; ", " -2 -> e; -1 -> f; 0 -> g; 1 -> h; 2 -> i; 3 -> j; 4 -> k; 5-> l; 6 -> m. ", " Any non-predefined code is translated to X. ", " The translated codes are returned in a factor with 14 levels: ", " a, b, ..., l, m, X. ", " ")), " ", " ", list(list(), list(" ", " ", list("match(x, table, nomatch=NAinteger, method=c("auto", "quick", "hash"))"),

":

", " Returns an integer vector of the length of ", list("x"), ", ", " containing the index of the first matching range in ", list("table"), " ", " (or ", list("nomatch"), " if there is no matching range) for each range ", " in ", list("x"), ". ", " ")), " ", " ", list(list(), list(" ", " ", list("selfmatch(x, method=c("auto", "quick", "hash"))"), ": ", " Equivalent to, but more efficient than, ", " ", list("match(x, x, method=method)"),

".

", " ")), " ", " ", list(list(), list(" ", " ", list("duplicated(x, fromLast=FALSE, method=c("auto", "quick", "hash"))"), ": ", " Determines which elements of ", list("x"), " are equal to elements ", " with smaller subscripts, and returns a logical vector indicating ", " which elements are duplicates. ", list("duplicated(x)"), " is equivalent to, ", " but more efficient than, ", list("duplicated(as.data.frame(x))"), " on an ", " ", list("IPosRanges"),

" derivative.

", " See ", list(list("duplicated")), " in the ", list("base"), " package for more ", " details. ", " ")), " ", " ", list(list(), list(" ", " ", list("unique(x, fromLast=FALSE, method=c("auto", "quick", "hash"))"), ": ", " Removes duplicate ranges from ", list("x"), ". ", list("unique(x)"), " is equivalent ", " to, but more efficient than, ", list("unique(as.data.frame(x))"), " on an ", " ", list("IPosRanges"), " derivative. ",

"      See ", list(list("unique")), " in the ", list("base"), " package for more

", " details. ", " ")), " ", " ", list(list(), list(" ", " ", list("x %in% table"), ": ", " A shortcut for finding the ranges in ", list("x"), " that match any of ", " the ranges in ", list("table"), ". Returns a logical vector of length ", " equal to the number of ranges in ", list("x"), ". ", " ")), " ", " ", list(list(), list(" ", " ", list("findMatches(x, table, method=c("auto", "quick", "hash"))"),

":

", " An enhanced version of ", list("match"), " that returns all the matches ", " in a ", list("Hits"), " object. ", " ")), " ", " ", list(list(), list(" ", " ", list("countMatches(x, table, method=c("auto", "quick", "hash"))"), ": ", " Returns an integer vector of the length of ", list("x"), " containing the ", " number of matches in ", list("table"), " for each element in ", list("x"), ". ", " ")), " ", " ", list(list(), list(" ", " ",

list("order(...)"), ":

", " Returns a permutation which rearranges its first argument (an ", " ", list("IPosRanges"), " derivative) into ascending order, breaking ties ", " by further arguments (also ", list("IPosRanges"), " derivatives). ", " ")), " ", " ", list(list(), list(" ", " ", list("sort(x)"), ": ", " Sorts ", list("x"), ". ", " See ", list(list("sort")), " in the ", list("base"), " package for more details. ", " ")), " ", " ", list(

list(), list("

", " ", list("rank(x, na.last=TRUE, ties.method=c("average", "first", "random", "max", "min"))"), ": ", " Returns the sample ranks of the ranges in ", list("x"), ". ", " See ", list(list("rank")), " in the ", list("base"), " package for more details. ", " ")), " ", " ")

Seealso

• The IPosRanges class.

• Vector-comparison in the S4Vectors package for general information about comparing, ordering, and tabulating vector-like objects.

• GenomicRanges-comparison in the GenomicRanges package for comparing and ordering genomic ranges.

• findOverlaps for finding overlapping ranges.

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

• setops-methods for set operations on IRanges objects.

Author

Hervé Pagès

Examples

## ---------------------------------------------------------------------
## A. ELEMENT-WISE (AKA "PARALLEL") COMPARISON OF 2 IPosRanges
##    DERIVATIVES
## ---------------------------------------------------------------------
x0 <- IRanges(1:11, width=4)
x0
y0 <- IRanges(6, 9)
pcompare(x0, y0)
pcompare(IRanges(4:6, width=6), y0)
pcompare(IRanges(6:8, width=2), y0)
pcompare(x0, y0) < 0   # equivalent to 'x0 < y0'
pcompare(x0, y0) == 0  # equivalent to 'x0 == y0'
pcompare(x0, y0) > 0   # equivalent to 'x0 > y0'

rangeComparisonCodeToLetter(-10:10)
rangeComparisonCodeToLetter(pcompare(x0, y0))

## Handling of zero-width ranges (a.k.a. empty ranges):
x1 <- IRanges(11:17, width=0)
x1
pcompare(x1, x1[4])
pcompare(x1, IRanges(12, 15))

## Note that x1[2] and x1[6] are empty ranges on the edge of non-empty
## range IRanges(12, 15). Even though -1 and 3 could also be considered
## valid codes for describing these configurations, pcompare()
## considers x1[2] and x1[6] to be *adjacent* to IRanges(12, 15), and
## thus returns codes -5 and 5:
pcompare(x1[2], IRanges(12, 15))  # -5
pcompare(x1[6], IRanges(12, 15))  #  5

x2 <- IRanges(start=c(20L, 8L, 20L, 22L, 25L, 20L, 22L, 22L),
width=c( 4L, 0L, 11L,  5L,  0L,  9L,  5L,  0L))
x2

which(width(x2) == 0)  # 3 empty ranges
x2[2] == x2[2]  # TRUE
x2[2] == x2[5]  # FALSE
x2 == x2[4]
x2 >= x2[3]

## ---------------------------------------------------------------------
## B. match(), selfmatch(), %in%, duplicated(), unique()
## ---------------------------------------------------------------------
table <- x2[c(2:4, 7:8)]
match(x2, table)

x2 %in% table

duplicated(x2)
unique(x2)

## ---------------------------------------------------------------------
## C. findMatches(), countMatches()
## ---------------------------------------------------------------------
findMatches(x2, table)
countMatches(x2, table)

x2_levels <- unique(x2)
countMatches(x2_levels, x2)

## ---------------------------------------------------------------------
## D. order() AND RELATED METHODS
## ---------------------------------------------------------------------
is.unsorted(x2)
order(x2)
sort(x2)
rank(x2, ties.method="first")

Memory-efficient representation of integer positions

Description

The IPos class is a container for storing a set of integer positions where most of the positions are typically (but not necessarily) adjacent. Because integer positions can be seen as integer ranges of width 1, the IPos class extends the IntegerRanges virtual class. Note that even though an IRanges object can be used for storing integer positions, using an IPos object will be much more memory-efficient, especially when the object contains long runs of adjacent positions in ascending order .

Usage

IPos(pos_runs)  # constructor function

Arguments

Value

An IPos object.

Seealso

• The GPos class in the list("GenomicRanges") package for a memory-efficient representation of list("genomic ", " positions") (i.e. genomic ranges of width 1).

• IntegerRanges and IRanges objects.

• IPosRanges-comparison for comparing and ordering integer ranges and/or positions.

• findOverlaps-methods for finding overlapping integer ranges and/or positions.

• nearest-methods for finding the nearest integer range and/or position.

Note

Like for any Vector derivative, the length of an IPos object cannot exceed .Machine$integer.max (i.e. 2^31 on most platforms). IPos() will return an error if pos_runs contains too many integer positions.

Author

Hervé Pagès; based on ideas borrowed from Georg Stricker georg.stricker@in.tum.de and Julien Gagneur gagneur@in.tum.de

Examples

## ---------------------------------------------------------------------
## BASIC EXAMPLES
## ---------------------------------------------------------------------

## Example 1:
ipos1 <- IPos(c("44-53", "5-10", "2-5"))
ipos1

length(ipos1)
pos(ipos1)  # same as 'start(ipos1)' and 'end(ipos1)'
as.character(ipos1)
as.data.frame(ipos1)
as(ipos1, "IRanges")
as.data.frame(as(ipos1, "IRanges"))
ipos1[9:17]

## Example 2:
pos_runs <- IRanges(c(1, 6, 12, 17), c(5, 10, 16, 20))
ipos2 <- IPos(pos_runs)
ipos2

## Example 3:
ipos3A <- ipos3B <- IPos(c("1-15000", "15400-88700"))
npos <- length(ipos3A)

mcols(ipos3A)$sample <- Rle("sA")
sA_counts <- sample(10, npos, replace=TRUE)
mcols(ipos3A)$counts <- sA_counts

mcols(ipos3B)$sample <- Rle("sB")
sB_counts <- sample(10, npos, replace=TRUE)
mcols(ipos3B)$counts <- sB_counts

ipos3 <- c(ipos3A, ipos3B)
ipos3

## ---------------------------------------------------------------------
## MEMORY USAGE
## ---------------------------------------------------------------------

## Coercion to IRanges works...
ipos4 <- IPos(c("1-125000", "135000-575000"))
ir4 <- as(ipos4, "IRanges")
ir4
## ... but is generally not a good idea:
object.size(ipos4)
object.size(ir4)  # 1739 times bigger than the IPos object!

## Shuffling the order of the positions impacts memory usage:
ipos4s <- sample(ipos4)
object.size(ipos4s)

## AN IMPORTANT NOTE: In the worst situations, IPos still performs as
## good as an IRanges object.
object.size(as(ipos4s, "IRanges"))  # same size as 'ipos4s'

## Best case scenario is when the object is strictly sorted (i.e.
## positions are in strict ascending order).
## This can be checked with:
is.unsorted(ipos4, strict=TRUE)  # 'ipos4' is strictly sorted

## ---------------------------------------------------------------------
## USING MEMORY-EFFICIENT METADATA COLUMNS
## ---------------------------------------------------------------------
## In order to keep memory usage as low as possible, it is recommended
## to use a memory-efficient representation of the metadata columns that
## we want to set on the object. Rle's are particularly well suited for
## this, especially if the metadata columns contain long runs of
## identical values. This is the case for example if we want to use an
## IPos object to represent the coverage of sequencing reads along a
## chromosome.

## Example 5:
library(pasillaBamSubset)
library(Rsamtools)  # for the BamFile() constructor function
bamfile1 <- BamFile(untreated1_chr4())
bamfile2 <- BamFile(untreated3_chr4())
ipos5 <- IPos(IRanges(1, seqlengths(bamfile1)[["chr4"]]))
library(GenomicAlignments)  # for "coverage" method for BamFile objects
cov1 <- coverage(bamfile1)$chr4
cov2 <- coverage(bamfile2)$chr4
mcols(ipos5) <- DataFrame(cov1, cov2)
ipos5

object.size(ipos5)  # lightweight

## Keep only the positions where coverage is at least 10 in one of the
## 2 samples:
|ipos5[mcols(ipos5)$cov1 >= 10 | mcols(ipos5)$cov2 >= 10]|

List of IRanges and NormalIRanges

Description

IRangesList and NormalIRangesList objects for storing IRanges and NormalIRanges objects respectively.

Seealso

IntegerRangesList , the parent of this class, for more functionality.

intra-range-methods and inter-range-methods for intra and inter range transformations of IRangesList objects.

setops-methods for set operations on IRangesList objects.

Author

Michael Lawrence

Examples

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))
named <- IRangesList(one = range1, two = range2)
length(named) # 2
names(named) # "one" and "two"
named[[1]] # range1
unnamed <- IRangesList(range1, range2)
names(unnamed) # NULL

x <- IRangesList(start=list(c(1,2,3), c(15,45,20,1)),
end=list(c(5,2,8), c(15,100,80,5)))
as.list(x)

IRanges and NormalIRanges objects

Description

The IRanges class is a simple implementation of the IntegerRanges container where 2 integer vectors of the same length are used to store the start and width values. See the IntegerRanges virtual class for a formal definition of IntegerRanges objects and for their methods (all of them should work for IRanges objects).

Some subclasses of the IRanges class are: NormalIRanges, Views , etc...

A NormalIRanges object is just an IRanges object that is guaranteed to be "normal". See the Normality section in the man page for IntegerRanges objects for the definition and properties of "normal" IntegerRanges objects.

Seealso

IntegerRanges-class ,

IRanges-constructor , IRanges-utils ,

intra-range-methods for intra range transformations,

inter-range-methods for inter range transformations,

setops-methods

Author

Hervé Pagès

Examples

showClass("IRanges")  # shows (some of) the known subclasses

## ---------------------------------------------------------------------
## A. MANIPULATING IRanges OBJECTS
## ---------------------------------------------------------------------
## All the methods defined for IntegerRanges objects work on IRanges
## objects.
## See ?IntegerRanges for some examples.
## Also see ?`IRanges-utils` and ?`setops-methods` for additional
## operations on IRanges objects.

## Concatenating IRanges objects
ir1 <- IRanges(c(1, 10, 20), width=5)
mcols(ir1) <- DataFrame(score=runif(3))
ir2 <- IRanges(c(101, 110, 120), width=10)
mcols(ir2) <- DataFrame(score=runif(3))
ir3 <- IRanges(c(1001, 1010, 1020), width=20)
mcols(ir3) <- DataFrame(value=runif(3))
some.iranges <- c(ir1, ir2)
## all.iranges <- c(ir1, ir2, ir3) ## This will raise an error
all.iranges <- c(ir1, ir2, ir3, ignore.mcols=TRUE)
stopifnot(is.null(mcols(all.iranges)))

## ---------------------------------------------------------------------
## B. A NOTE ABOUT PERFORMANCE
## ---------------------------------------------------------------------
## Using an IRanges object for storing a big set of ranges is more
## efficient than using a standard R data frame:
N <- 2000000L  # nb of ranges
W <- 180L      # width of each range
start <- 1L
end <- 50000000L
set.seed(777)
range_starts <- sort(sample(end-W+1L, N))
range_widths <- rep.int(W, N)
## Instantiation is faster
system.time(x <- IRanges(start=range_starts, width=range_widths))
system.time(y <- data.frame(start=range_starts, width=range_widths))
## Subsetting is faster
system.time(x16 <- x[c(TRUE, rep.int(FALSE, 15))])
system.time(y16 <- y[c(TRUE, rep.int(FALSE, 15)), ])
## Internal representation is more compact
object.size(x16)
object.size(y16)

The IRanges constructor and supporting functions

Description

The IRanges function is a constructor that can be used to create IRanges instances.

solveUserSEW0 and solveUserSEW are utility functions that solve a set of user-supplied start/end/width values.

Usage

## IRanges constructor:
IRanges(start=NULL, end=NULL, width=NULL, names=NULL)
## Supporting functions (not for the end user):
solveUserSEW0(start=NULL, end=NULL, width=NULL)
solveUserSEW(refwidths, start=NA, end=NA, width=NA,
             rep.refwidths=FALSE,
             translate.negative.coord=TRUE,
             allow.nonnarrowing=FALSE)

Arguments

Seealso

IRanges-class , narrow

Author

Hervé Pagès

Examples

## ---------------------------------------------------------------------
## A. USING THE IRanges() CONSTRUCTOR
## ---------------------------------------------------------------------
IRanges(start=11, end=rep.int(20, 5))
IRanges(start=11, width=rep.int(20, 5))
IRanges(-2, 20)  # only one range
IRanges(start=c(2, 0, NA), end=c(NA, NA, 14), width=11:0)
IRanges()  # IRanges instance of length zero
IRanges(names=character())

## With logical input:
x <- IRanges(c(FALSE, TRUE, TRUE, FALSE, TRUE))  # logical vector input
isNormal(x)  # TRUE
x <- IRanges(Rle(1:30) %% 5 <= 2)  # logical Rle input
isNormal(x)  # TRUE

## ---------------------------------------------------------------------
## B. USING solveUserSEW()
## ---------------------------------------------------------------------
refwidths <- c(5:3, 6:7)
refwidths

solveUserSEW(refwidths)
solveUserSEW(refwidths, start=4)
solveUserSEW(refwidths, end=3, width=2)
solveUserSEW(refwidths, start=-3)
solveUserSEW(refwidths, start=-3, width=2)
solveUserSEW(refwidths, end=-4)

## The start/end/width arguments are recycled:
solveUserSEW(refwidths, start=c(3, -4, NA), end=c(-2, NA))

## Using 'rep.refwidths=TRUE':
solveUserSEW(10, start=-(1:6), rep.refwidths=TRUE)
solveUserSEW(10, end=-(1:6), width=3, rep.refwidths=TRUE)

IRanges internals

Description

Objects, classes and methods defined in the IRanges package that are not intended to be used directly.

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

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

Seealso

• 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

Author

Hervé Pagès

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)

IntegerRangesList objects

Description

The IntegerRangesList virtual class is a general container for storing a list of IntegerRanges objects.

Most users are probably more interested in the IRangesList container, an IntegerRangesList derivative for storing a list of IRanges objects.

Details

The place of IntegerRangesList in the list("Vector class hierarchy") : | list(" ", " Vector ", " ^ ", " | ", " List ", " ^ ", " | ", " RangesList ", " ^ ^ ", " /
", " /
", " /
", " /
", | | " /
", " /
", " IntegerRangesList GenomicRangesList ", " ^ ^ ", " | | ", " IRangesList GRangesList ", " ^ ^ ^ ^ ", " / \ /
", " / \ /
", |

"          /           \                     /           \

", " SimpleIRangesList \ SimpleGRangesList
", " CompressedIRangesList CompressedGRangesList ", " ") Note that the list("Vector class hierarchy") has many more classes. In particular Vector , List , RangesList , and IntegerRangesList have other subclasses not shown here.

Seealso

• IRangesList objects.

• IntegerRanges and IRanges objects.

Author

M. Lawrence & H. Pagès

Examples

## ---------------------------------------------------------------------
## Basic manipulation
## ---------------------------------------------------------------------

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))
named <- IRangesList(one = range1, two = range2)
length(named) # 2
start(named) # same as start(c(range1, range2))
names(named) # "one" and "two"
named[[1]] # range1
unnamed <- IRangesList(range1, range2)
names(unnamed) # NULL

# edit the width of the ranges in the list
edited <- named
width(edited) <- rep(c(3,2), elementNROWS(named))
edited

# same as list(range1, range2)
as.list(IRangesList(range1, range2))

# coerce to data.frame
as.data.frame(named)

IRangesList(range1, range2)

## zoom in 2X
collection <- IRangesList(one = range1, range2)
collection * 2

IntegerRanges objects

Description

The IntegerRanges virtual class is a general container for storing ranges on the space of integers.

Details

TODO

List objects (old man page)

Description

IMPORTANT NOTE - 9/4/2014: This man page is being refactored. Most of the things that used to be documented here have been moved to the man page for List objects located in the S4Vectors package.

Details

The only thing left here is the documentation of the stack method for List objects. In the code snippets below, x is a List object.

list(" ", " ", list(list(), list(" ", " ", list("stack(x, index.var = "name", value.var = "value")"), ": ", " As with ", list(list("stack")), " on a ", list("list"), ", ", " constructs a ", list("DataFrame"), " with two columns: one for the ", " unlisted values, the other indicating the name of the element from ", " which each value was obtained. ", list("index.var"), " specifies the column ", " name for the index (source name) column and ", list("value.var"),

"

", " specifies the column name for the values. ", " ")), " ", " ")

Seealso

• The List class defined and documented in the S4Vectors package.

Examples

starts <- IntegerList(c(1, 5), c(2, 8))
ends <- IntegerList(c(3, 8), c(5, 9))
rgl <- IRangesList(start=starts, end=ends)
rangeDataFrame <- stack(rgl, "space", "ranges")

MaskCollection objects

Description

The MaskCollection class is a container for storing a collection of masks that can be used to mask regions in a sequence.

Details

In the context of the Biostrings package, a mask is a set of regions in a sequence that need to be excluded from some computation. For example, when calling alphabetFrequency or matchPattern on a chromosome sequence, you might want to exclude some regions like the centromere or the repeat regions. This can be achieved by putting one or several masks on the sequence before calling alphabetFrequency on it.

A MaskCollection object is a vector-like object that represents such set of masks. Like standard R vectors, it has a "length" which is the number of masks contained in it. But unlike standard R vectors, it also has a "width" which determines the length of the sequences it can be "put on". For example, a MaskCollection object of width 20000 can only be put on an XString object of 20000 letters.

Each mask in a MaskCollection object x is just a finite set of integers that are >= 1 and <= width(x) . When "put on" a sequence, these integers indicate the positions of the letters to mask. Internally, each mask is represented by a NormalIRanges object.

Seealso

NormalIRanges-class , read.Mask , MaskedXString-class , reverse , alphabetFrequency , matchPattern

Author

Hervé Pagès

Examples

## Making 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
length(mymasks)
width(mymasks)
collapse(mymasks)

## Names and descriptions:
names(mymasks) <- c("A", "B", "C")  # names should be short and unique...
mymasks
mymasks[c("C", "A")]  # ...to make subsetting by names easier
desc(mymasks) <- c("you can be", "more verbose", "here")
mymasks[-2]

## Activate/deactivate masks:
active(mymasks)["B"] <- FALSE
mymasks
collapse(mymasks)
active(mymasks) <- FALSE  # deactivate all masks
mymasks
active(mymasks)[-1] <- TRUE  # reactivate all masks except mask 1
active(mymasks) <- !active(mymasks)  # toggle all masks

## Other advanced operations:
mymasks[[2]]
length(mymasks[[2]])
mymasks[[2]][-3]
append(mymasks[-2], gaps(mymasks[2]))

Nested Containment List objects

Description

The NCList class is a container for storing the Nested Containment List representation of a IntegerRanges object. Preprocessing a IntegerRanges object as a Nested Containment List allows efficient overlap-based operations like findOverlaps .

The NCLists class is a container for storing a collection of NCList objects. An NCLists object is typically the result of preprocessing each list element of a IntegerRangesList object as a Nested Containment List. Like with NCList, the NCLists object can then be used for efficient overlap-based operations.

To preprocess a IntegerRanges or IntegerRangesList object, simply call the NCList or NCLists constructor function on it.

Usage

NCList(x, circle.length=NA_integer_)
NCLists(x, circle.length=NA_integer_)

Arguments

Details

The GenomicRanges package also defines the GNCList constructor and class for preprocessing and representing a vector of genomic ranges as a data structure based on Nested Containment Lists.

Some important differences between the new findOverlaps/countOverlaps implementation based on Nested Containment Lists (BioC >= 3.1) and the old implementation based on Interval Trees (BioC < 3.1):

• With the new implementation, the hits returned by findOverlaps are not fully ordered (i.e. ordered by queryHits and subject Hits) anymore, but only partially ordered (i.e. ordered by queryHits only). Other than that, and except for the 2 particular situations mentioned below, the 2 implementations produce the same output. However, the new implementation is faster and more memory efficient.

• With the new implementation, either the query or the subject can be preprocessed with NCList for a IntegerRanges object (replacement for IntervalTree ), NCLists for a IntegerRangesList object (replacement for IntervalForest ), and GNCList for a GenomicRanges object (replacement for GIntervalTree ). However, for a one-time use, it is NOT advised to explicitely preprocess the input. This is because findOverlaps or countOverlaps will take care of it and do a better job at it (by preprocessing only what's needed when it's needed, and releasing memory as they go).

• With the new implementation, countOverlaps on IntegerRanges or GenomicRanges objects doesn't call findOverlaps in order to collect all the hits in a growing Hits object and count them only at the end. Instead, the counting happens at the C level and the hits are not kept. This reduces memory usage considerably when there is a lot of hits.

• When minoverlap=0 , zero-width ranges are now interpreted as insertion points and considered to overlap with ranges that contain them. With the old alogrithm, zero-width ranges were always ignored. This is the 1st situation where the new and old implementations produce different outputs.

• When using select="arbitrary" , the new implementation will generally not select the same hits as the old implementation. This is the 2nd situation where the new and old implementations produce different outputs.

• The new implementation supports preprocessing of a GenomicRanges object with ranges defined on circular sequences (e.g. on the mitochnodrial chromosome). See GNCList in the GenomicRanges package for some examples.

• Objects preprocessed with NCList , NCLists , and GNCList are serializable (with save ) for later use. Not a typical thing to do though, because preprocessing is very cheap (i.e. very fast and memory efficient).

Value

An NCList object for the NCList constructor and an NCLists object for the NCLists constructor.

Seealso

• The GNCList constructor and class defined in the GenomicRanges package.

• findOverlaps for finding/counting interval overlaps between two range-based objects.

• IntegerRanges and IntegerRangesList objects.

Author

Hervé Pagès

References

Alexander V. Alekseyenko and Christopher J. Lee -- Nested Containment List (NCList): a new algorithm for accelerating interval query of genome alignment and interval databases. Bioinformatics (2007) 23 (11): 1386-1393. doi: 10.1093/bioinformatics/btl647

Examples

## The example below is for illustration purpose only and does NOT
## reflect typical usage. This is because, for a one-time use, it is
## NOT advised to explicitely preprocess the input for findOverlaps()
## or countOverlaps(). These functions will take care of it and do a
## better job at it (by preprocessing only what's needed when it's
## needed, and release memory as they go).

query <- IRanges(c(1, 4, 9), c(5, 7, 10))
subject <- IRanges(c(2, 2, 10), c(2, 3, 12))

## Either the query or the subject of findOverlaps() can be preprocessed:

ppsubject <- NCList(subject)
hits1 <- findOverlaps(query, ppsubject)
hits1

ppquery <- NCList(query)
hits2 <- findOverlaps(ppquery, subject)
hits2

## Note that 'hits1' and 'hits2' contain the same hits but not in the
## same order.
stopifnot(identical(sort(hits1), sort(hits2)))

Data on ranges

Description

IMPORTANT NOTE: RangedData objects are deprecated in BioC 3.9! The use of RangedData objects has been discouraged in favor of GRanges or GRangesList objects since BioC 2.12, that is, since 2014. The GRanges and GRangesList classes are defined in the GenomicRanges package. See ?GRanges and ?GenomicRanges (after loading the GenomicRanges package) for more information about these classes. PLEASE MIGRATE YOUR CODE TO USE GRanges OR GRangesList OBJECTS INSTEAD OF RangedData OBJECTS AS SOON AS POSSIBLE. Don't hesitate to ask on the bioc-devel mailing list ( https://bioconductor.org/help/support/#bioc-devel ) if you need help with this.

RangedData supports storing data, i.e. a set of variables, on a set of ranges spanning multiple spaces (e.g. chromosomes). Although the data is split across spaces, it can still be treated as one cohesive dataset when desired and extends DataTable .

Details

A RangedData object consists of two primary components: a IntegerRangesList holding the ranges over multiple spaces and a parallel SplitDataFrameList , holding the split data. There is also an universe slot for denoting the source (e.g. the genome) of the ranges and/or data.

There are two different modes of interacting with a RangedData . The first mode treats the object as a contiguous "data frame" annotated with range information. The accessors start , end , and width get the corresponding fields in the ranges as atomic integer vectors, undoing the division over the spaces. The [[ and matrix-style [, extraction and subsetting functions unroll the data in the same way. [[<- does the inverse. The number of rows is defined as the total number of ranges and the number of columns is the number of variables in the data. It is often convenient and natural to treat the data this way, at least when the data is small and there is no need to distinguish the ranges by their space.

The other mode is to treat the RangedData as a list, with an element (a virtual IntegerRanges / DataFrame pair) for each space. The length of the object is defined as the number of spaces and the value returned by the names accessor gives the names of the spaces. The list-style [ subset function behaves analogously.

Seealso

DataTable , the parent of this class, with more utilities.

Author

Michael Lawrence

Examples

ranges <- IRanges(c(1,2,3),c(4,5,6))
filter <- c(1L, 0L, 1L)
score <- c(10L, 2L, NA)

## constructing RangedData instances

## no variables
rd <- RangedData()
rd <- RangedData(ranges)
ranges(rd)
## one variable
rd <- RangedData(ranges, score)
rd[["score"]]
## multiple variables
rd <- RangedData(ranges, filter, vals = score)
rd[["vals"]] # same as rd[["score"]] above
rd$vals
rd[["filter"]]
rd <- RangedData(ranges, score + score)
rd[["score...score"]] # names made valid

## split some data over chromosomes

range2 <- IRanges(start=c(15,45,20,1), end=c(15,100,80,5))
both <- c(ranges, range2)
score <- c(score, c(0L, 3L, NA, 22L))
filter <- c(filter, c(0L, 1L, NA, 0L))
chrom <- paste("chr", rep(c(1,2), c(length(ranges), length(range2))), sep="")

rd <- RangedData(both, score, filter, space = chrom)
rd[["score"]] # identical to score
rd[1][["score"]] # identical to score[1:3]

## subsetting

## list style: [i]

rd[numeric()] # these three are all empty
rd[logical()]
rd[NULL]
rd[] # missing, full instance returned
rd[FALSE] # logical, supports recycling
rd[c(FALSE, FALSE)] # same as above
rd[TRUE] # like rd[]
rd[c(TRUE, FALSE)]
rd[1] # numeric index
rd[c(1,2)]
rd[-2]

## matrix style: [i,j]

rd[,NULL] # no columns
rd[NULL,] # no rows
rd[,1]
rd[,1:2]
rd[,"filter"]
rd[1,] # now by the rows
rd[c(1,3),]
rd[1:2, 1] # row and column
rd[c(1:2,1,3),1] ## repeating rows

## dimnames

colnames(rd)[2] <- "foo"
colnames(rd)
rownames(rd) <- head(letters, nrow(rd))
rownames(rd)

## space names

names(rd)
names(rd)[1] <- "chr1"

## variable replacement

count <- c(1L, 0L, 2L)
rd <- RangedData(ranges, count, space = c(1, 2, 1))
## adding a variable
score <- c(10L, 2L, NA)
rd[["score"]] <- score
rd[["score"]] # same as 'score'
## replacing a variable
count2 <- c(1L, 1L, 0L)
rd[["count"]] <- count2
## numeric index also supported
rd[[2]] <- score
rd[[2]] # gets 'score'
## removing a variable
rd[[2]] <- NULL
ncol(rd) # is only 1
rd$score2 <- score

## combining

rd <- RangedData(ranges, score, space = c(1, 2, 1))
c(rd[1], rd[2]) # equal to 'rd'
rd2 <- RangedData(ranges, score)

Selection of ranges and columns

Description

A RangedSelection represents a query against a table of interval data in terms of ranges and column names. The ranges select any table row with an overlapping interval. Note that the intervals are always returned, even if no columns are selected.

Details

Traditionally, tabular data structures have supported the subset function, which allows one to select a subset of the rows and columns from the table. In that case, the rows and columns are specified by two separate arguments. As querying interval data sources, especially those external to R, such as binary indexed files and databases, is increasingly common, there is a need to encapsulate the row and column specifications into a single data structure, mostly for the sake of interface cleanliness. The RangedSelection class fills that role.

Author

Michael Lawrence

Examples

rl <- IRangesList(chr1 = IRanges(c(1, 5), c(3, 6)))

RangedSelection(rl)
as(rl, "RangedSelection") # same as above

RangedSelection(rl, "score")

List of RleViews

Description

An extension of ViewsList that holds only RleViews objects. Useful for storing coverage vectors over a set of spaces (e.g. chromosomes), each of which requires a separate RleViews object.

Details

For more information on methods available for RleViewsList objects consult the man pages for ViewsList-class and view-summarization-methods .

Seealso

ViewsList-class , view-summarization-methods

Author

P. Aboyoun

Examples

## Rle objects
subject1 <- Rle(c(3L,2L,18L,0L), c(3,2,1,5))
set.seed(0)
subject2 <- Rle(c(0L,5L,2L,0L,3L), c(8,5,2,7,4))

## Views
rleViews1 <- Views(subject1, 3:0, 5:8)
rleViews2 <- Views(subject2, subject2 > 0)

## RleList and IntegerRangesList objects
rleList <- RleList(subject1, subject2)
rangesList <- IRangesList(IRanges(3:0, 5:8), IRanges(subject2 > 0))

## methods for construction
method1 <- RleViewsList(rleViews1, rleViews2)
method2 <- RleViewsList(rleList = rleList, rangesList = rangesList)
identical(method1, method2)

## calculation over the views
viewSums(method1)

The RleViews class

Description

The RleViews class is the basic container for storing a set of views (start/end locations) on the same Rle object.

Details

An RleViews object contains a set of views (start/end locations) on the same Rle object called "the subject vector" or simply "the subject". Each view is defined by its start and end locations: both are integers such that start <= end. An RleViews object is in fact a particular case of a Views object (the RleViews class contains the Views class) so it can be manipulated in a similar manner: see ? for more information. Note that two views can overlap and that a view can be "out of limits" i.e. it can start before the first element of the subject or/and end after its last element.

Seealso

Views-class , Rle-class , view-summarization-methods

Author

P. Aboyoun

Examples

subject <- Rle(rep(c(3L, 2L, 18L, 0L), c(3,2,1,5)))
myViews <- Views(subject, 3:0, 5:8)
myViews
subject(myViews)
length(myViews)
start(myViews)
end(myViews)
width(myViews)
myViews[[2]]

set.seed(0)
vec <- Rle(sample(0:2, 20, replace = TRUE))
vec
Views(vec, vec > 0)

Rle objects (old man page)

Description

IMPORTANT NOTE - 7/3/2014: This man page is being refactored. Most of the things that used to be documented here have been moved to the man page for Rle objects located in the S4Vectors package.

Seealso

The Rle class defined and documented in the S4Vectors package.

Examples

x <- Rle(10:1, 1:10)
x

Vector objects (old man page)

Description

IMPORTANT NOTE - 4/29/2014: This man page is being refactored. Most of the things that used to be documented here have been moved to the man page for Vector objects located in the S4Vectors package.

Seealso

The Vector class defined and documented in the S4Vectors package.

List of Views

Description

An extension of List that holds only Views objects.

Details

ViewsList is a virtual class. Specialized subclasses like e.g. RleViewsList are useful for storing coverage vectors over a set of spaces (e.g. chromosomes), each of which requires a separate RleViews object.

As a List subclass, ViewsList inherits all the methods available for List objects. It also presents an API that is very similar to that of Views , where operations are vectorized over the elements and generally return lists.

Seealso

List-class , RleViewsList-class .

findOverlaps .

Author

P. Aboyoun and H. Pagès

Examples

showClass("ViewsList")

Views objects

Description

The Views virtual class is a general container for storing a set of views on an arbitrary Vector object, called the "subject".

Its primary purpose is to introduce concepts and provide some facilities that can be shared by the concrete classes that derive from it.

Some direct subclasses of the Views class are: RleViews , XIntegerViews (defined in the XVector package), XStringViews (defined in the Biostrings package), etc...

Seealso

IRanges-class , Vector-class , IRanges-utils , XVector .

Some direct subclasses of the Views class: RleViews-class , XIntegerViews-class , XDoubleViews-class , XStringViews-class .

findOverlaps .

Author

Hervé Pagès

Examples

showClass("Views")  # shows (some of) the known subclasses

## Create a set of 4 views on an XInteger subject of length 10:
subject <- Rle(3:-6)
v1 <- Views(subject, start=4:1, end=4:7)

## Extract the 2nd view:
v1[[2]]

## Some views can be "out of limits"
v2 <- Views(subject, start=4:-1, end=6)
trim(v2)
subviews(v2, end=-2)

## See ?`XIntegerViews-class` in the XVector package for more examples.

Coverage of a set of ranges

Description

For each position in the space underlying a set of ranges, counts the number of ranges that cover it.

Usage

coverage(x, shift=0L, width=NULL, weight=1L, ...)
list(list("coverage"), list("IntegerRanges"))(x, shift=0L, width=NULL, weight=1L,
            method=c("auto", "sort", "hash"))
list(list("coverage"), list("IntegerRangesList"))(x, shift=0L, width=NULL, weight=1L,
            method=c("auto", "sort", "hash"))

Arguments

• If x is an IntegerRanges or Views object: each of these arguments must be an integer or numeric vector parallel to x (will get recycled if necessary). Alternatively, each of these arguments can also be specified as a single string naming a metadata column in x (i.e. a column in mcols(x) ) to be used as the shift (or weight ) vector. Note that when x is an IPos object, each of these arguments can only be a single number.

• If x is an IntegerRangesList object: each of these arguments must be a numeric vector or list-like object of the same length as x (will get recycled if necessary). If it's a numeric vector, it's first turned into a list with as.list . After recycling, each list element shift[[i]] (or weight[[i]] ) must be an integer or numeric vector parallel to x[[i]] (will get recycled if necessary). If weight is an integer vector or list-like object of integer vectors, the coverage vector(s) will be returned as integer- Rle object(s). If it's a numeric vector or list-like object of numeric vectors, the coverage vector(s) will be returned as numeric- Rle object(s). |width | Specifies the length of the returned coverage vector(s). |

• If x is an IntegerRanges object: width must be NULL (the default), an NA, or a single non-negative integer. After being shifted, the ranges in x are always clipped on the left to keep only their positive portion i.e. their intersection with the [1, +inf) interval. If width is a single non-negative integer, then they're also clipped on the right to keep only their intersection with the [1, width] interval. In that case coverage returns a vector of length width . Otherwise, it returns a vector that extends to the last position in the underlying space covered by the shifted ranges.

• If x is a Views object: Same as for a IntegerRanges object, except that, if width is NULL then it's treated as if it was length(subject(x)) .

• If x is a IntegerRangesList object: width must be NULL or an integer vector parallel to x (i.e. with one element per list element in x ). If not NULL , the vector must contain NAs or non-negative integers and it will get recycled to the length of x if necessary. If NULL , it is replaced with NA and recycled to the length of x . Finally width[i] is used to compute the coverage vector for x[[i]] and is therefore treated like explained above (when x is a IntegerRanges object).
  |method | If method is set to "sort" , then x is sorted previous to the calculation of the coverage. If method is set to hash , then x is hashed directly to a vector of length width without previous sorting. The "hash" method is faster than the "sort" method when x is large (i.e. contains a lot of ranges). When x is small and width is big (e.g. x represents a small set of reads aligned to a big chromosome), then method="sort" is faster and uses less memory than method="hash" . Using method="auto" selects the best method based on length(x) and width . | |... | Further arguments to be passed to or from other methods. |

Value

If x is a IntegerRanges or Views object: An integer- or numeric- Rle object depending on whether weight is an integer or numeric vector.

If x is a IntegerRangesList object: An RleList object with one coverage vector per list element in x , and with x names propagated to it. The i-th coverage vector can be either an integer- or numeric- Rle object, depending on the type of weight[[i]] (after weight has gone thru as.list and recycling, like described previously).

Seealso

• coverage-methods in the GenomicRanges package for more coverage methods.

• The slice function for slicing the Rle or RleList object returned by coverage .

• IntegerRanges , IPos , IntegerRangesList , Rle , and RleList objects.

Author

H. Pagès and P. Aboyoun

Examples

## ---------------------------------------------------------------------
## A. COVERAGE OF AN IRanges OBJECT
## ---------------------------------------------------------------------
x <- IRanges(start=c(-2L, 6L, 9L, -4L, 1L, 0L, -6L, 10L),
width=c( 5L, 0L, 6L,  1L, 4L, 3L,  2L,  3L))
coverage(x)
coverage(x, shift=7)
coverage(x, shift=7, width=27)
coverage(x, shift=c(-4, 2))  # 'shift' gets recycled
coverage(x, shift=c(-4, 2), width=12)
coverage(x, shift=-max(end(x)))

coverage(restrict(x, 1, 10))
coverage(reduce(x), shift=7)
coverage(gaps(shift(x, 7), start=1, end=27))

## With weights:
coverage(x, weight=as.integer(10^(0:7)))  # integer-Rle
coverage(x, weight=c(2.8, -10))  # numeric-Rle, 'shift' gets recycled

## ---------------------------------------------------------------------
## B. COVERAGE OF AN IPos OBJECT
## ---------------------------------------------------------------------
pos_runs <- IRanges(c(1, 5, 9), c(10, 8, 15))
ipos <- IPos(pos_runs)
coverage(ipos)

## ---------------------------------------------------------------------
## C. COVERAGE OF AN IRangesList OBJECT
## ---------------------------------------------------------------------
x <- IRangesList(A=IRanges(3*(4:-1), width=1:3), B=IRanges(2:10, width=5))
cvg <- coverage(x)
cvg

stopifnot(identical(cvg[[1]], coverage(x[[1]])))
stopifnot(identical(cvg[[2]], coverage(x[[2]])))

coverage(x, width=c(50, 9))
coverage(x, width=c(NA, 9))
coverage(x, width=9)  # 'width' gets recycled

## Each list element in 'shift' and 'weight' gets recycled to the length
## of the corresponding element in 'x'.
weight <- list(as.integer(10^(0:5)), -0.77)
cvg2 <- coverage(x, weight=weight)
cvg2  # 1st coverage vector is an integer-Rle, 2nd is a numeric-Rle

identical(mapply(coverage, x=x, weight=weight), as.list(cvg2))

## ---------------------------------------------------------------------
## D. SOME MATHEMATICAL PROPERTIES OF THE coverage() FUNCTION
## ---------------------------------------------------------------------

## PROPERTY 1: The coverage vector is not affected by reordering the
## input ranges:
set.seed(24)
x <- IRanges(sample(1000, 40, replace=TRUE), width=17:10)
cvg0 <- coverage(x)
stopifnot(identical(coverage(sample(x)), cvg0))

## Of course, if the ranges are shifted and/or assigned weights, then
## this doesn't hold anymore, unless the 'shift' and/or 'weight'
## arguments are reordered accordingly.

## PROPERTY 2: The coverage of the concatenation of 2 IntegerRanges
## objects 'x' and 'y' is the sum of the 2 individual coverage vectors:
y <- IRanges(sample(-20:280, 36, replace=TRUE), width=28)
stopifnot(identical(coverage(c(x, y), width=100),
coverage(x, width=100) + coverage(y, width=100)))

## Note that, because adding 2 vectors in R recycles the shortest to
## the length of the longest, the following is generally FALSE:
identical(coverage(c(x, y)), coverage(x) + coverage(y))  # FALSE

## It would only be TRUE if the 2 coverage vectors that we add had the
## same length, which would only happen by chance. By using the same
## 'width' value when we computed the 2 coverages previously, we made
## sure they had the same length.

## Because of properties 1 & 2, we have:
x1 <- x[c(TRUE, FALSE)]  # pick up 1st, 3rd, 5th, etc... ranges
x2 <- x[c(FALSE, TRUE)]  # pick up 2nd, 4th, 6th, etc... ranges
cvg1 <- coverage(x1, width=100)
cvg2 <- coverage(x2, width=100)
stopifnot(identical(coverage(x, width=100), cvg1 + cvg2))

## PROPERTY 3: Multiplying the weights by a scalar has the effect of
## multiplying the coverage vector by the same scalar:
weight <- runif(40)
cvg3 <- coverage(x, weight=weight)
stopifnot(all.equal(coverage(x, weight=-2.68 * weight), -2.68 * cvg3))

## Because of properties 1 & 2 & 3, we have:
stopifnot(identical(coverage(x, width=100, weight=c(5L, -11L)),
5L * cvg1 - 11L * cvg2))

## PROPERTY 4: Using the sum of 2 weight vectors produces the same
## result as using the 2 weight vectors separately and summing the
## 2 results:
weight2 <- 10 * runif(40) + 3.7
stopifnot(all.equal(coverage(x, weight=weight + weight2),
cvg3 + coverage(x, weight=weight2)))

## PROPERTY 5: Repeating any input range N number of times is
## equivalent to multiplying its assigned weight by N:
times <- sample(0:10L, length(x), replace=TRUE)
stopifnot(all.equal(coverage(rep(x, times), weight=rep(weight, times)),
coverage(x, weight=weight * times)))

## In particular, if 'weight' is not supplied:
stopifnot(identical(coverage(rep(x, times)), coverage(x, weight=times)))

## PROPERTY 6: If none of the input range actually gets clipped during
## the "shift and clip" process, then:
##
##     sum(cvg) = sum(width(x) * weight)
##
stopifnot(sum(cvg3) == sum(width(x) * weight))

## In particular, if 'weight' is not supplied:
stopifnot(sum(cvg0) == sum(width(x)))

## Note that this property is sometimes used in the context of a
## ChIP-Seq analysis to estimate "the number of reads in a peak", that
## is, the number of short reads that belong to a peak in the coverage
## vector computed from the genomic locations (a.k.a. genomic ranges)
## of the aligned reads. Because of property 6, the number of reads in
## a peak is approximately the area under the peak divided by the short
## read length.

## PROPERTY 7: If 'weight' is not supplied, then disjoining or reducing
## the ranges before calling coverage() has the effect of "shaving" the
## coverage vector at elevation 1:
table(cvg0)
shaved_cvg0 <- cvg0
runValue(shaved_cvg0) <- pmin(runValue(cvg0), 1L)
table(shaved_cvg0)

stopifnot(identical(coverage(disjoin(x)), shaved_cvg0))
stopifnot(identical(coverage(reduce(x)), shaved_cvg0))

## ---------------------------------------------------------------------
## E. SOME SANITY CHECKS
## ---------------------------------------------------------------------
dummy_coverage <- function(x, shift=0L, width=NULL)
{
y <- IRanges:::unlist_as_integer(shift(x, shift))
if (is.null(width))
width <- max(c(0L, y))
Rle(tabulate(y,  nbins=width))
}

check_real_vs_dummy <- function(x, shift=0L, width=NULL)
{
res1 <- coverage(x, shift=shift, width=width)
res2 <- dummy_coverage(x, shift=shift, width=width)
stopifnot(identical(res1, res2))
}
check_real_vs_dummy(x)
check_real_vs_dummy(x, shift=7)
check_real_vs_dummy(x, shift=7, width=27)
check_real_vs_dummy(x, shift=c(-4, 2))
check_real_vs_dummy(x, shift=c(-4, 2), width=12)
check_real_vs_dummy(x, shift=-max(end(x)))

## With a set of distinct single positions:
x3 <- IRanges(sample(50000, 20000), width=1)
stopifnot(identical(sort(start(x3)), which(coverage(x3) != 0L)))

Group elements of a vector-like object into a list-like object

Description

relist and split are 2 common ways of grouping the elements of a vector-like object into a list-like object. The IRanges and S4Vectors packages define relist and split methods that operate on a Vector object and return a List object. Note that the split methods defined in S4Vectors delegate to the splitAsList function defined in IRanges and documented below.

Because relist and split both impose restrictions on the kind of grouping that they support (e.g. every element in the input object needs to go in a group and can only go in one group), the IRanges package introduces the extractList generic function for performing arbitrary groupings.

Usage

## relist()
## --------
list(list("relist"), list("ANY,List"))(flesh, skeleton)
list(list("relist"), list("Vector,list"))(flesh, skeleton)
## splitAsList()
## -------------
splitAsList(x, f, drop=FALSE, ...)
## extractList()
## -------------
extractList(x, i)
## regroup()
## ---------
regroup(x, g)

Arguments

Details

relist , split , and extractList have in common that they return a list-like object where each list element has the same class as the original vector-like object. Thus they need to be able to select the appropriate List concrete subclass to use for this returned value. This selection is performed by relistToClass and is based only on the class of the original object.

By default, extractList(x, i) is equivalent to: list(" relist(x[unlist(i)], i) ") An exception is made when x is a data-frame-like object. In that case x is subsetted along the rows, that is, extractList(x, i) is equivalent to: list(" relist(x[unlist(i), ], i) ") This is more or less how the default method is implemented, except for some optimizations when i is a IntegerRanges object.

relist and split (or splitAsList ) can be seen as special cases of extractList : list(" relist(flesh, skeleton) is equivalent to ", " extractList(flesh, PartitioningByEnd(skeleton)) ", " ", " split(x, f) is equivalent to ", " extractList(x, split(seq_along(f), f)) ") It is good practise to use extractList only for cases not covered by relist or split . Whenever possible, using relist or split is preferred as they will always perform more efficiently. In addition their names carry meaning and are familiar to most R users/developers so they'll make your code easier to read/understand.

Note that the transformation performed by relist or split is always reversible (via unlist and unsplit , respectively), but not the transformation performed by extractList (in general).

The regroup function splits the elements of unlist(x) into a list according to the grouping g . Each element of unlist(x) inherits its group from its parent element of x . regroup is different from relist and split , because x is already grouped, and the goal is to combine groups.

Value

The relist methods behave like utils::relist except that they return a List object. If skeleton has names, then they are propagated to the returned value.

splitAsList behaves like base::split except that the former returns a List object instead of an ordinary list.

extractList returns a list-like object parallel to i and with the same "shape" as i (i.e. same element lengths). If i has names, then they are propagated to the returned value.

All these functions return a list-like object where the list elements have the same class as x . relistToClass gives the exact class of the returned object.

Seealso

• The unlist and relist functions in the base and utils packages, respectively.

• The split and unsplit functions in the base package.

• The split methods defined in the S4Vectors package.

• Vector , List , Rle , and DataFrame objects in the S4Vectors package. relistToClass is documented in the man page for List objects.

• IntegerRanges objects.

Author

Hervé Pagès

Examples

## On an Rle object:
x <- Rle(101:105, 6:2)
i <- IRanges(6:10, 16:12, names=letters[1:5])
extractList(x, i)

## On a DataFrame object:
df <- DataFrame(X=x, Y=LETTERS[1:20])
extractList(df, i)

Extract list fragments from a list-like object

Description

Utilities for extracting list fragments from a list-like object.

Usage

extractListFragments(x, aranges, use.mcols=FALSE,
                     msg.if.incompatible=INCOMPATIBLE_ARANGES_MSG)
equisplit(x, nchunk, chunksize, use.mcols=FALSE)

Arguments

Details

A list fragment of list-like object x is a window in one of its list elements.

extractListFragments is a low-level utility that extracts list fragments from list-like object x according to the absolute ranges in aranges .

equisplit fragments and splits list-like object x into a specified number of partitions with equal (total) width. This is useful for instance to ensure balanced loading of workers in parallel evaluation. For example, if x is a GRanges object, each partition is also a GRanges object and the set of all partitions is returned as a GRangesList object.

Value

An object of the same class as x for extractListFragments .

An object of class relistToClass for equisplit .

Seealso

• IRanges and IRangesList objects.

• Partitioning objects.

• IntegerList objects.

• breakInChunks from breaking a vector-like object in chunks.

• GRanges and GRangesList objects defined in the GenomicRanges package.

• List objects defined in the S4Vectors package.

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

Author

Hervé Pagès

Examples

## ---------------------------------------------------------------------
## A. extractListFragments()
## ---------------------------------------------------------------------

x <- IntegerList(a=101:109, b=5:-5)
x

aranges <- IRanges(start=c(2, 4, 8, 17, 17), end=c(3, 6, 14, 16, 19))
aranges
extractListFragments(x, aranges)

x2 <- IRanges(c(1, 101, 1001, 10001), width=c(10, 5, 0, 12),
names=letters[1:4])
mcols(x2)$label <- LETTERS[1:4]
x2

aranges <- IRanges(start=13, end=20)
extractListFragments(x2, aranges)
extractListFragments(x2, aranges, use.mcols=TRUE)

aranges2 <- PartitioningByWidth(c(3, 9, 13, 0, 2))
extractListFragments(x2, aranges2)
extractListFragments(x2, aranges2, use.mcols=TRUE)

x2b <- as(x2, "IntegerList")
extractListFragments(x2b, aranges2)

x2c <- as.list(x2b)
extractListFragments(x2c, aranges2, use.mcols=TRUE)

## ---------------------------------------------------------------------
## B. equisplit()
## ---------------------------------------------------------------------

## equisplit() first calls breakInChunks() internally to create a
## PartitioningByWidth object that contains the absolute ranges of the
## chunks, then calls extractListFragments() on it 'x' to extract the
## fragments of 'x' that correspond to these absolute ranges. Finally
## the IRanges object returned by extractListFragments() is split into
## an IRangesList object where each list element corresponds to a chunk.
equisplit(x2, nchunk=2)
equisplit(x2, nchunk=2, use.mcols=TRUE)

equisplit(x2, chunksize=5)

library(GenomicRanges)
gr <- GRanges(c("chr1", "chr2"), IRanges(1, c(100, 1e5)))
equisplit(gr, nchunk=2)
equisplit(gr, nchunk=1000)

## ---------------------------------------------------------------------
## C. ADVANCED extractListFragments() EXAMPLES
## ---------------------------------------------------------------------

## === D1. Fragment list-like object into length 1 fragments ===

## First we construct a Partitioning object where all the partitions
## have a width of 1:
x2_cumlen <- nobj(PartitioningByWidth(x2))  # Equivalent to
# length(unlist(x2)) except
# that it doesn't unlist 'x2'
# so is much more efficient.
aranges1 <- PartitioningByEnd(seq_len(x2_cumlen))
aranges1

## Then we use it to fragment 'x2':
extractListFragments(x2, aranges1)
extractListFragments(x2b, aranges1)
extractListFragments(x2c, aranges1, use.mcols=TRUE)

## === D2. Fragment a Partitioning object ===

partitioning2 <- PartitioningByEnd(x2b)  # same as PartitioningByEnd(x2)
extractListFragments(partitioning2, aranges2)

## Note that when the 1st arg is a Partitioning derivative, then
## swapping the 1st and 2nd elements in the call to extractListFragments()
## doesn't change the returned partitioning:
extractListFragments(aranges2, partitioning2)

## ---------------------------------------------------------------------
## D. SANITY CHECKS
## ---------------------------------------------------------------------

## If 'aranges' is 'PartitioningByEnd(x)' or 'PartitioningByWidth(x)'
## and 'x' has no zero-length list elements, then
## 'extractListFragments(x, aranges, use.mcols=TRUE)' is a no-op.
check_no_ops <- function(x) {
aranges <- PartitioningByEnd(x)
stopifnot(identical(
extractListFragments(x, aranges, use.mcols=TRUE), x
))
aranges <- PartitioningByWidth(x)
stopifnot(identical(
extractListFragments(x, aranges, use.mcols=TRUE), x
))
}

check_no_ops(x2[lengths(x2) != 0])
check_no_ops(x2b[lengths(x2b) != 0])
check_no_ops(x2c[lengths(x2c) != 0])
check_no_ops(gr)

Finding overlapping ranges

Description

Various methods for finding/counting interval overlaps between two "range-based" objects: a query and a subject.

NOTE: This man page describes the methods that operate on IntegerRanges and IntegerRangesList derivatives. See ?`` in the GenomicRanges package for methods that operate on [GenomicRanges](#genomicranges) or [GRangesList](#grangeslist) objects. ## Usage ```r findOverlaps(query, subject, maxgap=-1L, minoverlap=0L, type=c("any", "start", "end", "within", "equal"), select=c("all", "first", "last", "arbitrary"), ...) countOverlaps(query, subject, maxgap=-1L, minoverlap=0L, type=c("any", "start", "end", "within", "equal"), ...) overlapsAny(query, subject, maxgap=-1L, minoverlap=0L, type=c("any", "start", "end", "within", "equal"), ...) query %over% subject query %within% subject query %outside% subject subsetByOverlaps(x, ranges, maxgap=-1L, minoverlap=0L, type=c("any", "start", "end", "within", "equal"), invert=FALSE, ...) overlapsRanges(query, subject, hits=NULL, ...) poverlaps(query, subject, maxgap = 0L, minoverlap = 1L, type = c("any", "start", "end", "within", "equal"), ...) mergeByOverlaps(query, subject, ...) findOverlapPairs(query, subject, ...) ``` ## Arguments |Argument |Description| |------------- |----------------| |query, subject, x, ranges| Each of them can be an [IntegerRanges](#integerranges) (e.g. [IRanges](#iranges) , [Views](#views) ) or [IntegerRangesList](#integerrangeslist) (e.g. [IRangesList](#irangeslist) , [ViewsList](#viewslist) ) derivative. In addition, ifsubjectorrangesis an [IntegerRanges](#integerranges) object,queryorxcan be an integer vector to be converted to length-one ranges. Ifquery(orx) is an [IntegerRangesList](#integerrangeslist) object, thensubject(orranges) must also be an [IntegerRangesList](#integerrangeslist) object. If both arguments are list-like objects with names, each list element from the 2nd argument is paired with the list element from the 1st argument with the matching name, if any. Otherwise, list elements are paired by position. The overlap is then computed between the pairs as described below. Ifsubjectis omitted,queryis queried against itself. In this case, and only this case, thedrop.selfanddrop.redundantarguments are allowed. By default, the result will contain hits for each range against itself, and if there is a hit from A to B, there is also a hit for B to A. Ifdrop.selfisTRUE, all self matches are dropped. Ifdrop.redundantisTRUE, only one of A->B and B->A is returned. | |maxgap| A single integer >= -1. Iftypeis set to"any",maxgapis interpreted as the maximum gap that is allowed between 2 ranges for the ranges to be considered as overlapping. The gap between 2 ranges is the number of positions that separate them. The gap between 2 adjacent ranges is 0. By convention when one range has its start or end strictly inside the other (i.e. non-disjoint ranges), the gap is considered to be -1. Iftypeis set to anything else,maxgaphas a special meaning that depends on the particulartype. Seetypebelow for more information. | |minoverlap| A single non-negative integer. Only ranges with a minimum ofminoverlapoverlapping positions are considered to be overlapping. Whentypeis"any", at least one ofmaxgapandminoverlapmust be set to its default value. | |type| By default, any overlap is accepted. By specifying thetypeparameter, one can select for specific types of overlap. The types correspond to operations in Allen's Interval Algebra (see references). Iftypeisstartorend, the intervals are required to have matching starts or ends, respectively. Specifyingequalas the type returns the intersection of thestartandendmatches. Iftypeiswithin, the query interval must be wholly contained within the subject interval. Note that all matches must additionally satisfy theminoverlapconstraint described above. Themaxgapparameter has special meaning with the special overlap types. Forstart,end, andequal, it specifies the maximum difference in the starts, ends or both, respectively. Forwithin, it is the maximum amount by which the subject may be wider than the query. Ifmaxgapis set to -1 (the default), it's replaced internally by 0. | |select| Ifqueryis an [IntegerRanges](#integerranges) derivative: Whenselectis"all"(the default), the results are returned as a [Hits](#hits) object. Otherwise the returned value is an integer vector parallel toquery(i.e. same length) containing the first, last, or arbitrary overlapping interval insubject, withNAindicating intervals that did not overlap any intervals insubject. Ifqueryis an [IntegerRangesList](#integerrangeslist) derivative: Whenselectis"all"(the default), the results are returned as a [HitsList](#hitslist) object. Otherwise the returned value depends on thedropargument. Whenselect != "all" && !drop, an [IntegerList](#integerlist) is returned, where each element of the result corresponds to a space inquery. Whenselect != "all" && drop, an integer vector is returned containing indices that are offset to align with the unlistedquery. | |invert| IfTRUE, keep only the ranges inxthat do not overlapranges. | |hits| The [Hits](#hits) or [HitsList](#hitslist) object returned byfindOverlaps, orNULL. IfNULLthenhitsis computed by callingfindOverlaps(query, subject, ...)internally (the extra arguments passed tooverlapsRangesare passed tofindOverlaps). | |...| Further arguments to be passed to or from other methods: | *drop: Supported only whenqueryis an [IntegerRangesList](#integerrangeslist) derivative.FALSEby default. Seeselectargument above for the details. *drop.self,drop.redundant: Whensubjectis omitted, thedrop.selfanddrop.redundantarguments (bothFALSEby default) are allowed. Seequeryandsubjectarguments above for the details. ## Details A common type of query that arises when working with intervals is finding which intervals in one set overlap those in another. The simplest approach is to call thefindOverlapsfunction on a [IntegerRanges](#integerranges) or other object with range information (aka "range-based object"). ## Value ForfindOverlaps: seeselectargument above. ForcountOverlaps: the overlap hit count for each range inqueryusing the specifiedfindOverlapsparameters. For [IntegerRangesList](#integerrangeslist) objects, it returns an [IntegerList](#integerlist) object.overlapsAnyfinds the ranges inquerythat overlap any of the ranges insubject. For [IntegerRanges](#integerranges) derivatives, it returns a logical vector of length equal to the number of ranges inquery. For [IntegerRangesList](#integerrangeslist) derivatives, it returns a [LogicalList](#logicallist) object where each element of the result corresponds to a space inquery.%over%and%within%are convenience wrappers for the 2 most common use cases. Currently defined as ``%over% <- function(query, subject) overlapsAny(query, subject)and ``%within% <- function(query, subject).%outside%is simply the inverse of%over%.subsetByOverlapsreturns the subset ofxthat has an overlap hit with a range inrangesusing the specifiedfindOverlapsparameters. Whenhitsis a [Hits](#hits) (or [HitsList](#hitslist) ) object,overlapsRanges(query, subject, hits)returns a [IntegerRanges](#integerranges) (or [IntegerRangesList](#integerrangeslist) ) object of the list("same ", " shape") ashitsholding the regions of intersection between the overlapping ranges in objectsqueryandsubject, which should be the same query and subject used in the call tofindOverlapsthat generatedhits. list("Same shape") means same length whenhitsis a [Hits](#hits) object, and same length and same elementNROWS whenhitsis a [HitsList](#hitslist) object.poverlapscomparesqueryandsubjectin parallel (like e.g.,pmin) and returns a logical vector indicating whether each pair of ranges overlaps. Integer vectors are treated as width-one ranges.mergeByOverlapscomputes the overlap between query and subject according to the arguments in list() . It then extracts the corresponding hits from each object and returns aDataFramecontaining one column for the query and one for the subject, as well as anymcolsthat were present on either object. The query and subject columns are named by quoting and deparsing the corresponding argument.findOverlapPairsis likemergeByOverlaps, except it returns a formal [Pairs](#pairs) object that provides useful downstream conveniences, such as finding the intersection of the overlapping ranges with [pintersect`](#pintersect) . ## Seealso Hits and HitsList objects in the S4Vectors package for representing a set of hits between 2 vector-like or list-like objects.
findOverlaps,GenomicRanges,GenomicRanges-method in the GenomicRanges package for methods that operate on GRanges or GRangesList objects.
The NCList class and constructor.
The IntegerRanges , Views , IntegerRangesList , and ViewsList classes.
* The IntegerList and LogicalList classes. ## Author Michael Lawrence and Hervé Pagès ## References Allen's Interval Algebra: James F. Allen: Maintaining knowledge about temporal intervals. In: Communications of the ACM. 26/11/1983. ACM Press. S. 832-843, ISSN 0001-0782 ## Examples r ## --------------------------------------------------------------------- ## findOverlaps() ## --------------------------------------------------------------------- query <- IRanges(c(1, 4, 9), c(5, 7, 10)) subject <- IRanges(c(2, 2, 10), c(2, 3, 12)) findOverlaps(query, subject) ## at most one hit per query findOverlaps(query, subject, select="first") findOverlaps(query, subject, select="last") findOverlaps(query, subject, select="arbitrary") ## including adjacent ranges in the result findOverlaps(query, subject, maxgap=0L) query <- IRanges(c(1, 4, 9), c(5, 7, 10)) subject <- IRanges(c(2, 2), c(5, 4)) ## one IRanges object with itself findOverlaps(query) ## single points as query subject <- IRanges(c(1, 6, 13), c(4, 9, 14)) findOverlaps(c(3L, 7L, 10L), subject, select="first") ## special overlap types query <- IRanges(c(1, 5, 3, 4), width=c(2, 2, 4, 6)) subject <- IRanges(c(1, 3, 5, 6), width=c(4, 4, 5, 4)) findOverlaps(query, subject, type="start") findOverlaps(query, subject, type="start", maxgap=1L) findOverlaps(query, subject, type="end", select="first") ov <- findOverlaps(query, subject, type="within", maxgap=1L) ov ## Using pairs to find intersection of overlapping ranges hits <- findOverlaps(query, subject) p <- Pairs(query, subject, hits=hits) pintersect(p) ## Shortcut p <- findOverlapPairs(query, subject) pintersect(p) ## --------------------------------------------------------------------- ## overlapsAny() ## --------------------------------------------------------------------- overlapsAny(query, subject, type="start") overlapsAny(query, subject, type="end") query %over% subject # same as overlapsAny(query, subject) query %within% subject # same as overlapsAny(query, subject, # type="within") ## --------------------------------------------------------------------- ## overlapsRanges() ## --------------------------------------------------------------------- ## Extract the regions of intersection between the overlapping ranges: overlapsRanges(query, subject, ov) ## --------------------------------------------------------------------- ## Using IntegerRangesList objects ## --------------------------------------------------------------------- query <- IRanges(c(1, 4, 9), c(5, 7, 10)) qpartition <- factor(c("a","a","b")) qlist <- split(query, qpartition) subject <- IRanges(c(2, 2, 10), c(2, 3, 12)) spartition <- factor(c("a","a","b")) slist <- split(subject, spartition) ## at most one hit per query findOverlaps(qlist, slist, select="first") findOverlaps(qlist, slist, select="last") findOverlaps(qlist, slist, select="arbitrary") query <- IRanges(c(1, 5, 3, 4), width=c(2, 2, 4, 6)) qpartition <- factor(c("a","a","b","b")) qlist <- split(query, qpartition) subject <- IRanges(c(1, 3, 5, 6), width=c(4, 4, 5, 4)) spartition <- factor(c("a","a","b","b")) slist <- split(subject, spartition) overlapsAny(qlist, slist, type="start") overlapsAny(qlist, slist, type="end") qlist%over% slist subsetByOverlaps(qlist, slist) countOverlaps(qlist, slist)

Inter range transformations of an IntegerRanges, Views, IntegerRangesList, or MaskCollection object

Description

Range-based transformations are grouped in 2 categories:

• Intra range transformations (e.g. shift ) transform each range individually (and independently of the other ranges). They return an object parallel to the input object, that is, where the i-th range corresponds to the i-th range in the input. Those transformations are described in the intra-range-methods man page (see ?`` ). * Inter range transformations (e.g.reduce()) transform all the ranges together as a set to produce a new set of ranges. They return an object that is generally NOT parallel to the input object. Those transformations are described below. ## Usage ```r ## range() ## ------- list(list("range"), list("IntegerRanges"))(x, ..., with.revmap=FALSE, na.rm=FALSE) list(list("range"), list("IntegerRangesList"))(x, ..., with.revmap=FALSE, na.rm=FALSE) ## reduce() ## -------- reduce(x, drop.empty.ranges=FALSE, ...) list(list("reduce"), list("IntegerRanges"))(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE, with.inframe.attrib=FALSE) list(list("reduce"), list("Views"))(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE, with.inframe.attrib=FALSE) list(list("reduce"), list("IntegerRangesList"))(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE, with.inframe.attrib=FALSE) ## gaps() ## ------ gaps(x, start=NA, end=NA) ## disjoin(), isDisjoint(), and disjointBins() ## ------------------------------------------- disjoin(x, ...) list(list("disjoin"), list("IntegerRanges"))(x, with.revmap=FALSE) list(list("disjoin"), list("IntegerRangesList"))(x, with.revmap=FALSE) isDisjoint(x, ...) disjointBins(x, ...) ``` ## Arguments |Argument |Description| |------------- |----------------| |x| A [IntegerRanges](#integerranges) or [IntegerRangesList](#integerrangeslist) object forrange,disjoin,isDisjoint, anddisjointBins. A [IntegerRanges](#integerranges) , [Views](#views) , or [IntegerRangesList](#integerrangeslist) object forreduceandgaps. | |...| Forrange, additional [IntegerRanges](#integerranges) or [IntegerRangesList](#integerrangeslist) object to consider. | |na.rm| Ignored. | |drop.empty.ranges|TRUEorFALSE. Should empty ranges be dropped? | |min.gapwidth| Ranges separated by a gap of at leastmin.gapwidthpositions are not merged. | |with.revmap|TRUEorFALSE. Should the mapping from output to input ranges be stored in the returned object? If yes, then it is stored as metadata columnrevmapof type [IntegerList](#integerlist) . | |with.inframe.attrib|TRUEorFALSE. For internal use. | |start, end| | * Ifxis a [IntegerRanges](#integerranges) or [Views](#views) object: A single integer orNA. Use these arguments to specify the interval of reference i.e. which interval the returned gaps should be relative to. * Ifxis a [IntegerRangesList](#integerrangeslist) object: Integer vectors containing the coordinate bounds for each [IntegerRangesList](#integerrangeslist) top-level element. ## Details Unless specified otherwise, whenxis a [IntegerRangesList](#integerrangeslist) object, any transformation described here is equivalent to applying the transformation to each [IntegerRangesList](#integerrangeslist) top-level element separately. list(list("reduce"), list(" ", " ", " ", list("reduce"), " first orders the ranges in ", list("x"), " from left to right, ", " then merges the overlapping or adjacent ones. ", " ", " ")) list(list("range"), list(" ", " ", " ", list("range"), " first concatenates ", list("x"), " and the objects in ", list("..."), " ", " together. If the ", list("IRanges"), " object resulting from this concatenation ", " contains at least 1 range, then ", list("range"), " returns an ", list("IRanges"), " ", " instance with a single range, from the minimum start to the maximum end ", " of the concatenated object. ", " Otherwise (i.e. if the concatenated object contains no range), ", " ", list("IRanges()"), " is returned (i.e. an ", list("IRanges"), " instance of ", " length 0). ", " ", " When passing more than 1 ", list("IntegerRangesList"), " object to ", list("range()"), ", ", " they are first merged into a single ", list("IntegerRangesList"), " object: by ", " name if all objects have names, otherwise, if they are all of the same ", " length, by position. Else, an exception is thrown. ", " ", " ")) list(list("gaps"), list(" ", " ", " ", list("gaps"), " returns the "normal" ", list("IRanges"), " object representing ", " the set of integers that remain after the set of integers represented ", " by ", list("x"), " has been removed from the interval specified by the ", " ", list("start"), " and ", list("end"), " arguments. ", " ", " If ", list("x"), " is a ", list("Views"), " object, then ", list("start=NA"), " and ", " ", list("end=NA"), " are interpreted as ", list( "start=1"), " and ", " ", list("end=length(subject(x))"), ", respectively, so, if ", list("start"), " ", " and ", list("end"), " are not specified, then gaps are extracted with respect ", " to the entire subject. ", " ", " ")) list(list("isDisjoint"), list(" ", " ", " An ", list("IntegerRanges"), " object ", list("x"), " is considered to be "disjoint" ", " if its ranges are non-overlapping. ", list("isDisjoint"), " tests whether the ", " object is "disjoint" or not. ", " ", " Note that a "normal" ", list("IntegerRanges"), " object is always "disjoint" but ", " the opposite is not true. See ", list("?isNormal"), " for more information about ", " normal ", list("IntegerRanges"), " objects. ", " ", " About empty ranges. ", list("isDisjoint"), " handles empty ranges (a.k.a. ", " zero-width ranges) as follow: single empty range A is considered to ", " overlap with single range B iff it's contained in B without being on ", " the edge of B (in which case it would be ambiguous whether A is ", " contained in or adjacent to B). More precisely, single empty range A ", " is considered to overlap with single range B iff ", " ", list(" start(B) < start(A) and end(A) < end(B)"), " ", " Because A is an empty range it verifies ", list("end(A) = start(A) - 1"), " ", " so the above is equivalent to: ", " ", list(" start(B) < start(A) <= end(B)"), " ", " and also equivalent to: ", " ", list(" start(B) <= end(A) < end(B)"), " ", " Finally, it is also equivalent to: ", " ", list(" pcompare(A, B) == 2"), " ", " See ", list("?", list("IPosRanges-comparison"), ""), " for the meaning of the codes ", " returned by the ", list(list("pcompare")), " function. ", " ", " ")) list(list("disjoin"), list(" ", " ", " ", list("disjoin"), " returns a disjoint object, by finding the union of the ", " end points in ", list("x"), ". In other words, the result consists of a range ", " for every interval, of maximal length, over which the set of overlapping ", " ranges in ", list("x"), " is the same and at least of size 1. ", " ", " ")) list(list("disjointBins"), list(" ", " ", " ", list("disjointBins"), " segregates ", list("x"), " into a set of bins so that the ", " ranges in each bin are disjoint. Lower-indexed bins are filled first. ", " The method returns an integer vector indicating the bin index for each ", " range. ", " ")) ## Value Ifxis an [IntegerRanges](#integerranges) object: *range,reduce,gaps, anddisjoinreturn an [IRanges](#iranges) instance. *isDisjointreturnsTRUEorFALSE. *disjointBinsreturns an integer vector parallel tox, that is, where the i-th element corresponds to the i-th element inx. Ifxis a [Views](#views) object:reduceandgapsreturn a [Views](#views) object on the same subject asxbut with modified views. Ifxis a [IntegerRangesList](#integerrangeslist) object: *range,reduce,gaps, anddisjoinreturn a [IntegerRangesList](#integerrangeslist) object parallel tox. *isDisjointreturns a logical vector parallel tox. *disjointBinsreturns an [IntegerList](#integerlist) object parallel tox. ## Seealso * [intra-range-methods](#intra-range-methods) for intra range transformations. * The [IntegerRanges](#integerranges) , [Views](#views) , [IntegerRangesList](#integerrangeslist) , and [MaskCollection](#maskcollection) classes. * The [inter-range-methods](#inter-range-methods) man page in the GenomicRanges package for inter range transformations of genomic ranges. * [setops-methods](#setops-methods) for set operations on [IRanges](#iranges) objects. * [endoapply`](#endoapply) in the S4Vectors package. ## Author H. Pagès, M. Lawrence, and P. Aboyoun ## Examples r ## --------------------------------------------------------------------- ## range() ## --------------------------------------------------------------------- ## On an IntegerRanges object: x <- IRanges(start=c(-2, 6, 9, -4, 1, 0, -6, 3, 10), width=c( 5, 0, 6, 1, 4, 3, 2, 0, 3)) range(x) ## On an IntegerRangesList object (XVector package required): 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) if (require(XVector)) { range(collection) } irl1 <- IRangesList(a=IRanges(c(1, 2),c(4, 3)), b=IRanges(c(4, 6),c(10, 7))) irl2 <- IRangesList(c=IRanges(c(0, 2),c(4, 5)), a=IRanges(c(4, 5),c(6, 7))) range(irl1, irl2) # matched by names names(irl2) <- NULL range(irl1, irl2) # now by position ## --------------------------------------------------------------------- ## reduce() ## --------------------------------------------------------------------- ## On an IntegerRanges object: reduce(x) y <- reduce(x, with.revmap=TRUE) mcols(y)$revmap # an IntegerList reduce(x, drop.empty.ranges=TRUE) y <- reduce(x, drop.empty.ranges=TRUE, with.revmap=TRUE) mcols(y)$revmap ## Use the mapping from reduced to original ranges to split the DataFrame ## of original metadata columns by reduced range: ir0 <- IRanges(c(11:13, 2, 7:6), width=3) mcols(ir0) <- DataFrame(id=letters[1:6], score=1:6) ir <- reduce(ir0, with.revmap=TRUE) ir revmap <- mcols(ir)$revmap revmap relist(mcols(ir0)[unlist(revmap), ], revmap) # a SplitDataFrameList ## On an IntegerRangesList object. These 4 are the same: res1 <- reduce(collection) res2 <- IRangesList(one=reduce(range1), reduce(range2), reduce(range3)) res3 <- do.call(IRangesList, lapply(collection, reduce)) res4 <- endoapply(collection, reduce) stopifnot(identical(res2, res1)) stopifnot(identical(res3, res1)) stopifnot(identical(res4, res1)) reduce(collection, drop.empty.ranges=TRUE) ## --------------------------------------------------------------------- ## gaps() ## --------------------------------------------------------------------- ## On an IntegerRanges object: x0 <- IRanges(start=c(-2, 6, 9, -4, 1, 0, -6, 10), width=c( 5, 0, 6, 1, 4, 3, 2, 3)) gaps(x0) gaps(x0, start=-6, end=20) ## On a Views object: subject <- Rle(1:-3, 6:2) v <- Views(subject, start=c(8, 3), end=c(14, 4)) gaps(v) ## On an IntegerRangesList object. These 4 are the same: res1 <- gaps(collection) res2 <- IRangesList(one=gaps(range1), gaps(range2), gaps(range3)) res3 <- do.call(IRangesList, lapply(collection, gaps)) res4 <- endoapply(collection, gaps) stopifnot(identical(res2, res1)) stopifnot(identical(res3, res1)) stopifnot(identical(res4, res1)) ## 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 gaps(mymasks) ## --------------------------------------------------------------------- ## disjoin() ## --------------------------------------------------------------------- ## On an IntegerRanges object: ir <- IRanges(c(1, 1, 4, 10), c(6, 3, 8, 10)) disjoin(ir) # IRanges(c(1, 4, 7, 10), c(3, 6, 8, 10)) disjoin(ir, with.revmap=TRUE) ## On an IntegerRangesList object: disjoin(collection) disjoin(collection, with.revmap=TRUE) ## --------------------------------------------------------------------- ## isDisjoint() ## --------------------------------------------------------------------- ## On an IntegerRanges object: isDisjoint(IRanges(c(2,5,1), c(3,7,3))) # FALSE isDisjoint(IRanges(c(2,9,5), c(3,9,6))) # TRUE isDisjoint(IRanges(1, 5)) # TRUE ## Handling of empty ranges: x <- IRanges(c(11, 16, 11, -2, 11), c(15, 29, 10, 10, 10)) stopifnot(isDisjoint(x)) ## Sliding an empty range along a non-empty range: sapply(11:17, function(i) pcompare(IRanges(i, width=0), IRanges(12, 15))) sapply(11:17, function(i) isDisjoint(c(IRanges(i, width=0), IRanges(12, 15)))) ## On an IntegerRangesList object: isDisjoint(collection) ## --------------------------------------------------------------------- ## disjointBins() ## --------------------------------------------------------------------- ## On an IntegerRanges object: disjointBins(IRanges(1, 5)) # 1L disjointBins(IRanges(c(3, 1, 10), c(5, 12, 13))) # c(2L, 1L, 2L) ## On an IntegerRangesList object: disjointBins(collection)

Intra range transformations of an IRanges, IPos, Views, RangesList, or MaskCollection object

Description

Range-based transformations are grouped in 2 categories:

• Intra range transformations (e.g. shift() ) transform each range individually (and independently of the other ranges). They return an object parallel to the input object, that is, where the i-th range corresponds to the i-th range in the input. Those transformations are described below.

• Inter range transformations (e.g. reduce ) transform all the ranges together as a set to produce a new set of ranges. They return an object that is generally NOT parallel to the input object. Those transformations are described in the inter-range-methods man page (see ?`` ). Except forthreebands(), 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. ## Usage ```r 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, ...) flank(x, width, start=TRUE, both=FALSE, use.names=TRUE, ...) promoters(x, upstream=2000, downstream=200, use.names=TRUE, ...) reflect(x, bounds, use.names=TRUE) restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE) threebands(x, start=NA, end=NA, width=NA) ``` ## Arguments |Argument |Description| |------------- |----------------| |x| An [IRanges](#iranges) , [IPos](#ipos) , [Views](#views) , [RangesList](#rangeslist) , or [MaskCollection](#maskcollection) object. | |shift| An integer vector containing the shift information. Recycled as necessary so that each element corresponds to a range inx. Can also be a list-like object parallel toxifxis a [RangesList](#rangeslist) object. | |use.names|TRUEorFALSE. Should names be preserved? | |start, end| Ifxis an [IRanges](#iranges) , [IPos](#ipos) or [Views](#views) object: A vector of integers for all functions except forflank. Forrestrict, the suppliedstartandendarguments 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 inx. Same thing fornarrowandthreebands, except that herestartandendmust contain coordinates relative to the ranges inx. See the Details section below. Forflank,startis a logical indicating whetherxshould be flanked at the start (TRUE) or the end (FALSE). Recycled as necessary so that each element corresponds to a range inx. Can also be list-like objects parallel toxifxis a [RangesList](#rangeslist) object. | |width| Ifxis an [IRanges](#iranges) , [IPos](#ipos) or [Views](#views) object: Fornarrowandthreebands, a vector of integers, eventually with NAs. See the SEW (Start/End/Width) interface for the details (?solveUserSEW). Forresizeandflank, the width of the resized or flanking regions. Note that ifbothisTRUE, this is effectively doubled. Recycled as necessary so that each element corresponds to a range inx. Can also be a list-like object parallel toxifxis a [RangesList](#rangeslist) object. | |fix| Ifxis an [IRanges](#iranges) , [IPos](#ipos) or [Views](#views) object: A character vector or character-Rle of length 1 orlength(x)containing the values"start","end", and"center"denoting what to use as an anchor for each element inx. Can also be a list-like object parallel toxifxis a [RangesList](#rangeslist) object. | |...| Additional arguments for methods. | |both| IfTRUE, extends the flanking regionwidthpositions into the range. The resulting range thus straddles the end point, withwidthpositions on either side. | |upstream, downstream| Vectors of non-NA non-negative integers. Recycled as necessary so that each element corresponds to a range inx. Can also be list-like objects parallel toxifxis a [RangesList](#rangeslist) object.upstreamdefines the number of nucleotides toward the 5' end anddownstreamdefines 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 forupstreamanddownstreamwere 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. | |bounds| An [IRanges](#iranges) object to serve as the reference bounds for the reflection, see below. | |keep.all.ranges|TRUEorFALSE. Should ranges that don't overlap with the restriction interval(s) be kept? Note that "don't overlap" means that they end strictly beforestart - 1or start strictly afterend + 1. Ranges that end atstart - 1or start atend + 1are always kept and their width is set to zero in the returned [IRanges](#iranges) object. | ## Details Unless specified otherwise, whenxis a [RangesList](#rangeslist) object, any transformation described here is equivalent to applying the transformation to each list element inx. list(list("shift"), list(" ", " ", " ", list("shift"), " shifts all the ranges in ", list("x"), " by the amount specified ", " by the ", list("shift"), " argument. ", " ", " ")) list(list("narrow"), list(" ", " ", " ", list("narrow"), " narrows the ranges in ", list("x"), " i.e. each range in the ", " returned ", list("IntegerRanges"), " object is a subrange of the corresponding ", " range in ", list("x"), ". ", " The supplied start/end/width values are solved by a call to ", " ", list("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 ", list("?", list("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. ", " ", " ")) list(list("resize"), list(" ", " ", " ", list("resize"), " resizes the ranges to the specified width where either ", " the start, end, or center is used as an anchor. ", " ", " ")) list(list("flank"), list(" ", " ", " ", list("flank"), " generates flanking ranges for each range in ", list("x"), ". If ", " ", list("start"), " is ", list("TRUE"), " for a given range, the flanking occurs at ", " the start, otherwise the end. The widths of the flanks are given by ", " the ", list("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 ", list("x"), ". The ", list("flank"), " operation is ", " illustrated below for a call of the form ", list("flank(x, 3, TRUE)"), ", ", " where ", list("x"), " indicates a range in ", list("x"), " and ", list("-"), " indicates ", " the resulting flanking region: ", " ", list(" ---xxxxxxx"), " ", " If ", list("start"), " were ", list("FALSE"), ": ", " ", list(" xxxxxxx---"), " ", " For negative width, i.e. ", list("flank(x, -3, FALSE)"), ", where ", list("*"), " ", " indicates the overlap between ", list("x"), " and the result: ", " ", list(" xxxx***"), " ", " If ", list("both"), " is ", list("TRUE"), ", then, for all ranges in ", list("x"), ", the ", " flanking regions are extended ", list("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 ", list("width"), ". This is illustrated below ", " for ", list("flank(x, 3, both=TRUE)"), ": ", " ", list(" ---***xxxx"), " ", " ", " ")) list(list("promoters"), list(" ", " ", " ", list("promoters"), " generates promoter ranges for each range in ", list("x"), " ", " relative to the transcription start site (TSS), where TSS is ", " ", list("start(x)"), ". The promoter range is expanded around the TSS ", " according to the ", list("upstream"), " and ", list("downstream"), " arguments. ", " ", list("upstream"), " represents the number of nucleotides in the 5' ", " direction and ", list("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 ", list("promoters"), " on a ", " ", list("GRanges"), " object see ", " ", list("?", list("promoters,GenomicRanges-method"), ""), " in ", " the ", list("GenomicRanges"), " package. ", " ", " ")) list(list("reflect"), list(" ", " ", " ", list("reflect"), " "reflects" or reverses each range in ", list("x"), " relative to ", " the corresponding range in ", list("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 ", list("x"), " represents ", " a range in ", list("x"), " and ", list("["), " and ", list("]"), " indicate the bounds: ", " ", list(" [..xxx.....] ", " becomes ", " [.....xxx..]"), " ", " ", " ")) list(list("restrict"), list(" ", " ", " ", list("restrict"), " restricts the ranges in ", list("x"), " to the interval(s) ", " specified by the ", list("start"), " and ", list("end"), " arguments. ", " ", " ")) list(list("threebands"), list(" ", " ", " ", list("threebands"), " extends the capability of ", list("narrow"), " by returning ", " the 3 ranges objects associated to the narrowing operation. ", " The returned value ", list("y"), " is a list of 3 ranges objects named ", " ", list(""left""), ", ", list(""middle""), " and ", list(""right""), ". ", " The middle component is obtained by calling ", list("narrow"), " with the ", " same arguments (except that names are dropped). The left and right ", " components are also instances of the same class as ", list("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 ", list("x"), " can be reconstructed from the ", " left and right bands with ", list("punion(y$left, y$right, fill.gap=TRUE)"), ". ", " ", " ")) ## Seealso * [inter-range-methods](#inter-range-methods) for inter range transformations. * The [IRanges](#iranges) , [IPos](#ipos) , [Views](#views) , [RangesList](#rangeslist) , and [MaskCollection](#maskcollection) classes. * The [intra-range-methods](#intra-range-methods) man page in the GenomicRanges package for intra range transformations of genomic ranges. * [setops-methods](#setops-methods) for set operations on [IRanges](#iranges) objects. * [endoapply`](#endoapply) in the S4Vectors package. ## Author H. Pagès, M. Lawrence, and P. Aboyoun ## Examples r ## --------------------------------------------------------------------- ## shift() ## --------------------------------------------------------------------- ## On an IRanges object: ir1 <- successiveIRanges(c(19, 5, 0, 8, 5)) ir1 shift(ir1, shift=-3) ## On an IRangesList 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) # same as endoapply(collection, shift, shift=5) ## Sanity check: res1 <- shift(collection, shift=5) res2 <- endoapply(collection, shift, shift=5) stopifnot(identical(res1, res2)) ## --------------------------------------------------------------------- ## narrow() ## --------------------------------------------------------------------- ## On an IRanges 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 an IRangesList 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 an IRanges object: resize(ir2, 200) resize(ir2, 2, fix="end") ## On an IRangesList object: resize(collection, width=200) ## --------------------------------------------------------------------- ## flank() ## --------------------------------------------------------------------- ## On an IRanges 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 an IRangesList object: flank(collection, width=10) ## --------------------------------------------------------------------- ## promoters() ## --------------------------------------------------------------------- ## On an IRanges 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 an IRangesList object: promoters(collection, upstream=5, downstream=2) ## --------------------------------------------------------------------- ## reflect() ## --------------------------------------------------------------------- ## On an IRanges object: bounds <- IRanges(c(0, 5, 3), c(10, 6, 9)) reflect(ir3, bounds) ## reflect() does not yet support IRangesList objects! ## --------------------------------------------------------------------- ## restrict() ## --------------------------------------------------------------------- ## On an IRanges object: restrict(ir1, start=12, end=34) restrict(ir1, start=20) restrict(ir1, start=21) restrict(ir1, start=21, keep.all.ranges=TRUE) ## On an IRangesList object: restrict(collection, start=2, end=8) ## --------------------------------------------------------------------- ## threebands() ## --------------------------------------------------------------------- ## On an IRanges 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 IRangesList objects.

Split elements belonging to multiple groups

Description

This is like split , except elements can belong to multiple groups, in which case they are repeated to appear in multiple elements of the return value.

Usage

multisplit(x, f)

Arguments

Value

A list-like object, with an element for each unique value in the unlisted f , containing the elements in x where the corresponding element in f contained that value. Just try it.

Author

Michael Lawrence

Examples

multisplit(1:3, list(letters[1:2], letters[2:3], letters[2:4]))

Finding the nearest range neighbor

Description

The nearest , precede , follow , distance and distanceToNearest methods for IntegerRanges objects and subclasses.

Usage

list(list("nearest"), list("IntegerRanges,IntegerRanges_OR_missing"))(x, subject, select = c("arbitrary", "all"))
list(list("precede"), list("IntegerRanges,IntegerRanges_OR_missing"))(x, subject, select = c("first", "all"))
list(list("follow"), list("IntegerRanges,IntegerRanges_OR_missing"))(x, subject, select = c("last", "all"))
list(list("distanceToNearest"), list("IntegerRanges,IntegerRanges_OR_missing"))(x, subject, select = c("arbitrary", "all"))
list(list("distance"), list("IntegerRanges,IntegerRanges"))(x, y)
list(list("distance"), list("Pairs,missing"))(x, y)

Arguments

Details

• list("nearest: ") list(" ", " The conventional nearest neighbor finder. Returns an integer vector ", " containing the index of the nearest neighbor range in ", list("subject"), " ", " for each range in ", list("x"), ". If there is no nearest neighbor ", " (if ", list("subject"), " is empty), NA's are returned. ", " ", " Here is roughly how it proceeds, for a range ", list("xi"), " in ", list("x"), ": ", " ", list(" ", " ", list(), " Find the ranges in ", list("subject"), " that overlap ", list("xi"), ". If a ", " single range ", list("si"), " in ", list("subject"), " overlaps ", list("xi"), ", ", " ", list("si"), " is returned as the nearest neighbor of ", list("xi"), ". If there ", " are multiple overlaps, one of the overlapping ranges is chosen ", " arbitrarily. ", " ", list(), " If no ranges in ", list("subject"), " overlap with ", list("xi"), ", then ", " the range in ", list("subject"), " with the shortest distance from its end ", " to the start ", list("xi"), " or its start to the end of ", list("xi"), " is ", " returned. ", " "), " ", " ")

• list("precede: ") list(" ", " For each range in ", list("x"), ", ", list("precede"), " returns the index of the ", " interval in ", list("subject"), " that is directly preceded by the query ", " range. Overlapping ranges are excluded. ", list("NA"), " is returned when ", " there are no qualifying ranges in ", list("subject"), ". ", " ")

• list("follow: ") list(" ", " The opposite of ", list("precede"), ", this function returns the index ", " of the range in ", list("subject"), " that a query range in ", list("x"), " ", " directly follows. Overlapping ranges are excluded. ", list("NA"), " is ", " returned when there are no qualifying ranges in ", list("subject"), ". ", " ")

• list("distanceToNearest: ") list(" ", " Returns the distance for each range in ", list("x"), " to its nearest ", " neighbor in ", list("subject"), ". ", " ")

• list("distance: ") list(" ", " Returns the distance for each range in ", list("x"), " to the range in ", " ", list("y"), ". ", " ", " The ", list("distance"), " method differs from others documented on this ", " page in that it is symmetric; ", list("y"), " cannot be missing. If ", list("x"), " ", " and ", list("y"), " are not the same length, the shortest will be recycled to ", " match the length of the longest. The ", list("select"), " argument is not ", " available for ", list("distance"), " because comparisons are made in a ", " pair-wise fashion. The return value is the length of the longest ", " of ", list("x"), " and ", list("y"), ". ", " ", " The ", list("distance"), " calculation changed in BioC 2.12 to accommodate ", " zero-width ranges in a consistent and intuitive manner. The new distance ", " can be explained by a ", list("block"), " model where a range is represented by ", " a series of blocks of size 1. Blocks are adjacent to each other and there ", " is no gap between them. A visual representation of ", list("IRanges(4,7)"), " ", " would be ", " ", " ", list(" ", " +-----+-----+-----+-----+ ", " 4 5 6 7 ", " "), " ", " ", " The distance between two consecutive blocks is 0L (prior to ", " Bioconductor 2.12 it was 1L). The new distance calculation now returns ", " the size of the gap between two ranges. ", " ", " This change to distance affects the notion of overlaps in that ", " we no longer say: ", " ", " x and y overlap <=> distance(x, y) == 0 ", " ", " Instead we say ", " ", " x and y overlap => distance(x, y) == 0 ", " ", " or ", " ", " x and y overlap or are adjacent <=> distance(x, y) == 0 ", " ")

• list("selectNearest: ") list(" ", " Selects the hits that have the minimum distance within those for ", " each query range. Ties are possible and can be broken with ", " ", list(list("breakTies")), ". ", " ")

Value

For nearest , precede and follow , an integer vector of indices in subject , or a Hits if select="all" .

For distanceToNearest , a Hits object with an elementMetadata column of the distance between the pair. Access distance with mcols accessor.

For distance , an integer vector of distances between the ranges in x and y .

For selectNearest , a Hits object, sorted by query.

Seealso

• The IntegerRanges and Hits classes.

• The GenomicRanges and GRanges classes in the GenomicRanges package.

• findOverlaps for finding just the overlapping ranges.

• list() list(" ", " GenomicRanges methods for ", " ", list(" ", " ", list(), " ", list("precede"), " ", " ", list(), " ", list("follow"), " ", " ", list(), " ", list("nearest"), " ", " ", list(), " ", list("distance"), " ", " ", list(), " ", list("distanceToNearest"), " ", " "), " ", " are documented at ", " ?", list(list("nearest-methods")), " or ", " ?", list(list("precede,GenomicRanges,GenomicRanges-method")), " ", " ")

Author

M. Lawrence

Examples

## ------------------------------------------
## precede() and follow()
## ------------------------------------------
query <- IRanges(c(1, 3, 9), c(3, 7, 10))
subject <- IRanges(c(3, 2, 10), c(3, 13, 12))

precede(query, subject)     # c(3L, 3L, NA)
precede(IRanges(), subject) # integer()
precede(query, IRanges())   # rep(NA_integer_, 3)
precede(query)              # c(3L, 3L, NA)

follow(query, subject)      # c(NA, NA, 1L)
follow(IRanges(), subject)  # integer()
follow(query, IRanges())    # rep(NA_integer_, 3)
follow(query)               # c(NA, NA, 2L)

## ------------------------------------------
## nearest()
## ------------------------------------------
query <- IRanges(c(1, 3, 9), c(2, 7, 10))
subject <- IRanges(c(3, 5, 12), c(3, 6, 12))

nearest(query, subject) # c(1L, 1L, 3L)
nearest(query)          # c(2L, 1L, 2L)

## ------------------------------------------
## distance()
## ------------------------------------------
## adjacent
distance(IRanges(1,5), IRanges(6,10)) # 0L
## overlap
distance(IRanges(1,5), IRanges(3,7))  # 0L
## zero-width
sapply(-3:3, function(i) distance(shift(IRanges(4,3), i), IRanges(4,3)))

Squeeze the ranges out of a range-based object

Description

S4 generic functions for squeezing the ranges out of a range-based object.

These are analog to range squeezers granges and grglist defined in the GenomicRanges package, except that ranges returns the ranges in an IRanges object (instead of a GRanges object for granges ), and rglist returns them in an IRangesList object (instead of a GRangesList object for grglist ).

Usage

ranges(x, use.names=TRUE, use.mcols=FALSE, ...)
rglist(x, use.names=TRUE, use.mcols=FALSE, ...)

Arguments

Details

Various packages (e.g. IRanges , GenomicRanges , SummarizedExperiment , GenomicAlignments , etc...) define and document various range squeezing methods for various types of objects.

Note that these functions can be seen as object getters or as functions performing coercion.

For some objects (e.g. GAlignments and GAlignmentPairs objects defined in the GenomicAlignments package), as(x, "IRanges") and as(x, "IRangesList") , are equivalent to ranges(x, use.names=TRUE, use.mcols=TRUE) and rglist(x, use.names=TRUE, use.mcols=TRUE) , respectively.

Value

An IRanges object for ranges .

An IRangesList object for rglist .

If x is a vector-like object (e.g. GAlignments ), the returned object is expected to be parallel to x , that is, the i-th element in the output corresponds to the i-th element in the input.

If use.names is TRUE, then the names on x (if any) are propagated to the returned object. If use.mcols is TRUE, then the metadata columns on x (if any) are propagated to the returned object.

Seealso

• IRanges and IRangesList objects.

• RangedSummarizedExperiment objects in the SummarizedExperiment packages.

• GAlignments , GAlignmentPairs , and GAlignmentsList objects in the GenomicAlignments package.

Author

H. Pagès

Examples

## See ?GAlignments in the GenomicAlignments package for examples of
## "ranges" and "rglist" methods.

Read a mask from a file

Description

read.agpMask and read.gapMask extract the AGAPS mask from an NCBI "agp" file or a UCSC "gap" file, respectively.

read.liftMask extracts the AGAPS mask from a UCSC "lift" file (i.e. a file containing offsets of contigs within sequences).

read.rmMask extracts the RM mask from a RepeatMasker .out file.

read.trfMask extracts the TRF mask from a Tandem Repeats Finder .bed file.

Usage

read.agpMask(file, seqname="?", mask.width=NA, gap.types=NULL, use.gap.types=FALSE)
read.gapMask(file, seqname="?", mask.width=NA, gap.types=NULL, use.gap.types=FALSE)
read.liftMask(file, seqname="?", mask.width=NA)
read.rmMask(file, seqname="?", mask.width=NA, use.IDs=FALSE)
read.trfMask(file, seqname="?", mask.width=NA)

Arguments

Seealso

MaskCollection-class , IRanges-class

Examples

## ---------------------------------------------------------------------
## A. Extract a mask of assembly gaps ("AGAPS" mask) with read.agpMask()
## ---------------------------------------------------------------------
## Note: The hs_b36v3_chrY.agp file was obtained by downloading,
## extracting and renaming the hs_ref_chrY.agp.gz file from
##
##   ftp://ftp.ncbi.nih.gov/genomes/H_sapiens/Assembled_chromosomes/
##     hs_ref_chrY.agp.gz      5 KB  24/03/08  04:33:00 PM
##
## on May 9, 2008.

chrY_length <- 57772954
file1 <- system.file("extdata", "hs_b36v3_chrY.agp", package="IRanges")
mask1 <- read.agpMask(file1, seqname="chrY", mask.width=chrY_length,
use.gap.types=TRUE)
mask1
mask1[[1]]

mask11 <- read.agpMask(file1, seqname="chrY", mask.width=chrY_length,
gap.types=c("centromere", "heterochromatin"))
mask11[[1]]

## ---------------------------------------------------------------------
## B. Extract a mask of assembly gaps ("AGAPS" mask) with read.liftMask()
## ---------------------------------------------------------------------
## Note: The hg18liftAll.lft file was obtained by downloading,
## extracting and renaming the liftAll.zip file from
##
##   http://hgdownload.cse.ucsc.edu/goldenPath/hg18/bigZips/
##     liftAll.zip             03-Feb-2006 11:35  5.5K
##
## on May 8, 2008.

file2 <- system.file("extdata", "hg18liftAll.lft", package="IRanges")
mask2 <- read.liftMask(file2, seqname="chr1")
mask2
if (interactive()) {
## contigs 7 and 8 for chrY are adjacent
read.liftMask(file2, seqname="chrY")

## displays the sequence names found in the file
read.liftMask(file2)

## specify an unknown sequence name
read.liftMask(file2, seqname="chrZ", mask.width=300)
}

## ---------------------------------------------------------------------
## C. Extract a RepeatMasker ("RM") or Tandem Repeats Finder ("TRF")
##    mask with read.rmMask() or read.trfMask()
## ---------------------------------------------------------------------
## Note: The ce2chrM.fa.out and ce2chrM.bed files were obtained by
## downloading, extracting and renaming the chromOut.zip and
## chromTrf.zip files from
##
##   http://hgdownload.cse.ucsc.edu/goldenPath/ce2/bigZips/
##     chromOut.zip            21-Apr-2004 09:05  2.6M
##     chromTrf.zip            21-Apr-2004 09:07  182K
##
## on May 7, 2008.

## Before you can extract a mask with read.rmMask() or read.trfMask(), you
## need to know the length of the sequence that you're going to put the
## mask on:
if (interactive()) {
library(BSgenome.Celegans.UCSC.ce2)
chrM_length <- seqlengths(Celegans)[["chrM"]]

## Read the RepeatMasker .out file for chrM in ce2:
file3 <- system.file("extdata", "ce2chrM.fa.out", package="IRanges")
RMmask <- read.rmMask(file3, seqname="chrM", mask.width=chrM_length)
RMmask

## Read the Tandem Repeats Finder .bed file for chrM in ce2:
file4 <- system.file("extdata", "ce2chrM.bed", package="IRanges")
TRFmask <- read.trfMask(file4, seqname="chrM", mask.width=chrM_length)
TRFmask
desc(TRFmask) <- paste(desc(TRFmask), "[period<=12]")
TRFmask

## Put the 2 masks on chrM:
chrM <- Celegans$chrM
masks(chrM) <- RMmask  # this would drop all current masks, if any
masks(chrM) <- append(masks(chrM), TRFmask)
chrM
}

reverse

Description

A generic function for reversing vector-like or list-like objects. This man page describes methods for reversing a character vector, a Views object, or a MaskCollection object. Note that reverse is similar to but not the same as rev .

Usage

reverse(x, ...)

Arguments

Details

On a character vector or a Views object, reverse reverses each element individually, without modifying the top-level order of the elements. More precisely, each individual string of a character vector is reversed.

Value

An object of the same class and length as the original object.

Seealso

reverse-methods , Views-class , MaskCollection-class , endoapply , rev

Examples

## On a character vector:
reverse(c("Hi!", "How are you?"))
rev(c("Hi!", "How are you?"))

## On a Views object:
v <- successiveViews(Rle(c(-0.5, 12.3, 4.88), 4:2), 1:4)
v
reverse(v)
rev(v)

## 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)
reverse(mymasks)

2 methods that should be documented somewhere else

Description

unsplit method for List object and split<- method for Vector object.

Usage

list(list("unsplit"), list("List"))(value, f, drop = FALSE)
list(list("split"), list("Vector"))(x, f, drop = FALSE, ...) <- value

Arguments

Details

unsplit unlists value , where the order of the returned vector is as if value were originally created by splitting that vector on the factor f .

split(x, f, drop = FALSE) <- value : Virtually splits x by the factor f , replaces the elements of the resulting list with the elements from the list value , and restores x to its original form. Note that this works for any Vector , even though split itself is not universally supported.

Author

Michael Lawrence

Set operations on IntegerRanges and IntegerRangesList objects

Description

Performs set operations on IntegerRanges and IntegerRangesList objects.

Usage

## Vector-wise set operations
## --------------------------
list(list("union"), list("IntegerRanges,IntegerRanges"))(x, y)
list(list("union"), list("Pairs,missing"))(x, y, ...)
list(list("intersect"), list("IntegerRanges,IntegerRanges"))(x, y)
list(list("intersect"), list("Pairs,missing"))(x, y, ...)
list(list("setdiff"), list("IntegerRanges,IntegerRanges"))(x, y)
list(list("setdiff"), list("Pairs,missing"))(x, y, ...)
## Element-wise (aka "parallel") set operations
## --------------------------------------------
list(list("punion"), list("IntegerRanges,IntegerRanges"))(x, y, fill.gap=FALSE)
list(list("punion"), list("Pairs,missing"))(x, y, ...)
list(list("pintersect"), list("IntegerRanges,IntegerRanges"))(x, y, resolve.empty=c("none", "max.start", "start.x"))
list(list("pintersect"), list("Pairs,missing"))(x, y, ...)
list(list("psetdiff"), list("IntegerRanges,IntegerRanges"))(x, y)
list(list("psetdiff"), list("Pairs,missing"))(x, y, ...)
list(list("pgap"), list("IntegerRanges,IntegerRanges"))(x, y)

Arguments

Details

The union , intersect and setdiff methods for IntegerRanges objects return a "normal" IntegerRanges object representing the union, intersection and (asymmetric!) difference of the sets of integers represented by x and y .

punion , pintersect , psetdiff and pgap are generic functions that compute the element-wise (aka "parallel") union, intersection, (asymmetric!) difference and gap between each element in x and its corresponding element in y . Methods for IntegerRanges objects are defined. For these methods, x and y must have the same length (i.e. same number of ranges). They return a IntegerRanges object parallel to x and y i.e. where the i-th range corresponds to the i-th range in x and in y ) and represents the union/intersection/difference/gap of/between the corresponding x[i] and y[i] .

If x is a Pairs object, then y should be missing, and the operation is performed between the members of each pair.

By default, pintersect will throw an error when an "ambiguous empty range" is formed. An ambiguous empty range can occur three different ways: 1) when corresponding non-empty ranges elements x and y have an empty intersection, 2) if the position of an empty range element does not fall within the corresponding limits of a non-empty range element, or 3) if two corresponding empty range elements do not have the same position. For example if empty range element [22,21] is intersected with non-empty range element [1,10], an error will be produced; but if it is intersected with the range [22,28], it will produce [22,21]. As mentioned in the Arguments section above, this behavior can be changed using the resolve.empty argument.

Value

On IntegerRanges objects, union , intersect , and setdiff return an IRanges instance that is guaranteed to be normal (see isNormal ) but is NOT promoted to NormalIRanges .

On IntegerRanges objects, punion , pintersect , psetdiff , and pgap return an object of the same class and length as their first argument.

Seealso

• pintersect is similar to narrow , except the end points are absolute, not relative. pintersect is also similar to restrict , except ranges outside of the restriction become empty and are not discarded.

• setops-methods in the GenomicRanges package for set operations on genomic ranges.

• findOverlaps-methods for finding/counting overlapping ranges.

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

• IntegerRanges and IntegerRangesList objects. In particular, normality of an IntegerRanges object is discussed in the man page for IntegerRanges objects.

• mendoapply in the S4Vectors package.

Author

H. Pagès and M. Lawrence

Examples

x <- IRanges(c(1, 5, -2, 0, 14), c(10, 9, 3, 11, 17))
subject <- Rle(1:-3, 6:2)
y <- Views(subject, start=c(14, 0, -5, 6, 18), end=c(20, 2, 2, 8, 20))

## Vector-wise operations:
union(x, ranges(y))
union(ranges(y), x)

intersect(x, ranges(y))
intersect(ranges(y), x)

setdiff(x, ranges(y))
setdiff(ranges(y), x)

## Element-wise (aka "parallel") operations:
try(punion(x, ranges(y)))
punion(x[3:5], ranges(y)[3:5])
punion(x, ranges(y), fill.gap=TRUE)
try(pintersect(x, ranges(y)))
pintersect(x[3:4], ranges(y)[3:4])
pintersect(x, ranges(y), resolve.empty="max.start")
psetdiff(ranges(y), x)
try(psetdiff(x, ranges(y)))
start(x)[4] <- -99
end(y)[4] <- 99
psetdiff(x, ranges(y))
pgap(x, ranges(y))

## On IntegerRangesList objects:
irl1 <- IRangesList(a=IRanges(c(1,2),c(4,3)), b=IRanges(c(4,6),c(10,7)))
irl2 <- IRangesList(c=IRanges(c(0,2),c(4,5)), a=IRanges(c(4,5),c(6,7)))
union(irl1, irl2)
intersect(irl1, irl2)
setdiff(irl1, irl2)

Slice a vector-like or list-like object

Description

slice is a generic function that creates views on a vector-like or list-like object that contain the elements that are within the specified bounds.

Usage

slice(x, lower=-Inf, upper=Inf, ...)
list(list("slice"), list("Rle"))(x, lower=-Inf, upper=Inf,
      includeLower=TRUE, includeUpper=TRUE, rangesOnly=FALSE)
list(list("slice"), list("RleList"))(x, lower=-Inf, upper=Inf,
      includeLower=TRUE, includeUpper=TRUE, rangesOnly=FALSE)

Arguments

Details

slice is useful for finding areas of absolute maxima (peaks), absolute minima (troughs), or fluctuations within specified limits. One or more view summarization methods can be used on the result of slice . See ?link{view-summarization-methods}` ## Value The method for [Rle](#rle) objects returns an [RleViews](#rleviews) object ifrangesOnly=FALSEor an [IRanges](#iranges) object ifrangesOnly=TRUE. The method for [RleList](#rlelist) objects returns an [RleViewsList](#rleviewslist) object ifrangesOnly=FALSEor an [IRangesList](#irangeslist) object ifrangesOnly=TRUE. ## Seealso * [view-summarization-methods](#view-summarization-methods) for summarizing the views returned byslice. * [slice-methods](#slice-methods) in the XVector package for moreslicemethods. * [coverage`](#coverage) for computing the coverage across a set of ranges.
* The Rle , RleList , RleViews , and RleViewsList classes. ## Author P. Aboyoun ## Examples r ## Views derived from coverage x <- IRanges(start=c(1L, 9L, 4L, 1L, 5L, 10L), width=c(5L, 6L, 3L, 4L, 3L, 3L)) cvg <- coverage(x) slice(cvg, lower=2) slice(cvg, lower=2, rangesOnly=TRUE)

Summarize views on a vector-like object with numeric values

Description

viewApply applies a function on each view of a Views or ViewsList object.

viewMins , viewMaxs , viewSums , viewMeans calculate respectively the minima, maxima, sums, and means of the views in a Views or ViewsList object.

Usage

viewApply(X, FUN, ..., simplify = TRUE)
viewMins(x, na.rm=FALSE)
list(list("min"), list("Views"))(x, ..., na.rm = FALSE)
viewMaxs(x, na.rm=FALSE)
list(list("max"), list("Views"))(x, ..., na.rm = FALSE)
viewSums(x, na.rm=FALSE)
list(list("sum"), list("Views"))(x, ..., na.rm = FALSE)
viewMeans(x, na.rm=FALSE)
list(list("mean"), list("Views"))(x, ...)
viewWhichMins(x, na.rm=FALSE)
list(list("which.min"), list("Views"))(x)
viewWhichMaxs(x, na.rm=FALSE)
list(list("which.max"), list("Views"))(x)
viewRangeMins(x, na.rm=FALSE)
viewRangeMaxs(x, na.rm=FALSE)

Arguments

Details

The viewMins , viewMaxs , viewSums , and viewMeans functions provide efficient methods for calculating the specified numeric summary by performing the looping in compiled code.

The viewWhichMins , viewWhichMaxs , viewRangeMins , and viewRangeMaxs functions provide efficient methods for finding the locations of the minima and maxima.

Value

For all the functions in this man page (except viewRangeMins and viewRangeMaxs ): A numeric vector of the length of x if x is an RleViews object, or a List object of the length of x if it's an RleViewsList object.

For viewRangeMins and viewRangeMaxs : An IRanges object if x is an RleViews object, or an IRangesList object if it's an RleViewsList object.

Seealso

• The slice function for slicing an Rle or RleList object.

• view-summarization-methods in the XVector package for more view summarization methods.

• The RleViews and RleViewsList classes.

• The which.min and colSums functions.

Note

For convenience, methods for min , max , sum , mean , which.min and which.max are provided as wrappers around the corresponding view* functions (which might be deprecated at some point).

Author

P. Aboyoun

Examples

## Views derived from coverage
x <- IRanges(start=c(1L, 9L, 4L, 1L, 5L, 10L),
width=c(5L, 6L, 3L, 4L, 3L,  3L))
cvg <- coverage(x)
cvg_views <- slice(cvg, lower=2)

viewApply(cvg_views, diff)

viewMins(cvg_views)
viewMaxs(cvg_views)

viewSums(cvg_views)
viewMeans(cvg_views)

viewWhichMins(cvg_views)
viewWhichMaxs(cvg_views)

viewRangeMins(cvg_views)
viewRangeMaxs(cvg_views)