cluster {CATALYST} | R Documentation

## `FlowSOM` clustering & `ConsensusClusterPlus` metaclustering

### Description

`cluster` will first group cells into `xdim`x`ydim` clusters using FlowSOM, and subsequently perform metaclustering with ConsensusClusterPlus into 2 through `maxK` clusters.

### Usage

    cluster(
      x,
      features = "type",
      xdim = 10,
      ydim = 10,
      maxK = 20,
      verbose = TRUE,
      seed = 1
    )

### Arguments

`x` | a `SingleCellExperiment`.
`features` | a character vector specifying which features to use for clustering; valid values are `"type"/"state"` for `type/state_markers(x)` if `rowData(x)$marker_class` have been specified; a subset of `rownames(x)`; NULL to use all features.
`xdim, ydim` | numeric specifying the grid size of the self-orginizing map; passed to `BuildSOM`. The default 10x10 grid will yield 100 clusters.
`maxK` | numeric specifying the maximum number of clusters to evaluate in the metaclustering; passed to `ConsensusClusterPlus`. The default (`maxK = 20`) will yield 2 through 20 metaclusters.
`verbose` | logical. Should information on progress be reported?
`seed` | numeric. Sets the random seed for reproducible results in `ConsensusClusterPlus`.

### Details

The delta area represents the amount of extra cluster stability gained when clustering into k groups as compared to k-1 groups. It can be expected that high stability of clusters can be reached when clustering into the number of groups that best fits the data. The "natural" number of clusters present in the data should thus corresponds to the value of k where there is no longer a considerable increase in stability (pleateau onset).

### Value

a `SingleCellEcperiment` with the following newly added data:

- `colData`

  - `cluster_id`: each cell's cluster ID as inferred by `FlowSOM`. One of 1, ..., `xdim`x`ydim`.

- `rowData`

  - `marker_class`: added when previosly unspecified. `"type"` when an antigen has been used for clustering, otherwise `"state"`.

  - `used_for_clustering`: logical indicating whether an antigen has been used for clustering.

- `metadata`

  - `SOM_codes`: a table with dimensions K x (# cell type markers), where K = `xdim` x `ydim`. Contains the SOM codes.

  - `cluster_codes`: a table with dimensions K x (`maxK` + 1). Contains the cluster codes for all metaclustering.

  - `delta_area`: a `ggplot` object (see details).

### Author(s)

Helena L Crowell helena.crowell@uzh.ch

### References

Nowicka M, Krieg C, Crowell HL, Weber LM et al. CyTOF workflow: Differential discovery in high-throughput high-dimensional cytometry datasets. F1000Research 2017, 6:748 (doi: 10.12688/f1000research.11622.1)

### Examples

    # construct SCE
    data(PBMC_fs, PBMC_panel, PBMC_md)
    sce <- prepData(PBMC_fs, PBMC_panel, PBMC_md)

    # run clustering
    (sce <- cluster(sce))

    # view all available clustering
    names(cluster_codes(sce))

    # access specific clustering resolution
    table(cluster_ids(sce, "meta8"))

    # view delta area plot
    delta_area(sce)

[Package CATALYST version 1.18.1 Index]