tooluniverse-cancer-genomics-tcga

がんゲノミクス／TCGA 解析

TCGA 解析は、「どのがん種か？」「どのデータ型か？」を決めることから始まります。 まずコホートを構築し（GDC フィルター）、その後に解析します。コホートを定義せずに変異を検索しないでください。GDC_get_mutation_frequency で得られるがん横断的な件数は、がん種のコンテキストがなければ有用ではありません。あるがん種で変異頻度が 10％でも、別のがん種では 0.5％の場合があります。必ず project_id を指定してください。後ろ向きの TCGA データを用いた生存解析（Kaplan-Meier）は仮説を生成するためのものです。必ずサンプル数と p 値を報告し、TCGA コホートは治療別に層別化されていないことを明記してください。

推測せず、必ず確認してください：TCGA プロジェクト ID、NCIt コード、遺伝子座の座標を決めつけないでください。GDC_list_projects でプロジェクト ID を確認し、Progenetix_list_filtering_terms で NCIt コードを確認してください。

体系的な TCGA／GDC 解析では、コホートを定義し、臨床データを取得して、体細胞変異のプロファイリング、コピー数変異の検索、生存解析を行い、OncoKB を使用してバリアントを解釈します。

使用する場面

• 「TCGA-BRCA における TP53 の変異頻度は？」
• 「TCGA-LUAD の患者の生存データを取得して」
• 「GDC で乳がん症例の臨床データを探して」
• 「KRAS G12C 変異がある TCGA プロジェクトは？」
• 「膠芽腫における EGFR の CNV 増幅を表示して」
• 「メラノーマにおける BRAF V600E の臨床的意義をアノテーションして」

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

• 精密腫瘍学の治療推奨 -> tooluniverse-precision-oncology を使用
• 希少疾患の遺伝子探索 -> tooluniverse-rare-disease-genomics を使用
• GWAS バリアントの解釈 -> tooluniverse-gwas-snp-interpretation を使用

---

ワークフローの概要

Input (cancer type / gene / TCGA project ID)
  |
  v
Phase 1: Study Selection  -- GDC_list_projects, GDC_search_cases
  |
  v
Phase 2: Clinical Data    -- GDC_get_clinical_data
  |
  v
Phase 3: Somatic Mutations -- GDC_get_ssm_by_gene, GDC_get_mutation_frequency
  |
  v
Phase 4: CNV Analysis     -- Progenetix_cnv_search, Progenetix_search_biosamples
  |
  v
Phase 5: Survival Analysis -- GDC_get_survival
  |
  v
Phase 6: Variant Interpretation -- OncoKB_annotate_variant

---

主な識別子

データ型	形式	例
GDC プロジェクト	TCGA-{ABBREV}	TCGA-BRCA、TCGA-LUAD、TCGA-SKCM
GDC 症例	UUID	3c6ef4c1-...
NCIt がんコード	NCIT:C######	NCIT:C4017（乳がん）、NCIT:C3058（GBM）
RefSeq 染色体	refseq:NC_######	refseq:NC_000007.14（chr7）

よく使われる TCGA プロジェクト ID

がん種	プロジェクト ID	NCIt コード
乳がん	TCGA-BRCA	NCIT:C4017
肺腺がん	TCGA-LUAD	NCIT:C3512
膠芽腫	TCGA-GBM	NCIT:C3058
メラノーマ	TCGA-SKCM	NCIT:C3510
大腸がん	TCGA-COAD	NCIT:C4349
卵巣がん	TCGA-OV	NCIT:C4908
前立腺がん	TCGA-PRAD	NCIT:C7378

---

フェーズ 1：研究の選択

GDC_list_projects：パラメーターは不要です。症例数とともに、すべての GDC／TCGA プロジェクトを返します。

• 利用可能なプロジェクトを確認し、がん種とプロジェクト ID を対応付けるために使用します。

GDC_search_cases：project_id（文字列、例：「TCGA-BRCA」）、size（整数、デフォルト 10）、offset（整数）。 症例 UUID と基本的なメタデータを返します。

• プロジェクトの存在確認と、詳細な検索を行う前の症例数の取得に使用します。

---

フェーズ 2：臨床データ

