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,
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.
pcompare(x, y):
Performs element-wise (aka "parallel") comparison of 2 Ranges
objects of x and y, that is, returns an integer vector
where the i-th element is a code describing how x[i] is
qualitatively positioned with respect to y[i].
Here is a summary of the 13 predefined codes (and their letter
equivalents) and their meanings:
Note that this way of comparing ranges is a refinement over the
standard ranges comparison defined by the ==, !=,
<=, >=, < and > operators. In particular
a code that is < 0, = 0, or > 0, corresponds to
x[i] < y[i], x[i] == y[i], or x[i] > y[i],
respectively.
The pcompare method for Ranges objects is guaranteed
to return predefined codes only but methods for other objects (e.g.
for GenomicRanges objects) can return
non-predefined codes. Like for the predefined codes, the sign of any
non-predefined code must tell whether x[i] is less than, or
greater than y[i].
rangeComparisonCodeToLetter(x):
Translate the codes returned by 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.
match(x, table, nomatch=NA_integer_, method=c("auto", "quick", "hash")):
Returns an integer vector of the length of x,
containing the index of the first matching range in table
(or nomatch if there is no matching range) for each range
in x.
selfmatch(x, method=c("auto", "quick", "hash")):
Equivalent to, but more efficient than,
match(x, x, method=method).
duplicated(x, fromLast=FALSE, method=c("auto", "quick", "hash")):
Determines which elements of x are equal to elements
with smaller subscripts, and returns a logical vector indicating
which elements are duplicates. duplicated(x) is equivalent to,
but more efficient than, duplicated(as.data.frame(x)) on a
Ranges object.
See duplicated in the base package for more
details.
unique(x, fromLast=FALSE, method=c("auto", "quick", "hash")):
Removes duplicate ranges from x. unique(x) is equivalent
to, but more efficient than, unique(as.data.frame(x)) on a
Ranges object.
See unique in the base package for more
details.
x %in% table:
A shortcut for finding the ranges in x that match any of
the ranges in table. Returns a logical vector of length
equal to the number of ranges in x.
findMatches(x, table, method=c("auto", "quick", "hash")):
An enhanced version of match that returns all the matches
in a Hits object.
countMatches(x, table, method=c("auto", "quick", "hash")):
Returns an integer vector of the length of x containing the
number of matches in table for each element in x.
order(...):
Returns a permutation which rearranges its first argument (a
Ranges object) into ascending order, breaking ties by further
arguments (also Ranges objects).
sort(x):
Sorts x.
See sort in the base package for more details.
rank(x, na.last=TRUE, ties.method=c("average", "first", "random", "max", "min")):
Returns the sample ranks of the ranges in x.
See rank in the base package for more details.
Author(s)
Herv<c3><83><c2><a9> Pag<c3><83><c2><a8>s
See Also
The Ranges 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.
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")
Results
R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.
R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.
Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.
> library(IRanges)
Loading required package: BiocGenerics
Loading required package: parallel
Attaching package: 'BiocGenerics'
The following objects are masked from 'package:parallel':
clusterApply, clusterApplyLB, clusterCall, clusterEvalQ,
clusterExport, clusterMap, parApply, parCapply, parLapply,
parLapplyLB, parRapply, parSapply, parSapplyLB
The following objects are masked from 'package:stats':
IQR, mad, xtabs
The following objects are masked from 'package:base':
Filter, Find, Map, Position, Reduce, anyDuplicated, append,
as.data.frame, cbind, colnames, do.call, duplicated, eval, evalq,
get, grep, grepl, intersect, is.unsorted, lapply, lengths, mapply,
match, mget, order, paste, pmax, pmax.int, pmin, pmin.int, rank,
rbind, rownames, sapply, setdiff, sort, table, tapply, union,
unique, unsplit
Loading required package: S4Vectors
Loading required package: stats4
Attaching package: 'S4Vectors'
The following objects are masked from 'package:base':
colMeans, colSums, expand.grid, rowMeans, rowSums
> png(filename="/home/ddbj/snapshot/RGM3/R_BC/result/IRanges/Ranges-comparison.Rd_%03d_medium.png", width=480, height=480)
> ### Name: Ranges-comparison
> ### Title: Comparing and ordering ranges
> ### Aliases: Ranges-comparison pcompare pcompare,Ranges,Ranges-method
> ### rangeComparisonCodeToLetter match,Ranges,Ranges-method
> ### selfmatch,Ranges-method order,Ranges-method
> ### Keywords: methods
>
> ### ** Examples
>
> ## ---------------------------------------------------------------------
> ## A. ELEMENT-WISE (AKA "PARALLEL") COMPARISON OF 2 Ranges OBJECTS
> ## ---------------------------------------------------------------------
> x0 <- IRanges(1:11, width=4)
> x0
IRanges object with 11 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 1 4 4
[2] 2 5 4
[3] 3 6 4
[4] 4 7 4
[5] 5 8 4
[6] 6 9 4
[7] 7 10 4
[8] 8 11 4
[9] 9 12 4
[10] 10 13 4
[11] 11 14 4
> y0 <- IRanges(6, 9)
> pcompare(x0, y0)
[1] -6 -5 -4 -4 -4 0 4 4 4 5 6
> pcompare(IRanges(4:6, width=6), y0)
[1] -3 -2 1
> pcompare(IRanges(6:8, width=2), y0)
[1] -1 2 3
> pcompare(x0, y0) < 0 # equivalent to 'x0 < y0'
[1] TRUE TRUE TRUE TRUE TRUE FALSE FALSE FALSE FALSE FALSE FALSE
> pcompare(x0, y0) == 0 # equivalent to 'x0 == y0'
[1] FALSE FALSE FALSE FALSE FALSE TRUE FALSE FALSE FALSE FALSE FALSE
> pcompare(x0, y0) > 0 # equivalent to 'x0 > y0'
[1] FALSE FALSE FALSE FALSE FALSE FALSE TRUE TRUE TRUE TRUE TRUE
>
> rangeComparisonCodeToLetter(-10:10)
[1] X X X X a b c d e f g h i j k l m X X X X
Levels: a b c d e f g h i j k l m X
> rangeComparisonCodeToLetter(pcompare(x0, y0))
[1] a b c c c g k k k l m
Levels: a b c d e f g h i j k l m X
>
> ## Handling of zero-width ranges (a.k.a. empty ranges):
> x1 <- IRanges(11:17, width=0)
> x1
IRanges object with 7 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 11 10 0
[2] 12 11 0
[3] 13 12 0
[4] 14 13 0
[5] 15 14 0
[6] 16 15 0
[7] 17 16 0
> pcompare(x1, x1[4])
[1] -6 -6 -6 0 6 6 6
> pcompare(x1, IRanges(12, 15))
[1] -6 -5 2 2 2 5 6
>
> ## 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
[1] -5
> pcompare(x1[6], IRanges(12, 15)) # 5
[1] 5
>
> x2 <- IRanges(start=c(20L, 8L, 20L, 22L, 25L, 20L, 22L, 22L),
+ width=c( 4L, 0L, 11L, 5L, 0L, 9L, 5L, 0L))
> x2
IRanges object with 8 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 20 23 4
[2] 8 7 0
[3] 20 30 11
[4] 22 26 5
[5] 25 24 0
[6] 20 28 9
[7] 22 26 5
[8] 22 21 0
>
> which(width(x2) == 0) # 3 empty ranges
[1] 2 5 8
> x2[2] == x2[2] # TRUE
[1] TRUE
> x2[2] == x2[5] # FALSE
[1] FALSE
> x2 == x2[4]
[1] FALSE FALSE FALSE TRUE FALSE FALSE TRUE FALSE
> x2 >= x2[3]
[1] FALSE FALSE TRUE TRUE TRUE FALSE TRUE TRUE
>
> ## ---------------------------------------------------------------------
> ## B. match(), selfmatch(), %in%, duplicated(), unique()
> ## ---------------------------------------------------------------------
> table <- x2[c(2:4, 7:8)]
> match(x2, table)
[1] NA 1 2 3 NA NA 3 5
>
> x2 %in% table
[1] FALSE TRUE TRUE TRUE FALSE FALSE TRUE TRUE
>
> duplicated(x2)
[1] FALSE FALSE FALSE FALSE FALSE FALSE TRUE FALSE
> unique(x2)
IRanges object with 7 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 20 23 4
[2] 8 7 0
[3] 20 30 11
[4] 22 26 5
[5] 25 24 0
[6] 20 28 9
[7] 22 21 0
>
> ## ---------------------------------------------------------------------
> ## C. findMatches(), countMatches()
> ## ---------------------------------------------------------------------
> findMatches(x2, table)
Hits object with 7 hits and 0 metadata columns:
queryHits subjectHits
<integer> <integer>
[1] 2 1
[2] 3 2
[3] 4 3
[4] 4 4
[5] 7 3
[6] 7 4
[7] 8 5
-------
queryLength: 8 / subjectLength: 5
> countMatches(x2, table)
[1] 0 1 1 2 0 0 2 1
>
> x2_levels <- unique(x2)
> countMatches(x2_levels, x2)
[1] 1 1 1 2 1 1 1
>
> ## ---------------------------------------------------------------------
> ## D. order() AND RELATED METHODS
> ## ---------------------------------------------------------------------
> order(x2)
[1] 2 1 6 3 8 4 7 5
> sort(x2)
IRanges object with 8 ranges and 0 metadata columns:
start end width
<integer> <integer> <integer>
[1] 8 7 0
[2] 20 23 4
[3] 20 28 9
[4] 20 30 11
[5] 22 21 0
[6] 22 26 5
[7] 22 26 5
[8] 25 24 0
> rank(x2, ties.method="first")
[1] 2 1 4 6 8 3 7 5
>
>
>
>
>
> dev.off()
null device
1
>