runTSNE {scater}R Documentation

Plot t-SNE for an SingleCellExperiment object

Description

Produce a t-distributed stochastic neighbour embedding (t-SNE) plot of two components for an SingleCellExperiment dataset.

Usage

runTSNE(object, ntop = 500, ncomponents = 2, exprs_values = "logcounts",
  feature_set = NULL, use_dimred = NULL, n_dimred = NULL,
  scale_features = TRUE, rand_seed = NULL,
  perplexity = floor(ncol(object)/5), ...)

plotTSNE(object, colour_by = NULL, shape_by = NULL, size_by = NULL,
  return_SCE = FALSE, draw_plot = TRUE, theme_size = 10,
  legend = "auto", rerun = FALSE, ncomponents = 2, ...)

Arguments

object

an SingleCellExperiment object

ntop

numeric scalar indicating the number of most variable features to use for the t-SNE Default is 500, but any ntop argument is overrided if the feature_set argument is non-NULL.

ncomponents

numeric scalar indicating the number of t-SNE components to plot, starting from the first t-SNE component. Default is 2. If ncomponents is 2, then a scatterplot of component 1 vs component 2 is produced. If ncomponents is greater than 2, a pairs plots for the top components is produced. NB: computing more than two components for t-SNE can become very time consuming.

exprs_values

character string indicating which values should be used as the expression values for this plot. Valid arguments are "tpm" (transcripts per million), "norm_tpm" (normalised TPM values), "fpkm" (FPKM values), "norm_fpkm" (normalised FPKM values), "counts" (counts for each feature), "norm_counts", "cpm" (counts-per-million), "norm_cpm" (normalised counts-per-million), "logcounts" (log-transformed count data; default), "norm_exprs" (normalised expression values) or "stand_exprs" (standardised expression values), or any other named element of the assayData slot of the SingleCellExperiment object that can be accessed with the assay function.

feature_set

character, numeric or logical vector indicating a set of features to use for the t-SNE calculation. If character, entries must all be in featureNames(object). If numeric, values are taken to be indices for features. If logical, vector is used to index features and should have length equal to nrow(object).

use_dimred

character(1), use named reduced dimension representation of cells stored in SingleCellExperiment object instead of recomputing (e.g. "PCA"). Default is NULL, no reduced dimension values are provided to Rtsne.

n_dimred

integer(1), number of components of the reduced dimension slot to use. Default is NULL, in which case (if use_dimred is not NULL) all components of the reduced dimension slot are used.

scale_features

logical, should the expression values be standardised so that each feature has unit variance? Default is TRUE.

rand_seed

(optional) numeric scalar that can be passed to set.seed to make plots reproducible.

perplexity

numeric scalar value defining the "perplexity parameter" for the t-SNE plot. Passed to Rtsne - see documentation for that package for more details.

...

further arguments passed to Rtsne

colour_by

character string defining the column of pData(object) to be used as a factor by which to colour the points in the plot. Alternatively, a data frame with one column containing values to map to colours for all cells.

shape_by

character string defining the column of pData(object) to be used as a factor by which to define the shape of the points in the plot. Alternatively, a data frame with one column containing values to map to shapes.

size_by

character string defining the column of pData(object) to be used as a factor by which to define the size of points in the plot. Alternatively, a data frame with one column containing values to map to sizes.

return_SCE

logical, should the function return an SingleCellExperiment object with principal component values for cells in the reducedDims slot. Default is FALSE, in which case a ggplot object is returned.

draw_plot

logical, should the plot be drawn on the current graphics device? Only used if return_SCE is TRUE, otherwise the plot is always produced.

theme_size

numeric scalar giving default font size for plotting theme (default is 10).

legend

character, specifying how the legend(s) be shown? Default is "auto", which hides legends that have only one level and shows others. Alternatives are "all" (show all legends) or "none" (hide all legends).

rerun

logical, should PCA be recomputed even if object contains a "PCA" element in the reducedDims slot?

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 plots (see set.seed to set a random seed for replicable results). The value of the perplexity parameter can have a large effect on the resulting plot, so it can often be worthwhile to try multiple values to find the most appealing visualisation.

Value

If return_SCE is TRUE, then the function returns a SingleCellExperiment object, otherwise it returns a ggplot object.

References

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

See Also

Rtsne

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)
drop_genes <- apply(exprs(example_sce), 1, function(x) {var(x) == 0})
example_sce <- example_sce[!drop_genes, ]

## Examples plotting t-SNE
plotTSNE(example_sce, perplexity = 10)
plotTSNE(example_sce, colour_by = "Cell_Cycle", perplexity = 10)
plotTSNE(example_sce, colour_by = "Cell_Cycle", shape_by = "Treatment",
size_by = "Mutation_Status", perplexity = 10)
plotTSNE(example_sce, shape_by = "Treatment", size_by = "Mutation_Status",
perplexity = 5)
plotTSNE(example_sce, feature_set = 1:100, colour_by = "Treatment",
shape_by = "Mutation_Status", perplexity = 5)

plotTSNE(example_sce, shape_by = "Treatment", return_SCE = TRUE,
perplexity = 10)



[Package scater version 1.6.3 Index]