multi_dittoDimPlotVaryCells {dittoSeq} | R Documentation

## Generates multiple dittoDimPlots, for a single feature, where each showing different cells

### Description

Generates multiple dittoDimPlots, for a single feature, where each showing different cells

### Usage

    multi_dittoDimPlotVaryCells(
      object,
      var,
      vary.cells.meta,
      vary.cells.levels = metaLevels(vary.cells.meta, object),
      show.titles = TRUE,
      show.allcells.plot = TRUE,
      allcells.main = "All Cells",
      show.legend.single = TRUE,
      show.legend.plots = FALSE,
      show.legend.allcells.plot = FALSE,
      nrow = NULL,
      ncol = NULL,
      list.out = FALSE,
      OUT.List = NULL,
      ...,
      assay = .default_assay(object),
      slot = .default_slot(object),
      adjustment = NULL,
      min = NULL,
      max = NULL,
      color.panel = dittoColors(),
      colors = seq_along(color.panel),
      data.out = FALSE,
      do.hover = FALSE,
      swap.rownames = NULL
    )

### Arguments

`object` | A Seurat, SingleCellExperiment, or SummarizedExperiment object.
`var` | String name of a "gene" or "metadata" (or "ident" for a Seurat `object`) to use for coloring the plots. This is the data that will be displayed, using colors, for each cell/sample. Alternatively, can be a vector of same length as there are cells/samples in the `object`. Discrete or continuous data both work.
`vary.cells.meta` | String name of a metadata that should be used for selecting which cells to show in each "VaryCells" `dittoDimPlot`.
`vary.cells.levels` | The values/groupings of the `vary.cells.meta` metadata for which to generate a plot.
`show.titles` | Logical which sets whether grouping-levels should be used as titles for the individual VaryCell plots. Default = TRUE.
`show.allcells.plot` | Logical which sets whether an additional plot showing all of the cells should be added.
`allcells.main` | String which adjusts the title of the allcells plot. Default = "All Cells". Set to `NULL` to remove.
`show.legend.single` | Logical which sets whether to add a single legend as an additional plot. Default = TRUE.
`show.legend.plots` | Logical which sets whether or not legends should be plotted in inidividual VaryCell plots. Default = FALSE.
`show.legend.allcells.plot` | Logical which sets whether or a legend should be plotted in the allcells plot. Default = FALSE.
`ncol, nrow` | Integers which set dimensions of the plot grid when `list.out = FALSE`.
`list.out` | Logical which controls whether the list of plots should be returned as a list instead of as a single grid arrangement of the plots.
`OUT.List` | Deprecated. Use `list.out`
`..., color.panel, colors, min, max, assay, slot, adjustment, data.out, do.hover, swap.rownames` | additional parameters passed to `dittoDimPlot`. All parameters of `dittoDimPlot` can be utilized and adjusted except for `cells.use`, `main`, and `legend.show` which are handled with alternative methods here. A few suggestions: `reduction.use` for setting which dimensionality reduction space to use. `xlab` and `ylab` can be set to `NULL` to remove the axes labels and provide extra room for the data. `size` can be used to adjust the size of the dots.

### Details

This function generates separate dittoDimPlots that show the same target data, but each for distinct cells.

How cells are separated into distinct plots is controlled with the `vary.cells.meta` parameter. Individual `dittoDimPlot`s are created for all levels of `var.cells.meta` groupings given to the `vary.cells.levels` input (default = all).

The function then appends a plot containing all cell/samples when `show.allcells.plot = TRUE`, with title of this plot controlled by `allcells.main`, as well as as single legend when `show.legend.single = TRUE`.

By default, these dittoDimPlots are output in a grid (default) with `ncol` columns and `nrow` rows, Alternatively, if `list.out` is set to `TRUE`, they are returned as a list. In the list, the VaryCell plots will be named by the levels of `vary.cells.meta` that they contain, and the optional allcells plot and single legend will be named "allcells" and "legend", respectively.

Either continuous or discrete `var` data can be displayed.

- For continuous data, the range of potential values is calculated at the start, and set, so that colors represent the same value across all plots.

- For discrete data, colors used in each plot are adjusted so that colors represent the same groupings across all plots.

### Value

A set of dittoDimPlots either arranged into a grid (default), or output as a list.

### Author(s)

Daniel Bunis

### See Also

`multi_dittoDimPlot` for an alternate `dittoDimPlot` multi-plotter where `var`s are varied across plots rather than cells/samples

`dittoDimPlot` for the base dittoDimPlot plotting function and details on all accepted inputs.

### Examples

    example(importDittoBulk, echo = FALSE)

    # This function can be used to quickly scan for differences in expression
    #   within or across clusters/cell types.
    multi_dittoDimPlotVaryCells(myRNA, "gene1", vary.cells.meta = "clustering")

    # Output as list instead
    multi_dittoDimPlotVaryCells(myRNA, "gene1", vary.cells.meta = "clustering",
        list.out = TRUE)

    # This function is also great for generating separate plots of each individual
    #   grouping of a tsne/PCA/umap. This can be useful to check for dispersion
    #   of groups that might otherwise be hidden behind other cells/samples.
    #   The effect is similar to faceting, but: all distinct plots are treated
    #   separately rather than being just a part of the whole, and with portrayal
    #   of all cells/samples in an additional plot by default.
    #
    #   To do so, set 'var' and 'vary.cells.meta' the same.
    multi_dittoDimPlotVaryCells(myRNA, "clustering", vary.cells.meta = "clustering")

    # The function can also be used to quickly visualize how separate clustering
    #   resolutions match up to each other, or perhaps how certain conditions of
    #   cells disperse across clusters.
    # (For an alternative method of viewing, and easily quantifying, how discrete
    #   conditions of cells disperse across clusters, see '?dittoBarPlot')
    multi_dittoDimPlotVaryCells(myRNA, "groups", vary.cells.meta = "clustering")

[Package dittoSeq version 1.4.4 Index]