dittoDotPlot {dittoSeq} | R Documentation

## Compact plotting of per group summaries for expression of multiple features

### Description

Compact plotting of per group summaries for expression of multiple features

### Usage

    dittoDotPlot(
      object,
      vars,
      group.by,
      scale = TRUE,
      split.by = NULL,
      cells.use = NULL,
      size = 6,
      min.percent = 0.01,
      max.percent = NA,
      min.color = "grey90",
      max.color = "#C51B7D",
      min = "make",
      max = NULL,
      summary.fxn.color = function(x) {     mean(x[x != 0]) },
      summary.fxn.size = function(x) {     mean(x != 0) },
      assay = .default_assay(object),
      slot = .default_slot(object),
      adjustment = NULL,
      swap.rownames = NULL,
      do.hover = FALSE,
      main = NULL,
      sub = NULL,
      ylab = group.by,
      y.labels = NULL,
      y.reorder = NULL,
      xlab = NULL,
      x.labels.rotate = TRUE,
      split.nrow = NULL,
      split.ncol = NULL,
      split.adjust = list(),
      theme = theme_classic(),
      legend.show = TRUE,
      legend.color.breaks = waiver(),
      legend.color.breaks.labels = waiver(),
      legend.color.title = "make",
      legend.size.title = "percent\nexpression",
      data.out = FALSE
    )

### Arguments

`object` | A Seurat, SingleCellExperiment, or SummarizedExperiment object.
`vars` | String vector (example: `c("gene1","gene2","gene3")`) which selects which variables, typically genes, to show.
`group.by` | String representing the name of a metadata to use for separating the cells/samples into discrete groups.
`scale` | String which sets whether the values shown with color (default: mean non-zero expression) should be centered and scaled.
`split.by` | 1 or 2 strings naming discrete metadata to use for splitting the cells/samples into multiple plots with ggplot faceting. When 2 metadatas are named, c(row,col), the first is used as rows and the second is used for columns of the resulting grid. When 1 metadata is named, shape control can be achieved with `split.nrow` and `split.ncol`
`cells.use` | String vector of cells'/samples' names OR an integer vector specifying the indices of cells/samples which should be included. Alternatively, a Logical vector, the same length as the number of cells in the object, which sets which cells to include.
`size` | Number which sets the dot size associated with the highest value shown by dot size (default: percent non-zero expression).
`min.percent, max.percent` | Numbers between 0 and 1 which sets the minimum and maximum percent expression to show. When set to NA, the minimum/maximum of the data are used.
`min.color, max.color` | colors to use for minimum and maximum color values. Default = light grey and purple.
`min, max` | Numbers which set the values associated with the minimum and maximum colors.
`summary.fxn.color, summary.fxn.size` | A function which sets how color or size will be used to summarize variables' data for each group. Any function can be used as long as it takes in a numeric vector and returns a single numeric value.
`assay` | single strings or integer that set which data to use when plotting expressin data. See `gene` for more information about how defaults for these are filled in when not provided.
`slot` | single strings or integer that set which data to use when plotting expressin data. See `gene` for more information about how defaults for these are filled in when not provided.
`adjustment` | When plotting gene expression (or antibody, or other forms of counts data), should that data be adjusted altogether before `cells.use` subsetting and splitting into groups? "relative.to.max": divided by the maximum expression value to give percent of max values between [0,1] "z-score": centered and scaled to produce a relative-to-mean z-score representation NULL: Default, no adjustment
`swap.rownames` | String. For SummarizeedExperiment or SingleCellExperiment objects, the column name of rowData(object) to be used to identify features instead of rownames(object).
`do.hover` | Logical. Default = `FALSE`. If set to `TRUE` the object will be converted to an interactive plotly object in which underlying data for individual dots will be displayed when you hover your cursor over them.
`main` | String which sets the plot title.
`sub` | String which sets the plot subtitle.
`ylab` | String which sets the y/grouping-axis label. Default is `group.by` so it defaults to the name of the grouping information. Set to `NULL` to remove.
`y.labels` | String vector, c("label1","label2","label3",...) which overrides the names of the samples/groups.
`y.reorder` | Integer vector. A sequence of numbers, from 1 to the number of groupings, for rearranging the order of groupings. Method: Make a first plot without this input. Then, treating the bottom-most grouping as index 1, and the top-most as index n, values of y.reorder should be these indices, but in the order that you would like them rearranged to be. Recommendation for advanced users: If you find yourself coming back to this input too many times, an alternative solution that can be easier long-term is to make the target data into a factor, and to put its levels in the desired order: `factor(data, levels = c("level1", "level2", ...))`. `metaLevels` can be used to quickly get the identities that need to be part of this 'levels' input.
`xlab` | String which sets the x/var-axis label. Set to `NULL` to remove.
`x.labels.rotate` | Logical which sets whether the var-labels should be rotated.
`split.nrow` | Integers which set the dimensions of faceting/splitting when a single metadata is given to `split.by`.
`split.ncol` | Integers which set the dimensions of faceting/splitting when a single metadata is given to `split.by`.
`split.adjust` | A named list which allows extra parameters to be pushed through to the faceting function call. List elements should be valid inputs to the faceting functions, e.g. 'list(scales = "free")'. For options, when giving 1 metadata to `split.by`, see `facet_wrap`, OR when giving 2 metadatas to `split.by`, see `facet_grid`.
`theme` | A ggplot theme which will be applied before dittoSeq adjustments. Default = `theme_classic()`. See https://ggplot2.tidyverse.org/reference/ggtheme.html for other options and ideas.
`legend.show` | Logical. Whether the legend should be displayed. Default = `TRUE`.
`legend.color.breaks` | Numeric vector which sets the discrete values to label in the color-scale legend for continuous data.
`legend.color.breaks.labels` | String vector, with same length as `legend.breaks`, which sets the labels for the tick marks of the color-scale.
`legend.color.title, legend.size.title` | String or `NULL`, sets the title displayed above legend keys.
`data.out` | Logical. When set to `TRUE`, changes the output, from the plot alone, to a list containing the plot (`p`) and data (`data`).

