第3章：ClinGen特征输出概述

ClinGen 的变异致病性分类结果，最终会以文件形式交到你手上。说白了，就是你解读完一个变异，平台给你吐出来的"成绩单"。我在项目里见过不少人直接拿 CSV 往 Excel 里拖，也有团队通过 API 拉 JSON 做自动化。两种格式各有脾气，搞不清楚的话，后面分析很容易翻车。

3.1 输出格式的整体框架

ClinGen 的 VCI（Variant Curation Interface）以及公共数据下载，主要提供两种格式：CSV 和 JSON。它们表达的是同一套分类结论，但组织方式完全不同。我个人习惯把 CSV 叫作"平铺视图"，JSON 叫作"树形视图"。

下面这张图能帮你快速建立全局认知：

3.2 CSV 格式详解

CSV 是 ClinGen 最常用的分发格式。每行一条变异，列字段固定。你直接拖进 Excel 就能看，非常方便。不过，这里有个坑——同一条变异可能出现在多行（比如对应不同疾病或不同评估日期）。

典型的 ClinGen CSV 输出包含以下核心列：

字段名	说明	示例值
variant_id	变异唯一标识	123456
chrom	染色体 (GRCh38)	17
pos	起始位置	7673802
ref	参考等位基因	C
alt	替代等位基因	T
gene	关联基因	TP53
clinical_significance	致病性分类	Pathogenic
condition	关联疾病	Li-Fraumeni syndrome
review_status	评估状态	criteria provided, multiple submitters
date_last_evaluated	最后评估日期	2024-03-15

下面是一段真实的 CSV 数据示例（我简化了部分字段）：

variant_id,chrom,pos,ref,alt,gene,clinical_significance,condition,review_status
1001,17,7673802,C,T,TP53,Pathogenic,Li-Fraumeni syndrome,criteria provided
1002,13,32914438,G,A,BRCA2,Likely Pathogenic,Hereditary breast cancer,criteria provided
1003,7,117559590,G,C,CFTR,Uncertain significance,Cystic fibrosis,single submitter
1004,1,55521789,T,C,PCSK9,Benign,Hypercholesterolemia,criteria provided
1005,3,179234119,G,T,PPM1L,Likely Benign,Cardiomyopathy,criteria provided

3.3 JSON 格式详解

JSON 格式比 CSV "厚"得多。它用嵌套结构把变异信息、证据条目、分类标准包在一起。你想想看，一个变异如果支持 Pathogenic 的证据有 8 条，反对的有 2 条，CSV 里只能挤在一个单元格里，JSON 却能清晰地列出来。

ClinGen 的 JSON 输出通常包含以下顶层键：

• variant：变异的基础注释（位置、基因、转录本等）
• classifications：分类结论列表（可能包含多个评估）
• evidence：证据详情（每条证据的来源、类型、强度）
• criteria：使用的 ACMG/AMP 标准列表
• metadata：提交者、评估日期、版本信息

我给你看一段简化的 JSON 结构。实际返回会比这个更复杂，但骨架是一样的：

{
  "variant_id": 1001,
  "chrom": "17",
  "pos": 7673802,
  "ref": "C",
  "alt": "T",
  "gene": "TP53",
  "classifications": [
    {
      "condition": "Li-Fraumeni syndrome",
      "clinical_significance": "Pathogenic",
      "review_status": "criteria provided, multiple submitters",
      "date_last_evaluated": "2024-03-15"
    }
  ],
  "evidence": [
    {
      "evidence_type": "PVS1",
      "description": "Null variant in a gene where LOF is a known mechanism",
      "strength": "very_strong",
      "source": "ClinGen Expert Panel"
    },
    {
      "evidence_type": "PM2",
      "description": "Absent from population databases",
      "strength": "moderate",
      "source": "gnomAD v4.0"
    }
  ],
  "criteria": [
    "PVS1:very_strong",
    "PM2:moderate",
    "PP3:supporting"
  ],
  "metadata": {
    "submitter": "ClinGen TP53 Expert Panel",
    "submission_date": "2024-03-15",
    "schema_version": "2.1"
  }
}

3.4 CSV vs JSON 实战对比

我在做 ClinGen 数据集成时，两种格式都跑过。下面这个表格是我在实际项目中总结的选型参考：

对比维度	CSV	JSON
可读性	Excel 直接打开，一眼看完	需要格式化工具，结构一目了然
数据密度	高，一行一条变异	低，但信息更完整
证据层级	仅文本摘要，丢失细节	完整保留每条证据的属性
程序解析	用 Python 的 csv 模块即可	需要解析嵌套结构，但更灵活
批处理效率	高，适合 10 万+ 变异	中等，文件体积大，解析稍慢
上下游对接	适合 LIS / 报告系统直接导入	适合 API 网关 / 数据湖 / 微服务

3.5 如何获取 ClinGen 的 CSV 和 JSON 输出

ClinGen 提供了两种主要获取方式：

• 批量下载：从 ClinGen 公共 FTP 或官网下载 CSV 压缩包。适合做大规模回顾性分析。
• REST API：通过 ClinGen API 查询单个或批量变异，返回 JSON 格式。适合嵌入到自动化流程中。

API 查询示例（伪代码风格）：

# 查询单个变异
GET /api/v1/variants/123456
返回：JSON（包含完整证据链）

# 批量下载 CSV
GET /api/v1/variants/export?format=csv
返回：CSV 文件流

3.6 格式选择的三个判断标准

嗯，讲了这么多，到底怎么选？我给你三个判断标准：

1. 看使用场景：做报表、画饼图 → CSV；做系统集成、证据溯源 → JSON。
2. 看数据量：少于 1000 条变异，JSON 完全扛得住；超过 1 万条，CSV 省时间。
3. 看下游工具：对接的是 Excel 分析师 → CSV；对接的是数据工程师 → JSON。

说实话，两者没有绝对的优劣。我在实际项目中通常是 CSV 做概览，JSON 做细节深挖。你慢慢也会找到自己的节奏。