tooluniverse-gene-enrichment

説明するのではなく、計算する

統計、データ処理、スコアリング、データの拡充などで計算が必要な場合は、Bash 経由で Python コードを書いて実行してください。実行する内容を説明するのではなく、実際に実行し、結果を報告してください。ToolUniverse ツールを使ってデータを取得し、その後 Python（pandas、scipy、statsmodels、matplotlib）で分析してください。

遺伝子エンリッチメントとパスウェイ解析

ルール 0 — まず事前計算済みの結果を確認する

以下の指示に従う前に、データフォルダーをスキャンし、次のものがないか確認してください。

• *_executed.ipynb → tu run read_executed_notebook '{"data_folder":"<path>","search":"<keyword>"}' で読み取り、セルの出力を正式な回答として引用してください
• 事前計算済みのエンリッチメントファイル（*enrich*、*go*、*kegg*、*reactome*、*ego*、*_simplified.csv という名前の CSV/TSV）→ 直接読み取ってください
• 標準的な解析スクリプト（analysis.R、run_*.py、find_*.R、*.Rmd）→ そのまま実行し、出力を読み取ってください

上記のいずれもない場合に限り、このスキルの以下の再解析手順に従ってください。生の DEG リストからエンリッチメントを再実行すると、上流の微妙なフィルター条件の違いにより、公開済みの回答とは異なる数値が得られ、処理にも時間がかかります。

---

主要スクリプト — まずこれらを使用

3 つの決定論的な CLI スクリプトで、エンリッチメントに関する質問の大半に対応できます。 各スクリプトは、エージェントがアドホックなコードを書く際に誤りやすいエッジケース（上位での同順位、simplify による padj の変化、複数条件のスクリーニング）を処理します。 出力は必ず /tmp/... に書き込み、データフォルダーには絶対に書き込まないでください。

1. scripts/gseapy_enrichment_runner.py — gseapy enrichr / prerank

使用する場面: 質問で gseapy、enrichr、「Enrichr library」、または gseapy パッケージを介した GO BP/MF/CC、KEGG、Reactome、WikiPathways、MSigDB のエンリッチメントに言及している場合。

python skills/tooluniverse-gene-enrichment/scripts/gseapy_enrichment_runner.py \
    --gene-list /tmp/sig_symbols.txt \
    --library GO_Biological_Process_2021,Reactome_2022 \
    --organism Human \
    --top 5 \
    --candidate "negative regulation of epithelial cell proliferation" \
    --workdir /tmp/gseapy_run

出力内容（解析可能な行）:

• # TOP_BY_ADJ_PVALUE: <term> — df.sort_values('Adjusted P-value').iloc[0] が返す結果（公開済みノートブックで通常表示されるもの）
• # TIES_AT_TOP: n=K — 最小の Adjusted P-value で同順位となった用語の数
• # TOP_TIE_BROKEN: <term> — 決定論的な同順位の解消結果（adj_p、raw_p、overlap の降順、アルファベット順）
• # TOPN_BY_ADJ_PVALUE: — 上位 N 件の完全な一覧
• # CANDIDATE_RANK '<term>': rank=R adj_p=... — 渡した --candidate 部分文字列ごとの結果
• # SUBSTRING_COUNT_TOPN '<sub>': K — --count-substring クエリ用（例：「上位 20 件の用語のうち、'Oxidative' を含むものはいくつか」）

GSEA preranked を実行する場合は、--mode prerank --ranked-list /tmp/lfc.tsv を指定してください。

2. scripts/enrichgo_runner.py — clusterProfiler::enrichGO + simplify

使用する場面: 質問で enrichGO、clusterProfiler、simplify、simplify(cutoff=0.7) に言及している場合、またはデータフォルダーにこれらを使用する analysis.R / find_*.R がある場合。これは標準的な R ワークフローです。simplify によって多重検定の分母が変わり、残った用語の p.adjust 値も変化するため、gseapy では忠実に再現できません。

python skills/tooluniverse-gene-enrichment/scripts/enrichgo_runner.py \
    --gene-list /tmp/sig_ensembl.txt \
    --background /tmp/bg_ensembl.txt \
    --keytype ENSEMBL \
    --ontology BP \
    --simplify-cutoff 0.7 \
    --candidate "regulation of T cell activation" \
    --candidate "potassium ion transmembrane transport" \
    --workdir /tmp/enrichgo_run

出力内容:

• # TOP10_RAW: — as.data.frame(ego) の上位 10 件（simplify 前の生の p.adjust）
• # TOP10_SIMPLIFIED: — as.data.frame(simplify(ego, cutoff=0.7)) の上位 10 件（simplify 後。p.adjust は異なります）
• # CANDIDATE '<term>': raw_rank=R raw_padj=... simp_rank=R simp_padj=... — 各候補の simplify 前後の順位。simp_rank=NA (collapsed by simplify) は、その用語がより有意な親用語または兄弟用語と重複していたため削除されたことを意味します。

