pathway_ridgeplot: 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. This helps interpret whether pathways are predominantly up- or down-regulated.

Usage

pathway_ridgeplot(
  gsea_results,
  abundance,
  metadata,
  group,
  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
)

Value

A ggplot2 object that can be further customized or saved.

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.
metadata: A data frame containing sample metadata with group information.
group: Character string specifying the column name in metadata for grouping.
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

The plot requires the ggridges package to be installed.

Examples

Run this code

if (FALSE) {
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)
}