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 existSKILL_MISSING_COLUMNS: required columns are missingSKILL_EMPTY_DATA: input is empty, or empty after filteringSKILL_INVALID_PARAMETER: an argument has an invalid valueSKILL_PACKAGE_NOT_FOUND: a required package is not installedSKILL_ANALYSIS_FAILED: GSEA still failed after retries
Triage doc: references/troubleshooting.md
Exit codes:
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
1---2name: gsea3description: Run GSEA on a ranked gene list and produce the enrichment table, running-score table, and enrichment plots.4license: MIT5---6> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)
7
8## When to read external files
9
10| Situation | Read | Purpose |
11|---|---|---|
12| Need algorithm details | `references/algorithm.md` | Statistical method and formulas |
13| Need to run an analysis | `scripts/main.R` | Full command reference |
14| Hit an error | `references/troubleshooting.md` | Look up error codes and fixes |
15| Need CLI examples | `references/cli-guide.md` | Worked argument examples |
16
17## Scope
18
19Use this skill for:
20- Running GSEA on a gene list ranked by a statistic
21- Generating enrichment curve plots from existing `enrichGSEA.csv` and `gsea_running_scores.csv`
22- Smoke-testing the pipeline with `tests/data/sample_deg_results.csv`
23
24Do not use it for:
25- Differential expression on raw expression matrices
26- Single-sample ssGSEA
27- Network analysis or multi-omics integration
28
29## Usage
30
31Analysis mode:
32`Rscript scripts/main.R --input tests/data/sample_deg_results.csv --outdir ./GSEA_analysis --type KEGG --species human --seed 42 --timeout 300`
33
34Plot mode:
35`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`
36
37See `references/cli-guide.md` for more.
38
39Mode selection:
40- Passing only `--input` runs analysis mode
41- Passing both `--running_file` and `--enrich_file` runs plot mode
42- If both sets of arguments are provided, plot mode takes precedence; analysis mode is skipped and a warning is logged
43
44## Arguments
45
46### Analysis-mode arguments
47
48| Short | Long | Type | Default | Required | Description |
49|---|---|---|---|---|---|
50| `-i` | `--input` | character | `NULL` | yes | Input CSV file |
51| `-o` | `--outdir` | character | `GSEA_analysis` | no | Output directory |
52| `-g` | `--gene_col` | character | `name` | no | Gene column name |
53| `-f` | `--fc_col` | character | `logFC` | no | Ranking-statistic column name |
54| `-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` |
55| `-s` | `--species` | character | `human` | no | Species: `human`, `mouse`, `rat` |
56| `-p` | `--pvalue_cutoff` | numeric | `0.05` | no | Significance threshold |
57| `-m` | `--method` | character | `fgsea` | no | GSEA backend: `fgsea` or `DOSE` |
58| `-c` | `--chunk_size` | numeric | `1000` | no | Chunk size for large gene-set conversion |
59| `-r` | `--rds_path` | character | `NULL` | no | Path to a pre-stored gene-set RDS |
60| `-v` | `--verbose` | logical | `FALSE` | no | Verbose logging |
61| | `--seed` | integer | `42` | no | Random seed |
62| | `--timeout` | integer | `300` | no | Timeout in seconds; `<=0` disables it |
63| `-h` | `--help` | logical | `FALSE` | no | Show help |
64
65### Plot-mode arguments
66
67| Short | Long | Type | Default | Required | Description |
68|---|---|---|---|---|---|
69| | `--running_file` | character | `NULL` | yes | Path to `gsea_running_scores.csv` |
70| | `--enrich_file` | character | `NULL` | yes | Path to `enrichGSEA.csv` |
71| | `--plot_output` | character | `gsea_plot.pdf` | no | Output plot path |
72| | `--plot_width` | numeric | `8` | no | Plot width |
73| | `--plot_height` | numeric | `6` | no | Plot height |
74| | `--plot_format` | character | `pdf` | no | Output format: `pdf` or `png` |
75| | `--top_n` | numeric | `1` | no | Number of top pathways to plot when `geneSetID` is not given |
76| | `--rank_by` | character | `p.adjust` | no | Column used to rank pathways |
77| | `--geneSetID` | character | `""` | no | Comma-separated pathway IDs |
78| | `--plot_title` | character | `""` | no | Plot title |
79| | `--colors` | character | `#4DBBD5,#E64B35,#00A087,#F39B7F,#3C5488,#8491B4` | no | Color list |
80| | `--base_size` | numeric | `11` | no | Base font size |
81| | `--subplots` | character | `1,2,3` | no | Sub-panel indices to display |
82| | `--rel_heights` | character | `1.5,0.8,1` | no | Relative panel heights |
83| | `--NES_table` | logical | `TRUE` | no | Show NES annotation |
84| | `--no_NES_table` | logical | `FALSE` | no | Disable NES annotation |
85| | `--NES_label_size` | numeric | `4` | no | NES label font size |
86| | `--NES_label_x` | numeric | `0.75` | no | NES label x position |
87| | `--NES_label_y` | numeric | `0.75` | no | NES label y position |
88| | `--NES_label_color` | character | `black` | no | NES label color |
89| | `--NES_label_hjust` | numeric | `0` | no | NES label horizontal justification |
90| | `--NES_label_vjust` | numeric | `1` | no | NES label vertical justification |
91| | `--line_width` | numeric | `1` | no | ES line width |
92| | `--dot_size` | numeric | `1.2` | no | ES dot size |
93| | `--legend_position` | character | `auto` | no | Legend position |
94| | `--legend_x` | numeric | `0.02` | no | Inset legend x coordinate |
95| | `--legend_y` | numeric | `0.02` | no | Inset legend y coordinate |
96| | `--legend_just_x` | numeric | `0` | no | Legend horizontal justification |
97| | `--legend_just_y` | numeric | `0` | no | Legend vertical justification |
98| | `--legend_text_size` | numeric | `9` | no | Legend text size |
99| | `--legend_key_size` | numeric | `0.6` | no | Legend key size |
100| | `--legend_bg_alpha` | numeric | `0` | no | Legend background alpha |
101| | `--grid_major_color` | character | `grey92` | no | Major grid color |
102| | `--grid_minor_color` | character | `grey92` | no | Minor grid color |
103| | `--ylab_es` | character | `Enrichment Score` | no | ES panel y-axis title |
104| | `--ylab_rank` | character | `Ranked List Metric` | no | Rank panel y-axis title |
105| | `--xlab_rank` | character | `Rank in Ordered Dataset` | no | Rank panel x-axis title |
106| | `--hit_height` | numeric | `1` | no | Hit-bar height |
107| | `--hit_gap` | numeric | `0` | no | Hit-bar gap |
108| | `--hit_linewidth` | numeric | `0.5` | no | Hit-bar line width |
109| | `--rank_bar_alpha` | numeric | `0.9` | no | Rank-bar alpha |
110| | `--rank_bar_height_ratio` | numeric | `0.3` | no | Rank-bar height ratio |
111| | `--rank_metric_segment_color` | character | `grey` | no | Rank-line color |
112| | `--rank_metric_segment_width` | numeric | `0.3` | no | Rank-line width |
113| | `--rank_metric_segment_alpha` | numeric | `1` | no | Rank-line alpha |
114| | `--pvalue_table` | logical | `FALSE` | no | Show p-value table |
115| | `--ES_geom` | character | `line` | no | ES geometry: `line` or `dot` |
116| | `--verbose` | logical | `FALSE` | no | Verbose logging |
117| | `--seed` | integer | `42` | no | Random seed |
118| | `--timeout` | integer | `300` | no | Timeout in seconds; `<=0` disables it |
119| `-h` | `--help` | logical | `FALSE` | no | Show help |
120
121## Input format
122
123Analysis-mode input is a CSV with at least:
124- a gene column (default name `name`)
125- a ranking-statistic column (default name `logFC`)
126
127Example:
128```csv
129name,logFC,pvalue,padj
130TP53,2.5,0.001,0.01
131BRCA1,1.8,0.005,0.02
132EGFR,-1.2,0.01,0.05
133```
134
135Value constraints:
136- `type` accepts `KEGG`, `HALLMARKS`, `GO_BP`, `GO_MF`, `GO_CC`
137- When using a preloaded RDS, `HALLMARKS` is automatically matched to the asset key `Hallmarks`
138- `species` accepts `human`, `mouse`, `rat`
139
140## Output files
141
142| File | Format | Description |
143|---|---|---|
144| `data/GSEA_list.rda` | RDA | Full GSEA result object |
145| `Table/enrichGSEA.csv` | CSV | Enrichment result table |
146| `Table/gsea_running_scores.csv` | CSV | Running-score table; if no enrichment passes, a header-only file is still written |
147| `plot/` | directory | Plot output directory |
148| `session_info.txt` | TXT | R version and package versions |
149
150`enrichGSEA.csv` mainly contains: `ID`, `Description`, `NES`, `pvalue`, `p.adjust`, `core_enrichment`.
151
152## Error handling
153
154Common error codes:
155- `SKILL_FILE_NOT_FOUND`: input file does not exist
156- `SKILL_MISSING_COLUMNS`: required columns are missing
157- `SKILL_EMPTY_DATA`: input is empty, or empty after filtering
158- `SKILL_INVALID_PARAMETER`: an argument has an invalid value
159- `SKILL_PACKAGE_NOT_FOUND`: a required package is not installed
160- `SKILL_ANALYSIS_FAILED`: GSEA still failed after retries
161
162Triage doc: `references/troubleshooting.md`
163
164Exit codes:
165- `0`: success
166- `1`: failure
167
168## Testing
169
170Minimal test dataset: `tests/data/sample_deg_results.csv`
171
172Minimal command:
173`Rscript scripts/main.R --input tests/data/sample_deg_results.csv --outdir ./test_output --type KEGG --species human --seed 42 --timeout 300 --verbose`
174
175Expected output:
176- `./test_output/data/GSEA_list.rda`
177- `./test_output/Table/enrichGSEA.csv`
178- `./test_output/Table/gsea_running_scores.csv`
179- `./test_output/session_info.txt`
180- If no significant enrichment is found, `gsea_running_scores.csv` is still written but contains only the header
181- Exit code `0`
gabrielmoreira