pathway_ridgeplot: Ridge Plot for GSEA Results

In ggpicrust2: Make 'PICRUSt2' Output Analysis and Visualization Easier

Ridge Plot for GSEA Results

Description

Creates a ridge plot (joy plot) to visualize the distribution of gene/KO abundances or fold changes for enriched pathways from GSEA analysis. The distribution is descriptive: it uses group means of the supplied abundance, not the covariate-adjusted model coefficients or voom weights from a camera/fry analysis. Direction colors describe the GSEA test and need not agree with every member's abundance ratio.

Usage

pathway_ridgeplot(
  gsea_results,
  abundance,
  metadata,
  group,
  comparison = NULL,
  pathway_reference = NULL,
  pathway_type = "KEGG",
  n_pathways = 10,
  sort_by = "p.adjust",
  show_direction = TRUE,
  colors = c(Down = "#3182bd", Up = "#de2d26"),
  title = "Ridge Plot: Gene Distribution in Enriched Pathways",
  x_lab = "log2 Fold Change",
  scale_height = 0.9,
  alpha = 0.7
)

Arguments

gsea_results	A data frame containing GSEA results from pathway_gsea. Must contain pathway_id column and either NES or direction column.
abundance	A data frame or matrix containing the original abundance data (genes/KOs as rows, samples as columns) used in the GSEA analysis. Data frames may also provide a leading non-numeric feature ID column (for example #NAME, feature, or pathway); it is converted to row names before sample alignment.
metadata	A data frame containing sample metadata with group information.
group	Character string specifying the column name in metadata for grouping.
comparison	Optional character vector of length 2 specifying c(group1, group2) for fold-change calculation. The ridge plot displays log2(group2 / group1). If NULL, the data must contain exactly two group levels and their factor-level order is used. For multi-group metadata, specify comparison explicitly so the plot matches the GSEA contrast being interpreted.
pathway_reference	A data frame containing pathway-to-gene mappings. Must have columns: pathway_id (or go_id for GO) and a column containing gene/KO members (semicolon-separated). If NULL, attempts to use built-in KEGG or GO reference data.
pathway_type	Character string specifying the pathway type: "KEGG", "GO", or "MetaCyc". Default is "KEGG".
n_pathways	Integer specifying the number of top pathways to display. Default is 10.
sort_by	Character string specifying how to sort pathways: "NES" (Normalized Enrichment Score), "pvalue", or "p.adjust". Default is "p.adjust".
show_direction	Logical. If TRUE, colors ridges by enrichment direction. Default is TRUE.
colors	Named character vector with colors for "Up" and "Down" directions. Default is blue for down-regulated and red for up-regulated.
title	Character string for plot title.
x_lab	Character string for x-axis label.
scale_height	Numeric value controlling the overlap of ridges. Default is 0.9. Higher values create more overlap.
alpha	Numeric value for ridge transparency (0-1). Default is 0.7.

Details

The ridge plot displays the distribution of gene abundances (or fold changes) for genes within each enriched pathway. This visualization helps to:

• Understand the overall direction of change for each pathway

• Identify pathways with consistent vs. heterogeneous gene expression

• Compare the magnitude of changes across pathways

Fold changes are calculated as log2(group2 / group1), where group1 and group2 come from comparison or, for a two-group dataset, from the factor-level order of group. GSEA pathway_id values must be non-empty and unique. Missing or empty pathway_name values are displayed as their corresponding pathway_id.

The plot requires the ggridges package to be installed.

Value

A ggplot2 object that can be further customized or saved.

See Also

pathway_gsea, visualize_gsea, pathway_volcano

Examples

## Not run: 
library(ggpicrust2)
library(tibble)

# Load example data
data("ko_abundance")
data("metadata")

# Run GSEA (using camera method - recommended)
gsea_results <- pathway_gsea(
  abundance = ko_abundance %>% column_to_rownames("#NAME"),
  metadata = metadata,
  group = "Environment",
  pathway_type = "KEGG",
  method = "camera"
)

# Create ridge plot
ridge_plot <- pathway_ridgeplot(
  gsea_results = gsea_results,
  abundance = ko_abundance %>% column_to_rownames("#NAME"),
  metadata = metadata,
  group = "Environment",
  n_pathways = 10
)
print(ridge_plot)

## End(Not run)

ggpicrust2 documentation built on Oct. 7, 2026, 1:07 a.m.