plotMDS {scater} | R Documentation

## Produce a multidimensional scaling plot for a SingleCellExperiment object

### Description

#' Produce an MDS plot from the cell pairwise distance data in an `SingleCellExperiment` dataset.

### Usage

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

### Arguments

`object` | an `SingleCellExperiment` object
`ncomponents` | numeric scalar indicating the number of principal components to plot, starting from the first principal component. Default is 2. If `ncomponents` is 2, then a scatterplot of PC2 vs PC1 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.
`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.
`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.
`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.
`rerun` | logical, should PCA be recomputed even if `object` contains a "PCA" element in the `reducedDims` slot?
`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.
`exprs_values` | a string specifying the expression values to use for colouring the points, if `colour_by` or `size_by` are set as feature names.
`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).
`...` | arguments passed to S4 plotMDS method

### Details

The function `cmdscale` is used internally to compute the multidimensional scaling components to plot.

### Value

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

### 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
    plotMDS(example_sce)
    plotMDS(example_sce, colour_by = "Cell_Cycle")
    plotMDS(example_sce, colour_by = "Cell_Cycle", shape_by = "Treatment")

    ## define cell-cell distances differently
    plotMDS(example_sce, colour_by = "Cell_Cycle",
    shape_by = "Treatment", size_by = "Mutation_Status", method = "canberra")

[Package scater version 1.6.3 Index]