Reduced dimension plots {scater} | R Documentation

## Plot specific reduced dimensions

### Description

Wrapper functions to create plots for specific types of reduced dimension results in a SingleCellExperiment object, or, if they are not already present, to calculate those results and then plot them.

### Usage

    plotPCASCE(object, ..., return_SCE = FALSE, draw_plot = TRUE,
      rerun = FALSE, ncomponents = 2, run_args = list())

    plotTSNE(object, ..., return_SCE = FALSE, draw_plot = TRUE, rerun = FALSE,
      ncomponents = 2, run_args = list())

    plotDiffusionMap(object, ..., return_SCE = FALSE, draw_plot = TRUE,
      rerun = FALSE, ncomponents = 2, run_args = list())

    plotMDS(object, ..., ncomponents = 2, return_SCE = FALSE, rerun = FALSE,
      draw_plot = TRUE, run_args = list())

    ## S4 method for signature 'SingleCellExperiment'
    plotPCA(object, ..., return_SCE = FALSE,
      draw_plot = TRUE, rerun = FALSE, ncomponents = 2, run_args = list())

### Arguments

`object` | A SingleCellExperiment object.
`...` | Additional arguments to pass to `plotReducedDim`.
`return_SCE` | Logical, should the function return a SingleCellExperiment object with reduced dimension results in the `reducedDim` slot? Default is `FALSE`, in which case a `ggplot` object is returned. This will be deprecated in the next release in favour of directly calling the underlying `run*` functions to compute the results.
`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.
`rerun` | Logical, should the reduced dimensions be recomputed even if `object` contains an appropriately named set of results in the `reducedDims` slot?
`ncomponents` | Numeric scalar indicating the number of dimensions components to (calculate and) plot. This can also be a numeric vector, see `?plotReducedDim` for details.
`run_args` | Arguments to pass to `runPCA`.

### Details

Each function will search the `reducedDims` slot for an appropriately named set of results and pass those coordinates onto `plotReducedDim`. If the results are not present or `rerun=TRUE`, they will be computed using the relevant `run*` function. The result name and `run*` function for each `plot*` function are:

- `"PCA"` and `runPCA` for `plotPCA`

- `"TSNE"` and `runTSNE` for `plotTSNE`

- `"DiffusionMap"` and `runDiffusionMap` for `plotDiffusionMap`

- `"MDS"` and `runMDS` for `"plotMDS"`

Users can specify arguments to the `run*` functions via `run_args`.

If `ncomponents` is a numeric vector, the maximum value will be used to determine the required number of dimensions to compute in the `run*` functions. However, only the specified dimensions in `ncomponents` will be plotted.

### Value

A ggplot object or an SingleCellExperiment object, depending on `return_SCE`.

### Author(s)

Davis McCarthy, with modifications by Aaron Lun

### See Also

`runPCA`, `runDiffusionMap`, `runTSNE`, `runMDS`, `plotReducedDim`

### 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)

    ## Examples plotting PC1 and PC2
    plotPCA(example_sce)
    plotPCA(example_sce, colour_by = "Cell_Cycle")
    plotPCA(example_sce, colour_by = "Cell_Cycle", shape_by = "Treatment")
    plotPCA(example_sce, colour_by = "Cell_Cycle", shape_by = "Treatment",
        size_by = "Mutation_Status")

    ## Force legend to appear for shape:
    example_subset <- example_sce[, example_sce$Treatment == "treat1"]
    plotPCA(example_subset, colour_by = "Cell_Cycle", shape_by = "Treatment",
        by_show_single = TRUE)

    ## Examples plotting more than 2 PCs
    plotPCA(example_sce, ncomponents = 4, colour_by = "Treatment",
        shape_by = "Mutation_Status")

    ## Same for TSNE:
    plotTSNE(example_sce, perplexity = 10)

    ## Same for DiffusionMaps:
    plotDiffusionMap(example_sce)

    ## Same for MDS plots:
    plotMDS(example_sce)

[Package scater version 1.8.4 Index]