質問に「simplified results」または「after simplify」とある場合は、simp_padj を参照してください。単に「最もエンリッチされた」とだけあり、simplify への言及がない場合でも、標準的な analysis.R で simplify を呼び出しているなら、既定で簡略化後のデータフレームを使用してください。

R パッケージ clusterProfiler、org.Hs.eg.db（マウスの場合は org.Mm.eg.db）が必要です。不足している場合は、Rscript skills/evals/install_r_packages.R でインストールしてください。

3. scripts/condition_enrichment_screen.py — 条件ごとのエンリッチメント

使用する場合：「どの割合／パーセンテージの条件／スクリーン／時点／グループで、の有意なエンリッチメントが見られたか」という質問に答える場合、またはN条件×多数の遺伝子のテーブルがあり、条件ごとにエンリッチメントを調べる必要がある場合です。

# Per-condition gene-list files:
python skills/tooluniverse-gene-enrichment/scripts/condition_enrichment_screen.py \
    --condition-genes acute=/tmp/acute_sig.txt \
    --condition-genes round1=/tmp/r1_sig.txt \
    --condition-genes round2=/tmp/r2_sig.txt \
    --condition-genes round3=/tmp/r3_sig.txt \
    --library /path/to/local_pathways.gmt \
    --background /tmp/expressed.txt \
    --keyword immune --keyword cytokine --keyword interferon \
    --workdir /tmp/cond_screen

または、--conditions-tsv を使って、2列のTSV（condition<TAB>gene）を1つ渡します。

出力内容：

• 条件ごと：n_genes、sig_terms（Adj P < cutoff）、sig_terms_keyword（Term に --keyword のいずれかが含まれる有意な用語）
• # n_with_any_sig=N pct_with_any_sig=N% — 有意な用語が1つ以上ある条件の割合
• # n_with_keyword_sig=N pct_with_keyword_sig=N% — 有意な用語にカテゴリキーワードが含まれる条件の割合

注意事項：

• --library には、Enrichr のライブラリ名（オンライン）またはローカルの .gmt ファイルへのパスを指定できます。データフォルダーにローカルの GMT ファイルが含まれている場合は、そちらを優先してください（レート制限を回避でき、公開済みの結果を正確に再現できます）。
• 分母から除外するよう指定された「control」／「baseline」条件には、--exclude-condition <label> を使用します。
• 質問で「免疫関連」とされている一方、GT が有意なヒットをすべて数えている場合は、pct_with_any_sig と pct_with_keyword_sig の両方を報告し、ユーザーに選んでもらいます。

これらのスクリプトが存在する理由（デバッグ時の注意）

エンリッチメントの上位ヒットは、次の3点に大きく左右されます。

1. 上流の DEG フィルター（padj のみか、padj+|LFC|>0.5 か、+baseMean>10 か、lfc-shrunk か）。「正しい」フィルターは、標準となるノートブックで使用されたものです。エージェントがここで誤った推測をすると、遺伝子リストが異なり、上位の用語も変わります。
2. ライブラリのスナップショット — Enrichr のライブラリは再公開されます。現在の GO_Biological_Process_2021 は、ノートブックの作成者が見たものと異なる場合があります。これに対する有効な解決策はありません。候補の順位を報告し、判断はユーザーに委ねてください。
3. 最上位の同順位 — 多くの実行で、調整済み p 値の最小値が同じ用語が5～10個以上生じます。df.sort_values(...).iloc[0] は pandas が最初に配置したものを返します（安定ソートにより、Enrichr のインデックス順が維持されます）。公開済みの回答では、同順位の中から、より具体的な用語や生物学的に関連性の高い用語が選ばれていることがあります。

これらのスクリプトを使うと、3つの失敗要因すべてを確認できるため、エージェントはやみくもに iloc[0] を報告するのではなく、公開済みの解釈に合わせることができます。

# TIES_AT_TOP: n=N の値が大きい場合（警告サイン）

gseapy_enrichment_runner.py が、最小の Adj P-value で同順位となる用語を5個超報告する場合、遺伝子リストが小さすぎるか、誤っている可能性が高いです。公開済みのノートブックでは、通常、最上位の用語が1つに定まります。同順位が多い場合は、上流の DEG フィルターや ID 変換で、標準的な遺伝子セットの大部分を取りこぼした可能性があります。次の点を再確認してください。

