Interaction compare {InteractionSet} | R Documentation

## Interaction comparisons

### Description

Methods to order, compare and de-duplicate GInteractions or InteractionSet objects, based on the anchor indices.

### Usage

    ## S4 method for signature 'GInteractions'
    order(..., na.last=TRUE, decreasing=FALSE)

    ## S4 method for signature 'GInteractions'
    sort(x, decreasing=FALSE, ...)

    ## S4 method for signature 'GInteractions'
    duplicated(x, incomparables=FALSE, fromLast=FALSE, ...)

    ## S4 method for signature 'GInteractions'
    unique(x, incomparables=FALSE, fromLast=FALSE, ...)

    ## S4 method for signature 'GInteractions'
    swapAnchors(x, mode=c("order", "reverse", "all"))

    ## Each of the above methods has an identical equivalent for
    ## InteractionSet objects (not shown for brevity).

    ## S4 method for signature 'GInteractions,GInteractions'
    match(x, table, nomatch=NA_integer_, incomparables=NULL, ...)

    ## S4 method for signature 'GInteractions,InteractionSet'
    match(x, table, nomatch=NA_integer_, incomparables=NULL, ...)

    ## S4 method for signature 'InteractionSet,GInteractions'
    match(x, table, nomatch=NA_integer_, incomparables=NULL, ...)

    ## S4 method for signature 'InteractionSet,InteractionSet'
    match(x, table, nomatch=NA_integer_, incomparables=NULL, ...)

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

### Arguments

`...` | For `order`, one or more InteractionSet or GInteractions objects with the same number of rows. Otherwise, ignored in all other methods.
`x` | An InteractionSet or GInteractions object. For `pcompare`, a GInteractions object only.
`na.last` | A logical scalar indicating whether `NA` values should be ordered last. This should not be relevant as anchor indices should be finite.
`decreasing` | A logical scalar indicating whether rows should be sorted in decreasing order.
`incomparables` | A logical scalar. See `?match` for a description of this in `match`. Otherwise, it is ignored.
`fromLast` | A logical scalar indicating whether the last entry of a repeated set in `x` should be considered as a non-duplicate.
`mode` | A string indicating what type of swapping should be performed in `swapAnchors`.
`table` | A GInteractions or InteractionSet object.
`nomatch` | An integer scalar indicating the value to use for unmatched entries.
`y` | A GInteractions object, of the same length as `x`.

### Value

For `sort` and `unique`, a GInteractions or InteractionSet object is returned, depending on the class of `x`.

For `order` and `duplicated`, an integer vector of permutations or a logical vector of duplicate specifications is returned, respectively.

### Sorting and ordering

Sorting is performed based on the anchor indices of the GInteraction object. Rows are ordered for increasing values of the `anchor1` slot - if these are equal, ordering is performed with values of the `anchor2` slot. This equates to ordering by the coordinates directly, as the GRanges in the `regions` slot is always sorted. Based on this, `sort` will return a sorted copy of `x` with permuted rows in increasing order.

The `order` method returns an integer vector indicating the permutation to rearrange `x` in increasing order. If multiple objects are supplied to `order`, ordering will be computed using anchor indices from successive objects. For example, ordering is first performed using anchor indices from the first object; any rows with the same `anchor1` and `anchor2` will be split using the second object; and so on.

For both of these methods, the sorting can be reversed by setting `decreasing=TRUE`. This will sort or order for decreasing values of `anchor1` and `anchor2`, rather than for increasing values.

### Removing duplicates

The `duplicated` method returns a logical vector indicating whether the rows of `x` are duplicated. Duplicated rows are identified on the basis of identical entries in the `anchor1` and `anchor2` slots. Values in other slots (e.g., in `mcols`) are ignored. For a set of duplicated rows, the first occurrence in `x` is marked as the non-duplicate if `fromLast=FALSE`, and the last entry otherwise.

