dittoDotPlot: Compact plotting of per group summaries for expression of...
In dittoSeq: User Friendly Single-Cell and Bulk RNA Sequencing Visualization

Description Usage Arguments Details Value Many characteristics of the plot can be adjusted using discrete inputs Author(s) See Also Examples

View source: R/dittoDotPlot.R

Compact plotting of per group summaries for expression of multiple features

dittoDotPlot(
  object,
  vars,
  group.by,
  scale = TRUE,
  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,
  do.hover = FALSE,
  main = NULL,
  sub = NULL,
  ylab = group.by,
  y.labels = NULL,
  y.reorder = NULL,
  xlab = NULL,
  x.labels.rotate = TRUE,
  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
)

`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.
`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
`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.
`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`). Note: plotly conversion is turned off in the `data.out = TRUE` setting, but hover.data is still calculated.

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.

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.

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.

Daniel Bunis

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.

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)