Skip to contents

Ridge Plot for GSEA Results

Source: R/pathway_ridgeplot.R
pathway_ridgeplot.Rd

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.

Value

A ggplot2 object that can be further customized or saved.

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.

See also

pathway_gsea, visualize_gsea, pathway_volcano

Examples

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