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, rand_seed = NULL,
  perplexity = min(50, floor(ncol(object)/5)), pca = TRUE,
  initial_dims = 50, ...)

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.

rand_seed

Deprecated, numeric scalar that can be passed to set.seed to make the results reproducible.

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.

...

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.

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.10.1 Index]