dittoBarPlot: Outputs a stacked bar plot to show the percent composition 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) Examples

View source: R/dittoBarPlot.R

Outputs a stacked bar plot to show the percent composition of samples, groups, clusters, or other groupings

dittoBarPlot(
  object,
  var,
  group.by,
  scale = c("percent", "count"),
  cells.use = NULL,
  data.out = FALSE,
  do.hover = FALSE,
  color.panel = dittoColors(),
  colors = seq_along(color.panel),
  y.breaks = NA,
  min = 0,
  max = NULL,
  var.labels.rename = NULL,
  var.labels.reorder = NULL,
  x.labels = NULL,
  x.labels.rotate = TRUE,
  x.reorder = NULL,
  theme = theme_classic(),
  xlab = group.by,
  ylab = "make",
  main = "make",
  sub = NULL,
  legend.show = TRUE,
  legend.title = NULL
)

`object`	A Seurat, SingleCellExperiment, or SummarizedExperiment object.
`var`	String name of a metadata that contains discrete data, or a factor or vector containing such data for all cells/samples in the target `object`.
`group.by`	String name of a metadata to use for separating the cells/samples into discrete groups.
`scale`	"count" or "percent". Sets whether data should be shown as raw counts or scaled to 1 and shown as a percentage.
`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. Note: When `cells.use` is combined with `scale = "percent"`, left out cells are not considered in calculating percentages. Percents will always total to 1.
`data.out`	Logical. When set to `TRUE`, changes the output, from the plot alone, to a list containing the plot ("p") and a data.frame ("data") containing the underlying data. Note: plotly output is turned off in the `data.out = TRUE` setting, but hover.data is still calculated.
`do.hover`	Logical which sets whether the ggplot output should be converted to a ggplotly object with data about individual bars displayed when you hover your cursor over them.
`color.panel`	String vector which sets the colors to draw from. `dittoColors()` by default.
`colors`	Integer vector, which sets the indexes / order, of colors from color.panel to actually use. (Provides an alternative to directly modifying `color.panel`.)
`y.breaks`	Numeric vector which sets the plot's tick marks / major gridlines. c(break1,break2,break3,etc.)
`min, max`	Scalars which control the zoom of the plot. These inputs set the minimum / maximum values of the y-axis. Default = set based on the limits of the data, 0 to 1 for `scale = "percent"`, or 0 to maximum count for 0 to 1 for `scale = "count"`.
`var.labels.rename`	String vector for renaming the distinct identities of `var` values.
`var.labels.reorder`	Integer vector. A sequence of numbers, from 1 to the number of distinct `var` value idententities, for rearranging the order of labels' groupings within the plot. Method: Make a first plot without this input. Then, treating the top-most grouping as index 1, and the bottom-most as index n. Values of `var.labels.reorder` should be these indices, but in the order that you would like them rearranged to be.
`x.labels`	String vector which will replaceme the x-axis groupings' labels. Regardless of `x.reorder`, the first component of `x.labels` sets the name for the left-most x-axis grouping.
`x.labels.rotate`	Logical which sets whether the x-axis grouping labels should be rotated.
`x.reorder`	Integer vector. A sequence of numbers, from 1 to the number of groupings, for rearranging the order of x-axis groupings. Method: Make a first plot without this input. Then, treating the leftmost grouping as index 1, and the rightmost as index n. Values of `x.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.
`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.
`xlab`	String which sets the x-axis title. Default is `group.by` so it defaults to the name of the grouping information. Set to `NULL` to remove.
`ylab`	String which sets the y-axis title.
`main`	String, sets the plot title
`sub`	String, sets the plot subtitle
`legend.show`	Logical which sets whether the legend should be displayed.
`legend.title`	String which adds a title to the legend.

The function creates a dataframe containing counts and percent makeup of var identities for each x-axis grouping (determined by the group.by input). If a set of cells/samples to use is indicated with the cells.use input, only those cells/samples are used for counts and percent makeup calculations. Then, a vertical bar plot is generated (ggplot2::geom_col()) showing either percent makeup if scale = "percent", which is the default, or raw counts if scale = "count".

A ggplot plot where discrete data, grouped by sample, condition, cluster, etc. on the x-axis, is shown on the y-axis as either counts or percent-of-total-per-grouping in a stacked barplot.

Alternatively, if data.out = TRUE, a list containing the plot ("p") and a dataframe of the underlying data ("data").

Alternatively, if do.hover = TRUE, a plotly conversion of the ggplot output in which underlying data can be retrieved upon hovering the cursor over the plot.

Colors can be adjusted with color.panel and/or colors.
y-axis zoom and tick marks can be adjusted using min, max, and y.breaks.
Titles can be adjusted with main, sub, xlab, ylab, and legend.title arguments.
The legend can be removed by setting legend.show = FALSE.
x-axis labels and groupings can be changed / reordered using x.labels and x.reorder, and rotation of these labels can be turned off with x.labels.rotate = FALSE.
y-axis var-group labels and their order can be changed / reordered using var.labels and var.labels.reorder.

Daniel Bunis

example(importDittoBulk, echo = FALSE)
myRNA

dittoBarPlot(myRNA, "clustering", group.by = "groups")
dittoBarPlot(myRNA, "clustering", group.by = "groups",
    scale = "count")

# Reordering the x-axis groupings to have "C" (#3) come first
dittoBarPlot(myRNA, "clustering", group.by = "groups",
    x.reorder = c(3,1,2,4))

### Accessing underlying data:
# as dataframe
dittoBarPlot(myRNA, "clustering", group.by = "groups",
    data.out = TRUE)
# through hovering the cursor over the relevant parts of the plot
if (requireNamespace("plotly", quietly = TRUE)) {
    dittoBarPlot(myRNA, "clustering", group.by = "groups",
        do.hover = TRUE)
    }