AGENT SKILL

gokegg-analysis

Use when performing GO and KEGG enrichment on a gene list from bulk RNA-seq or microarray studies, then generating a combined GO/KEGG dot chart. NOT for single-cell RNA-seq, methylation data, or non-expression data.

License 许可
MIT
最近更新
2026-10-12
Stars
★ 2
Forks
0

01 前言 Front Matter

name
gokegg-analysis
author
AIPOCH
license
MIT
description
Use when performing GO and KEGG enrichment on a gene list from bulk RNA-seq or microarray studies, then generating a combined GO/KEGG dot chart. NOT for single-cell RNA-seq, methylation data, or non-expression data.

02 资源文件 10

03 SKILL.md 正文

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

When To Read External Files

Situation File To Read Purpose
Need algorithm details references/algorithm.md Statistical methods and formulas
Need to run the analysis scripts/main.R Full execution command
Encounter an error references/troubleshooting.md Troubleshooting guidance
Need CLI examples references/cli-guide.md Parameter usage examples

When To Use

Use this skill for:

  • GO and KEGG enrichment from a gene list derived from bulk RNA-seq or microarray studies
  • Supported gene ID types: SYMBOL, ENSEMBL, ENTREZID
  • Supported species databases: org.Hs.eg.db, org.Mm.eg.db, org.Rn.eg.db

Do not use this skill for:

  • Single-cell RNA-seq analysis
  • Methylation, proteomics, or non-expression omics workflows
  • Differential expression testing from raw count matrices

Usage

Main analysis and plotting: Rscript scripts/main.R --feature "TP53,EGFR,BRCA1,MYC" --output_dir ./output --sp org.Hs.eg.db --gene_type SYMBOL --pvalue_cutoff 0.05 --qvalue_cutoff 0.2 --pAdjustMethod BH --seed 66 --go_top_n 3 --kegg_top_n 3 --format pdf

Notes:

  • scripts/main.R is the only command-line entry point
  • scripts/dochart.R currently provides plotting functions and is sourced by scripts/main.R
  • If --go_input, --kegg_input, or --outdir are omitted, main.R uses output_dir/temp/GO_list.rda, output_dir/temp/KEGG_list.rda, and output_dir/plot automatically

Agent Output

On success, the agent should report:

  • Whether GO enrichment completed successfully
  • Whether KEGG enrichment completed successfully
  • The normalized input gene count after trimming and parsing
  • The main output directory
  • The generated files, especially GO_df.csv, KEGG_df.csv, GO_list.rda, KEGG_list.rda, and the combined dot chart
  • The path to session_info.txt

Post-run checklist:

  • Re-parse the original --feature string using the documented separator rules and report the deduplicated gene count after trimming
  • Check temp/GO_df.csv and temp/GO_list.rda before claiming GO success
  • Check temp/KEGG_df.csv and temp/KEGG_list.rda before claiming KEGG success
  • Check plot/gokegg_dot_chart.<format>, plot/gokegg_dot_chart_data.csv, plot/gokegg_dot_chart_data.rda, and session_info.txt before claiming full success
  • Summarize the final result with: parsed gene count, GO status, KEGG status, plot status, output directory, and key output files

On failure, the agent should report:

  • The exact SKILL_* error code
  • The failing step, such as gene parsing, ID conversion, enrichment, or plotting
  • The actionable next step, such as fixing input IDs, checking missing packages, or regenerating .rda files

Parameter Reference

scripts/main.R