GDC_get_clinical_data：project_id（文字列）、primary_site（文字列、例：「Breast」）、disease_type（文字列）、vital_status（「Alive」または「Dead」）、gender（「female」／「male」）、size（整数、1～100）、offset（整数）。 {status, data: [{case_id, demographics: {gender, race, ethnicity, vital_status, age_at_index}, diagnoses: [{primary_diagnosis, tumor_stage, age_at_diagnosis, days_to_last_follow_up}], treatments: [{therapeutic_agents, treatment_type}]}]} を返します。

• project_id と任意のフィルターを使用して、患者単位の臨床属性を取得します。
• age_at_diagnosis は日数単位です。年数に換算するには 365.25 で割ります。
• 症例ごとに複数の診断や治療が記録されている場合があります。

# Get clinical data for deceased BRCA patients
result = tu.tools.GDC_get_clinical_data(
    project_id="TCGA-BRCA", vital_status="Dead", size=50
)

---

フェーズ 3：体細胞変異

GDC_get_mutation_frequency：gene_symbol (string REQUIRED, alias: gene)。がん種横断のSSM発生数を返します。

• すべてのTCGAにおける合計数を返します。プロジェクトごとの内訳はありません。
• がん種に特化したデータには、project_idを指定してGDC_get_ssm_by_geneを使用してください。

GDC_get_ssm_by_gene：gene_symbol (string REQUIRED)、project_id (string, optional)、size (int, 1-100)。 {status, data: [{ssm_id, mutation_type, genomic_dna_change, aa_change, consequence_type}]}を返します。

• mutation_type：「Single base substitution」、「Insertion」、「Deletion」。
• aa_change：アミノ酸変化の表記（例：「Val600Glu」）。

# TP53 mutations in lung adenocarcinoma
mutations = tu.tools.GDC_get_ssm_by_gene(
    gene_symbol="TP53", project_id="TCGA-LUAD", size=50
)

---

フェーズ 4：CNV解析（Progenetix）

Progenetix_search_biosamples：filters (string REQUIRED, NCIt code e.g., "NCIT:C4017")、limit (int)、skip (int)。 {status, data: {biosamples: [{biosample_id, histological_diagnosis, pathological_stage, external_references}]}}を返します。

• 指定したがん種のCNVプロファイルを持つサンプルを検索するために使用します。

Progenetix_cnv_search：reference_name (string REQUIRED, RefSeq accession)、start (int REQUIRED, GRCh38 1-based)、end (int REQUIRED)、variant_type ("DUP"/"DEL")、filters (string, NCIt code)、limit (int)。 指定したゲノム領域にCNVを持つバイオサンプルを返します。

• 増幅にはvariant_type="DUP"、欠失には"DEL"を指定します。
• filtersを使ってがん種を絞り込んでください。

# EGFR amplifications (chr7:55019017-55211628) in breast cancer
result = tu.tools.Progenetix_cnv_search(
    reference_name="refseq:NC_000007.14",
    start=55019017, end=55211628,
    variant_type="DUP", filters="NCIT:C4017", limit=10
)

Progenetix_list_filtering_terms：パラメーターはありません。利用可能なNCItコードとラベルをすべて返します。

• がん種のNCItコードを調べる必要がある場合に使用してください。

Progenetix_list_cohorts：パラメーターはありません。Progenetixで利用可能な名前付きコホートを返します。

---

フェーズ 5：生存分析

GDC_get_survival：project_id (string REQUIRED, e.g., "TCGA-BRCA")、gene_symbol (string, optional -- 変異のある症例に絞り込みます)。 {status, data: {project_id, gene_symbol, total_donors, alive_censored, deceased, max_follow_up_days, median_follow_up_days, donors: [{id, submitter_id, project_id, time, censored, survivalEstimate}], note}}を返します。

• donorsには最初の50人のドナーのみが含まれます（その旨がnoteに記載されています）。total_donors、alive_censored、deceased、追跡日数はコホート全体の集計値です。
• 各ドナーには、time（日数）、censored（bool：True=生存／打ち切り、False=死亡イベント）、survivalEstimate（Kaplan-Meier推定値）が含まれます。
• このツールはログランク検定のp値を返さず、変異型と野生型の比較も行いません。gene_symbolを指定すると、GDCがその遺伝子に関連付けている症例にコホートを絞り込みます（TCGA-BRCA + TP53の場合、1,076人中708人）。そのため、2回呼び出して比較するか、自分でログランク検定を実行してください（例：lifelines）。