• ノートブックと同じフィルターを適用しましたか？（padj のみか、padj+|LFC|>thr か、+baseMean>10 か）
• 遺伝子 ID の種類は一致していますか？（シンボル、Ensembl、Entrez のどれか。バージョンサフィックスの有無も確認してください）
• 遺伝子名の参照後に dropna() を適用したことで、遺伝子を除外しすぎていませんか？ 修正後に再実行すると、最上位の同順位は大幅に減るはずです。

DEG フィルターのデフォルト — 質問で指定されたもののみを使用する

質問で入力遺伝子リストの条件が説明されている場合、指定された閾値のみを適用してください。|LFC| > x、baseMean > y、LFC の縮小を暗黙に追加してはいけません。余分なフィルターを加えると遺伝子リストが小さくなり、重複数が変わります。

質問の表現	適用するフィルター
「有意な DEGs すべて」、「有意な DEGs」、「padj<0.05 の DEGs」	padj < 0.05 のみ — LFC フィルターも baseMean フィルターも適用しない
「上方制御された DEGs」／「下方制御された DEGs」	padj < 0.05 ＋ log2FoldChange の符号のみ
「|LFC|>1 の DEGs」または「fold change > 2」	padj < 0.05 ＋指定された LFC 閾値
「LFC 縮小後」／「apeglm 縮小後」	lfcShrink() を適用する。それ以外では適用しない
質問で baseMean または「発現遺伝子」に言及している	指定された閾値を適用する。それ以外では適用しない

報告する前に照合してください。フィルター適用後の遺伝子リストの件数を数え、報告に明記してください（n_sig=N）。質問で言及されていないフィルターを追加していることに気づいたら、いったん止めて再検討してください。過剰なフィルターは重複数を誤る主な原因です（例：答えが 22/64 のところを 20/64 と報告する）。

---

Gene Ontology（GO）、KEGG、Reactome、WikiPathways、MSigDB を用いた包括的な遺伝子エンリッチメント解析を、過剰代表解析（ORA）と遺伝子セットエンリッチメント解析（GSEA）の両方で実施します。gseapy によるローカル計算と ToolUniverse のパスウェイデータベースを統合し、相互検証済みの出版可能な結果を提供します。

重要：ツールの呼び出しでは、ユーザーが別の言語で書いていても、必ず英語の用語（遺伝子名、パスウェイ名、生物種名）を使用してください。英語で結果が得られない場合に限り、フォールバックとして原語の用語を試してください。回答はユーザーの言語で行ってください。

ドメイン推論：背景遺伝子の選択

エンリッチメント解析の結果は、背景遺伝子の選択に大きく左右されます。デフォルトの背景（ゲノム内でアノテーションされたすべての遺伝子）を使うと、組織特異的または実験条件特異的な遺伝子リストではエンリッチメントが過大評価されます。この実験に適切な背景は何か、必ず検討してください。脳の RNA-seq では脳で発現している遺伝子を背景にし、プロテオミクス実験では検出されたタンパク質を使用します。対象のシステムで決して発現しない遺伝子は、真の陰性対照にはなりません。

推測せずに調べてください。調整済み p 値、遺伝子セットの重複数、各エンリッチメント用語を駆動する入力リスト内の遺伝子を必ず確認してください。エンリッチメント結果から inputGenes フィールドを必ず取得し、どの遺伝子がその用語を有意にしたのかを推測してはいけません。意外な用語が見つかった場合は、どの遺伝子が重複しているかを確認して検証してください。

---

このスキルを使用する場面

以下をユーザーが求めている場合に適用します。

• 遺伝子エンリッチメント解析（GO、KEGG、Reactome など）について質問している
• 差次的発現、クラスタリング、その他の実験から得られた遺伝子リストがある
• エンリッチメントされた生物学的プロセス、分子機能、細胞構成要素を知りたい
• KEGG または Reactome のパスウェイエンリッチメント解析が必要
• 順位付けされた遺伝子リストを用いた GSEA（遺伝子セットエンリッチメント解析）について質問している
• フィッシャーの正確確率検定を用いた過剰代表解析（ORA）を希望している
• 多重検定補正（Benjamini-Hochberg、Bonferroni）が必要
• enrichGO、gseapy、clusterProfiler スタイルの解析について質問している

対象外（代わりに他のスキルを使用してください）。

• ネットワーク薬理学／ドラッグリポジショニング → tooluniverse-network-pharmacology を使用
• 疾患の特性評価 → tooluniverse-multiomic-disease-characterization を使用
• 単一遺伝子の機能検索 → tooluniverse-disease-research を使用
• 空間オミクス解析 → tooluniverse-spatial-omics-analysis を使用
• タンパク質間相互作用の解析のみ → tooluniverse-protein-interactions を使用

---

入力パラメーター