`unique` returns a GInteractions object where all duplicate rows have been removed from `x`. This is equivalent to `x[!duplicated(x),]`, with any additional arguments passed to `duplicated` as specified.

### Matching and comparing

The `match` function will return an integer vector of length equal to that of `x`. Each entry of the vector corresponds to an interaction in `x` and contains the index of the first interaction `table` with the same anchor regions. Interactions in `x` without any matches are assigned `NA` values by default. If the `regions` slot is not the same between `x` and `table`, `match` will call `findOverlaps` to identify exact two-dimensional overlaps.

The `pcompare` function will return an integer vector of length equal to `x` and `y`. This performs parallel comparisons between corresponding entries in two GInteractions objects, based on the values of the anchor indices (`anchor1` first, and then `anchor2` if `anchor1` is tied). Negative, zero and positive values indicate that the corresponding interaction in `x` is “lesser”, equal or “greater” than the corresponding interaction in `y`. If the `regions` slot is not the same between the two objects, the union of regions for both objects will be used to obtain comparable indices.

### Swapping anchors

For GInteractions objects, `swapAnchors` returns a GInteractions object where `anchor1` and `anchor2` values are swapped. If `mode="order"`, this is done so that all values in the `anchor2` slot are not less than values in `anchor1` in the returned object. If `mode="reverse"`, all values in `anchor1` are not less than all values in `anchor2`. If `mode="all"`, the anchor indices in `x` are directly swapped without consideration of ordering.

It is recommended to apply this method before running methods like `order` or `duplicated`. This ensures that redundant permutations are coerced into the same format for a valid comparison. In many applications, permutations of pairwise interactions are not of interest, i.e., an interaction between regions 1 and 2 is the same as that between 2 and 1. Application of `swapAnchors` with `mode="order"` ensures that all indices are arranged in a comparable manner. Alternatively, users can use a (Reverse)StrictGInteractions object which enforces a consistent arrangement of indices across interactions.

### Methods for InteractionSet objects

For all InteractionSet methods, the corresponding method is called on the GInteractions object in the `interactions` slot of the InteractionSet object. Return values for each InteractionSet method is the same as those for the corresponding GInteractions method - except for `sort` and `unique`, which return a row-permuted or row-subsetted InteractionSet, respectively, instead of a GInteractions object; and `swapAnchors`, which returns an InteractionSet object where the internal GInteractions has its anchor indices swapped around.

Note that no additional information from the InteractionSet (beyond that in `interactions`) is used for sorting or duplicate marking, i.e., the assay or metadata values for each interaction are not used in distinguishing rows with the same interaction. For this reason, the `pcompare` method is not implemented for InteractionSet objects. It makes little sense to do a parallel comparison in an InteractionSet without examining the data.

### Author(s)

Aaron Lun

### See Also

`GInteractions-class`, `InteractionSet-class`, `match`, `pcompare`

### Examples

    example(GInteractions, echo=FALSE)

    anchors(gi, id=TRUE)
    anchors(swapAnchors(gi, mode="all"), id=TRUE)
    gi <- swapAnchors(gi)

    anchors(gi)
    gi2 <- sort(gi)
    gi2
    anchors(gi2)

    # Can also order them.
    o <- order(gi)
    o
    stopifnot(all.equal(gi[o], gi2))

    # Checking duplication.
    summary(duplicated(gi))
    summary(duplicated(c(gi, gi)))
    stopifnot(all.equal(unique(gi), unique(c(gi, gi))))

    # Matching and comparing.
    another.gi <- gi[sample(length(gi))]
    match(gi, another.gi)
    match(gi, another.gi[1:5])

    pcompare(gi, another.gi)

    #################
    # Same can be done for an InteractionSet object:

    example(InteractionSet, echo=FALSE)
    iset <- swapAnchors(iset)

    anchors(iset)
    anchors(sort(iset))
    order(iset)
    summary(duplicated(iset))
    unique(iset)

[Package InteractionSet version 1.12.0 Index]