colPairs: Column pair methods
In SingleCellExperiment: S4 Classes for Single Cell Data

Description Getters Single setter Other setters Interaction with SingleCellExperiment operations Author(s) See Also Examples

Methods to get or set column pairings in a SingleCellExperiment object. These are typically used to store and retrieve relationships between cells, e.g., in nearest-neighbor graphs or for inferred cell-cell interactions.

In the following examples, x is a SingleCellExperiment object.

colPair(x, type, asSparse=FALSE):

Retrieves a SelfHits object where each entry represents a pair of columns of x and has number of nodes equal to ncol(x). type is either a string specifying the name of the column pairing in x to retrieve, or a numeric scalar specifying the index of the desired result.

If asSparse=TRUE, a sparse matrix is returned instead, see below for details.

colPairNames(x):

Returns a character vector containing the names of all column pairings in x. This is guaranteed to be of the same length as the number of results, though the names may not be unique.

colPairs(x, asSparse=FALSE):

Returns a named List of matrices containing one or more column pairings as SelfHits objects. If asSparse=FALSE, each entry is instead a sparse matrix.

When asSparse=TRUE, the return value will be a triplet-form sparse matrix where each row/column corresponds to a column of x. The values in the matrix will be taken from the first metadata field of the underlying SelfHits object, with an error being raised if the first metadata field is not of an acceptable type. If there are duplicate pairs, only the value from the last pair is used. If no metadata is available, the matrix values are set to TRUE for all pairs.

colPair(x, type) <- value will add or replace a column pairing in a SingleCellExperiment object x. The value of type determines how the pairing is added or replaced:

If type is missing, value is assigned to the first pairing. If the pairing already exists, its name is preserved; otherwise it is given a default name "unnamed1".
If type is a numeric scalar, it must be within the range of existing pairings, and value will be assigned to the pairing at that index.
If type is a string and a pairing exists with this name, value is assigned to to that pairing. Otherwise a new pairing with this name is append to the existing list of pairings.

value is expected to be a SelfHits with number of nodes equal to ncol(x). Any number of additional fields can be placed in mcols(value). Duplicate column pairs are supported and will not be collapsed into a single entry.

value may also be a sparse matrix with number of rows and columns equal to ncol(x). This is converted into a SelfHits object with values stored in the metadata as the "x" field.

Alternatively, if value is NULL, the pairings corresponding to type are removed from x.

In the following examples, x is a SingleCellExperiment object.

colPairs(x) <- value:

Replaces all column pairings in x with those in value. The latter should be a list-like object containing any number of SelfHits or sparse matrices, each of which is subject to the constraints described for the single setter.

If value is named, those names will be used to name the column pairings in x. Otherwise, unnamed pairings are assigned default names prefixed with "unnamed".

If value is NULL, all column pairings in x are removed.

colPairNames(x) <- value:

Replaces all names for column pairings in x with a character vector value. This should be of length equal to the number of pairings currently in x.

When column-subset replacement is performed on a SingleCellExperiment object (i.e., x[,i] <- y), a pair of columns in colPair(x) is only replaced if both columns are present in i. This replacement not only affects the value of the pair but also whether it even exists in y. For example, if a pair exists between two columns in x[,i] but not in the corresponding columns of y, it is removed upon subset replacement.

Importantly, pairs in x with only one column in i are preserved by replacement. This ensures that x[,i] <- x[,i] is a no-op. However, if the replacement is fundamentally altering the identity of the features in x[,i], it is unlikely that the pairings involving the old identities are applicable to the replacement features in y. In such cases, additional pruning may be required to remove all pairs involving i prior to replacement.

Another interesting note is that, for some i <- 1:n where n is in [1, ncol(x)), cbind(x[,i], x[,-i]) will not return a SingleCellExperiment equal to x with respect to colPairs. This operation will remove any pairs involving one column in i and another column outside of i, simply because each individual subset operation will remove pairs involving columns outside of the subset.

Aaron Lun

rowPairs, for the row equivalent.

example(SingleCellExperiment, echo=FALSE)

# Making up some regulatory pairings:
hits <- SelfHits(
    sample(ncol(sce), 10),
    sample(ncol(sce), 10),
    nnode=ncol(sce)
)
mcols(hits)$value <- runif(10)

colPair(sce, "regulators") <- hits
colPair(sce, "regulators")

as.mat <- colPair(sce, "regulators", asSparse=TRUE)
class(as.mat)

colPair(sce, "coexpression") <- hits
colPairs(sce)

colPair(sce, "regulators") <- NULL
colPairs(sce)

colPairs(sce) <- SimpleList()
colPairs(sce)