calculateTSNE {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

    calculateTSNE(x, ...)

    ## S4 method for signature 'ANY'
    calculateTSNE(x, ncomponents = 2, ntop = 500,
      subset_row = NULL, feature_set = NULL, scale = FALSE,
      scale_features = NULL, transposed = FALSE, perplexity = NULL,
      normalize = TRUE, theta = 0.5, ..., external_neighbors = FALSE,
      BNPARAM = KmknnParam(), BPPARAM = SerialParam())

    ## S4 method for signature 'SummarizedExperiment'
    calculateTSNE(x, ...,
      exprs_values = "logcounts")

    ## S4 method for signature 'SingleCellExperiment'
    calculateTSNE(x, ...,
      pca = is.null(dimred), exprs_values = "logcounts", dimred = NULL,
      use_dimred = NULL, n_dimred = NULL)

    runTSNE(x, ..., altexp = NULL, name = "TSNE")

### Arguments

`x` | For `calculateTSNE`, a numeric matrix of log-expression values where rows are features and columns are cells. Alternatively, a SummarizedExperiment or SingleCellExperiment containing such a matrix. For `runTSNE`, a SingleCellExperiment object.
`...` | For the `calculateTSNE` generic, additional arguments to pass to specific methods. For the ANY method, additional arguments to pass to `Rtsne`. For the SummarizedExperiment and SingleCellExperiment methods, additional arguments to pass to the ANY method. For `runTSNE`, additional arguments to pass to `calculateTSNE`.
`ncomponents` | Numeric scalar indicating the number of t-SNE dimensions to obtain.
`ntop` | Numeric scalar specifying the number of features with the highest variances to use for PCA, see `?"scater-red-dim-args"`.
`subset_row` | Vector specifying the subset of features to use for PCA, see `?"scater-red-dim-args"`.
`feature_set` | Deprecated, same as `subset_row`.
`scale` | Logical scalar, should the expression values be standardised? See `?"scater-red-dim-args"` for details.
`scale_features` | Deprecated, same as `scale` but with a different default.
`transposed` | Logical scalar, is `x` transposed with cells in rows? See `?"scater-red-dim-args"` for details.
`perplexity` | Numeric scalar defining the perplexity parameter, see `?Rtsne` for more details.
`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`.
`exprs_values` | Integer scalar or string indicating which assay of `x` contains the expression values, see `?"scater-red-dim-args"`.
`pca` | Logical scalar indicating whether a PCA step should be performed inside `Rtsne`.
`dimred` | String or integer scalar specifying the existing dimensionality reduction results to use, see `?"scater-red-dim-args"`.
`use_dimred` | Deprecated, same as `dimred`.
`n_dimred` | Integer scalar or vector specifying the dimensions to use if `dimred` is specified, see `?"scater-red-dim-args"`.
`altexp` | String or integer scalar specifying an alternative experiment to use to compute the PCA, see `?"scater-red-dim-args"`.
`name` | String specifying the name to be used to store the result in the `reducedDims` of the output.

### 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 set a “reasonable” perplexity that scales with the number of cells in `x`. (Specifically, it is the number of cells divided by 5, capped at a maximum of 50.) However, it is often worthwhile to manually try multiple values to ensure that the conclusions are robust.

If `external_neighbors=TRUE`, the nearest neighbor search step will use 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.

If `dimred` is specified, the PCA step of the `Rtsne` function is automatically turned off by default. This presumes that the existing dimensionality reduction is sufficient such that an additional PCA is not required.

### Value

For `calculateTSNE`, a numeric matrix is returned containing the t-SNE coordinates for each cell (row) and dimension (column).

For `runTSNE`, a modified `x` is returned that contains the t-SNE coordinates in `reducedDim(x, name)`.

### Author(s)

Aaron Lun, based on code by Davis McCarthy

### References

van der Maaten LJP, Hinton GE (2008). Visualizing High-Dimensional Data Using t-SNE. J. Mach. Learn. Res. 9, 2579-2605.

### See Also

`Rtsne`, for the underlying calculations.

`plotTSNE`, to quickly visualize the results.

`?"scater-red-dim-args"`, for a full description of various options.

### Examples

    example_sce <- mockSCE()
    example_sce <- logNormCounts(example_sce)

    example_sce <- runTSNE(example_sce, scale_features=NULL)
    reducedDimNames(example_sce)
    head(reducedDim(example_sce))

[Package scater version 1.14.0 Index]