dittoBarPlot {dittoSeq} | R Documentation

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

### Description

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

### Usage

    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
    )

### Arguments

`object` | A Seurat or SingleCellExperiment 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 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. For the typically easier logical method, provide `USE` in `colnames(object)[USE]` OR `object@cell.names[USE]`. 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.
`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.

### Details

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"`.

### Value

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.

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

- 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`.

### Author(s)

Daniel Bunis

### 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

    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)
        }

[Package dittoSeq version 1.0.2 Index]