plotScoreDistribution {SingleR} | R 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))

[Package SingleR version 1.8.1 Index]