quickSubCluster {scran} | R Documentation

## Quick and dirty subclustering

### Description

Performs a quick subclustering for all cells within each group.

### Usage

    quickSubCluster(x, ...)

    ## S4 method for signature 'ANY'
    quickSubCluster(x, groups, normalize = TRUE,
      prepFUN = NULL, min.ncells = 50, clusterFUN = NULL,
      format = "%s.%s")

    ## S4 method for signature 'SingleCellExperiment'
    quickSubCluster(x, groups,
      normalize = TRUE, prepFUN = NULL, min.ncells = 50,
      clusterFUN = NULL, format = "%s.%s", assay.type = "counts")

### Arguments

`x` | A matrix of counts or log-normalized expression values (if `normalize=FALSE`). Alternatively, a SingleCellExperiment object containing such a matrix.
`...` | Further arguments to pass to specific methods.
`groups` | A vector of group assignments for all cells, usually corresponding to cluster identities.
`normalize` | Logical scalar indicating whether each subset of `x` should be log-transformed prior to further analysis.
`prepFUN` | A function that accepts a single SingleCellExperiment object and returns another SingleCellExperiment containing any additional elements required for clustering (e.g., PCA results).
`min.ncells` | An integer scalar specifying the minimum number of cells in a group to be considered for subclustering.
`clusterFUN` | A function that accepts a single SingleCellExperiment object and returns a vector of cluster assignments for each cell in that object.
`format` | A string to be passed to `sprintf`, specifying how the subclusters should be named with respect to the parent level in `groups` and the level returned by `clusterFUN`.
`assay.type` | String or integer scalar specifying the relevant assay.

### Details

`quickSubCluster` is a simple convenience function that loops over all levels of `groups` to perform subclustering. It subsets `x` to retain all cells in one level and then runs `prepFUN` and `clusterFUN` to cluster them. Levels with fewer than `min.ncells` are not subclustered and have `"subcluster"` set to the name of the level.

The distinction between `prepFUN` and `clusterFUN` is that the former's calculations are preserved in the output. For example, we would put the PCA in `prepFUN` so that the PCs are returned in the `reducedDims` for later use. In contrast, `clusterFUN` is only used to obtain the subcluster assignments so any intermediate objects are lost.

By default, `prepFUN` will run `modelGeneVar`, take the top 10 `clusterFUN` will then perform graph-based clustering with `buildSNNGraph` and `cluster_walktrap`. Either or both of these functions can be replaced with custom functions.

The default behavior of this function is the same as running `quickCluster` on each subset with default parameters except for `min.size=0`.

### Value

A named List of SingleCellExperiment objects. Each object corresponds to a level of `groups` and contains a `"subcluster"` column metadata field with the subcluster identities for each cell.

### Author(s)

Aaron Lun

### See Also

`quickCluster`, for a related function to quickly obtain clusters.

### Examples

    library(scater)
    sce <- mockSCE(ncells=200)

    # Lowering min.size for this small demo:
    clusters <- quickCluster(sce, min.size=50)

    # Getting subclusters:
    out <- quickSubCluster(sce, clusters)

    # Defining custom prep functions:
    out2 <- quickSubCluster(sce, clusters,
        prepFUN=function(x) {
            dec <- modelGeneVarWithSpikes(x, "Spikes")
            top <- getTopHVGs(dec, prop=0.2)
            runPCA(x, subset_row=top, ncomponents=25)
        }
    )

    # Defining custom cluster functions:
    out3 <- quickSubCluster(sce, clusters,
        clusterFUN=function(x) {
            kmeans(reducedDim(x, "PCA"), sqrt(ncol(x)))$cluster
        }
    )

[Package scran version 1.14.6 Index]