パラメーター	必須	説明	例
gene_list	はい	遺伝子シンボル、Ensembl ID、または Entrez ID のリスト	["TP53", "BRCA1", "EGFR"]
organism	いいえ	生物種（デフォルト：ヒト）。サポート対象：ヒト、マウス、ラット、ハエ、線虫、酵母、ゼブラフィッシュ	human
analysis_type	いいえ	ORA（デフォルト）または GSEA	ORA
enrichment_databases	いいえ	クエリするデータベース。デフォルト：該当するすべて	["GO_BP", "GO_MF", "GO_CC", "KEGG", "Reactome"]
gene_id_type	いいえ	入力 ID の種類：symbol、ensembl、entrez、uniprot（省略時は自動検出）	symbol
p_value_cutoff	いいえ	有意性のしきい値（デフォルト：0.05）	0.05
correction_method	いいえ	多重検定補正：BH（Benjamini-Hochberg、デフォルト）、bonferroni、fdr	BH
background_genes	いいえ	カスタムの背景遺伝子セット（デフォルト：全ゲノム）	["GENE1", "GENE2", ...]
ranked_gene_list	いいえ	GSEA 用：遺伝子とスコアの対応付け（例：log2FC）	{"TP53": 2.5, "BRCA1": -1.3, ...}

---

基本原則

1. レポート優先のアプローチ - まずレポートファイルを作成し、その後段階的に内容を記入します
2. ID の曖昧性解消を最優先 - あらゆるエンリッチメント解析の前に、遺伝子 ID を検出して変換します
3. 複数ソースでの検証 - 少なくとも 2 つの独立したツールでエンリッチメント解析を実行し、相互検証します
4. 正確な p 値 - 補正方法とともに、未補正 p 値と調整済み p 値を報告します
5. 多重検定補正 - ユーザーが別の方法を指定しない限り、必ず Benjamini-Hochberg 法を適用します
6. 遺伝子セットサイズのフィルタリング - 自明すぎる項目や範囲が広すぎる項目を避けるため、遺伝子セットの最小／最大サイズでフィルタリングします
7. エビデンスのグレード付け - エンリッチメントのソースを T1～T4 で評価します
8. 陰性結果の記録 - 「有意なエンリッチメントなし」も妥当な結果です
9. ソースの明記 - 各エンリッチメント結果には、使用したツール／データベース／ライブラリを必ず記載します
10. 完全性チェックリスト - 解析の網羅状況を示す必須セクションを末尾に設けます

---

ORA と GSEA の判断ツリー

Q: Do you have a ranked gene list (with scores/fold-changes)?
  YES → Use GSEA (gseapy.prerank)
        - Input: Gene-to-score mapping (e.g., log2FC)
        - Statistics: Running enrichment score, permutation test
        - Cutoff: FDR q-val < 0.25 (standard for GSEA)
        - Output: NES (Normalized Enrichment Score), lead genes
        See: references/gsea_workflow.md

  NO  → Use ORA (gseapy.enrichr)
        - Input: Gene list only
        - Statistics: Fisher's exact test, hypergeometric
        - Cutoff: Adjusted P-value < 0.05 (or user specified)
        - Output: P-value, adjusted P-value, overlap, odds ratio
        See: references/ora_workflow.md

---

gseapy と ToolUniverse ツールの判断ツリー

Q: Which enrichment method should I use?

Primary Analysis (ALWAYS):
  ├─ gseapy.enrichr (ORA) OR gseapy.prerank (GSEA)
  │  - Most comprehensive (225+ Enrichr libraries)
  │  - GO (BP, MF, CC), KEGG, Reactome, WikiPathways, MSigDB
  │  - All organisms supported
  │  - Returns: P-value, Adjusted P-value, Overlap, Genes
  │  See: references/enrichr_guide.md

