IRanges (version 2.6.0)

Ranges-comparison: Comparing and ordering ranges

Description

Methods for comparing and/or ordering Ranges objects.

Usage

## match() & selfmatch()
## ---------------------
## S3 method for class 'Ranges,Ranges':
match(x, table, nomatch=NA_integer_, incomparables=NULL,
      method=c("auto", "quick", "hash"))
## S3 method for class 'Ranges':
selfmatch(x, method=c("auto", "quick", "hash"))
## order()
## -------
## S3 method for class 'Ranges':
order(..., na.last=TRUE, decreasing=FALSE, method=c("shell", "radix"))
## Generalized parallel comparison of 2 Ranges objects
## ---------------------------------------------------
## S3 method for class 'Ranges,Ranges':
pcompare(x, y)
rangeComparisonCodeToLetter(code)

Arguments

x, table, y

Ranges objects.

nomatch

The value to be returned in the case when no match is found. It is coerced to an integer.

incomparables

Not supported.

method

For match and selfmatch: Use a Quicksort-based (method="quick") or a hash-based (method="hash") algorithm. The latter tends to give better performance, except maybe for some pathological input that we've not encountered so far. When method="auto" is specified, the most efficient algorithm will be used, that is, the hash-based algorithm if length(x) <= 2^29<="" code="">, otherwise the Quicksort-based algorithm.

For order: The method argument is ignored.

...

One or more Ranges objects. The Ranges objects after the first one are used to break ties.

na.last

Ignored.

decreasing

TRUE or FALSE.

code

A vector of codes as returned by pcompare.

Details

Two ranges are considered equal iff they share the same start and width. 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.

Ranges are ordered by starting position first, and then by width. This way, the space of ranges is totally ordered. On a Ranges object, order, sort, and rank are consistent with this order.

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

See Also

• TheRangesclass.
• Vector-comparisonin theS4Vectorspackage for general information about comparing, ordering, and tabulating vector-like objects.
• GenomicRanges-comparisonin theGenomicRangespackage for comparing and ordering genomic ranges.
• findOverlapsfor finding overlapping ranges.
• intra-range-methodsandinter-range-methodsfor intra and inter range transformations.
• setops-methodsfor set operations onIRangesobjects.

Examples

## ---------------------------------------------------------------------
## A. ELEMENT-WISE (AKA "PARALLEL") COMPARISON OF 2 Ranges OBJECTS
## ---------------------------------------------------------------------
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
## ---------------------------------------------------------------------
order(x2)
sort(x2)
rank(x2, ties.method="first")