multi_dittoDimPlotVaryCells {dittoSeq} | R Documentation

## Generates multiple dittoDimPlots, each showing different cells, arranged into a grid.

### Description

Generates multiple dittoDimPlots, each showing different cells, arranged into a grid.

### Usage

    multi_dittoDimPlotVaryCells(
      object,
      var,
      vary.cells.meta,
      vary.cells.levels = metaLevels(vary.cells.meta, object),
      assay = .default_assay(object),
      slot = .default_slot(object),
      adjustment = NULL,
      min = NULL,
      max = NULL,
      color.panel = dittoColors(),
      colors = seq_along(color.panel),
      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,
      OUT.List = FALSE,
      ...
    )

### Arguments

`object` | A Seurat or SingleCellExperiment object to work with
`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 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. REQUIRED.
`vary.cells.meta` | String name of a metadata that should be used for selecting which cells to show in each "varycells" plot. REQUIRED.
`vary.cells.levels` | The values/groupings of the `vary.cells.meta` metadata that should get a plot. Defaults to all levels of the metadata.
`color.panel, colors, min, max, assay, slot, adjustment, ...` | additional parameters passed to `dittoDimPlot`. All parameters except for `cells.use`, `main`, and `legend.show` can be used. 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.
`show.titles` | Logical which sets whether titles should be added to the individual varycells plots
`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` or `""` 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 varycells plot. 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.
`OUT.List` | Logical which controls whether the list of plots should be returned as a list instead of as a single grid arrangement of the plots.

### Details

This function generates separate dittoDimPlots that show the same target data, but for distinct cells. Which cells fall into which plot is controlled with the `vary.cells.meta` parameter. When the quoted name of a metadata containing discrete groupings is given to `vary.cells.meta`, the function makes separate plots containing all cells/samples of each grouping.

If plots for only certain groupings of cells are wanted, names of the wanted groupings can be supplied to the `vary.cells.levels` input.

The function then appends a plot containing all groupings, titled as "All Cells" (unless otherwise changed with the `allcells.main` parameter), as well as a single legend. Either of these can be turned off with the `show.allcells.plot` and `show.legend.single` parameters.

Plots are either output in a grid (default) with `ncol` columns and `nrow` rows, or alternatively as a simple list of ggplots if `OUT.List` is set to `TRUE`. In the list, the varycells plots will be named by the value of `vary.cells.meta` that they contain, the allcells plot will be named "allcells" and the single legend will be named "legend".

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 values accross all plots.

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

### Value

multiple dittoDimPlot `ggplot`s either arranged in a grid OR as a list

### Author(s)

Daniel Bunis

### See Also

`dittoDimPlot` for the base DimPlot plotting function

`multi_dittoDimPlot` for plotting distinct `var`s accross plots instead of disctinct cells

### Examples

    # dittoSeq handles bulk and single-cell data quit similarly.
    # The SingleCellExperiment object structure is used for both,
    # but all functions can be used similarly directly on Seurat
    # objects as well.

    example(importDittoBulk, echo = FALSE)
    myRNA

    multi_dittoDimPlotVaryCells(myRNA, "gene1", vary.cells.meta = "clustering")

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

    # This function is also great for generating separate plots of each individual
    #   element of a tsne/PCplot/umap. This can be useful to check for dispersion
    #   of groups that might otherwise be hidden behind other cells/samples.
    #   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 accross clusters.
    multi_dittoDimPlotVaryCells(myRNA, "groups", vary.cells.meta = "clustering")

    # For an alternative method of viewing, and easily quantifying, how discrete
    #   conditions of cells disperse accross clusters, see '?dittoBarPlot'

    # Note, for displaying expression or scoring of distinct genes or metadata,
    #   use 'multi_dittoDimPlot'.  Its split.by variable can then be used to add
    #   a varyCells-like effect.

[Package dittoSeq version 1.0.2 Index]