interaction-compare: Interaction comparisons
In InteractionSet: Base Classes for Storing Genomic Interaction Data

Description Usage Arguments Value Sorting and ordering Removing duplicates Matching and comparing Swapping anchors Methods for InteractionSet objects Author(s) See Also Examples

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

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

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

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

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.

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.

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.

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.

Aaron Lun

GInteractions-class, InteractionSet-class, match, pcompare

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)