plotScoreDistribution: Plot score distributions

View source: R/plotScoreDistribution.R

plotScoreDistributionR Documentation

Plot score distributions

Description

Plot the distribution of assignment scores across all cells assigned to each reference label.

Usage

plotScoreDistribution(
  results,
  show = NULL,
  labels.use = colnames(results$scores),
  references = NULL,
  scores.use = NULL,
  calls.use = 0,
  pruned.use = NULL,
  size = 0.5,
  ncol = 5,
  dots.on.top = TRUE,
  this.color = "#F0E442",
  pruned.color = "#E69F00",
  other.color = "gray60",
  show.nmads = 3,
  show.min.diff = NULL,
  grid.vars = list()
)

Arguments

results

A DataFrame containing the output from SingleR, classifySingleR, combineCommonResults, or combineRecomputedResults.

show

Deprecated, use plotDeltaDistribution instead for show!="scores".

labels.use

Character vector specifying the labels to show in the plot facets. Defaults to all labels in results.

references

Integer scalar or vector specifying the references to visualize. This is only relevant for combined results, see Details.

scores.use

Deprecated, see references.

calls.use

Deprecated and ignored.

pruned.use

Deprecated and ignored.

size

Numeric scalar to set the size of the dots.

ncol

Integer scalar to set the number of labels to display per row.

dots.on.top

Logical scalar specifying whether cell dots should be plotted on top of the violin plots.

this.color

String specifying the color for cells that were assigned to the label.

pruned.color

String specifying the color for cells that were assigned to the label but pruned.

other.color

String specifying the color for other cells not assigned to the label.

show.nmads, show.min.diff

Deprecated, use plotDeltaDistribution instead.

grid.vars

Named list of extra variables to pass to grid.arrange, used to arrange the multiple plots generated when references is of length greater than 1.

Details

This function creates jitter and violin plots showing assignment scores for all cells across one or more labels. Each facet represents a label in labels.use and contains three violin plots:

  • “Assigned”, containing scores for all cells assigned to that label. Colored according to this.color. “Pruned”, containing scores for all cells assigned to that label but pruned out, e.g., by pruneScores. Colored according to pruned.color, and can be omitted by setting pruned.color=NA.

  • “Other”, containing the scores for all cells assigned to other labels. Colored according to other.color.

The expectation is that the former is higher than the latter, though the deltas generated by plotDeltaDistribution are often more informative in this regard.

For combined results (see ?combineRecomputedResults), this function can show both the combined and individual scores. This is done using the references argument, entries of which refer to columns of results$orig.results if positive or to the combined results if zero. For example:

  • If we set references=2, we will plot the scores from the second individual reference.

  • If we set references=1:2, we will plot the scores from first and second references (in separate plots) faceted by their corresponding labels.

  • By default, the function will create a separate plot for the combined scores and each individual reference, equivalent to references=0:N for N individual references.

Value

If references specifies a single set of scores, a ggplot object is returned showing the scores in violin plots.

If references specifies multiple scores for a combined result, multiple ggplot objects are generated in a grid on the current graphics device.

If references specifies multiple scores and grid.vars=NULL, a list is returned containing the ggplot objects for manual display.

Author(s)

Daniel Bunis and Aaron Lun

See Also

pruneScores, to remove low-quality labels based on the scores.

plotDeltaDistribution and plotScoreHeatmap, for alternative diagnostic plots.

Examples

example(SingleR, echo=FALSE)

# To show the distribution of scores grouped by label:
plotScoreDistribution(results = pred)

# We can display a particular label using the label
plotScoreDistribution(results = pred,
    labels.use = "B")

# For multiple references, default output will contain separate plots for
# each original reference as well as for the the combined scores.
example(combineRecomputedResults, echo = FALSE)
plotScoreDistribution(results = combined)

# 'references' specifies which original results to plot distributions for.
plotScoreDistribution(results = combined, references = 0)
plotScoreDistribution(results = combined, references = 1:2)

# Tweaking the grid arrangement:
plotScoreDistribution(combined, grid.vars = list(ncol = 2))


LTLA/SingleR documentation built on July 30, 2022, 4:11 a.m.