tooluniverse-cancer-genomics-tcga

癌症基因组学 / TCGA 分析

TCGA 分析首先要明确：癌症类型是什么？数据类型是什么？ 先构建队列（GDC 筛选条件），再进行分析。不要在未定义队列的情况下查询突变——如果没有癌症类型的背景信息，GDC_get_mutation_frequency 的泛癌计数就没有参考价值。在一种癌症类型中频率为 10% 的突变，在另一种癌症类型中可能只有 0.5%；务必指定 project_id。生存分析（Kaplan-Meier）在回顾性 TCGA 数据中只能用于生成假设——务必报告样本量和 p 值，并指出 TCGA 队列未按治疗方案分层。

查证，不要猜测：切勿假设 TCGA 项目 ID、NCIt 编码或基因坐标——使用 GDC_list_projects 确认项目 ID，并使用 Progenetix_list_filtering_terms 查询 NCIt 编码。

系统化开展 TCGA/GDC 分析：定义队列、获取临床数据、分析体细胞突变、查询拷贝数变异、开展生存分析，并使用 OncoKB 解读变异。

适用场景

• “TCGA-BRCA 中 TP53 的突变频率是多少？”
• “获取 TCGA-LUAD 患者的生存数据”
• “查找 GDC 中乳腺癌病例的临床数据”
• “哪些 TCGA 项目存在 KRAS G12C 突变？”
• “显示胶质母细胞瘤中的 EGFR 拷贝数扩增”
• “注释 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（必填字符串，别名：gene）。返回泛癌种 SSM 发生次数。

• 返回所有 TCGA 的总计数；不提供各项目的明细。
• 如需癌种特异性数据，请使用带有 project_id 的 GDC_get_ssm_by_gene。

GDC_get_ssm_by_gene：gene_symbol（必填字符串）、project_id（字符串，可选）、size（整数，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（必填字符串，NCIt 代码，例如 “NCIT:C4017”）、limit（整数）、skip（整数）。 返回 {status, data: {biosamples: [{biosample_id, histological_diagnosis, pathological_stage, external_references}]}}。

• 用于查找具有 CNV 谱的指定癌种样本。

Progenetix_cnv_search：reference_name（必填字符串，RefSeq 登录号）、start（必填整数，GRCh38 1-based）、end（必填整数）、variant_type（“DUP”/“DEL”）、filters（字符串，NCIt 代码）、limit（整数）。 返回指定基因组区域内存在 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（必填字符串，例如 “TCGA-BRCA”）、gene_symbol（字符串，可选——用于筛选突变病例）。 返回 {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（布尔值：True=存活/删失，False=死亡事件）和 survivalEstimate（Kaplan-Meier 估计值）。
• 此工具不返回 log-rank p 值，也不区分突变型与野生型。提供 gene_symbol 时，它会将队列限定为 GDC 关联到该基因的病例（TCGA-BRCA + TP53：1,076 名供体中的 708 名）；因此请比较两次调用，或自行运行 log-rank 检验（例如 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（字符串，别名 gene_symbol）、variant（字符串，别名 alteration，例如 “V600E”）、tumor_type（字符串，OncoTree 代码，例如 “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（可选）	Kaplan-Meier 供体数组 + 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% 的基因很可能是候选驱动基因（例如，TP53 在全部 TCGA 样本中的突变率为 36%）。突变频率 <1% 的突变通常是乘客突变，除非发生在已知热点。务必结合 OncoKB 致癌性注释进行交叉验证。

生存分析（Kaplan-Meier）：log-rank 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 每次调用最多返回 100 个病例；请使用 offset 进行分页。
• Progenetix 使用 GRCh38 坐标；调用 Progenetix_cnv_search 时请提供 GRCh38 位置。
• 如果未设置 ONCOKB_API_TOKEN，OncoKB_annotate_variant 将以演示模式运行（仅限 BRAF、TP53、ROS1）。
• Progenetix 的 filters 参数要求使用 NCIt CURIE 格式（例如，“NCIT:C4017”），而非自由文本。