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, by_show_single = FALSE,
      xlab = NULL, feature_colours = TRUE, one_facet = TRUE, ncol = 2,
      scales = "fixed", ...)

### Arguments

`object` | A SingleCellExperiment object containing expression values and other metadata.
`features` | A character vector (of feature names), a logical vector or numeric vector (of indices) specifying the features to plot.
`x` | Specification of a column metadata field or a feature to show on the x-axis, see `?"scater-vis-var"` 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 `?"scater-vis-var"` for possible values.
`shape_by` | Specification of a column metadata field or a feature to shape by, see `?"scater-vis-var"` for possible values.
`size_by` | Specification of a column metadata field or a feature to size by, see `?"scater-vis-var"` 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 `?"scater-vis-var"` for details.
`by_show_single` | Logical scalar specifying whether single-level factors should be used for point aesthetics, see `?"scater-vis-var"` for details.
`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.
`...` | 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

    ## prepare data
    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 <- calculateQCMetrics(example_sce)
    sizeFactors(example_sce) <- colSums(counts(example_sce))
    example_sce <- normalize(example_sce)

    ## default plot
    plotExpression(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, 1:6, colour_by = "Mutation_Status")
    plotExpression(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, 1:4, "Gene_0004", show_smooth = TRUE)

[Package scater version 1.8.4 Index]