Short Long Type Default Required Description
-f --feature character "" Yes Gene list separated by commas, Chinese commas, semicolons, tabs, or newlines
-o --output_dir character ./output/ No Main output directory
-s --sp character org.Hs.eg.db No Species database
-g --gene_type character SYMBOL No Input gene ID type
-p --pvalue_cutoff numeric 0.05 No Enrichment p-value cutoff
-q --qvalue_cutoff numeric 0.2 No Enrichment q-value cutoff
-m --pAdjustMethod character BH No P-value adjustment method
--seed integer 66 No Random seed
--go_input character NULL No Optional GO .rda; defaults to output_dir/temp/GO_list.rda
--kegg_input character NULL No Optional KEGG .rda; defaults to output_dir/temp/KEGG_list.rda
--outdir character NULL No Plot output directory; defaults to output_dir/plot
--go_top_n numeric 3 No Top GO terms per ontology
--kegg_top_n numeric 3 No Top KEGG pathways
-w --width numeric 20 No Plot width in cm
--height numeric 16 No Plot height in cm
--format character pdf No Plot format: pdf, png, svg
--dpi numeric 300 No DPI for raster output
-c --colors character #E41A1C,#FFFF33,#2E86AB,#4DAF4A No Colors for GO:BP,GO:CC,GO:MF,KEGG
--title character GO + KEGG Dot Chart No Plot title
--xlab character NULL No Horizontal axis label override
--ylab character NULL No Vertical axis label override
--dot_size numeric 4.5 No Dot size
--shape numeric 19 No Dot shape
--rotate / --no-rotate logical flag TRUE No Rotate plot orientation on or off
--sorting character descending No Dot sorting order
--label_width numeric 35 No Label wrap width
--title_size numeric 12 No Title font size
--axis_title_size numeric 9 No Axis title font size
--axis_text_size numeric 8 No Axis text font size
--legend_title_size numeric 8 No Legend title font size
--legend_text_size numeric 7 No Legend text font size
--legend_position character top No Legend position
--plot_margin character 10,10,10,10 No Plot margins: top,right,bottom,left
--axis_line_size numeric 0.5 No Axis line width
--axis_ticks_size numeric 0.5 No Axis tick width
--show_grid logical FALSE No Show grid lines
-v --verbose logical FALSE No Enable verbose logging

Input Format

Main Analysis Input

  • --feature should be provided as a gene list
  • Preferred separator: comma
  • Also accepted: Chinese commas, semicolons, tabs, and newlines
  • Leading and trailing spaces around each gene are removed automatically with trimming
  • The gene ID type must match --gene_type
  • --sp supports only org.Hs.eg.db, org.Mm.eg.db, and org.Rn.eg.db

Examples: TP53,EGFR,BRCA1,MYC

TP53, EGFR, BRCA1, MYC

TP53;EGFR;BRCA1;MYC

TP53\nEGFR\nBRCA1\nMYC

Example command with minimal input: Rscript scripts/main.R --feature "TP53,EGFR,BRCA1,MYC" --output_dir ./example_output --sp org.Hs.eg.db --gene_type SYMBOL

Example command with custom plotting parameters: Rscript scripts/main.R --feature "TP53,EGFR,BRCA1,MYC" --output_dir ./example_plot_output --sp org.Hs.eg.db --gene_type SYMBOL --go_top_n 5 --kegg_top_n 8 --colors "#E41A1C,#FFFF33,#2E86AB,#4DAF4A" --title "Custom GO + KEGG Dot Chart" --xlab="-log10(adjusted p-value)" --ylab="Enriched Terms" --width 24 --height 18 --label_width 40 --format png --dpi 300 --no-rotate --verbose

Note: values passed to --xlab or --ylab that start with - should use --option=value syntax to avoid being parsed as flags.

Note: separator variants are supported only when they are passed inside a single --feature argument value.

Plot Input

  • Plotting is triggered by scripts/main.R
  • --go_input: optional .rda file containing a GO_list object
  • --kegg_input: optional .rda file containing a KEGG_list object
  • If not provided, main.R uses the newly generated files under output_dir/temp
  • Plotting requires result tables with at least Description and p.adjust

Output Files

File Name Format Description
temp/GO_df.csv CSV GO enrichment result table
temp/GO_list.rda RDA Full GO enrichment object
temp/KEGG_df.csv CSV KEGG enrichment result table
temp/KEGG_list.rda RDA Full KEGG enrichment object
plot/gokegg_dot_chart.pdf etc. PDF/PNG/SVG Combined GO/KEGG dot chart
plot/gokegg_dot_chart_data.csv CSV Combined plotting table used for the figure
plot/gokegg_dot_chart_data.rda RDA Plot bundle with plotting data and parameters
session_info.txt TXT Runtime session information

Error Handling

