gsea

Run GSEA on a ranked gene list and produce the enrichment table, running-score table, and enrichment plots.

Quality

74%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./awesome-med-research-skills/Data Analysis/gsea/SKILL.md

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
`-r`	`--rds_path`	character	`NULL`	no	Path to a pre-stored gene-set RDS
`-v`	`--verbose`	logical	`FALSE`	no	Verbose logging
	`--seed`	integer	`42`	no	Random seed
	`--timeout`	integer	`300`	no	Timeout in seconds; `<=0` disables it
`-h`	`--help`	logical	`FALSE`	no	Show help

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`	no	Base font size
	`--subplots`	character	`1,2,3`	no	Sub-panel indices to display
	`--rel_heights`	character	`1.5,0.8,1`	no	Relative panel heights
	`--NES_table`	logical	`TRUE`	no	Show NES annotation
	`--no_NES_table`	logical	`FALSE`	no	Disable NES annotation
	`--NES_label_size`	numeric	`4`	no	NES label font size
	`--NES_label_x`	numeric	`0.75`	no	NES label x position
	`--NES_label_y`	numeric	`0.75`	no	NES label y position
	`--NES_label_color`	character	`black`	no	NES label color
	`--NES_label_hjust`	numeric	`0`	no	NES label horizontal justification
	`--NES_label_vjust`	numeric	`1`	no	NES label vertical justification
	`--line_width`	numeric	`1`	no	ES line width
	`--dot_size`	numeric	`1.2`	no	ES dot size
	`--legend_position`	character	`auto`	no	Legend position
	`--legend_x`	numeric	`0.02`	no	Inset legend x coordinate
	`--legend_y`	numeric	`0.02`	no	Inset legend y coordinate
	`--legend_just_x`	numeric	`0`	no	Legend horizontal justification
	`--legend_just_y`	numeric	`0`	no	Legend vertical justification
	`--legend_text_size`	numeric	`9`	no	Legend text size
	`--legend_key_size`	numeric	`0.6`	no	Legend key size
	`--legend_bg_alpha`	numeric	`0`	no	Legend background alpha
	`--grid_major_color`	character	`grey92`	no	Major grid color
	`--grid_minor_color`	character	`grey92`	no	Minor grid color
	`--ylab_es`	character	`Enrichment Score`	no	ES panel y-axis title
	`--ylab_rank`	character	`Ranked List Metric`	no	Rank panel y-axis title
	`--xlab_rank`	character	`Rank in Ordered Dataset`	no	Rank panel x-axis title
	`--hit_height`	numeric	`1`	no	Hit-bar height
	`--hit_gap`	numeric	`0`	no	Hit-bar gap
	`--hit_linewidth`	numeric	`0.5`	no	Hit-bar line width
	`--rank_bar_alpha`	numeric	`0.9`	no	Rank-bar alpha
	`--rank_bar_height_ratio`	numeric	`0.3`	no	Rank-bar height ratio
	`--rank_metric_segment_color`	character	`grey`	no	Rank-line color
	`--rank_metric_segment_width`	numeric	`0.3`	no	Rank-line width
	`--rank_metric_segment_alpha`	numeric	`1`	no	Rank-line alpha
	`--pvalue_table`	logical	`FALSE`	no	Show p-value table
	`--ES_geom`	character	`line`	no	ES geometry: `line` or `dot`
	`--verbose`	logical	`FALSE`	no	Verbose logging
	`--seed`	integer	`42`	no	Random seed
	`--timeout`	integer	`300`	no	Timeout in seconds; `<=0` disables it
`-h`	`--help`	logical	`FALSE`	no	Show help

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

Repository: aipoch/medical-research-skills
Path: awesome-med-research-skills/Data Analysis/gsea/SKILL.md
Commit: f5ef65b

Last updated: ~10 hours ago
First committed: 3 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.