Waterfall Plot

Generates a waterfall plot.

WaterfallPlot(object, ...)

# S3 method for Seurat
WaterfallPlot(
  seu,
  features,
  group.by = NULL,
  cell = NULL,
  cells = NULL,
  slot = "data",
  assay = NULL,
  priority = c("expr", "none"),
  ident.1 = NULL,
  ident.2 = NULL,
  exp.transform = (length == "logFC"),
  order = TRUE,
  length = "logFC",
  color = "p",
  len.threshold = 0,
  col.threshold = 0,
  color_theme = "BuRd",
  center_color = NULL,
  top.n = NULL,
  flip = FALSE,
  y.label = NULL,
  angle = NULL,
  hjust = NULL,
  vjust = NULL,
  title = NULL,
  style = c("bar", "segment")
)

# S3 method for default
WaterfallPlot(
  matr,
  f,
  ident.1 = NULL,
  ident.2 = NULL,
  exp.transform = FALSE,
  order = TRUE,
  length = "tscore",
  color = "tscore",
  len.threshold = 0,
  col.threshold = 0,
  color_theme = "BuRd",
  center_color = NULL,
  top.n = NULL,
  flip = TRUE,
  y.label = NULL,
  angle = NULL,
  hjust = NULL,
  vjust = NULL,
  title = NULL,
  style = c("bar", "segment")
)

Arguments

object

Either a Seurat object or a matrix.

...

Additional arguments passed to other methods.

seu

A Seurat object. Only applicable when using the Seurat method.

features

Features to be plotted, which can include gene expression, metrics, PC scores, or any other data that can be retrieved using the `FetchData()` function. Only applicable for the Seurat method.

group.by

A variable from `meta.data` for grouping, or a character vector of the same length as the number of cells. Only applicable for the Seurat method.

cell

Cell identifiers to be used in the plot. Defaults to all cells. Only applicable for the Seurat method.

cells

Alternative parameter name for cell identifiers. Same functionality as 'cell'. Defaults to all cells.

slot

Slot from which to retrieve feature data. Only applicable for the Seurat method.

assay

Name of the assay to use. If not specified, the active assay will be used. Only applicable for the Seurat method.

priority

If set to "expr", the function will fetch data from the expression matrix rather than `meta.data`. Only applicable for the Seurat method.

ident.1

The primary identity class. If not specified, the first class will be used.

ident.2

An optional secondary identity class for comparison. If NULL, comparisons will be made against all other cells.

exp.transform

Indicates whether to transform data using `expm1`. This is particularly useful when calculating the log fold change of normalized gene counts. Defaults to FALSE for matrix input and TRUE for Seurat object input.

order

Determines whether the features should be ordered. Defaults to TRUE.

length

Specifies the statistic to determine the length of the bar. Possible values are "tscore" (default for matrix input), "p", or "logFC" (default for Seurat object input).

color

Specifies the statistic to determine the color of the bar. Possible values are "tscore" (default), "p" (default for Seurat object input), or "logFC".

len.threshold

Excludes features with a value for the `length` parameter below this threshold. Defaults to 0.

col.threshold

Excludes features with a value for the `color` parameter below this threshold. Defaults to 0.

center_color

Logical or NULL. Determines whether the color scale should be centered at zero. If TRUE, the color scale will be centered at zero, with the midpoint color representing zero. If FALSE, the color scale will span the full range of the data without centering. If NULL (default), it will automatically determine based on the color scheme: TRUE for diverging color palettes, FALSE for sequential palettes or custom color schemes. This is particularly useful for visualizing data with both positive and negative values, such as z-scores or log fold changes.

top.n

Retains only the top `n` bars in both positive and negative directions. If `length(top.n)` is 1, the function retains `top.n` bars for both positive and negative directions. If `length(top.n)` is 2, it retains `top.n[1]` positive bars and `top.n[2]` negative bars. Defaults to NULL.

flip

Determines whether the plot should be flipped. Defaults to TRUE for matrix input and FALSE for Seurat object input.

y.label

Label for the y-axis. Defaults to "length".

angle

Angle of the x-axis labels. This argument is passed to `element_text()`.

hjust

Horizontal justification for the x-axis labels. This argument is passed to `element_text()`.

vjust

Vertical justification for the x-axis labels. This argument is passed to `element_text()`.

title

Title of the plot. Defaults to NULL.

style

Character string specifying the plot style. Either "bar" (default) for traditional bar plot style, or "segment" for thin segments with end points.

matr

A matrix or data frame where rows represent features and columns represent cells.

f

A factor or vector indicating the identity of each cell. The length should match the number of columns in `matr`.

color_scheme

Specifies the color gradient for the heatmap visualization. This parameter accepts multiple input formats to provide flexibility in defining color schemes:

- Predefined color schemes from the `viridis` package ("A" to "H").

- Named vector with keys "low", "mid", and "high" for three-point gradients. Example: `c(low = muted("blue"), mid = "white", high = muted("red"))`.

- Two-point gradient with keys "low" and "high". Example: `c(low = "lightblue", high = "red")`.

- RColorBrewer sequential palettes: "Blues", "BuGn", "BuPu", "GnBu", "Greens", "Greys", "Oranges", "OrRd", "PuBu", "PuBuGn", "PuRd", "Purples", "RdPu", "Reds", "YlGn", "YlGnBu", "YlOrBr", "YlOrRd".

- RColorBrewer diverging palettes: "BrBG", "PiYG", "PRGn", "PuOr", "RdBu", "RdGy", "RdYlBu", "RdYlGn", "Spectral".

- Custom diverging palettes: "GnYlRd", "BuYlRd", "GyRd", "BuRd", "PuOr".

- Append "-rev" to any RColorBrewer palette name to reverse the color order. Example: "RdBu-rev".

- Custom color gradient using a vector of colors.

Value

A ggplot object.

Details

For more detailed usage, see the examples provided.

Examples

# First, create a matrix using the GeneSetAnalysis() function.
# Rows represent the Hallmark 50 genesets, and columns represent cells.
pbmc <- GeneSetAnalysis(pbmc, genesets = hall50$human)
matr <- pbmc@misc$AUCell$genesets

# Generate a waterfall plot comparing CD14+ Mono with CD8 T cells.
WaterfallPlot(matr, f = pbmc$cluster, ident.1 = "Mono CD14", ident.2 = "CD8 T cell")

# Keep only bars with a length (tscore, in this instance) greater than 1.
WaterfallPlot(matr, f = pbmc$cluster, ident.1 = "Mono CD14", ident.2 = "CD8 T cell", len.threshold = 1)

# Create a plot using the alternative segment style with points
WaterfallPlot(
  matr,
  f = pbmc$cluster,
  ident.1 = "Mono CD14",
  ident.2 = "CD8 T cell",
  style = "segment",
  color_theme = "D"
)

# Use a Seurat object as input and compare 100 genes, using LogFC as bar length.
genes <- VariableFeatures(pbmc)[1:80]
WaterfallPlot(
  pbmc, group.by = "cluster", features = genes,
  ident.1 = "Mono CD14", ident.2 = "CD8 T cell", length = "logFC")

# Keep only the top and bottom 20 genes.
WaterfallPlot(
  pbmc, group.by = "cluster", features = genes,
  ident.1 = "Mono CD14", ident.2 = "CD8 T cell", length = "logFC",
  top.n = 20)