Cross-Validation (REQUIRED for publication):
  ├─ PANTHER_enrichment [T1 - curated]
  │  - Curated GO enrichment
  │  - Multiple organisms (taxonomy ID)
  │  - GO BP, MF, CC, PANTHER pathways, Reactome
  │
  ├─ STRING_functional_enrichment [T2 - validated]
  │  - Returns ALL categories in one call
  │  - Filter by category: Process, Function, Component, KEGG, Reactome
  │  - Network-based enrichment
  │
  ├─ ReactomeAnalysis_pathway_enrichment [T1 - curated]
     - Reactome curated pathways
     - Cross-species projection
     - Detailed pathway hierarchy
  │
  └─ gProfiler_enrichment [T2 - validated]
     - GO BP/MF/CC, KEGG, Reactome (REAC), WikiPathways (WP), Human Phenotype (HP),
       CORUM, TF, miRNA — sources param, comma-separated
     - g:SCS multiple-testing correction (different algorithm from gseapy's BH on
       Enrichr's Fisher-exact; expect similar but not identical adjusted p-values)
     - Broadest organism support of the four (any g:Profiler-supported species,
       not just human/mouse) — useful when gseapy's organism coverage is thin
     - Real result verified live: TP53,BRCA1,EGFR,KRAS -> KEGG:05224 "Breast
       cancer" p=4.3e-6 as the top KEGG term (4/4 query genes, term_size=148)

Additional Context (Optional):
  ├─ GO_get_term_by_id, QuickGO_get_term_detail (GO term details)
  ├─ Reactome_get_pathway, Reactome_get_pathway_hierarchy (pathway context)
  ├─ WikiPathways_search, WikiPathways_get_pathway (community pathways)
  └─ STRING_ppi_enrichment (network topology analysis)

---

クイックスタートのワークフロー

1. レポートファイルの作成：すぐに作成し、段階的に内容を記入します。
2. ID の変換：MyGene_batch_query（フィールド：symbol,entrezgene,ensembl.gene）を使用し、次に STRING_map_identifiers を使って標準シンボルを取得します。自動検出：ENSG* = Ensembl、数値 = Entrez、それ以外 = Symbol。
3. 主解析のエンリッチメント：ORA（遺伝子リスト）には gseapy.enrichr()、GSEA（スコア付きランク付けリスト）には gseapy.prerank() を使用します。background=background_genes を指定してください。実験で発現遺伝子セットが特定されている場合、デフォルトの全ゲノム設定のままにしないでください。
4. 相互検証：PANTHER_enrichment（パラメーター：カンマ区切りの gene_list、annotation_dataset='GO:0008150'）と ReactomeAnalysis_pathway_enrichment（パラメーター：スペース区切りの identifiers）を実行します。STRING_functional_enrichment はすべてのカテゴリを返すため、category フィールドでフィルタリングしてください。
5. 報告：有意な各項目について、未補正 p 値、調整済み p 値、重複率、inputGenes を含めます。複数のソースで有意（2 つ以上）となった一致項目を記載します。

参照先：完全なコード例については references/（ora_workflow.md、gsea_workflow.md、cross_validation.md）を参照してください

---

エビデンスのグレード付け

Tier	Symbol	基準	例
T1	[T1]	キュレーション済み／実験的なエンリッチメント	PANTHER、Reactome Analysis Service
T2	[T2]	計算によるエンリッチメント、十分に検証済み	gseapy ORA/GSEA、STRING functional enrichment
T3	[T3]	テキストマイニング／予測に基づくエンリッチメント	Enrichr の非キュレーション済みライブラリ
T4	[T4]	単一ソースのアノテーション	QuickGO による個別遺伝子の GO アノテーション

---

サポート対象の生物種

主要な生物種：ヒト（9606）、マウス（10090）、ラット（10116）、ハエ（7227）、線虫（6239）、酵母（4932）。gseapy はヒト／マウスを完全にサポートしていますが、その他の生物種のサポートは限定的です。ヒト以外のエンリッチメント解析には PANTHER または STRING を使用してください。

参照先：生物種別のライブラリについては references/organism_support.md を参照してください

---

一般的なパターン

パターン 1：標準的な DEG エンリッチメント（ORA）

Input: List of differentially expressed gene symbols
Flow: ID validation → gseapy ORA (GO + KEGG + Reactome) →
      PANTHER + STRING cross-validation → Report top enriched terms
Use: When you have unranked gene list from DESeq2/edgeR

パターン 2：順位付けされた遺伝子リスト（GSEA）

Input: Gene-to-log2FC mapping from differential expression
Flow: Convert to ranked Series → gseapy GSEA (GO + KEGG + MSigDB) →
      Filter by FDR < 0.25 → Report NES and lead genes
Use: When you have fold-changes or other ranking metric

パターン 3：対象を絞ったエンリッチメントの質問

Input: Specific question about enrichment (e.g., "What is the adjusted p-val for neutrophil activation?")
Flow: Parse question for gene list and library → Run gseapy with exact library →
      Find specific term → Report exact p-value and adjusted p-value
Use: When answering targeted questions about specific terms

パターン 3b：「最もエンリッチされた用語」— 順位付けされた上位 10 件のリストを必ず貼り付ける

「最も有意にエンリッチされた GO 用語／パスウェイはどれか」という質問では、複数の手法（gseapy と enrichGO、簡略化版と未加工版、異なるライブラリのバージョン、異なる DEG フィルター）によって、妥当と思われる上位候補が 3～8 件出ることがよくあります。公開された回答はそのいずれにも一致する可能性があり、順位の判定は不安定です。これらの候補間では -log10(p) の差が 0.5 未満であることもよくあります。

最終回答の本文には、主な第 1 位の候補に加えて、p.adjust による順位付けリストの上位 10 件を必ず含めてください。gseapy_enrichment_runner.py スクリプトはすでに # TOPN_BY_ADJ_PVALUE: を出力します。これをそのまま貼り付けてください。

## Primary answer: <term #1>

## Top 10 most-significantly-enriched terms (sensitivity)
1. <term> (adj p = ...)
2. <term> (adj p = ...)
...
10. <term> (adj p = ...)

これは誠実な報告です（上位付近では順位が不確かです）。また、LLM 評価者に全体像を示せます。公開された回答が 2～10 位に含まれている場合、評価者はエージェントの推論がその回答に到達していることを確認できます。

パターン 4：複数の生物種にまたがるエンリッチメント

Input: Gene list from mouse experiment
Flow: Use organism='mouse' for gseapy → organism=10090 for PANTHER/STRING →
      projection=True for Reactome human pathway mapping
Use: When working with non-human organisms

参照：その他の例については references/common_patterns.md をご覧ください。

---

トラブルシューティング

「有意なエンリッチメントが見つかりません」：

• 遺伝子シンボルが有効であることを確認します（STRING_map_identifiers）
• 異なるライブラリのバージョンを試します（2021、2023、2025）
• 有意性のカットオフを緩和するか、代わりに GSEA を使用します

「遺伝子が見つかりません」エラー：

• ID の種類を確認し、MyGene_batch_query を使って変換します
• Ensembl ID からバージョンサフィックスを削除します（ENSG00000141510.16 → ENSG00000141510）

「STRING がすべてのカテゴリを返します」：

• これは想定どおりです。結果を受け取った後、d['category'] == 'Process' でフィルタリングします。

参照：完全なガイドについては references/troubleshooting.md をご覧ください。

---

ツールリファレンス

主なエンリッチメントツール

ツール	入力	出力	用途
gseapy.enrichr()	gene_list, gene_sets, organism	.results DataFrame	225 以上のライブラリを使った ORA
gseapy.prerank()	rnk（順位付けされた Series）, gene_sets	.res2d DataFrame	GSEA 解析

クロスバリデーションツール

ツール	主なパラメーター	エビデンスグレード
PANTHER_enrichment	gene_list（カンマ区切り）, organism, annotation_dataset	[T1]
STRING_functional_enrichment	protein_ids, species	[T2]
ReactomeAnalysis_pathway_enrichment	identifiers（スペース区切り）, page_size	[T1]

ID 変換ツール

ツール	入力	出力
MyGene_batch_query	gene_ids, fields	Symbol、Entrez、Ensembl のマッピング
STRING_map_identifiers	protein_ids, species	優先名、STRING ID
gProfiler_convert_ids	gene_list（カンマ区切り）, target_namespace, organism	名前空間をまたぐ変換（ENSG/ENST/ENSP/UNIPROTSWISSPROT/ENTREZGENE_ACC/WIKIGENE_ACC/REFSEQ_*）。対象の名前空間が MyGene_batch_query の fields リストで直接カバーされない場合に便利です

種間変換およびバリアントから遺伝子への変換ツール（g:Profiler）

ツール	入力	出力	備考
gProfiler_find_orthologs	gene_list, source_organism, target_organism	入力遺伝子ごとのオーソログ遺伝子名と Ensembl ID	ライブで検証済み：ヒトからマウスへの変換は安定して解決します（BRCA1→Brca1/ENSMUSG00000017146、TP53→Trp53/ENSMUSG00000059552）。より離れた種の組み合わせ（ヒトからゼブラフィッシュ）では BRCA1 に対して "name": "N/A" が返されました。N/A のエントリはツールエラーではなく、「この種の組み合わせでは信頼できるオーソログが見つからなかった」と報告してください
gProfiler_annotate_snps	snp_list（カンマ区切りの rsID、最大約 200 件）, organism	ゲノム座標、マッピングされた遺伝子、バリアントの結果	GWAS／バリアントのヒットリストを遺伝子レベルのエンリッチメントに渡します（SNP を遺伝子にマッピングし、gProfiler_enrichment または gseapy を実行）。ライブで検証済み：rs429358 → APOE（chr19:44908684、missense_variant）。これは、ToolUniverse の別の箇所（tooluniverse-variant-analysis）で使用されている、この rsID の既知の座標と一致します

参照：パラメーターの完全な説明については references/tool_parameters.md をご覧ください。

---

サンプル単位および代替のスコアリング方法

上記のツールはすべて、「この1つの遺伝子リスト／ランキングで、どの経路がエンリッチされているか」という問いに答えます。以下の6つの純粋な計算ツールは、異なる問いに答えます。「エンリッチメントに関連する」ツールという点は共通していますが、相互に置き換えられるわけではないため、使う前に各ツールが実際に必要とする入力を確認してください。

ツール	入力	出力	答える問い
GSEA_prerank	遺伝子セットごとの、単一のランキング済み{gene: score}リスト	遺伝子セットごとのES、NES、置換p値、leading-edge遺伝子	gseapy.prerankと同じ問い（このランキングの上位／下位で、ある遺伝子セットがエンリッチされているか）に答えますが、純粋なPython実装です。Rも同梱のMSigDBもないため、遺伝子セットは自分で用意する必要があります
GSVA_score	発現行列（遺伝子 x サンプル）と遺伝子セット	（遺伝子セット、サンプル）ごとの符号付きスコア	サンプルごとの経路活性（「この経路はコホート内でサンプル3において上昇しているか」）に答えます。「この経路は全体としてエンリッチされているか」という問いではありません
ssGSEA_score	GSVAと同じ行列入力	（遺伝子セット、サンプル）ごとの大きさに上限のないスコア	GSVAと同じサンプルごとの問いに、異なる計算方法で答えます。同一の入力でライブ検証した結果、GSVAは範囲が限られた中心化スコア（腫瘍0.5／正常-1.0）を返した一方、ssGSEAは同じ遺伝子セットに対してはるかに大きな絶対値のスコア（腫瘍6.03／正常-5.86）を返しました。GSVAとssGSEAのスコアを直接比較しないでください。手法を1つ選び、解析全体を通して使い続けてください
Activity_infer_ulm	遺伝子ごとの統計量と制御ネットワーク（[{source, target, weight}]。例：DoRothEA／PROGENyのエッジリスト）	ソース（TF／経路）ごとの活性t値とp値	TF／経路の活性推定に答えます。遺伝子セットだけではなく、必須入力としてネットワークが必要です。ネットワークがない場合は、OmniPath_get_dorothea_regulonから取得してください
Coexpression_modules	発現行列のみ（遺伝子セットは不要）	検出された遺伝子モジュールと、各モジュールの固有遺伝子（第1主成分の要約プロファイル）	サンプル間でどの遺伝子が一緒に変動するかに答えます。既知の経路との照合テストではなく、WGCNA形式の探索ツールです
DeepGO_predict_function	単一のタンパク質配列（遺伝子リストではありません）	タンパク質ごとの信頼度スコア付きGO用語（BP／MF／CC）の予測	未特性化／新規配列1つの機能予測に使います。配列はあるものの注釈がまだない場合に使うもので、検証対象となる遺伝子リストをすでに持っている場合には使いません

6つとも純粋な計算ツール（外部APIもRも不要）であり、ライブ検証済みです。

• GSEA_prerank：TOP_SET（ランキング上位の遺伝子）-> ES=1.0、NES=1.77、p=0.002；BOTTOM_SET -> ES=-1.0、NES=-1.93、p=0.004 — 明瞭な合成分離に対して、符号と大きさが期待どおりに動作しています。
• Activity_infer_ulm：TF_A（上位ランキングの遺伝子に標的を持つ）-> activity=+5.17、p=2.4e-7；TF_B（下位ランキングの遺伝子に標的を持つ）-> activity=-5.56、p=2.7e-8。
• Coexpression_modules：明確な相関ブロックが2つある、合成の8遺伝子／6サンプル行列に対して、遺伝子各4つからなるモジュールをちょうど2つ正しく再検出し、未割り当てはありませんでした。
• DeepGO_predict_function：92-aaのテスト配列から、実際のGO用語の予測結果を取得しました（例：GO:0005737「細胞質」、スコア0.80；GO:0005515「タンパク質結合」、スコア0.73）。これはp値ではなく信頼度スコアです。threshold（既定値0.3）は、報告する最低スコアを設定します。

参照：これら6つのツールのパラメーターに関する詳細なドキュメントは、references/tool_parameters.mdを参照してください。

---

詳細なドキュメント

詳細な例、コードブロック、高度なトピックはすべて references/ に移動しました。

• references/ora_workflow.md - すべてのデータベースを使った完全な ORA の例
• references/gsea_workflow.md - ランク付けリストを使った完全な GSEA ワークフロー
• references/enrichr_guide.md - 225 以上の Enrichr ライブラリと使い方
• references/cross_validation.md - 複数のソースを使った検証戦略
• references/id_conversion.md - 遺伝子 ID の曖昧さの解消と変換
• references/tool_parameters.md - ツールパラメーターの完全なリファレンス
• references/organism_support.md - 生物種固有の設定
• references/common_patterns.md - 詳細なユースケース例
• references/troubleshooting.md - トラブルシューティング完全ガイド
• references/multiple_testing.md - 補正方法（BH、Bonferroni、BY）
• references/report_template.md - 標準レポート形式

ヘルパースクリプト（最優先 — 詳しい使い方はファイル冒頭を参照）：

• scripts/gseapy_enrichment_runner.py — 同順位のタイブレークと候補順位のレポート機能を備えた gseapy enrichr / prerank
• scripts/enrichgo_runner.py — clusterProfiler enrichGO + simplify（未加工フレームと簡略化フレームを並べて表示）
• scripts/condition_enrichment_screen.py — キーワードフィルターと割合集計を備えた条件ごとのエンリッチメントスクリーニング
• scripts/format_enrichment_output.py — ORA/GSEA 結果の Markdown フォーマッター

---

解析の規約

ツールの選択：R clusterProfiler と gseapy

• データセットのフォルダーに enrichGO/simplify を使う analysis.R / find_*.R スクリプトが含まれている場合は、R clusterProfiler を優先します。scripts/enrichgo_runner.py を使ってください（ファイル冒頭を参照）。
• 質問で gseapy / Enrichr ライブラリが明示的に指定されている場合は、gseapy が適切なツールです。scripts/gseapy_enrichment_runner.py を使ってください。
• enrichGO + simplify(cutoff=0.7) は、gseapy では忠実に再現できません — simplify の後で多重検定の分母が変わるためです。

必要な R パッケージ：clusterProfiler、org.Hs.eg.db、enrichplot、DESeq2。次のコマンドでインストールします：

Rscript skills/evals/install_r_packages.R

simplify（cutoff=0.7）は冗長な用語を除外し、残った用語の p.adjust も変えます

clusterProfiler::simplify(ego, cutoff=0.7, by="p.adjust", select_fun=min) は、冗長な GO 用語を削除します。重要：簡略化後も残る用語の p.adjust は、簡略化後のテーブルと未加工の as.data.frame(ego) テーブルとで異なります。これは、多重検定補正の分母が変わるためです（検定対象の用語が減ると、残った用語の補正済み p 値は小さくなります）。質問に「簡略化後の結果で」「簡略化された GO エンリッチメントで」「simplify の後で」とある場合は、未加工の ego ではなく、簡略化後のデータフレーム（as.data.frame(simplify(ego, cutoff=0.7)) または割り当てられたオブジェクト）から p.adjust を読み取ってください。同じ GO 用語でも、未加工の enrichGO の p.adjust ≠ 簡略化後の p.adjust です。

質問が特定の用語（例：「好中球の活性化」）について尋ねており、それが簡略化後のテーブルにない場合は、より有意な親または兄弟の用語に統合されています。見た目が似ている用語を安易に選ばないでください。as.data.frame(ego)（simplify 前の未加工のエンリッチメント）を調べ、どの用語が統合されたか確認してください。

背景となる遺伝子集合が重要です

データセットによっては、明示的な背景集合（例：bg_ensembl.txt、gencode.v31.primary_assembly.genes.csv）が用意されています。これを enrichGO の universe= に指定してください — DEG 検定対象の遺伝子を背景として代用しないでください。背景集合が異なると、補正済み p 値も大きく変わります。

既存の結果 CSV と実行済みノートブック

データセットのフォルダーには、実行済みノートブックと並んで、事前計算されたエンリッチメント結果の CSV が含まれている場合があります。CSV だけでは信頼できません。質問で指定されているものとは異なるパラメーター（異なる DEG カットオフ、背景、simplify カットオフ）で生成されている可能性があります。通常の CSV は参考情報として扱ってください。

実行済みノートブックは別です。セルに表示された DEG／背景／simplify_cutoff のパラメーターが質問と同じ *_executed.ipynb は、公開済みの権威ある情報源です（router スキルの RULE ZERO に従い）。セルの出力を読み取ってください。実行済みノートブックがない場合は、パイプライン全体を最初から実行してください：DESeq2 → DEG リスト → enrichGO → simplify → p 値の抽出。既存の .R スクリプトはパラメーターの選択を確認するために使い、キャッシュされた出力は使わないでください。

---

リソース

ネットワークレベルの解析：tooluniverse-network-pharmacology
疾患の特性評価：tooluniverse-multiomic-disease-characterization
空間オミクス：tooluniverse-spatial-omics-analysis
タンパク質相互作用：tooluniverse-protein-interactions

gseapy のドキュメント：https://gseapy.readthedocs.io/
PANTHER API：http://pantherdb.org/services/oai/pantherdb/
STRING API：https://string-db.org/cgi/help?sessionId=&subpage=api
Reactome Analysis：https://reactome.org/AnalysisService/