# Survival summary for TCGA-BRCA restricted to TP53 (verified 2026-09-21)
surv = tu.tools.GDC_get_survival(project_id="TCGA-BRCA", gene_symbol="TP53")
info = surv["data"]
print(info["total_donors"], info["deceased"], info["median_follow_up_days"])
first_50 = info["donors"]  # [{'time': 1, 'censored': True, 'survivalEstimate': 0.998, ...}, ...]

---

フェーズ 6：変異の解釈（OncoKB）

OncoKB_annotate_variant：gene (string, alias gene_symbol)、variant (string, alias alteration, e.g., "V600E")、tumor_type (string, OncoTree code e.g., "MEL")。 {status, data: {oncogenic, mutationEffect, highestSensitiveLevel, treatments: [{drugs, level, indication}]}}を返します。

• oncogenic：「Oncogenic」、「Likely Oncogenic」、「Neutral」、「Inconclusive」、「Unknown」。
• highestSensitiveLevel：FDA承認レベル（"LEVEL_1"=FDA承認済み、"LEVEL_2"=標準治療など）。
• APIキーなしで、BRAF、TP53、ROS1のデモモードを利用できます。
• すべての機能を利用するには、ONCOKB_API_TOKENを設定してください。

# Annotate KRAS G12C in lung adenocarcinoma
result = tu.tools.OncoKB_annotate_variant(
    gene="KRAS", variant="G12C", tumor_type="LUAD"
)

ツールのクイックリファレンス

ツール	主なパラメーター	戻り値
GDC_list_projects	（なし）	件数を含むすべての TCGA/GDC プロジェクト
GDC_search_cases	project_id、size、offset	ケース UUID とメタデータ
GDC_get_clinical_data	project_id、vital_status、gender、size	人口統計情報、診断、治療
GDC_get_mutation_frequency	gene_symbol（別名：gene）	がん種横断の SSM 件数
GDC_get_ssm_by_gene	gene_symbol、project_id、size	aa_change を含む変異ごとの記録
GDC_get_survival	project_id、gene_symbol（任意）	カプラン・マイヤーのドナー配列と pValue
Progenetix_search_biosamples	filters（NCIt コード）、limit	バイオサンプルの記録
Progenetix_cnv_search	reference_name、start、end、variant_type、filters	該当地域に CNV があるバイオサンプル
Progenetix_list_filtering_terms	（なし）	Progenetix のすべての NCIt コード
OncoKB_annotate_variant	gene、variant、tumor_type	発がん性と治療

---

ワークフローの例

ワークフロー 1：遺伝子中心の変異・生存分析

1. GDC_get_mutation_frequency(gene_symbol="KRAS")
   -> Pan-cancer mutation count

2. GDC_get_ssm_by_gene(gene_symbol="KRAS", project_id="TCGA-LUAD", size=50)
   -> Specific amino acid changes in lung adenocarcinoma

3. GDC_get_survival(project_id="TCGA-LUAD", gene_symbol="KRAS")
   -> Survival split by KRAS mutation status + p-value

4. OncoKB_annotate_variant(gene="KRAS", variant="G12C", tumor_type="LUAD")
   -> Clinical significance + approved therapies (sotorasib)

ワークフロー 2：コホートの臨床的概要

1. GDC_list_projects()  -> confirm TCGA-OV exists

2. GDC_get_clinical_data(project_id="TCGA-OV", size=100)
   -> Demographics, tumor stage, treatment history

3. GDC_get_survival(project_id="TCGA-OV")
   -> Baseline overall survival curve for the cohort

ワークフロー 3：遺伝子の CNV 分析

1. Progenetix_search_biosamples(filters="NCIT:C3058", limit=10)
   -> GBM biosamples with CNV data

2. Progenetix_cnv_search(
       reference_name="refseq:NC_000007.14",
       start=55019017, end=55211628,
       variant_type="DUP", filters="NCIT:C3058"
   )
   -> GBM samples with EGFR amplification

---

推論フレームワーク

エビデンスのグレード

ティア	説明	例
T1	FDA が認定したバイオマーカーで、承認済み治療法がある	メラノーマの BRAF V600E（ベムラフェニブ）
T2	十分な検出力を持つ臨床研究で、標準治療との関連性がある	NSCLC の KRAS G12C（ソトラシブ）、OncoKB レベル 2
T3	前臨床または小規模コホートのエビデンス、生物学的妥当性	TCGA で再発するホットスポットだが、承認済み治療法はない
T4	計算による予測、または意義不明のバリアント	低頻度の変異で、機能データがない

