plotReducedDim {scater} | R Documentation

## Plot reduced dimensions

### Description

Plot cell-level reduced dimension results stored in a SingleCellExperiment object.

### Usage

    plotReducedDim(
      object,
      dimred,
      ncomponents = 2,
      percentVar = NULL,
      colour_by = NULL,
      shape_by = NULL,
      size_by = NULL,
      by_exprs_values = "logcounts",
      text_by = NULL,
      text_size = 5,
      text_colour = "black",
      label_format = c("%s %i", " (%i%%)"),
      other_fields = list(),
      ...
    )

### Arguments

`object` | A SingleCellExperiment object.
`dimred` | A string or integer scalar indicating the reduced dimension result in `reducedDims(object)` to plot.
`ncomponents` | A numeric scalar indicating the number of dimensions to plot, starting from the first dimension. Alternatively, a numeric vector specifying the dimensions to be plotted.
`percentVar` | A numeric vector giving the proportion of variance in expression explained by each reduced dimension. Only expected to be used in PCA settings, e.g., in the `plotPCA` function.
`colour_by` | Specification of a column metadata field or a feature to colour by, see the `by` argument in `?retrieveCellInfo` for possible values.
`shape_by` | Specification of a column metadata field or a feature to shape by, see the `by` argument in `?retrieveCellInfo` for possible values.
`size_by` | Specification of a column metadata field or a feature to size by, see the `by` argument in `?retrieveCellInfo` for possible values.
`by_exprs_values` | A string or integer scalar specifying which assay to obtain expression values from, for use in point aesthetics - see the `exprs_values` argument in `?retrieveCellInfo`.
`text_by` | String specifying the column metadata field with which to add text labels on the plot. This must refer to a categorical field, i.e., coercible into a factor. Alternatively, an AsIs vector or data.frame, see `?retrieveCellInfo`.
`text_size` | Numeric scalar specifying the size of added text.
`text_colour` | String specifying the colour of the added text.
`label_format` | Character vector of length 2 containing format strings to use for the axis labels. The first string expects a string containing the result type (e.g., `"PCA"`) and an integer containing the component number, while the second string shows the rounded percentage of variance explained and is only relevant when this information is provided in `object`.
`other_fields` | Additional cell-based fields to include in the data.frame, see `?"scater-plot-args"` for details.
`...` | Additional arguments for visualization, see `?"scater-plot-args"` for details.

### Details

If `ncomponents` is a scalar equal to 2, a scatterplot of the first two dimensions is produced. If `ncomponents` is greater than 2, a pairs plots for the top dimensions is produced.

Alternatively, if `ncomponents` is a vector of length 2, a scatterplot of the two specified dimensions is produced. If it is of length greater than 2, a pairs plot is produced containing all pairwise plots between the specified dimensions.

The `text_by` option will add factor levels as labels onto the plot, placed at the median coordinate across all points in that level. This is useful for annotating position-related metadata (e.g., clusters) when there are too many levels to distinguish by colour. It is only available for scatterplots.

### Value

A ggplot object

### Author(s)

Davis McCarthy, with modifications by Aaron Lun

### Examples

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

    example_sce <- runPCA(example_sce, ncomponents=5)
    plotReducedDim(example_sce, "PCA")
    plotReducedDim(example_sce, "PCA", colour_by="Cell_Cycle")
    plotReducedDim(example_sce, "PCA", colour_by="Gene_0001")

    plotReducedDim(example_sce, "PCA", ncomponents=5)
    plotReducedDim(example_sce, "PCA", ncomponents=5, colour_by="Cell_Cycle",
        shape_by="Treatment")

[Package scater version 1.16.2 Index]