runTSNE {scater} | R Documentation

## Perform t-SNE on cell-level data

### Description

Perform t-stochastic neighbour embedding (t-SNE) for the cells, based on the data in a SingleCellExperiment object.

### Usage

    runTSNE(object, ncomponents = 2, ntop = 500, feature_set = NULL,
      exprs_values = "logcounts", scale_features = TRUE,
      use_dimred = NULL, n_dimred = NULL, perplexity = min(50,
      floor(ncol(object)/5)), pca = TRUE, initial_dims = 50,
      normalize = TRUE, theta = 0.5, external_neighbors = FALSE,
      BNPARAM = KmknnParam(), BPPARAM = SerialParam(), ...)

### Arguments

`object` | A SingleCellExperiment object.
`ncomponents` | Numeric scalar indicating the number of t-SNE dimensions to obtain.
`ntop` | Numeric scalar specifying the number of most variable features to use for t-SNE.
`feature_set` | Character vector of row names, a logical vector or a numeric vector of indices indicating a set of features to use for t-SNE. This will override any `ntop` argument if specified.
`exprs_values` | Integer scalar or string indicating which assay of `object` should be used to obtain the expression values for the calculations.
`scale_features` | Logical scalar, should the expression values be standardised so that each feature has unit variance?
`use_dimred` | String or integer scalar specifying the entry of `reducedDims(object)` to use as input to `Rtsne`. Default is to not use existing reduced dimension results.
`n_dimred` | Integer scalar, number of dimensions of the reduced dimension slot to use when `use_dimred` is supplied. Defaults to all available dimensions.
`perplexity` | Numeric scalar defining the perplexity parameter, see `?Rtsne` for more details.
`pca` | Logical scalar passed to `Rtsne`, indicating whether an initial PCA step should be performed. This is ignored if `use_dimred` is specified.
`initial_dims` | Integer scalar passed to `Rtsne`, specifying the number of principal components to be retained if `pca=TRUE`.
`normalize` | Logical scalar indicating if input values should be scaled for numerical precision, see `normalize_input`.
`theta` | Numeric scalar specifying the approximation accuracy of the Barnes-Hut algorithm, see `Rtsne` for details.
`external_neighbors` | Logical scalar indicating whether a nearest neighbors search should be computed externally with `findKNN`.
`BNPARAM` | A BiocNeighborParam object specifying the neighbor search algorithm to use when `external_neighbors=TRUE`.
`BPPARAM` | A BiocParallelParam object specifying how the neighbor search should be parallelized when `external_neighbors=TRUE`.
`...` | Additional arguments to pass to `Rtsne`.

### Details

The function `Rtsne` is used internally to compute the t-SNE. Note that the algorithm is not deterministic, so different runs of the function will produce differing results. Users are advised to test multiple random seeds, and then use `set.seed` to set a random seed for replicable results.

The value of the `perplexity` parameter can have a large effect on the results. By default, the function will try to provide a reasonable setting, by scaling the perplexity with the number of cells until it reaches a maximum of 50. However, it is often worthwhile to manually try multiple values to ensure that the conclusions are robust.

Setting `use_dimred` allows users to easily perform t-SNE on low-rank approximations of the original expression matrix (e.g., after PCA). In such cases, arguments such as `ntop`, `feature_set`, `exprs_values` and `scale_features` will be ignored.

If `external_neighbors=TRUE`, the nearest neighbor search step is conducted using a different algorithm to that in the `Rtsne` function. This can be parallelized or approximate to achieve greater speed for large data sets. The neighbor search results are then used for t-SNE via the `Rtsne_neighbors` function.

### Value

A SingleCellExperiment object containing the coordinates of the first `ncomponent` t-SNE dimensions for each cell. This is stored in the `"TSNE"` entry of the `reducedDims` slot.

### Author(s)

Aaron Lun, based on code by Davis McCarthy

### References

L.J.P. van der Maaten. Barnes-Hut-SNE. In Proceedings of the International Conference on Learning Representations, 2013.

### See Also

`Rtsne`, `plotTSNE`

### Examples

    ## Set up an example SingleCellExperiment
    data("sc_example_counts")
    data("sc_example_cell_info")
    example_sce <- SingleCellExperiment(
        assays = list(counts = sc_example_counts),
        colData = sc_example_cell_info
    )
    example_sce <- normalize(example_sce)

    example_sce <- runTSNE(example_sce)
    reducedDimNames(example_sce)
    head(reducedDim(example_sce))

[Package scater version 1.12.2 Index]