Hits-comparison {S4Vectors} | R Documentation

## Comparing and ordering hits

### Description

`==`, `!=`, `<=`, `>=`, `<`, `>`, `match()`, `%in%`, `order()`, `sort()`, and `rank()` can be used on Hits objects to compare and order hits.

Note that only the `"pcompare"`, `"match"`, and `"order"` methods are actually defined for Hits objects. This is all what is needed to make all the other comparing and ordering operations (i.e. `==`, `!=`, `<=`, `>=`, `<`, `>`, `%in%`, `sort()`, and `rank()`) work on these objects (see `?`Vector-comparison`` for more information about this).

### Usage

    ## S4 method for signature 'Hits,Hits'
    pcompare(x, y)

    ## S4 method for signature 'Hits,Hits'
    match(x, table, nomatch=NA_integer_, incomparables=NULL,
          method=c("auto", "quick", "hash"))

    ## S4 method for signature 'Hits'
    order(..., na.last=TRUE, decreasing=FALSE, method=c("auto", "shell", "radix"))

### Arguments

`x, y, table` | Compatible Hits objects, that is, Hits objects with the same subject and query lengths.
`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`: 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 Hits objects. The additional Hits objects are used to break ties.
`na.last` | Ignored.
`decreasing` | `TRUE` or `FALSE`.

### Details

Only hits that belong to Hits objects with same subject and query lengths can be compared.

Hits are ordered by query hit first, and then by subject hit. On a Hits object, `order`, `sort`, and `rank` are consistent with this order.

  `pcompare(x, y)`: Performs element-wise (aka "parallel") comparison of 2 Hits objects `x` and `y`, that is, returns an integer vector where the i-th element is less than, equal to, or greater than zero if `x[i]` is considered to be respectively less than, equal to, or greater than `y[i]`. See `?`Vector-comparison`` for how `x` or `y` is recycled when the 2 objects don't have the same length.

  `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 hit in `table` (or `nomatch` if there is no matching hit) for each hit in `x`.

  `order(...)`: Returns a permutation which rearranges its first argument (a Hits object) into ascending order, breaking ties by further arguments (also Hits objects).

### Author(s)

Hervé Pagès

### See Also

- Hits objects.

- Vector-comparison for general information about comparing, ordering, and tabulating vector-like objects.

### Examples

    ## ---------------------------------------------------------------------
    ## A. ELEMENT-WISE (AKA "PARALLEL") COMPARISON OF 2 Hits OBJECTS
    ## ---------------------------------------------------------------------
    hits <- Hits(c(2, 4, 4, 4, 5, 5), c(3, 1, 3, 2, 3, 2), 6, 3)
    hits

    pcompare(hits, hits[3])
    pcompare(hits[3], hits)

    hits == hits[3]
    hits != hits[3]
    hits >= hits[3]
    hits < hits[3]

    ## ---------------------------------------------------------------------
    ## B. match(), %in%
    ## ---------------------------------------------------------------------
    table <- hits[-c(1, 3)]
    match(hits, table)

    hits %in% table

    ## ---------------------------------------------------------------------
    ## C. order(), sort(), rank()
    ## ---------------------------------------------------------------------
    order(hits)
    sort(hits)
    rank(hits)

[Package S4Vectors version 0.22.1 Index]