plotDeltaDistribution: Plot delta distributions
In SingleR: Reference-Based Single-Cell RNA-Seq Annotation

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

Plot the distribution of deltas (i.e., the gap between the assignment score for the assigned label and those of the remaining labels) across cells assigned to each reference label.

plotDeltaDistribution(
  results,
  show = c("delta.med", "delta.next"),
  labels.use = colnames(results$scores),
  references = NULL,
  chosen.only = TRUE,
  size = 2,
  ncol = 5,
  dots.on.top = TRUE,
  this.color = "#000000",
  pruned.color = "#E69F00",
  grid.vars = list()
)

`results`	A DataFrame containing the output from `SingleR`, `classifySingleR`, `combineCommonResults`, or `combineRecomputedResults`.
`show`	String specifying whether to show the difference from the median (`"delta.med"`) or the difference from the next-best score (`"delta.next"`).
`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.
`chosen.only`	Logical scalar indicating whether to only show deltas for individual labels that were chosen as the final label in a combined result.
`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.
`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 the deltas for all cells across one or more labels. The idea is to provide a visual diagnostic for the confidence of assignment of each cell to its label. The show argument determines what values to show on the y-axis:

"delta.med", the difference between the score of the assigned label and the median of all scores for each cell.
"delta.next", the difference between best and second-best scores of each cell at the last round of fine-tuning.

If any fine-tuning was performed, the highest scoring label for an individual cell may not be its final label. This may manifest as negative values when show="delta.med". show="delta.next" is guaranteed to be positive but may be overly stringent for references involving very similar labels.

Pruned calls are identified as NAs in the pruned.labels field in results. Points corresponding to cells with pruned calls are colored by pruned.color; this can be disabled by setting pruned.color=NA.

For combined results (see ?combineRecomputedResults), this function will show the deltas faceted by the assigned label within each individual reference. The references to show in this manner can be specified using the references argument, entries of which refer to columns of results$orig.results.

By default, a separate plot is created for each individual reference in a combined results. Deltas are only shown in each plot if the label in the corresponding reference was chosen as the overall best label in the combined results. However, this can be changed to show all deltas for an individual reference by setting chosen.only=FALSE.

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

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

If delta.use specifies multiple deltas and grid.vars is set to 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.

plotScoreDistribution and plotScoreHeatmap, for alternative diagnostic plots.

example(SingleR, echo=FALSE)

# Showing the delta to the median:
plotDeltaDistribution(pred)

# Showing the delta to the next-highest score:
plotDeltaDistribution(pred, show = "delta.next")

# Multi-reference compatibility:
example(combineRecomputedResults, echo = FALSE)

plotDeltaDistribution(results = combined)

plotDeltaDistribution(results = combined, chosen.only=FALSE)

# Tweaking the grid controls:
plotDeltaDistribution(combined, grid.vars = list(ncol = 2))