Create a Volcano Plot Comparing Two Groups — VolcanoPlot • SeuratExtend

Creates a volcano plot to visualize differential expression or other comparative analyses between two groups. The plot displays a measure of change (typically log fold change) on the x-axis versus a measure of significance (typically -log10 p-value) on the y-axis. Points are colored based on their significance levels, and top features in both up- and down-regulated directions are labeled.

VolcanoPlot(object, ...)

# S3 method for Seurat
VolcanoPlot(
  seu,
  features = rownames(seu),
  group.by = NULL,
  cell = NULL,
  cells = NULL,
  slot = "data",
  assay = NULL,
  priority = c("expr", "none"),
  ident.1 = NULL,
  ident.2 = NULL,
  exp.transform = TRUE,
  x = "logFC",
  y = "p",
  x.threshold = NULL,
  y.threshold = NULL,
  x.quantile = 0.99,
  y.quantile = 0.99,
  top.n = 10,
  color = c("grey20", "grey50", "red3"),
  title = NULL
)

# S3 method for default
VolcanoPlot(
  matr,
  f,
  ident.1 = NULL,
  ident.2 = NULL,
  exp.transform = FALSE,
  x = "logFC",
  y = c("p", "tscore"),
  x.threshold = NULL,
  y.threshold = NULL,
  x.quantile = 0.99,
  y.quantile = 0.99,
  top.n = 10,
  color = c("grey20", "grey50", "red3"),
  title = NULL
)

Arguments

seu: A Seurat object. Only applicable when using the Seurat method.
features: Features to be plotted, which can include gene expression 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 TRUE for Seurat object input and FALSE for matrix input.
x: A character specifying the statistic for x-axis. Must be one of c("logFC", "tscore"). Defaults to "logFC".
y: A character specifying the statistic for y-axis. Must be one of c("p", "tscore"). Defaults to "p".
x.threshold: Threshold for the x-axis statistic. Features beyond this threshold will be labeled. Defaults to NULL (auto-detected).
y.threshold: Threshold for the y-axis statistic. Features beyond this threshold will be labeled. Defaults to NULL (auto-detected).
x.quantile: Quantile threshold for x-axis (between 0 and 1) used when auto-calculating x.threshold. Defaults to 0.99.
y.quantile: Quantile threshold for y-axis (between 0 and 1) used when auto-calculating y.threshold. Defaults to 0.99.
top.n: Number of top features to label. Defaults to 10.
color: A vector of three colors specifying the color scheme: c(center_color, non_significant_color, significant_color). Defaults to c("grey20", "grey50", "red3"). The first color is used for points near zero (below thresholds), the second for points passing single threshold, and the third for points passing both thresholds.
title: Title of the plot. Defaults to NULL.
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`.

Details

The function supports both Seurat objects and raw matrices as input. For Seurat objects, it automatically handles data extraction and can work with any features available in the object. The plot uses automatic threshold detection based on data quantiles if thresholds are not manually specified.

The visualization employs a three-color scheme: * Points below both thresholds are colored using the first specified color * Points passing either x or y threshold (but not both) use the second color * Points passing both thresholds use the third color

The function automatically labels the top features in both directions (positive and negative changes) that pass both thresholds. The number of features to label can be controlled using the `top.n` parameter.

When `y = "p"`, the y-axis displays -log10 transformed p-values.

Examples

# Basic usage with a Seurat object
VolcanoPlot(pbmc)

# Compare specific cell types with customized thresholds
VolcanoPlot(
  pbmc,
  ident.1 = "B cell",
  ident.2 = "CD8 T cell",
  x.threshold = 1,
  y.threshold = 5
)

# Customize appearance
VolcanoPlot(
  pbmc,
  ident.1 = "B cell",
  ident.2 = "CD8 T cell",
  x.quantile = 0.99,    # Less stringent x threshold
  y.quantile = 0.95,    # More stringent y threshold
  top.n = 5,            # Label fewer genes
  color = c("grey20", "grey70", "darkred")  # Custom colors
)

# Use t-score instead of p-value for y-axis
VolcanoPlot(
  pbmc,
  ident.1 = "B cell",
  ident.2 = "CD8 T cell",
  y = "tscore"
)

# Direct usage with a matrix
pbmc <- GeneSetAnalysisGO(pbmc, parent = "immune_system_process", spe = "human")
matr <- pbmc@misc$AUCell$GO$immune_system_process

# Generate a volcano plot comparing B cell with CD8 T cells.
VolcanoPlot(
  matr,
  f = pbmc$cluster,
  ident.1 = "B cell",
  ident.2 = "CD8 T cell",
  x.quantile = 0.8,
  y.quantile = 0.8,
  top.n = 5)