plotExpression {scater} | R Documentation

## Plot expression values for a set of features (e.g. genes or transcripts)

### Description

Plot expression values for a set of features (e.g. genes or transcripts)

### Usage

    plotExpression(object, features, x = NULL, exprs_values = "logcounts",
      log2_values = FALSE, colour_by = NULL, shape_by = NULL,
      size_by = NULL, ncol = 2, xlab = NULL, show_median = FALSE,
      show_violin = TRUE, theme_size = 10, ...)

    plotExpressionDefault(object, aesth, ncol = 2, xlab = NULL, ylab = NULL,
      show_median = FALSE, show_violin = TRUE, show_smooth = FALSE,
      theme_size = 10, alpha = 0.6, size = NULL, scales = "fixed",
      one_facet = FALSE, se = TRUE, jitter = "swarm")

### Arguments

`object` | an `SingleCellExperiment` object containing expression values and experimental information. Must have been appropriately prepared. For the `plotExpressionDefault` method, the `object` argument is a data.frame in 'long' format providing expression values for a set of features to plot, plus metadata used in the `aesth` argument, but this is not meant to be a user-level operation.
`features` | a character vector of feature names or Boolean vector or numeric vector of indices indicating which features should have their expression values plotted
`x` | character string providing a column name of `pData(object)` or a feature name (i.e. gene or transcript) to plot on the x-axis in the expression plot(s). If a feature name, then expression values for the feature will be plotted on the x-axis for each subplot.
`exprs_values` | character string indicating which values should be used as the expression values for this plot. Valid arguments are `"tpm"` (transcripts per million), `"norm_tpm"` (normalised TPM values), `"fpkm"` (FPKM values), `"norm_fpkm"` (normalised FPKM values), `"counts"` (counts for each feature), `"norm_counts"`, `"cpm"` (counts-per-million), `"norm_cpm"` (normalised counts-per-million), `"logcounts"` (log-transformed count data; default), `"norm_exprs"` (normalised expression values) or `"stand_exprs"` (standardised expression values) or any other slots that have been added to the `"assayData"` slot by the user.
`log2_values` | should the expression values be transformed to the log2-scale for plotting (with an offset of 1 to avoid logging zeroes)?
`colour_by` | optional character string supplying name of a column of `pData(object)` which will be used as a variable by which to colour expression values on the plot. Alternatively, a data frame with one column, containing a value for each cell that will be mapped to a colour.
`shape_by` | optional character string supplying name of a column of `pData(object)` which will be used as a variable to define the shape of points for expression values on the plot. Alternatively, a data frame with one column containing values to map to shapes.
`size_by` | optional character string supplying name of a column of `pData(object)` which will be used as a variable to define the size of points for expression values on the plot. Alternatively, a data frame with one column containing values to map to sizes.
`ncol` | number of columns to be used for the panels of the plot
`xlab` | label for x-axis; if `NULL` (default), then `x` will be used as the x-axis label
`show_median` | logical, show the median for each group on the plot
`show_violin` | logical, show a violin plot for the distribution for each group on the plot
`theme_size` | numeric scalar giving default font size for plotting theme (default is 10)
`...` | optional arguments (from those listed above) passed to `plotExpressionDefault`
`aesth` | an `aes` object to use in the call to `ggplot`.
`ylab` | character string defining a label for the y-axis (y-axes) of the plot.
`show_smooth` | logical, show a smoothed fit through the expression values on the plot
`alpha` | numeric value between 0 (completely transparent) and 1 (completely solid) defining how transparent plotted points (cells) should be. Points are jittered horizontally if the x-axis value is categorical rather than numeric to avoid overplotting.
`size` | numeric scalar optionally providing size for points if `size_by` argument is not given. Default is `NULL`, in which case ggplot2 default is used.
`scales` | character scalar, should scales be fixed ("fixed"), free ("free"), or free in one dimension ("free_x"; "free_y", the default). Passed to the `scales` argument in the `facet_wrap` function from the `ggplot2` package.
`one_facet` | logical, should expression values for features be plotted in one facet instead of mutiple facets, one per feature? Default if `x = NULL`.
`se` | logical, should standard errors be shown (default `TRUE`) for the smoothed fit through the cells. (Ignored if `show_smooth` is `FALSE`).
`jitter` | character scalar to define whether points are to be jittered (`"jitter"`) or presented in a "beeswarm" style (if `"swarm"`; default). "Beeswarm" style usually looks more attractive, but for datasets with a large number of cells, or for dense plots, the jitter option may work better.

### Details

Plot expression values (default log2(counts-per-million + 1), if available) for a set of features.

### Value

a ggplot plot object

### 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)
    plotExpression(example_sce, 1:15, jitter = "jitter")

    ## plot expression against an x-axis value
    plotExpression(example_sce, 1:6, "Mutation_Status")

    ## explore options
    plotExpression(example_sce, 1:6, x = "Mutation_Status", exprs_values = "logcounts",
    colour_by = "Cell_Cycle", show_violin = TRUE, show_median = TRUE)
    plotExpression(example_sce, 1:6, x = "Mutation_Status", exprs_values = "counts",
    colour_by = "Cell_Cycle", show_violin = TRUE, show_median = TRUE)

    plotExpression(example_sce, "Gene_0001", x = "Mutation_Status")
    plotExpression(example_sce, c("Gene_0001", "Gene_0004"), x="Mutation_Status")
    plotExpression(example_sce, "Gene_0001", x = "Gene_0002")
    plotExpression(example_sce, c("Gene_0001", "Gene_0004"), x="Gene_0002")
    ## plot expression against expression values for Gene_0004
    plotExpression(example_sce, 1:4, "Gene_0004")
    plotExpression(example_sce, 1:4, "Gene_0004", show_smooth = TRUE)
    plotExpression(example_sce, 1:4, "Gene_0004", show_smooth = TRUE, se = FALSE)

[Package scater version 1.6.3 Index]