plotExpression {scater} | R Documentation

## Plot expression values for all cells

### Description

Plot expression values for a set of features (e.g. genes or transcripts) in a SingleExperiment object, against a continuous or categorical covariate for all cells.

### Usage

    plotExpression(
      object,
      features,
      x = NULL,
      exprs_values = "logcounts",
      log2_values = FALSE,
      colour_by = NULL,
      shape_by = NULL,
      size_by = NULL,
      by_exprs_values = exprs_values,
      xlab = NULL,
      feature_colours = TRUE,
      one_facet = TRUE,
      ncol = 2,
      scales = "fixed",
      other_fields = list(),
      swap_rownames = NULL,
      ...
    )

### Arguments

`object` | A SingleCellExperiment object containing expression values and other metadata.
`features` | A character vector or a list specifying the features to plot. If a list is supplied, each entry of the list can be a string, an AsIs-wrapped vector or a data.frame - see `?retrieveCellInfo`.
`x` | Specification of a column metadata field or a feature to show on the x-axis, see the `by` argument in `?retrieveCellInfo` for possible values.
`exprs_values` | A string or integer scalar specifying which assay in `assays(object)` to obtain expression values from.
`log2_values` | Logical scalar, specifying whether the expression values be transformed to the log2-scale for plotting (with an offset of 1 to avoid logging zeroes).
`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`.
`xlab` | String specifying the label for x-axis. If `NULL` (default), `x` will be used as the x-axis label.
`feature_colours` | Logical scalar indicating whether violins should be coloured by feature when `x` and `colour_by` are not specified and `one_facet=TRUE`.
`one_facet` | Logical scalar indicating whether grouped violin plots for multiple features should be put onto one facet. Only relevant when `x=NULL`.
`ncol` | Integer scalar, specifying the number of columns to be used for the panels of a multi-facet plot.
`scales` | String indicating whether should multi-facet scales be fixed (`"fixed"`), free (`"free"`), or free in one dimension (`"free_x"`, `"free_y"`). Passed to the `scales` argument in the `facet_wrap` when multiple facets are generated.
`other_fields` | Additional cell-based fields to include in the data.frame, see `?"scater-plot-args"` for details.
`swap_rownames` | Column name of `rowData(object)` to be used to identify features instead of `rownames(object)` when labelling plot elements.
`...` | Additional arguments for visualization, see `?"scater-plot-args"` for details.

### Details

This function plots expression values for one or more features. If `x` is not specified, a violin plot will be generated of expression values. If `x` is categorical, a grouped violin plot will be generated, with one violin for each level of `x`. If `x` is continuous, a scatter plot will be generated.

If multiple features are requested and `x` is not specified and `one_facet=TRUE`, a grouped violin plot will be generated with one violin per feature. This will be coloured by feature if `colour_by=NULL` and `feature_colours=TRUE`, to yield a more aesthetically pleasing plot. Otherwise, if `x` is specified or `one_facet=FALSE`, a multi-panel plot will be generated where each panel corresponds to a feature. Each panel will be a scatter plot or (grouped) violin plot, depending on the nature of `x`.

Note that this assumes that the expression values are numeric. If not, and `x` is continuous, horizontal violin plots will be generated. If `x` is missing or categorical, rectangule plots will be generated where the area of a rectangle is proportional to the number of points for a combination of factors.

### Value

A ggplot object.

### Author(s)

Davis McCarthy, with modifications by Aaron Lun

### Examples

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

    ## default plot
    plotExpression(example_sce, rownames(example_sce)[1:15])

    ## plot expression against an x-axis value
    plotExpression(example_sce, c("Gene_0001", "Gene_0004"),
        x="Mutation_Status")
    plotExpression(example_sce, c("Gene_0001", "Gene_0004"),
        x="Gene_0002")

    ## add visual options
    plotExpression(example_sce, rownames(example_sce)[1:6],
        colour_by = "Mutation_Status")
    plotExpression(example_sce, rownames(example_sce)[1:6],
        colour_by = "Mutation_Status", shape_by = "Treatment",
        size_by = "Gene_0010")

    ## plot expression against expression values for Gene_0004
    plotExpression(example_sce, rownames(example_sce)[1:4],
        "Gene_0004", show_smooth = TRUE)

[Package scater version 1.22.0 Index]