gsea

name	gsea
description	Run GSEA on a ranked gene list and produce the enrichment table, running-score table, and enrichment plots.
license	MIT
author	AIPOCH

Source: https://github.com/aipoch/medical-research-skills

When to read external files

Situation	Read	Purpose
Need algorithm details	references/algorithm.md	Statistical method and formulas
Need to run an analysis	scripts/main.R	Full command reference
Hit an error	references/troubleshooting.md	Look up error codes and fixes
Need CLI examples	references/cli-guide.md	Worked argument examples

Scope

Use this skill for:

• Running GSEA on a gene list ranked by a statistic
• Generating enrichment curve plots from existing enrichGSEA.csv and gsea_running_scores.csv
• Smoke-testing the pipeline with tests/data/sample_deg_results.csv

Do not use it for:

• Differential expression on raw expression matrices
• Single-sample ssGSEA
• Network analysis or multi-omics integration

Usage

Analysis mode: Rscript scripts/main.R --input tests/data/sample_deg_results.csv --outdir ./GSEA_analysis --type KEGG --species human --seed 42 --timeout 300

Plot mode: Rscript scripts/main.R --running_file ./GSEA_analysis/Table/gsea_running_scores.csv --enrich_file ./GSEA_analysis/Table/enrichGSEA.csv --plot_output ./GSEA_analysis/plot/gsea_plot.pdf --top_n 5 --plot_format pdf --seed 42 --timeout 300

See references/cli-guide.md for more.

Mode selection:

• Passing only --input runs analysis mode
• Passing both --running_file and --enrich_file runs plot mode
• If both sets of arguments are provided, plot mode takes precedence; analysis mode is skipped and a warning is logged

Arguments

Analysis-mode arguments

Short	Long	Type	Default	Required	Description
-i	--input	character	NULL	yes	Input CSV file
-o	--outdir	character	GSEA_analysis	no	Output directory
-g	--gene_col	character	name	no	Gene column name
-f	--fc_col	character	logFC	no	Ranking-statistic column name
-t	--type	character	KEGG	no	Gene-set type: KEGG, HALLMARKS, GO_BP, GO_MF, GO_CC. With a preloaded RDS, HALLMARKS is automatically mapped to the asset key Hallmarks
-s	--species	character	human	no	Species: human, mouse, rat
-p	--pvalue_cutoff	numeric	0.05	no	Significance threshold
-m	--method	character	fgsea	no	GSEA backend: fgsea or DOSE
-c	--chunk_size	numeric	1000	no	Chunk size for large gene-set conversion

Plot-mode arguments

Short	Long	Type	Default	Required	Description
	--running_file	character	NULL	yes	Path to gsea_running_scores.csv
	--enrich_file	character	NULL	yes	Path to enrichGSEA.csv
	--plot_output	character	gsea_plot.pdf	no	Output plot path
	--plot_width	numeric	8	no	Plot width
	--plot_height	numeric	6	no	Plot height
	--plot_format	character	pdf	no	Output format: pdf or png
	--top_n	numeric	1	no	Number of top pathways to plot when geneSetID is not given
	--rank_by	character	p.adjust	no	Column used to rank pathways
	--geneSetID	character	""	no	Comma-separated pathway IDs
	--plot_title	character	""	no	Plot title
	--colors	character	#4DBBD5,#E64B35,#00A087,#F39B7F,#3C5488,#8491B4	no	Color list
	--base_size	numeric	11

Input format

Analysis-mode input is a CSV with at least:

• a gene column (default name name)
• a ranking-statistic column (default name logFC)

Example:

name,logFC,pvalue,padj
TP53,2.5,0.001,0.01
BRCA1,1.8,0.005,0.02
EGFR,-1.2,0.01,0.05

Value constraints:

• type accepts KEGG, HALLMARKS, GO_BP, GO_MF, GO_CC
• When using a preloaded RDS, HALLMARKS is automatically matched to the asset key Hallmarks
• species accepts human, mouse, rat

Output files

File	Format	Description
data/GSEA_list.rda	RDA	Full GSEA result object
Table/enrichGSEA.csv	CSV	Enrichment result table
Table/gsea_running_scores.csv	CSV	Running-score table; if no enrichment passes, a header-only file is still written
plot/	directory	Plot output directory
session_info.txt	TXT	R version and package versions

enrichGSEA.csv mainly contains: ID, Description, NES, pvalue, p.adjust, core_enrichment.

Error handling

Common error codes:

• SKILL_FILE_NOT_FOUND: input file does not exist
• SKILL_MISSING_COLUMNS: required columns are missing
• SKILL_EMPTY_DATA: input is empty, or empty after filtering
• SKILL_INVALID_PARAMETER: an argument has an invalid value
• SKILL_PACKAGE_NOT_FOUND: a required package is not installed
• SKILL_ANALYSIS_FAILED: GSEA still failed after retries

Triage doc: references/troubleshooting.md

Exit codes:

• 0: success
• 1: failure

Testing

Minimal test dataset: tests/data/sample_deg_results.csv

Minimal command: Rscript scripts/main.R --input tests/data/sample_deg_results.csv --outdir ./test_output --type KEGG --species human --seed 42 --timeout 300 --verbose

Expected output:

• ./test_output/data/GSEA_list.rda
• ./test_output/Table/enrichGSEA.csv
• ./test_output/Table/gsea_running_scores.csv
• ./test_output/session_info.txt
• If no significant enrichment is found, gsea_running_scores.csv is still written but contains only the header
• Exit code 0