plotExpression: Plot expression values for all cells

Description Usage Arguments Details Value Author(s) Examples

View source: R/plotExpression.R

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

1
2
3
4
5
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
## 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)

scater documentation built on May 2, 2018, 3:36 a.m.