getClusterIndex: getClusterIndex

In epurdom/clusterCells: Compare Clusterings for Single-Cell Sequencing

getClusterIndex

Description

Finds index of clustering in clusterMatrix slot of object based on descriptions of clusters.

Usage

## S4 method for signature 'ClusterExperiment'
getClusterIndex(
  object,
  whichClusters,
  noMatch = c("silentlyRemove", "throwError")
)

## S4 method for signature 'ClusterExperiment'
getSingleClusterIndex(object, whichCluster, passedArgs = NULL, ...)

Arguments

object	a ClusterExperiment object
whichClusters	argument that can be either numeric or character vector indicating the clusterings to be used. See details of getClusterIndex.
noMatch	how to handle if there is no match to an given value of whichClusters. "silentlyRemove" means that no error will be given, and the result will be just those that do match (resulting in a vector of length zero if there are none that match). "throwError" means that the function will stop with an error describing the problem with the match.
whichCluster	argument that can be a single numeric or character value indicating the single clustering to be used. Giving values that result in more than one clustering will result in an error. See details of getClusterIndex.
passedArgs	other arguments passed to the function (only used internally)
...	Not for user use. Argument allows function getSingleClusterIndex to catch the wrong argument (the plural whichClusters argument rather than singular whichCluster).

Details

The function getClusterIndex is largely used internally to parse the argument whichClusters which is used as an argument extensively across functions in this package. Note that some functions require the match return a single clustering, in which case those functions use the function getSingleClusterIndex with the singular argument whichCluster and returns an error if it indicates more than one clustering. Furthermore getSingleClusterIndex does not allow for any mismatches (noMatch="throwError". Otherwise the parsing of the two arguments whichClusters and whichCluster is the same, and is described in what follows.

If whichClusters is numeric, then the function just returns the numeric values of whichClusters, after checking that they are valid. If any are invalid, they are silently removed if silentlyRemove=TRUE. The values will be returned in the order given, so this argument can also be used to defined by functions to give an ordering for the clusterings (as relevant).

If whichClusters is a character value, then it the function attempts to use the character value to identify the clustering. The value of the argument is first matched against a set of "special" values: "workflow","all","none","primaryCluster","dendro" using the argument match.arg, which does partial matching. If whichClusters is a vector of values, only the first value of the vector is matched against these values and if it matches, the remaining values are ignored. If it matches one of these values, then the cluster indices are given as follows.

• "workflow"all clusterings in the current workflow (see workflowClusters)

• "all"all clusterings, with the primary clustering put first.

• "none"no clusterings

• "primaryCluster"the primary clustering index as given by primaryClusterIndex

• "dendro"the index of the clustering given to create the cluster dendrogram, if it exists

@details If whichClusters is a character value, but its first element does not match these predesignated values, then all the values of whichClusters are attempted to be matched to the clusterTypes of the object. Note that there may be more than one clustering that matches a given type. For any entries that do not match a value in clusterTypes(object) are then matched based on the value of clusterLabels of the object.

Value

getClusterIndex returns a vector of all numeric indices that are indicated by the requested whichClusters. Note that there is not a one-to-one match between input values and returned values since there may be more than one value for a given value of whichClusters or no value at all.

Examples

#load CE object
data(rsecFluidigm)
# get the cluster index from mergeClusters step
getClusterIndex(rsecFluidigm,whichClusters="mergeClusters")
# get the cluster indices from mergeClusters step
getClusterIndex(rsecFluidigm,whichClusters="clusterMany")

epurdom/clusterCells documentation built on Oct. 12, 2022, 4:44 a.m.