calculateMDS {scater} | R Documentation

## Perform MDS on cell-level data

### Description

Perform multi-dimensional scaling (MDS) on cells, based on the data in a SingleCellExperiment object.

### Usage

    calculateMDS(x, ...)

    ## S4 method for signature 'ANY'
    calculateMDS(
      x,
      FUN = dist,
      ncomponents = 2,
      ntop = 500,
      subset_row = NULL,
      scale = FALSE,
      transposed = FALSE,
      keep_dist = FALSE,
      ...
    )

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

    ## S4 method for signature 'SingleCellExperiment'
    calculateMDS(
      x,
      ...,
      exprs_values = "logcounts",
      dimred = NULL,
      n_dimred = NULL
    )

    runMDS(x, ..., altexp = NULL, name = "MDS")

### Arguments

`x` | For `calculateMDS`, 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 `runMDS`, a SingleCellExperiment object.
`...` | For the `calculateMDS` generic, additional arguments to pass to specific methods. For the SummarizedExperiment and SingleCellExperiment methods, additional arguments to pass to the ANY method. For `runMDS`, additional arguments to pass to `calculateMDS`.
`FUN` | A function that accepts a numeric matrix as its first argument, where rows are samples and columns are features; and returns a distance structure such as that returned by `dist` or a full symmetric matrix containing the dissimilarities.
`ncomponents` | Numeric scalar indicating the number of MDS?g dimensions to obtain.
`ntop` | Numeric scalar specifying the number of features with the highest variances to use for dimensionality reduction.
`subset_row` | Vector specifying the subset of features to use for dimensionality reduction. This can be a character vector of row names, an integer vector of row indices or a logical vector.
`scale` | Logical scalar, should the expression values be standardized?
`transposed` | Logical scalar, is `x` transposed with cells in rows?
`keep_dist` | Logical scalar indicating whether the `dist` object calculated by `FUN` should be stored as ‘dist’ attribute of the matrix returned/stored by `calculateMDS` or `runMDS`.
`exprs_values` | Integer scalar or string indicating which assay of `x` contains the expression values.
`dimred` | String or integer scalar specifying the existing dimensionality reduction results to use.
`n_dimred` | Integer scalar or vector specifying the dimensions to use if `dimred` is specified.
`altexp` | String or integer scalar specifying an alternative experiment containing the input data.
`name` | String specifying the name to be used to store the result in the `reducedDims` of the output.

### Details

The function `cmdscale` is used internally to compute the MDS components with `eig = TRUE`. The `eig` and `GOF` fields of the object returned by `cmdscale` are stored as attributes “eig” and “GOF” of the MDS matrix calculated.

### Value

For `calculateMDS`, a matrix is returned containing the MDS coordinates for each cell (row) and dimension (column).

For `runMDS`, a modified `x` is returned that contains the MDS coordinates in `reducedDim(x, name)`.

### Feature selection

This section is relevant if `x` is a numeric matrix of (log-)expression values with features in rows and cells in columns; or if `x` is a SingleCellExperiment and `dimred=NULL`. In the latter, the expression values are obtained from the assay specified by `exprs_values`.

The `subset_row` argument specifies the features to use for dimensionality reduction. The aim is to allow users to specify highly variable features to improve the signal/noise ratio, or to specify genes in a pathway of interest to focus on particular aspects of heterogeneity.

If `subset_row=NULL`, the `ntop` features with the largest variances are used instead. We literally compute the variances from the expression values without considering any mean-variance trend, so often a more considered choice of genes is possible, e.g., with scran functions. Note that the value of `ntop` is ignored if `subset_row` is specified.

If `scale=TRUE`, the expression values for each feature are standardized so that their variance is unity. This will also remove features with standard deviations below 1e-8.

### Using reduced dimensions

If `x` is a SingleCellExperiment, the method can be applied on existing dimensionality reduction results in `x` by setting the `dimred` argument. This is typically used to run slower non-linear algorithms (t-SNE, UMAP) on the results of fast linear decompositions (PCA). We might also use this with existing reduced dimensions computed from a priori knowledge (e.g., gene set scores), where further dimensionality reduction could be applied to compress the data.

The matrix of existing reduced dimensions is taken from `reducedDim(x, dimred)`. By default, all dimensions are used to compute the second set of reduced dimensions. If `n_dimred` is also specified, only the first `n_dimred` columns are used. Alternatively, `n_dimred` can be an integer vector specifying the column indices of the dimensions to use.

When `dimred` is specified, no additional feature selection or standardization is performed. This means that any settings of `ntop`, `subset_row` and `scale` are ignored.

If `x` is a numeric matrix, setting `transposed=TRUE` will treat the rows as cells and the columns as the variables/diemnsions. This allows users to manually pass in dimensionality reduction results without needing to wrap them in a SingleCellExperiment. As such, no feature selection or standardization is performed, i.e., `ntop`, `subset_row` and `scale` are ignored.

### Using alternative Experiments

This section is relevant if `x` is a SingleCellExperiment and `altexp` is not `NULL`. In such cases, the method is run on data from an alternative SummarizedExperiment nested within `x`. This is useful for performing dimensionality reduction on other features stored in `altExp(x, altexp)`, e.g., antibody tags.

Setting `altexp` with `exprs_values` will use the specified assay from the alternative SummarizedExperiment. If the alternative is a SingleCellExperiment, setting `dimred` will use the specified dimensionality reduction results from the alternative. This option will also interact as expected with `n_dimred`.

Note that the output is still stored in the `reducedDims` of the output SingleCellExperiment. It is advisable to use a different `name` to distinguish this output from the results generated from the main experiment's assay values.

### Author(s)

Aaron Lun, based on code by Davis McCarthy

### See Also

`cmdscale`, to perform the underlying calculations.

`dist` for the function used as default to calculate the `dist` object.

`plotMDS`, to quickly visualize the results.

### Examples

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

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

[Package scater version 1.22.0 Index]