解釈のガイダンス

変異頻度：TCGA コホートの 10% 超で変異している遺伝子は、ドライバー候補である可能性が高いです（例：全 TCGA の 36% における TP53）。頻度が 1% 未満の変異は、既知のホットスポットに生じたものでない限り、通常はパッセンジャー変異です。必ず OncoKB の発がん性アノテーションと照合してください。

生存分析（カプラン・マイヤー）：ログランク検定の p 値が 0.05 未満の場合、その遺伝子の変異が生存期間の差と関連していることが示唆されます。ハザード比（HR）が 1 を超える場合、変異群の予後がより不良であることを示します。慎重に解釈してください。TCGA コホートは後ろ向きで、治療別に層別化されていません。小規模なサブグループ（n < 20）では、信頼性の低い生存推定値が得られます。

コピー数変異：がん遺伝子（EGFR、MYC、ERBB2）の局所的増幅（狭いピーク）は、広範な染色体腕レベルのイベントよりも、機能的に重要である可能性が高いです。腫瘍抑制遺伝子（CDKN2A、PTEN、RB1）のホモ接合性欠失は、強い機能喪失シグナルです。Progenetix の DUP 数は、コピー数の大きさではなく、サンプル頻度を示します。

統合のための質問

完全ながんゲノミクスレポートでは、次の問いに答える必要があります。

1. このがん種で最も頻繁に変異している遺伝子は何か、また、そのうち既知のドライバーはどれか？
2. 対象遺伝子の変異状態は生存期間と関連するか（p < 0.05）？
3. 既知のがん遺伝子または腫瘍抑制遺伝子の座位に、再発性 CNV イベント（増幅または欠失）が存在するか？
4. 特定されたバリアントの OncoKB 臨床的アクショナビリティレベルはどの程度か？
5. 変異の全体像は、TCGA のがん種間でどのように異なるか（がん種横断的な文脈）？

---

プログラムからのアクセス（ツール以外）

ToolUniverse ツールの結果が途中で切り詰められる場合や、一括データが必要な場合は、GDC API を直接使用してください。

import requests, pandas as pd

# Bulk clinical data for a TCGA project
filters = {"op":"and","content":[
    {"op":"=","content":{"field":"project.project_id","value":"TCGA-BRCA"}}
]}
all_cases = []
offset = 0
while True:
    resp = requests.post("https://api.gdc.cancer.gov/cases", json={
        "filters": filters, "size": 500, "from": offset,
        "fields": "submitter_id,demographic.vital_status,demographic.days_to_death,diagnoses.tumor_stage"
    }).json()
    hits = resp["data"]["hits"]
    if not hits: break
    all_cases.extend(hits)
    offset += len(hits)
df = pd.json_normalize(all_cases)

# Download MAF mutation file by UUID
file_uuid = "abc123-..."  # from GDC_list_files result
url = f"https://api.gdc.cancer.gov/data/{file_uuid}"
content = requests.get(url, headers={"Content-Type": "application/json"}).content

# Gene expression: query files endpoint for HTSeq counts
expr_filters = {"op":"and","content":[
    {"op":"=","content":{"field":"cases.project.project_id","value":"TCGA-BRCA"}},
    {"op":"=","content":{"field":"data_type","value":"Gene Expression Quantification"}}
]}

ページネーション、エラー処理、形式の解析パターンについては、tooluniverse-data-wrangling スキルを参照してください。

---

制限事項

• GDC_get_survival は gene_symbol を指定すると、変異の有無だけで層別化します。複数遺伝子や病期に基づく層別化には対応していません。
• GDC_get_mutation_frequency は、全がんの合計のみを返します。がんごとの頻度を取得するには、プロジェクトごとに GDC_get_ssm_by_gene を使用してください。
• GDC_get_clinical_data は、1 回の呼び出しにつき最大 100 症例を返します。ページネーションには offset を使用してください。
• Progenetix は GRCh38 の座標を使用します。Progenetix_cnv_search には GRCh38 の位置を指定してください。
• ONCOKB_API_TOKEN を指定しない場合、OncoKB_annotate_variant はデモモードで動作し、BRAF、TP53、ROS1 のみに対応します。
• Progenetix の filters パラメーターには、自由入力テキストではなく NCIt CURIE 形式（例："NCIT:C4017"）が必要です。