plotScoreDistribution {SingleR} | R Documentation

## Plot score distributions of labels.

### Description

Plot score distributions of labels.

### Usage

    plotScoreDistribution(
      results,
      show = c("delta.med", "delta.next", "scores"),
      labels = colnames(results$scores),
      size = 0.5,
      ncol = 5,
      dots.on.top = TRUE,
      this.color = "#F0E442",
      pruned.color = "#E69F00",
      other.color = "gray60",
      show.nmads = NULL,
      show.min.diff = NULL
    )

### Arguments

`results` | A DataFrame containing the output from `SingleR` or `classifySingleR`.
`show` | String specifying whether to show the scores, the difference from the median or the difference from the next-best score.
`labels` | String vector indicating one or more labels to show. If `NULL`, all labels available in `results` are presented.
`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 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` | Numeric scalar that shows the threshold that would be used for pruning with `pruneScores`. Only used when `show="delta.med"`.
`show.min.diff` | Numeric scalar that shows the threshold that would be used for pruning with `pruneScores`. Only used when `show="delta.med"` or `"delta.next"`.

### Details

This function creates jitter and violin plots showing assignment scores or related values for all cells across one or more labels. It is intended for visualizing and adjusting the `nmads`, `min.diff.med`, and `min.diff.next` cutoffs of the `pruneScores` function.

The `show` argument determines what values to show on the y-axis. Options are:

- `"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 tuning scores of each cell.

- `"scores"`, the raw assignment scores prior to fine-tuning.

For a given label X, cells distributions in several categories are shown:

- Was assigned to label X, and the label was not pruned away.

- Was assigned to label X, and the label was pruned away.

- Was assigned as any label, including label X.

Each category is grouped and colored separately based on `this.color` and related parameters.

Values are stratified according to the assigned labels in `results$labels`. 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"`.

Also note that `pruneScores` trims based on the `min.diff.med` and `min.diff.next` cutoffs first, before calculating the first-labels' delta medians. Thus, the actual `nmads` cut-off used in `pruneScores` may vary from the one portrayed in the plot.

### Value

A ggplot object showing assignment scores in violin plots.

### Author(s)

Daniel Bunis and Aaron Lun

### See Also

`SingleR`, to generate scores.

`pruneScores`, to remove low-quality labels based on the scores, and to see more about the quailty cutoffs.

### 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 = "B")

    # To show the distribution of deltas between cells' maximum and median scores,
    #   grouped by label, change `show` to "delta.med":
    #   This is useful for checking/adjusting nmads and min.diff.med
    plotScoreDistribution(results = pred, show = "delta.med")
    # The nmads cutoff can be displayed using show.nmads.
    plotScoreDistribution(results = pred, show = "delta.med",
        show.nmads = 3)
    # A min.diff.med cutoff can be shown using show.min.diff
    plotScoreDistribution(results = pred, show = "delta.med",
        show.min.diff = 0.03)

    # To show the distribution of deltas between cells' top 2 fine-tuning scores,
    #   grouped by label, change `show` to "delta.next":
    #   This is useful for checking/adjusting min.diff.next
    plotScoreDistribution(results = pred, show = "delta.next")
    # A min.diff.med cutoff can be shown using show.min.diff
    plotScoreDistribution(results = pred, show = "delta.next",
        show.min.diff = 0.03)

[Package SingleR version 1.0.6 Index]