getClusterIndex {clusterExperiment} | R Documentation

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

[Package clusterExperiment version 2.7.2 Index]