Common error codes and fixes:

  • SKILL_FILE_NOT_FOUND: Input file does not exist; check the path and permissions
  • SKILL_FILE_FORMAT_ERROR: .rda cannot be read or is malformed; regenerate upstream results
  • SKILL_MISSING_COLUMNS: Result table is missing Description or p.adjust
  • SKILL_EMPTY_DATA: Input genes are empty after parsing, cannot be converted, or enrichment results are empty
  • SKILL_INVALID_PARAMETER: Required parameter missing, unsupported species, or insufficient color count
  • SKILL_PACKAGE_NOT_FOUND: Required package is not installed
  • SKILL_ANALYSIS_FAILED: Internal GO/KEGG enrichment failure; verify gene_type, sp, and input genes

For detailed troubleshooting, read references/troubleshooting.md.

Testing

Minimal test dataset: use a small built-in gene list directly, with no extra files required.

Smoke test command: Rscript scripts/main.R --feature "TP53,EGFR,BRCA1,MYC" --output_dir ./test_output --sp org.Hs.eg.db --gene_type SYMBOL --pvalue_cutoff 0.05 --qvalue_cutoff 0.2 --pAdjustMethod BH --seed 66 --go_top_n 3 --kegg_top_n 3 --format pdf --verbose

Expected smoke-test outputs:

  • ./test_output/temp/GO_list.rda
  • ./test_output/temp/KEGG_list.rda
  • ./test_output/temp/GO_df.csv
  • ./test_output/temp/KEGG_df.csv
  • ./test_output/plot/gokegg_dot_chart.pdf
  • ./test_output/plot/gokegg_dot_chart_data.csv
  • ./test_output/plot/gokegg_dot_chart_data.rda
  • ./test_output/session_info.txt
  • Exit status code 0

Automated regression script: Rscript test/test_regressions.R

The regression script covers:

  • Separator parsing with comma, Chinese semicolon, newline, tab, and mixed separators
  • Empty parsed-gene handling
  • Invalid --plot_margin validation
  • Plot input validation for missing GO/KEGG inputs

Separator examples for manual CLI verification: Rscript scripts/main.R --feature "TP53,EGFR,BRCA1,MYC" --output_dir ./test_sep_comma Rscript scripts/main.R --feature "TP53;EGFR;BRCA1;MYC" --output_dir ./test_sep_cn_semicolon Rscript scripts/main.R --feature $'TP53\nEGFR\nBRCA1\nMYC' --output_dir ./test_sep_newline Rscript scripts/main.R --feature $'TP53\tEGFR\tBRCA1\tMYC' --output_dir ./test_sep_tab Rscript scripts/main.R --feature $'TP53; EGFR, BRCA1 MYC' --output_dir ./test_sep_mixed

Note: all separators must be passed inside a single --feature argument value.

04 同仓库更多 Skills

mrsonord2240
mrsonord2240/openscience-specialists

bio-workflows-metabolomics-pipeline

Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC/drift/normalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics/isotope-tracing.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-xcms-preprocessing

Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment/XcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave/grouping/alignment parameters. For drift correction and QC/CV filtering execution see metabolomics/normalization-qc; for metabolite identification see metabolomics/metabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics/msdial-preprocessing; for downstream statistics see metabolomics/statistical-analysis.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-statistical-analysis

Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA/HCA for QC), permutation-validated PLS-DA/OPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch/Mann-Whitney/ANOVA/LMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization/drift correction see metabolomics/normalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning/biomarker-discovery and machine-learning/model-validation; for pathway interpretation see metabolomics/pathway-mapping; for design/power/multiplicity regime see experimental-design/multiple-testing.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-pathway-mapping

Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA/QEA), mummichog/PSEA on raw m/z peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference/background set. For annotation confidence levels feeding ORA see metabolomics/metabolite-annotation; for gene-set concepts see pathway-analysis/go-enrichment and pathway-analysis/gsea; for joint gene+metabolite pathways see multi-omics-integration/mofa-integration.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-normalization-qc

Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS/GC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak/feature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics/xcms-preprocessing or metabolomics/msdial-preprocessing; transformation/scaling for modeling defers to metabolomics/statistical-analysis; cross-study design issues link to experimental-design/batch-design.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-msdial-preprocessing

Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA/DIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics/xcms-preprocessing; for lipid annotation mode see metabolomics/lipidomics; for MSI-level confidence honesty see metabolomics/metabolite-annotation; for drift correction and QC see metabolomics/normalization-qc.

★ 2