plotScoreDistribution: Plot score distributions
In SingleR: Reference-Based Single-Cell RNA-Seq Annotation

Description Usage Arguments Details Value Author(s) See Also Examples

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

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()
)

`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.

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.

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.

Daniel Bunis and Aaron Lun

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

plotDeltaDistribution and plotScoreHeatmap, for alternative diagnostic plots.

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))