### Details

This function will output a compact summary of expression of multiple genes, or of values of multiple numeric metadata, across cell/sample groups (clusters, sample identity, conditions, etc.), where dot-size and dot-color are used to reflect distinct features of the data. Typically, and by default, size will reflect the percent of non-zero values, and color will reflect the mean of non-zero values for each var and group pairing.

Internally, the data for each element of `vars` is obtained. When elements are genes/features, `assay` and `slot` are utilized to determine which expression data to use, and `adjustment` determines if and how the expression data might be adjusted. (Note that 'adjustment' would be applied before cells/samples subsetting, and across all groups of cells/samples.)

Groupings are determined using `group.by`, and then data for each variable is summarized based on `summary.fxn.color` & `summary.fxn.size`.

If `scale = TRUE` (default setting), the color summary values are centered and scaled. Doing so 1) puts values for all `vars` in a similar range, and 2) emphasizes relative differences between groups.

Finally, data is plotted as dots of differing colors and sizes.

### Value

a ggplot object where dots of different colors and sizes summarize continuous data for multiple features (columns) per multiple groups (rows)

Alternatively when `data.out = TRUE`, a list containing the plot ("p") and the underlying data as a dataframe ("data").

Alternatively when `do.hover = TRUE`, a plotly converted version of the plot where additional data will be displayed when the cursor is hovered over the dots.

### Many characteristics of the plot can be adjusted using discrete inputs

- Size of the dots can be changed with `size`.

- Subsetting to utilize only certain cells/samples can be achieved with `cells.use`.

- Colors can be adjusted with `min.color` and `max.color`.

- Displayed value ranges can be adjusted with `min` and `max` for color, or `min.percent` and `max.percent` for size.

- Titles and axes labels can be adjusted with `main`, `sub`, `xlab`, `ylab`, `legend.color.title`, and `legend.size.title` arguments.

- The legend can be hidden by setting `legend.show = FALSE`.

- The color legend tick marks and associated labels can be adjusted with `legend.color.breaks` and `legend.color.breaks.labels`, respectively.

- The groupings labels and order can be changed using `y.labels` and `y.reorder`

- Rotation of x-axis labels can be turned off with `x.labels.rotate = FALSE`.

### Author(s)

Daniel Bunis

### See Also

`dittoPlotVarsAcrossGroups` for a method of summarizing expression of multiple features across distinct groups that can be better (and more compact) when the identities of the individual genes are unimportant.

`dittoPlot` and `multi_dittoPlot` for plotting of expression and metadata vars, each as separate plots, on a per cell/sample basis.

### Examples

    example(importDittoBulk, echo = FALSE)
    myRNA

    # These random data aren't very exciting, but we can at least add some zeros
    #   for making slightly more interesting dot plots.
    counts(myRNA)[1:4,1:40] <- 0
    logcounts(myRNA)[1:4,1:40] <- 0

    dittoDotPlot(
        myRNA, c("gene1", "gene2", "gene3", "gene4"),
        group.by = "clustering")

    # 'size' adjusts the dot-size associated with the highest percent expression
    dittoDotPlot(myRNA, c("gene1", "gene2", "gene3", "gene4"), "clustering",
        size = 12)

    # 'scale' input can be used to control / turn off scaling of avg exp values.
    dittoDotPlot(myRNA, c("gene1", "gene2", "gene3", "gene4"), "clustering",
        scale = FALSE)

    # x-axis label rotation can be controlled with 'x.labels.rotate'
    dittoDotPlot(myRNA, c("gene1", "gene2", "gene3", "gene4"), "clustering",
        x.labels.rotate = FALSE)

    # Title are adjustable via various discrete inputs:
    dittoDotPlot(myRNA, c("gene1", "gene2", "gene3", "gene4"), "clustering",
        main = "Title",
        sub = "Subtitle",
        ylab = "y-axis label",
        xlab = "x-axis label",
        legend.color.title = "Colors title",
        legend.size.title = "Dot size title")

    # For certain specialized applications, it may be helpful to adjust the
    #   functions used for summarizing the data as well. Inputs are:
    #   summary.fxn.color & summary.fxn.size
    #     Requirement for each: Any function that takes in a numeric vector &
    #     returns, as output, a single numeric value.
    dittoDotPlot(myRNA, c("gene1", "gene2", "gene3", "gene4"), "clustering",
        summary.fxn.color = mean,
        legend.color.title = "mean\nexpression\nincluding 0s",
        main = "scater::plotDots() defaulting recreation",
        x.labels.rotate = FALSE,
        scale = FALSE)

[Package dittoSeq version 1.4.4 Index]