信息速览
CIViC — 肿瘤变异临床解读开放知识库 AI-Ready Wikipedia
INFOBOX
| 数据集名称 | CIViC |
| 英文全称 | Clinical Interpretation of Variants in Cancer |
| 别名/简称 | CIViC、CIViCdb、civicdb |
| 疾病分类 | 恶性肿瘤全病谱（ICD-11：2A00-2F9Z 新生生物章节，详见 §2.1） |
| SNOMED CT | 363346000 Malignant neoplastic disease / 254637007 Non-small cell lung cancer / 372244006 Malignant melanoma（详见 §2.1b） |
| 数据模态 | 结构化变异-临床解读知识库（文献策展，非影像/信号） |
| AI 任务类型 | 变异可药性预测、证据等级自动分级、变异标准化（文本 NLP）、肿瘤注释流水线、医疗 LLM 检索增强（RAG） |
| 样本总数 | 11,561 条证据项 / 302 条断言 / 4,132 个变异 / 978 个基因特征（截至 2026-09-12） |
| 数据格式 | TSV / VCF / GraphQL API（JSON）/ CIViCpy SDK |
| 许可证 | CC0 1.0 Universal（公有领域贡献） |
| 访问级别 | 开放（无需注册即可下载与调用 API） |
| DUO 标签 | NRES（文献衍生知识库，无使用限制） |
| 语言 | 英文 |
| 首发日期 | 2017-01-31（Nature Genetics 论文发表） |
| 最后更新 | 持续更新（nightly 发布，截至 2026-09-12） |
| 发布机构 | 华盛顿大学圣路易斯分校 Griffith 实验室 |
| 官方主页 | https://civicdb.org |
| 下载地址 | https://civicdb.org/releases |
| DOI | 10.1038/ng.3774（原始论文）/ 10.1093/nar/gkac979（CIViCdb 2022 更新论文） |
| 引用次数 | 711+（Google Scholar，截至 2026-09） |
| AI 就绪度评分 | ⭐⭐⭐⭐（4/5）— CC0+API+SDK+全量溯源文档齐备；扣分项：无官方 ML 任务划分、变异命名自由文本需自行规范化 |
| 页面状态 | published |
§0 E-E-A-T 专业保障
医学审核者：千方病案医学编辑部交叉审核：§2 医学背景（ICD-11 与 SNOMED CT 映射、变异解读临床任务定义、金标准描述）、§7 偏倚分析。
数据工程审核者：千方病案医学编辑部交叉审核：§4 DAIMS 数据字典（证据项-变异-基因三级实体体系）、§5 数据划分策略、§6 预处理 Pipeline 和坑点。
审核日期：2026-09-05
审核方式：交叉审核
利益冲突声明：千方病案医数集与华盛顿大学圣路易斯分校、Griffith 实验室及 National Cancer Institute 无任何商业利益关联。本页面不销售 CIViC 数据集本身，仅提供 AI 就绪指南与学术信息服务。编辑者未接受上述机构的任何形式资助。
医疗免责声明：本页面提供的医学信息仅供研究和教育目的，不构成医疗建议、诊断或治疗方案。数据集的医学描述基于公开发表的文献，未经逐一临床验证。任何基于该数据集训练的 AI 模型在应用于临床决策前，必须经过独立的临床验证和监管审批。
技术免责声明：本页面的代码示例、预处理建议和基准性能数据基于公开资料整理，不保证在特定环境下的准确性和适用性。使用者应自行验证代码安全性和数据预处理流程的正确性。千方病案医数集不对因使用本页面信息而导致的任何直接或间接损失承担责任。
数据使用合规：使用本页面描述的数据集前，请务必阅读并遵守数据集原始许可协议。CIViC 内容以 CC0 1.0 公有领域许可发布，可自由使用、修改与再分发，无需注册或签署协议；官方建议使用其内容时引用 CIViC 论文。具体使用限制以数据集官方协议为准。
§1 数据集概览
§1.0 📌 30 秒速览
这是什么？ CIViC 是一个"肿瘤变异说明书库"。当肿瘤基因测序发现某个突变（比如 EGFR L858R）时，医生和研究者需要知道：这个突变意味着该用什么药、预后如何、还是遗传风险？CIViC 由 419 位注册贡献者阅读 4,386 篇科学文献，把答案写成 11,561 条结构化"证据条目"，按 A-E 五级标注证据强度，任何人都可以免费下载、复制、修改（CC0 公有领域）。
为什么重要？ 各大肿瘤中心曾各自为战解读变异，形成"信息孤岛"：内容不公开、许可受限、无公开 API、无法快速更新。CIViC 是最早系统性解决这四个问题的开放知识库之一，其证据分级已被映射到临床界公认的 AMP/ASCO/CAP Tier I/II 框架，原始论文被引用 711+ 次（Google Scholar，截至 2026-09），已成为肿瘤注释流水线和 VICC 跨机构联盟的基石资源。
我能用它做什么？ 训练变异可药性/意义预测模型、为肿瘤患者报告自动注释变异、构建医疗 LLM 的检索增强（RAG）知识库、评测生物医学文本挖掘系统。TSV/VCF 批量下载、GraphQL API 与 CIViCpy SDK 三条通道齐备，笔记本级硬件即可上手。
§1.1 技术摘要
CIViC 采用"专家众包+编辑审核"的生产模式：任何注册用户（Curator）可提交证据项（Evidence Item, EID），每条 EID 结构化记录基因、变异、疾病、疗法、证据来源 PMID、证据类型、临床意义、证据等级与评分，随后由经选拔培训的 Editor 审核通过才进入 accepted 状态。数据模型以基因（Feature）→ 变异（Variant）→ 分子特征（Molecular Profile）→ 证据项 → 断言（Assertion）五级实体组织，断言是对多条同类证据的总结性临床判断。全部 44,656 次修订保留完整溯源。内容 CC0 发布，提供 nightly/monthly 的 TSV 与 VCF 快照、与网站前端同源的公共 GraphQL API，以及官方 Python SDK CIViCpy（Griffith et al., 2017；CIViCdb 2022）。
§1.2 战略价值分析
维度一：许可与工程自由度。CC0 1.0 意味着无需注册、无 DUA、无再分发限制——这是与 OncoKB（部分层级内容受限）、JAX-CKB（商业许可）等同类知识库的关键差异，使 CIViC 可直接嵌入商业注释产品与公开基准，而无需法务审查。配套的公开 API 与 nightly 发布使增量同步工程成本极低。
维度二：证据可追溯性。每条解读都能回溯到具体文献 PMID 与策展人修订记录，而非黑盒汇总。对 AI 而言，这提供了天然的对齐监督信号：模型输出可以逐条对照"文献原文主张"而非"不可审计的整合结论"，显著降低幻觉评估成本，也使证据等级 A-E 成为可用的弱监督标签。
维度三：社区与工具链成熟度。从 2017 年至今，CIViC 已沉淀出完整的外围生态：官方 Python SDK（CIViCpy）、GraphQL API、与 ClinGen Allele Registry/ProteinPaint/openCRAVAT 等工具的双向集成、VICC 跨库协调标准，以及面向 LLM 时代的官方 MCP server。这意味着围绕 CIViC 的工程投入（解析器、特征库、评估集）有长期延续保障，不太可能因项目停更而沦为"孤儿数据"——这是选择训练语料与知识源时经常被忽视但决定性的考量。
§1.3 同类数据集横向对比
| 数据集 | 主办机构 | 规模口径 | 许可模式 | 与 CIViC 的差异化 |
|---|---|---|---|---|
| CIViC | 华盛顿大学 | 11,561 证据项（截至 2026-09-12） | CC0 完全开放 | 开放策展+全量溯源+五级证据评分 |
| OncoKB | MSKCC | 分级解读数千条量级（官方口径） | 部分内容受限 | FDA/NCCN 治疗层级导向，与 CIViC 互补 |
| ClinVar | NCBI | 变异-表型记录数百万级 | 公有领域 | 覆盖良性与致病全谱，临床意义粒度较粗 |
| JAX-CKB | Jackson Laboratory | 商业知识库 | 商业许可 | 深度治疗细节但闭源 |
| My Cancer Genome | Vanderbilt | 商业知识库 | 内容受限 | 面向临床医生的教育型内容 |
对比依据见 CIViC 原始论文对现有资源访问性的系统评述（Griffith et al., 2017）与 VICC 跨库协调研究（VICC Meta-knowledgebase Task Team, 2020）。
§1.4 版本时间轴
| 时间 | 版本/事件 | 说明 |
|---|---|---|
| 2017-01-31 | Nature Genetics 论文 | 提出 CIViC 开放框架与 A-E 证据分级（DOI 10.1038/ng.3774） |
| 2021-06 | 演进论文预印本 | 引入 nightly/monthly TSV+VCF 发布、CIViCpy、ClinGen Allele Registry 集成（bioRxiv） |
| 2023-01 | CIViCdb 2022 更新论文（NAR 51(D1)） | Molecular Profiles 新数据模型、ClinGen Somatic 合作（DOI 10.1093/nar/gkac979） |
| 2026-02 | Regions 支持 | 支持区域级（非点突变）特征描述 |
| 2026-04 | AI 政策 + ClinVar 自动提交 | Curation Help Chat（RAG）、官方 MCP server 上线；断言自动提交 ClinVar |
| 2026-06 | Advanced Search | 高级检索界面增强 |
§1.5 典型应用场景
- 肿瘤患者报告自动注释：用 VCF 与 CIViC 证据对接，为 NGS 报告中的每个体细胞变异附加治疗/预后/诊断解读与证据等级。实现要点：VCF 通道 + TSV 文本匹配兜底（坑点 1），输出层附 PMID 溯源供病理医生复核。
- 变异可药性预测模型：以变异特征+基因+疾病为输入，A-E 等级为弱监督标签训练分级模型。实现要点：遵循 §5 分组切分纪律，用二次加权 Kappa 评估有序等级。
- 医疗 LLM 检索增强（RAG）：将证据项+文献溯源作为知识片段，构建可审计的肿瘤问答系统；官方 MCP server 已提供即用接口。实现要点：检索粒度取单条 EID 而非整基因，引用时保留 PMID。
- 生物医学文本挖掘基准：以"文献摘要 → 结构化证据"的映射评测信息抽取系统。实现要点：以 evidence_type/clinical_significance 字段为抽取目标 schema。
- 生物信息学教学：开放策展界面与 Source Suggestions 队列已被用于本科/研究生策展实训（bioRxiv 2021）。实现要点：无需下载，直接使用官方策展界面即可开课。
§2 医学背景
§2.1 ICD-11 编码映射
CIViC 覆盖恶性肿瘤全病谱（同时包含少量胚系易感综合征相关内容），不针对单一癌种。其"疾病"实体经 EBI 本体服务对齐 Disease Ontology 术语（VICC Meta-knowledgebase Task Team, 2020），与 ICD-11 的映射关系如下：
| CIViC 覆盖范围 | ICD-11 编码 | ICD-11 中文名 | 说明 |
|---|---|---|---|
| 全部恶性肿瘤（主域） | 2A00-2F9Z | 新生生物（恶性肿瘤）章节 | 证据覆盖各系统癌种 |
| 支气管和肺恶性肿瘤 | 2A12 | 支气管或肺恶性肿瘤 | EGFR/ALK/ROS1/KRAS 证据密集区 |
| 乳腺恶性肿瘤 | 2C60-2C6Z | 乳腺恶性肿瘤 | ERBB2/PIK3CA/ESR1 相关证据集中 |
| 皮肤恶性肿瘤 | 2C31 | 皮肤恶性肿瘤 | BRAF/NRAS 黑色素瘤证据密集区 |
§2.1b SNOMED CT 映射
| 标签 | ICD-11 | SNOMED CT 码 | SNOMED 术语 |
|---|---|---|---|
| 恶性肿瘤（总域） | 2A00-2F9Z | 363346000 | Malignant neoplastic disease |
| 非小细胞肺癌 | 2A12 | 254637007 | Non-small cell lung cancer (disorder) |
| 乳腺恶性肿瘤 | 2C60-2C6Z | 254837004 | Malignant tumor of breast (disorder) |
| 恶性黑色素瘤 | 2C31 | 372244006 | Malignant melanoma (disorder) |
§2.2 疾病简介与流行病学
癌症是全球主要死因之一，其分子本质是体细胞突变的逐步累积：癌基因激活（如 EGFR、KRAS）、抑癌基因失活（如 TP53、CDKN2A）与基因组维护通路缺陷共同驱动肿瘤发生与治疗抵抗。肿瘤基因组高度异质：同组织学类型的两位患者可能携带完全不同的驱动变异集合，因此"按变异而非按器官"选择治疗已成为精准肿瘤学的基本范式。规范测序（NGS panel）在临床的普及使变异解读成为瓶颈环节——单例行全外显子测序可报告数百个非同义变异，逐一人工检索文献在临床上不可行，这正是 CIViC 类知识库存在的根本动因（Griffith et al., 2017）。
从文献结构看，肿瘤变异临床知识呈"金字塔"分布：塔尖是少数被专业指南与 FDA 批准覆盖的高频变异-疗法组合（对应 CIViC Level A），塔身是临床试验支撑的证据（Level B），基座则是海量病例报告、临床前研究与推断性文献（Level C-E）。CIViC 的策展策略即沿这一金字塔逐层展开：热点变异快速跟进指南级证据，同时用开放众包填补长尾变异的文献解读空白。理解这一结构对 AI 使用者至关重要——它决定了标签分布的重尾形态与"头部高置信、长尾低密度"的知识覆盖格局。
§2.3 临床任务定义
CIViC 证据覆盖四类临床解读任务，每条 EID 归属其一：
- 治疗预测（Therapeutic）：变异提示对某药物的敏感性或耐药性——这是证据占比最高、临床最直接的任务，也是 FDA 批准与专业指南最集中的领域。典型示例：EGFR L858R 预测 NSCLC 对 EGFR-TKI 的敏感性；KRAS G12C 预测 sotorasib 获益；KIT 外显子 17 突变提示对伊马替尼原发耐药。
- 预后（Prognostic）：变异与生存期、复发风险等自然病程指标的关联，不涉及治疗选择。典型示例：TP53 共突变与 AML 不良预后；POLE 超突变型子宫内膜癌的较好自然病程。
- 诊断（Diagnostic）：变异辅助肿瘤分类鉴别（如特定融合界定组织学不确定的肿瘤）。典型示例：SS18-SSX1/2/4 融合界定滑膜肉瘤；特定组织学突变谱辅助原发灶不明癌溯源。
- 易感性（Predisposing）：胚系变异提示遗传性肿瘤综合征风险（如 BRCA1/2、VHL）。典型示例：VHL 胚系变异与 von Hippel-Lindau 病；Lynch 系列错配修复基因胚系变异与结直肠癌风险。
证据等级体系（详见 §3.1）将上述任务按文献强度分为 A-E 五级，并映射到 AMP/ASCO/CAP 指南的 Tier I/II 框架，使"同一变异不同证据"可在统一标准下比较（Li et al., 2017；VICC Meta-knowledgebase Task Team, 2020）。
§2.4 证据来源人群
CIViC 是文献衍生知识库，不直接收录患者数据；其"人群"体现为被策展文献的研究人群。
| 维度 | 描述 |
|---|---|
| 证据来源 | 4,386 篇同行评审文献（截至 2026-09-12） |
| 时间跨度 | 持续回溯与跟进，nightly 更新 |
| 患者年龄/性别/种族 | 于文献层面存在，CIViC 不做人群级再统计 |
| 就医类型 | 跨越临床试验、真实世界队列与病例报告 |
| 地域 | 全球文献来源，无地理限制 |
§2.5 临床价值定位
在肿瘤测序报告的生成链路中，CIViC 位于"变异检出 → 变异解读 → 治疗决策"的中游：上游变异数据库（ClinVar、gnomAD）回答"这个变异是否存在、是否良性"，下游临床决策系统回答"该患者该入组哪个试验"，CIViC 则回答"这个变异在该癌种中意味着什么、证据有多强"。其 A-E 等级与 AMP/ASCO/CAP Tier 映射使分子病理委员会（Molecular Tumor Board）可直接采用，而完整溯源允许临床药师逐条复核原始文献主张。
对三类读者的具体价值：分子病理医生——以 Tier 框架快速定位强证据，减少逐篇文献检索时间；生物信息工程师——CC0+API 让注释服务无需法务谈判即可上线；AI 研究者——结构化标签+全文溯源的组合在同类知识库中罕见，可直接支撑可解释模型研究。值得注意的是，CIViC 的开放性是把双刃剑：它同时意味着内容质量的最终把关在使用者自身，这正是本页 §6.5 坑点清单存在的意义。
§2.6 标注金标准描述
| 属性 | CIViC 的实现 |
|---|---|
| 划分方式 | 按实体层级组织（基因 → 变异 → 证据 → 断言），非任务级预划分 |
| 标注方式 | 全人工专家策展：Curator 阅读文献提取结构化主张，非自动抽取 |
| 标注者资质 | Curator 开放注册（419 位贡献者）；Editor 经独立选拔与强化培训后才有接受/拒绝权限 |
| 标注一致性机制 | 双层审核（提交 → Editor 接受）+ 全量修订历史 + Flags 纠错机制 |
| 标注性质 | 解读型标注（interpretation）：记录文献作者主张及其证据强度，不做原始数据再分析 |
§3 数据集规格
§3.0 版本抉择矩阵
CIViC 无传统"版本号"，以发布频率与格式区分获取通道：
| 你的需求 | 推荐通道 | 格式 | 理由 |
|---|---|---|---|
| 追踪最新证据、需完整溯源 | GraphQL API | JSON | 与前端同源，元数据最全、内容最新 |
| 快速原型/批量分析 | Monthly TSV | TSV | 月度稳定快照，pandas 直接读取 |
| 客户端注释流水线 | Nightly TSV | TSV | 每日最新，适合定时同步 |
| VCF 注释工具（ANNOVAR/VEP 等） | Nightly VCF | VCF | 仅含完整坐标变异，直接对接注释器 |
| Python 全流程 | CIViCpy + 缓存 | 本地缓存 | 官方 SDK，对象化访问与本地缓存 |
§3.1 数据模态详情
CIViC 是单一模态的结构化知识库，核心实体五层：
- 证据项（Evidence Item, EID）：最小知识单元，11,561 条。一条 = 一篇文献 × 一个变异 × 一种疾病 × 一种疗法（或预后/诊断语境）的结构化解读，含证据类型（Predictive/Prognostic/Diagnostic/Predisposing 等）、临床意义、等级 A-E 与 1-5 星评分。
- 断言（Assertion, AID）：302 条。Editor 级总结判断，汇总多条证据对同一变异-疾病组合的结论，可自动提交 ClinVar。
- 变异（Variant, VID）：4,132 个，挂载于基因下，可含规范化基因组坐标与 ClinGen Allele Registry ID。
- 分子特征（Molecular Profile）：4,237 个，2022 年模型引入，表达"变异+修饰因子"的组合以支持更复杂生物学陈述。
- 基因特征（Feature, GID）：978 个，锚定 Entrez Gene ID，聚合其下全部变异与证据。
证据等级五级与 AMP/ASCO/CAP 层级的官方映射如下（VICC Meta-knowledgebase Task Team, 2020）：
| CIViC 等级 | 定义 | AMP/ASCO/CAP | 典型来源 |
|---|---|---|---|
| Level A | 已验证关联：专业指南或 FDA 批准疗法证据 | Tier I | NCCN 指南、FDA 标签 |
| Level B | 临床证据：临床试验或有把握的临床研究+专家共识 | Tier I | III/IV 期临床试验 |
| Level C | 病例研究：病例系列的治疗预测证据或若干小研究 | Tier II | 病例报告、I/II 期试验 |
| Level D | 临床前证据：临床前发现或预后/诊断病例研究 | Tier II | 细胞系/动物实验 |
| Level E | 推断性关联：间接证据 | 推断级 | 多基因签名、旁证推理 |
每条证据另附 1-5 星评分，从研究规模、研究设计、正交验证与重现性四个维度综合评价文献质量（5 星 = 可靠来源的强证据、对照良好且可重复；1 星 = 极弱证据，缺乏重现性或实验支持）。等级（强度层级）与评分（单条文献质量）二者正交，使用时不可互相替代。
§3.2 按实体的样本规模
| 实体 | 数量（截至 2026-09-12） | 主键 | 说明 |
|---|---|---|---|
| Evidence Items | 11,561 | EID | 核心证据单元，仅 accepted 计入主口径 |
| Assertions | 302 | AID | 总结性临床判断 |
| Variants | 4,132 | VID | 含坐标未完全策展的变异 |
| Molecular Profiles | 4,237 | MPID | 变异+修饰组合 |
| Genes (Features) | 978 | GID | Entrez 基因锚定 |
| Diseases | 459 | DID | Disease Ontology 对齐 |
| Therapies | 655 | TID | 含药物与疗法类别 |
| Sources | 4,386 | PMID | 同行评审文献 |
| Revisions | 44,656 | — | 全量修订记录 |
| Contributors | 419 | — | 注册策展贡献者 |
数据来源：civicdb.org 首页统计。
读表注意三点：(1) Molecular Profiles（4,237）多于 Variants（4,132），因为一个变异可对应多个"变异+修饰因子"组合，属正常现象而非统计口径错误；(2) Variants 表主口径仅含具 accepted 证据的变异，故与早期快照不可直接比较（坑点 7）；(3) Revisions 与 Contributors 是持续性指标，会随时间单调增长，引用时务必标注检索日期。
§3.3 数据格式
| 格式 | 覆盖实体 | 发布频率 | 适用场景 |
|---|---|---|---|
| TSV（Accepted 口径） | Features/Variants/Molecular Profiles/Evidence/Variant Groups/Assertions | nightly + monthly | 常规分析，pandas/R 直接读取 |
| TSV（Accepted & Submitted 口径） | Evidence/Assertions | nightly + monthly | 需要含 submitted 状态记录的完整视图 |
| VCF（Accepted） | 变异（完整坐标） | nightly + monthly | 注释工具对接 |
| VCF（Accepted & Submitted） | 变异（完整坐标） | nightly + monthly | 更宽口径注释 |
| GraphQL API | 全部实体+溯源+讨论 | 实时 | 应用集成、增量同步 |
| CIViCpy 缓存 | 全部实体对象化 | 本地刷新 | Python 工程化项目 |
格式选择的三条经验法则：(1) 能用 ID 关联就不要用名字字符串关联，故生产系统优先 API/SDK；(2) 探索性分析与教学场景 TSV 最省事，pandas 一行读入；(3) 需要复现历史实验时锁定 monthly 快照而非 nightly——月度快照的可获得性已在发布页长期保留，nightly 文件则滚动覆盖。
§3.4 存储规模
官方发布页未标注静态文件总大小。按实体规模（万余行级文本表格）与 TSV 格式估算，全部 TSV/VCF 合计为数十 MB 量级，任何现代工作站均可直接处理，无需分布式存储；确切大小以发布页当期文件为准。
§3.5 标注方式
三层人工流程：(1) Curator 提交——任何注册用户在策展界面阅读文献后按表单提交 EID，字段含证据类型、临床意义、等级建议与描述文本；(2) Editor 审核——经选拔培训的 Editor 修订并接受/拒绝，形成双层质量门；(3) 持续修订——Flags 机制允许任何人标记潜在错误，交由 Editor 复核。另有 Source Suggestions 队列按基因/疾病/年份推荐待策展文献（bioRxiv 2021）。
一条典型证据的策展生命周期：
文献遴选（Source Suggestions 或自由选择）
→ Curator 阅读 PubMed 文献全文
→ 填写结构化表单：基因/变异/疾病/疗法/证据类型/临床意义
→ 建议证据等级（A-E）与评分（1-5 星）
→ 提交 EID（进入 submitted 状态）
→ Editor 修订或退回（讨论区留痕）
→ Editor 接受（accepted 状态，进入 TSV 快照）
→ 后续任何人可提交修订建议（revision）
2026-04 起该流程引入 AI 辅助组件（Curation Help Chat 提供 RAG 式文献定位），但官方 AI 政策明确禁止纯 AI 生成内容直接提交，人工策展与审核仍是质量主体。
§3.6 标注者资质与一致性
策展队伍分两级：Curator 开放注册（截至 2026-09-12 共 419 位贡献者），Editor 为独立选拔+强化培训的领域专家，全员操作留痕。一致性由流程性机制保障：Editor 独占接受权、与 ClinGen Somatic Clinical Domain 工作组的合作策展、标准作业程序（SOP）文档化，而非统计性 Kappa 系数（知识库未发布标注者间一致性统计）（CIViCdb 2022）。
§3.7 采集周期
数据生产为持续流式：文献跟进无固定周期，技术上以 nightly（每日快照）与 monthly（每月 1 日快照）两种发布节律输出，API 实时反映全部状态。夜间快照由服务器自动生成，覆盖 Features/Variants/Molecular Profiles/Evidence/Variant Groups/Assertions 六类实体的 TSV 与两类口径的 VCF；月度快照于每月 1 日固化并长期归档，是跨期研究与可复现实验的推荐锚点。对外部同步系统而言，"monthly 为基线、nightly 为热更新、API 为实时层"的三层节律足以覆盖从离线分析到在线服务的全部延迟需求。
§3.8 地域覆盖
- 文献来源地域：全球分布，无地理限制，英语文献为主。
- 策展团队分布：核心团队位于华盛顿大学圣路易斯分校（Griffith 实验室），Editor 与 Curator 社区国际化，含与欧洲机构（EBI、Charité 等）的长期合作。
- 使用方限制：无地域约束，CC0 许可对全球使用者同等生效。
- 癌种地域相关性：文献人群以欧美队列为主，亚洲高发癌种（如鼻咽癌、食管鳞癌）的覆盖相对薄弱，区域性应用需自行补充本地文献解读。
§3.9 设备与测量规格
不适用。CIViC 不含测序/影像原始数据，无采集设备、平台或批次元数据；涉及检测方法的描述仅出现在证据描述文本层面。
§3.10 深度溯源链
每条 EID/AID 的完整溯源链为：文献 PMID → Curator 提交（含时间戳与用户 ID）→ Editor 修订/接受（含时间戳）→ 后续全部修订。API 返回每条记录的 last_modified 与来源对象；44,656 条修订记录使任何历史状态可重建。注意：TSV 静态导出不含溯源与修订历史（详见坑点 2）。
溯源链的结构化表达：
EID 7002
├── source: PMID 26960520（原始文献）
├── curator: 用户 A（提交于 D1，含等级建议）
├── editor: 用户 B（修订描述文本于 D2，接受于 D3）
├── revisions: ×3（含一次等级 C→B 的修订，D4）
└── linked assertion: AID 120（Editor 汇总层）
对 AI 应用而言，这条链意味着每个模型输出都可绑定"文献主张 + 策展轨迹"双层凭据：文献主张用于对照原文防幻觉，策展轨迹用于评估该解读的稳定性（修订次数少且等级未翻转的记录置信更高）。
§4 数据结构
§4.0 目录树
从发布页下载并解压后的文件布局（文件名含发布日期，以下为结构示意）：
civic_release/
├── Features-<date>.tsv # 基因特征（978 行级）
├── Variants-<date>.tsv # 变异（accepted 证据口径）
├── MolecularProfiles-<date>.tsv # 分子特征
├── Evidence-<date>-accepted.tsv # 证据项（accepted）
├── Evidence-<date>-acceptedAndSubmitted.tsv # 证据项（宽口径）
├── VariantGroups-<date>.tsv # 变异组
├── Assertions-<date>-accepted.tsv # 断言
└── <date>_accepted_variants.vcf # VCF（含 accepted/acceptedAndSubmitted 变体）
实际文件名以当期发布页为准；TSV 均为 UTF-8 制表符分隔文本，首行为表头。
§4.1 DAIMS 字段字典
核心表 Evidence-<date>-accepted.tsv 的关键字段（列名以当期发布表头为准）：
| 字段名 | 类型 | 说明 | 示例值 | AI 用途 | 观测误差 | 信息性缺失 | 取值范围 |
|---|---|---|---|---|---|---|---|
| id | Integer | 证据项主键 EID | 7002 | 主键/去重 | 无 | 无 | 全局唯一 |
| gene | Text | 基因符号 | EGFR | 实体链接 | 别名冲突（见坑点 3） | 无 | HGNC 符号 |
| variant | Text | 变异名（自由文本） | L858R | 匹配键 | 命名不统一（坑点 3） | 无 | 官方命名规范 |
| variant_origin | Text | 变异来源 | Somatic | 体细胞/胚系分型 | 历史记录区分不清（坑点 6） | 无 | Somatic/Germline/Rare Germline/Both/NA |
| disease | Text | 疾病名 | Non-small cell lung cancer | 分层标签 | 命名粒度不一 | 可为空 | DO 对齐术语 |
| therapies | Text | 疗法名 | Osimertinib | 药物映射 | 组合疗法多值 | 可为空（非治疗类证据） | NCIt 对齐 |
| evidence_type | Text | 证据类别 | Predictive | 任务类型过滤 | 无 | 无 | Predictive/Prognostic/Diagnostic/Predisposing/Oncogenic 等 |
| clinical_significance | Text | 临床意义 | Sensitivity/Response | 主预测标签 | 类别长尾（坑点 8） | 无 | Sensitivity/Resistance/… |
| evidence_level | Text | 证据等级 | A | 弱监督标签 | 等级随时间修订（坑点 5） | 无 | A/B/C/D/E |
| evidence_rating | Integer | 证据评分（星） | 5 | 质量加权 | 主观性 | 无 | 1-5 |
| description | Text | 证据描述全文 | … | 文本编码输入 | 转写自文献主张 | 无 | 自由文本 |
| source_pmid | Integer | 文献 PMID | 26960520 | 溯源/引用图谱 | 无 | 无 | PubMed ID |
§4.2 变异表字段字典
次核心表 Variants-<date>.tsv 的关键字段（列名以当期发布表头为准）：
| 字段名 | 类型 | 说明 | 示例值 | AI 用途 | 观测误差 | 信息性缺失 | 取值范围 |
|---|---|---|---|---|---|---|---|
| id | Integer | 变异主键 VID | 33 | 主键 | 无 | 无 | 全局唯一 |
| gene | Text | 所属基因符号 | EGFR | 实体链接 | 无 | 无 | HGNC 符号 |
| name | Text | 变异名（自由文本） | L858R | 匹配键 | 命名不统一（坑点 3） | 无 | 官方命名规范 |
| entrez_id | Integer | Entrez 基因 ID | 1956 | 跨库链接 | 无 | 无 | NCBI Gene |
| reference_build | Text | 参考基因组版本 | GRCh37 | 坐标解释 | 双版本并存 | 可为空 | GRCh37/GRCh38 |
| coordinate | Text | 基因组坐标 | chr7:55259515 T>G | VCF 对接 | 未策展时空缺（坑点 1） | 缺失=未策展 | 标准坐标串 |
| allele_registry_id | Text | ClinGen 等位基因注册 ID | CA126718 | 跨库规范化 | 无 | 可为空 | CA 前缀 ID |
| variant_types | Text | 变异类型（SO 术语） | missense_variant | 类型分层 | 无 | 无 | Sequence Ontology |
坐标缺失是该表最重要的信息性缺失：它不是数据错误，而是策展进度的真实信号——坐标已策展的变异才能进入 VCF 导出。
§4.3 标签分布
标签体系为二维：evidence_level（A-E，强度）× clinical_significance（意义类型）。官方未发布整体分布统计；第三方研究显示证据库存在明显的等级长尾——在 2019 年对 645 个 SNV/indel 的抽样中，近半数证据处于 Level C（病例研究级），Level A（指南/FDA 级）占比很小（VIC 对比研究）。使用前应按当期 TSV 自行统计，勿依赖历史快照分布训练生产模型。
自行统计的三行代码：
print(evidence["evidence_level"].value_counts()) # 等级分布
print(evidence["clinical_significance"].value_counts()) # 意义分布
print(evidence.groupby("evidence_type")
["evidence_level"].value_counts()) # 交叉分布
交叉分布的意义在于识别"任务 × 强度"的空洞组合：例如 Predisposing 类证据几乎不可能有 Level A（胚系用药指南极少进入肿瘤治疗指南），若模型在这些组合上输出高置信预测，应视为分布外信号。
§4.4 关键统计
- 平均每变异约 2.8 条证据（11,561 EID / 4,132 变异），头部变异（EGFR L858R、BRAF V600E 等）证据密度远高于中位数。
- 证据与断言比例约 38:1，绝大多数知识停留在"单条证据"层，未经断言层总结。
- 修订活动活跃：44,656 条修订对应约 3.9 次修订/证据项，说明内容处于持续校准状态。
- 基因-证据集中度高：978 个基因中，头部约 50 个基因承载了不成比例的证据份额，中位基因仅有个位数证据（可由当期 TSV 直接验证）。
- 文献-证据比约 2.6（11,561 EID / 4,386 篇文献），与 VICC 协调研究中"平均 2.95 条解读/文献"的量级一致（PMC7127986）。
§4.5 数据层级
Gene (Feature, GID)
└── Variant (VID) ── Molecular Profile (MPID)
├── Evidence Item (EID) ×N ← 每条挂 PMID 溯源
└── Assertion (AID) ← Editor 总结，可提交 ClinVar
层级语义：一个基因含多个变异；一个变异可对应多个分子特征；证据项是最小知识单元，断言是人工总结层。关联分析时以 gene_id/variant_id 外键展开。
§4.6 缺失值与信息性缺失
| 缺失模式 | 位置 | 语义 | 处理建议 |
|---|---|---|---|
| 空字符串/空单元格 | therapies、disease 等 | 该证据不涉及（如预后类无疗法） | 保留为"不适用"，勿填充 |
| 坐标字段缺失 | variants 表部分行 | 坐标未策展完成 | VCF 导出自动剔除（坑点 1） |
| NA | variant_origin | 历史记录未区分 | 见坑点 6，按记录时间分桶处理 |
| 无 | 主键与等级字段 | — | — |
§5 数据划分与使用建议
§5.1 官方划分
CIViC 无官方 train/val/test 划分——它是知识库而非 ML 基准数据集。任何划分均为社区自定行为，因此论文报告中必须显式声明划分协议与快照日期，否则结果不可比较、不可复现。
§5.2 社区惯例划分
- 时间切分：以快照日期为界，旧快照训练、后续新增证据测试，模拟"预测新文献解读"的真实任务。
- 实体 hold-out：按基因或按疾病整组切分，测试跨基因泛化（此切分难度显著更高）。
- 证据 → 断言对齐：以断言（AID）为"金标准层"，检验从证据层聚合推理的模型上限。
- 难度分层切分：按证据密度分层（头部基因 vs 长尾基因），分别报告指标以暴露冷启动短板。
§5.3 泄漏风险 ⭐
三大泄漏源必须显式处理：
- 同变异多证据：同一 VID 的多条 EID 高度同源（常出自同一文献或同一策展波次），随机切分必致训练/测试近重复。
- 同文献多证据：一篇 PMID 可产生多条 EID，文本描述高度雷同。
- 修订前向泄漏：旧快照中某证据的等级可能已被后续修订推翻，训练时若混用不同日期快照会引入时间泄漏。
推荐：以 PMID 或 VID 为组键做 GroupShuffleSplit，并冻结单一快照日期。
§5.4 交叉验证建议
分组 K 折（GroupKFold by VID）5 折；报告每折的类级 F1 与等级序相关性，警惕 Level A/B 稀有类在单折中缺位。若关注意义类型长尾类，建议改用分层分组采样：先按 evidence_type × evidence_level 分层，再在层内按 VID 分组抽样，保证每折的标签边缘分布近似稳定。
§5.5 切分实现示例
from sklearn.model_selection import GroupShuffleSplit
# 组键：同变异 + 同文献永不跨集（§5.3 泄漏源 1/2）
groups = clean["variant"].astype(str) + "|" + \
clean["source_pmid"].astype(str)
gss = GroupShuffleSplit(n_splits=1, test_size=0.2,
random_state=42)
train_idx, test_idx = next(gss.split(clean, groups=groups))
train_df, test_df = clean.iloc[train_idx], clean.iloc[test_idx]
print(len(train_df), len(test_df),
len(set(train_df["variant"]) & set(test_df["variant"])))
# 最后一项必须为 0
§5.6 外部验证建议
以 OncoKB Level 1/2 与 ClinVar 五星评级做跨库一致性抽检（VICC 联盟研究显示六库仅极少数文献被共同覆盖，跨库验证信息量大且互补性强，PMC7127986）。
§6 AI 就绪指南 ⭐
§6.0 云端快速启动
CIViC 体量小（§3.4），本地即可完成全流程，无需 GPU 集群。如需云端复现：数据文件可任意托管（CC0 允许），GraphQL API 可从任何环境直连；官方项目曾使用 Google BigQuery 与 AWS Open Data 基础设施（CIViCdb 2022 致谢）。
§6.1 快速上手（5 分钟）
目录结构预期与最小编译子集：
# ============================================================
# 目录结构预期：
# data_root/civic/
# ├── Features-<date>.tsv
# ├── Variants-<date>.tsv
# └── Evidence-<date>-accepted.tsv # 最小可用子集：本文件
# data_root 与文件名按发布页当期命名拼接；
# 以下用 glob 匹配，兼容任意发布日期后缀。
# ============================================================
import pandas as pd
from pathlib import Path
data_root = Path("data_root/civic")
evidence = pd.read_csv(
sorted(data_root.glob("Evidence-*-accepted.tsv"))[-1],
sep="\t", low_memory=False,
)
print(len(evidence), "条 accepted 证据")
print(evidence["evidence_level"].value_counts()) # 等级分布速览
sub = evidence[["gene", "variant", "disease",
"clinical_significance", "evidence_level"]]
print(sub.head())
§6.2 数据获取
| 通道 | 地址 | 认证 | 大小/频率 |
|---|---|---|---|
| TSV/VCF 快照 | https://civicdb.org/releases | 无需注册 | 数十 MB 量级 / nightly+monthly |
| GraphQL API | https://civicdb.org/api/ | 无需注册 | 实时 |
| CIViCpy SDK | pip install civicpy |
无需注册 | 本地缓存刷新 |
CIViCpy 获取全量对象化缓存：
# pip install civicpy
from civicpy import civic
# 首次运行下载完整缓存；on_stale 控制过期策略
civic.load_cache(local_cache_path="civic_cache.pkl",
on_stale="overwrite")
eids = civic.get_all_evidence() # 全部证据项对象
accepted = [e for e in eids if e.status == "Accepted"]
print(len(accepted))
GraphQL 增量拉取（以证据项分页为例）：
import requests
url = "https://civicdb.org/api/graphql"
query = """
query($first: Int!, $after: String) {
evidenceItems(first: $first, after: $after) {
pageInfo { endCursor hasNextPage }
nodes { id name evidenceLevel evidenceType
clinicalSignificance status }
}
}
"""
cursor, rows = None, []
while True:
r = requests.post(url, json={
"query": query,
"variables": {"first": 100, "after": cursor}}).json()
page = r["data"]["evidenceItems"]
rows += page["nodes"]
if not page["pageInfo"]["hasNextPage"]:
break
cursor = page["pageInfo"]["endCursor"]
print(len(rows))
§6.3 预处理全流程
格式统一 → 等级映射 → 疾病规范化三步：
import pandas as pd
LEVEL2TIER = { # 官方映射：VICC Table 1
"A": "Tier I", "B": "Tier I",
"C": "Tier II", "D": "Tier II", "E": "Inferential",
}
def preprocess(ev: pd.DataFrame) -> pd.DataFrame:
# 1) 清洗：去空白、统一大小写占位
ev = ev.copy()
for col in ("gene", "variant", "disease",
"clinical_significance"):
ev[col] = ev[col].astype(str).str.strip()
# 2) 等级映射到 AMP/ASCO/CAP 层级
ev["amp_tier"] = ev["evidence_level"].map(LEVEL2TIER)
# 3) 疾病粒度粗化（示例：小细胞→肺；细则按 DO 上位词表）
ev["disease_bucket"] = ev["disease"].replace({
"Non-small cell lung cancer": "Lung cancer",
"Lung adenocarcinoma": "Lung cancer",
})
return ev.drop_duplicates(subset=["id"])
clean = preprocess(evidence)
§6.4 PyTorch DataLoader 完整示例
<details>
<summary>展开完整可运行代码（约 45 行）</summary>
# ============================================================
# 任务：预测证据等级 A-E（弱监督多分类）
# 输入：基因/变异/疾病/意义四字段拼接文本 → 字符级词表
# 说明：生产环境建议替换为 BioBERT/PubMedBERT 分词器；
# 本示例零外部依赖，可直接运行验证数据管线。
# ============================================================
import pandas as pd
import torch
from torch.utils.data import Dataset, DataLoader
from pathlib import Path
class CivicLevelDataset(Dataset):
def __init__(self, tsv_path: Path, vocab=None):
df = pd.read_csv(tsv_path, sep="\t", low_memory=False)
df = df.dropna(subset=["evidence_level"])
# 组键防泄漏：同变异同疾病归组（§5.3）
df["group"] = (df["variant"].astype(str) + "|" +
df["disease"].astype(str))
self.df = df.reset_index(drop=True)
text = (self.df["gene"].fillna("") + " " +
self.df["variant"].fillna("") + " " +
self.df["disease"].fillna(""))
if vocab is None:
vocab = {"<pad>": 0, "<unk>": 1}
for line in text:
for tok in line.lower().split():
vocab.setdefault(tok, len(vocab))
self.vocab = vocab
self.levels = sorted(df["evidence_level"].unique())
self.l2i = {l: i for i, l in enumerate(self.levels)}
def __len__(self):
return len(self.df)
def __getitem__(self, i):
r = self.df.iloc[i]
ids = [self.vocab.get(t, 1) for t in
str(r["gene"]) .split() +
str(r["variant"]).split() +
str(r["disease"]).split()]
x = torch.tensor(ids[:64], dtype=torch.long)
y = self.l2i[r["evidence_level"]]
return x, y
def collate(batch):
xs, ys = zip(*batch)
L = max(len(x) for x in xs)
X = torch.zeros(len(xs), L, dtype=torch.long)
for i, x in enumerate(xs):
X[i, :len(x)] = x
return X, torch.tensor(ys)
ds = CivicLevelDataset(
sorted(Path("data_root/civic").glob(
"Evidence-*-accepted.tsv"))[-1])
loader = DataLoader(ds, batch_size=32, shuffle=True,
collate_fn=collate)
X, y = next(iter(loader))
print(X.shape, y.shape)
</details>
§6.5 坑点清单（8 个真实失败模式）
⚠️ 坑点 1：VCF 与 TSV 变异数不一致，注释流水线静默漏变异（分类：工程陷阱）
问题：VCF 规范只能表达具完整基因组坐标的变异，CIViC 中坐标未策展完成或无法用 VCF 表示的变异（如某些融合、表达标记）被 VCF 导出自动剔除，导致 VCF 变异数显著少于 TSV。
症状：用 VCF 跑 ANNOVAR/VEP 注释后统计"已被 CIViC 覆盖"的变异数低于预期；或以 TSV 数量为基准做覆盖率报告时发现 VCF 通道"丢失"了记录，误判为下载不完整。
解决：
- 简单方法：下载前阅读发布页口径说明，向下游明示"VCF = accepted + 完整坐标"子集；对覆盖率统计统一用 TSV 口径。
- 进阶方法：双通道合并——VCF 注释 + TSV（自由文本变异名）模糊匹配兜底，把 VCF 漏掉的变异回补进报告；回补命中率写入流水线日志。
- SOTA 方法：通过 API 取每个变异的
coordinates字段做完整性分级（完整坐标/部分/无），按等级路由到 VCF 注释或文本匹配两条支路，并对"部分坐标"变异记录引线置信度。
参考：https://civicdb.org/releases（官方口径说明）
⚠️ 坑点 2：TSV 快照缺溯源与修订历史，审计需求走错通道（分类：工程陷阱）
问题：静态 TSV 导出刻意不含用户档案、讨论、数据溯源与修订历史，也不含外部动态资源（MyVariant.Info 等）的实时信息；审计/合规场景需要 provenance 时，TSV 无法满足。
症状：下游合规审计要求"每条 AI 输出的证据可追溯到策展人与修订时间"时，发现 TSV 里既无 curator 字段也无 last_modified 修订链，被迫重构取数层。
解决：
- 简单方法：审计字段需求明确的项目直接全量走 GraphQL API（与前端同源），跳过 TSV。
- 进阶方法：混合架构——TSV 做日常批量计算，API 定期增量拉取 provenance 表单独落库，两表以 EID/AID 主键关联。
- SOTA 方法：用 CIViCpy 本地缓存（对象含完整元数据）作为项目内"冻结知识库快照"，配合数据版本控制（DVC）把缓存文件纳入版本管理，实现可复现审计。
参考：https://civicdb.org/releases；https://github.com/griffithlab/civicpy
⚠️ 坑点 3：自由文本变异命名阻碍自动匹配，跨库 join 产生假匹配（分类：预处理陷阱）
问题：CIViC 为策展灵活性允许自由文本变异名与别名（密码子级如
L858、外显子级、融合如EML4-ALK、表达标记如p16 表达），命名规范虽在但无法穷举；第三方研究发现 CIViC 独有的点突变记录因描述不特异在跨库匹配中产生假阳性。
症状：把 CIViC 变异名与 VEP/HGVS 输出直接字符串 join 时匹配率骤低；或更危险——模糊匹配"看似成功"但把 EGFR L858R 错配到 L861Q 类记录上，注释结果静默错误。
解决：
- 简单方法：匹配前做规范化（大小写、去空格、别名表展开），只接受完全匹配，未匹配显式标记而非猜测。
- 进阶方法：优先用
variant_id/ClinGen Allele Registry ID 做 join（API 可取 allele registry ID），字符串匹配仅作降级路径；融合/密码子级变异建立专门映射规则。- SOTA 方法：接入 VARIANT-NORMALIZER 类规范化服务把自由文本解析为结构化（基因+蛋白质变化+坐标），解析失败样本进入人工复核队列；对解析结果抽样评估精确率再放量。
参考：https://doi.org/10.1093/nar/gkac979（官方自述可互操作性受限）；https://www.medrxiv.org/content/10.1101/2022.11.08.22282064v1（假匹配实例）
⚠️ 坑点 4：同变异/同文献多证据导致随机切分泄漏（分类：数据泄漏）
问题：一个变异常有多条证据（平均约 2.8 条/变异，头部变异更多），一篇文献可产生多条 EID；这些兄弟记录文本与标签高度同源。
症状：随机 train/test 切分下模型指标虚高（常见 0.9+ 的等级预测 F1），上线后对新变异/新文献的表现断崖式下跌；测试集中出现与训练集近乎相同的描述文本。
解决：
- 简单方法：按 VID 做分组切分（GroupShuffleSplit），保证同变异不跨集。
- 进阶方法：双重分组——同 PMID 与同 VID 皆不跨集（合并组键
VID|PMID取并查集再切分）。- SOTA 方法：时间切分——冻结快照日期 D，用 D 前证据训练、D 后新增证据测试，同时保持 VID 分组；报告"新增变异子集"单独指标以模拟真实冷启动场景。
参考：本页 §5.3；https://civicdb.org/releases（快照机制）
⚠️ 坑点 5：证据等级是文献强度不是模型可执行度，Level A ≠ 自动可信（分类：标签理解）
问题：A-E 等级刻画"文献主张的强度"（指南/FDA → 临床试验 → 病例 → 临床前 → 推断），不等于变异-疗法因果被独立验证，也不含检测场景适配性；第三方自动重分级研究显示 CIViC Level A 记录也可能与自动工具结论冲突。
症状：以等级为"真值"训练模型后，把 Level A 直接当决策阈值输出给临床用户，被分子病理委员会驳回"该证据针对的组织学/检测方法与患者场景不符"；或发现某 Level A 胚系用药证据被当作体细胞治疗证据使用。
解决：
- 简单方法：把等级当"先验强度"而非真值，输出时附带原始 significance 与 origin 字段供人工复核。
- 进阶方法：构建等级 × 类型 × origin 三维过滤再进入模型；对胚系/体细胞混合记录单独分层评估。
- SOTA 方法：多任务建模（同时预测等级与意义类型），并以 AMP/ASCO/CAP Tier 映射做后约束（VICC Table 1 官方映射），输出层强制满足映射一致性。
参考：https://doi.org/10.1093/nar/gkac979（官方"谨慎解读"声明）；https://tomesphere.com/paper/PMC6708137（Level A 冲突实例）；https://pmc.ncbi.nlm.nih.gov/articles/PMC7127986/（Tier 映射）
⚠️ 坑点 6：variant_origin 语义含混，体细胞与胚系证据被混用（分类：偏倚陷阱）
问题：CIViC 同时收录体细胞与胚系（易感性）解读，早期记录 origin 标注不严格，部分记录为 NA 或 Both；外部综述明确指出该库"未清晰区分遗传性罕见变异与获得性体细胞变异"。
症状：把 Predisposing 类胚系证据（如某基因胚系突变提示癌症风险）混入体细胞治疗预测训练集，模型输出"该体细胞突变预测某靶向药获益"的假关联；或相反地漏掉真正的胚系用药证据（如 DPYD 药物基因组学）。
解决：
- 简单方法：训练/推理均按
evidence_type过滤，治疗类只取 Predictive 且variant_origin含 Somatic 的记录。- 进阶方法：对 origin 为 NA/Both 的历史记录按证据类型+疾病语义做规则回填（Predisposing→Germline），回填结果单独打标。
- SOTA 方法：双塔建模——体细胞治疗解读与胚系易感解读分别建知识库分片，共享编码器但不共享标签空间，从架构上杜绝混用。
参考：https://pmc.ncbi.nlm.nih.gov/articles/pmid/39543667/（综述明确指出混用问题）
⚠️ 坑点 7：发布口径随时间漂移，跨版本比较与增量同步踩坑（分类：工程陷阱）
问题：Variant TSV 在 2020-08 前包含全部变异、之后仅含具 accepted 证据的变异；deprecation/retraction 状态的记录处理在物化视图中仍在演进；证据等级本身也会被修订（FDA 批准可使 C→A）。
症状：用 2020 年前后的快照对比"变异数增长"时得到虚假下降；增量同步脚本按主键 diff 时把"被撤回证据"当作新增；训练集中混入已撤回（retracted）文献的解读。
解决：
- 简单方法：所有跨期分析锁定同一种发布口径文件（如只比较 accepted EID TSV），并在报告中注明快照日期。
- 进阶方法：增量同步以 API 的修订时间戳为准而非主键存在性；拉取时过滤 status ≠ Accepted 且含 retraction 标记的记录并单独归档。
- SOTA 方法：建立项目内"证据生命周期表"（EID → 状态 → 生效快照区间），任何下游表都按生命周期表物化，使任意历史时点的库状态可重建。
参考：https://civicdb.org/releases（口径变更说明）；https://github.com/griffithlab/civic-v2/issues（#1399 等状态过滤议题）
⚠️ 坑点 8：策展密度不均，热门基因主导统计结论（分类：偏倚陷阱）
问题：开放策展不指定任务方向，EGFR 等热点基因证据数百条而冷门基因寥寥，官方论文明确承认"基因与疾病间策展完整度差异显著"；覆盖以 FDA 相关、英语文献癌种为主。
症状：按基因聚合的"可药性知识覆盖率"报告严重高估整体水平；以证据数当权重做疾病排名时肺癌/乳腺类癌种压倒性主导；少样本基因上的模型评估方差极大。
解决：
- 简单方法：统计与建模前先做基因/疾病分层描述（记录数中位数 vs 均值），报告中显式给出热点-冷门比例。
- 进阶方法：少样本基因采用分层采样与基因级交叉验证，并对证据数 < 阈值的基因单独报告置信区间。
- SOTA 方法：与 ClinVar/OncoKB 做跨库覆盖互补分析（VICC 协调研究显示六库文献重合度极低），用跨库并集重估真实覆盖并标注单库盲区。
参考：https://doi.org/10.1093/nar/gkac979；https://pmc.ncbi.nlm.nih.gov/articles/PMC7127986/
§6.6 数据增强
- ✅ 安全：同义词表扩展（基因别名、疗法通用名/商品名映射）；疾病术语按 Disease Ontology 上位词粗化；文本描述的句子级重组（保留 PMID-主张对应关系）。
- ✅ 安全：以证据评分为采样权重（高分证据过采样），模拟"审稿偏好"。
- ✅ 安全：按 evidence_type 分支独立增强——治疗类与预后类的文本模式差异大，混合增强会污染任务语义。
- ❌ 危险：跨变异复用描述文本（破坏"一条证据一篇文献"的溯源语义）；对变异名做字符级扰动（等位命名极敏感，L858R→L858Q 直接改变生物学含义）；把 Level E 推断性证据与 A/B 级同等混入增强池。
- ❌ 危险：对 therapy 字段做随机替换增强——药物名是强实体，替换后的"变异-药物"对可能违背生物学事实并污染训练信号。
§6.7 模型推荐
| 任务 | 推荐模型 | 起点理由 |
|---|---|---|
| 变异名规范化 | 规则+查表（HGNC/Allele Registry） | 确定性映射优于学习法（坑点 3） |
| 等级/意义预测 | PubMedBERT / BioBERT 微调 | 领域词表对证据描述文本友好 |
| 变异-疾病图建模 | 异构图神经网络（R-GCN） | 天然五级实体图结构（§4.5） |
| 肿瘤问答/RAG | LLM + 证据项检索（官方 MCP server） | 逐条溯源可审计，抑制幻觉 |
| 文献抽取（摘要→EID） | LLM few-shot + 结构化输出 | 与策展表单字段对齐 |
| 等级回归（连续强度） | 序数回归/梯度提升树 | 结构化特征（类型/评分/origin）先于文本特征 |
§6.8 硬件需求
| 场景 | 配置 | 说明 |
|---|---|---|
| TSV 分析/统计 | 4 核 / 8 GB RAM | 数据数十 MB 量级，笔记本足够 |
| BERT 级微调 | 单卡 16 GB 显存（如 T4/4060） | 11,561 条文本，小时级 |
| LLM RAG 服务 | CPU 推理可行（检索层）+ 可选 GPU 生成 | 证据文本短，向量检索轻量 |
| 图神经网络实验 | 单卡 8-16 GB 显存 | 实体图规模（数千节点）远低于显存瓶颈 |
| 全量缓存构建 | 2 核 / 4 GB RAM | CIViCpy 本地缓存构建仅需数分钟 |
§6.9 评估指标
from sklearn.metrics import (f1_score,
cohen_kappa_score)
# 等级 A-E 为有序标签：报告宏 F1 + 有序一致性
y_true, y_pred = [...], [...]
print("macro-F1:", f1_score(y_true, y_pred,
average="macro"))
print("quadratic kappa:",
cohen_kappa_score(y_true, y_pred,
weights="quadratic"))
要点：等级是有序的（A>B>C>D>E），用二次加权 Kappa 衡量"跨级错误惩罚"；意义类型为多分类长尾，必须报宏平均并给出每类支持数。
§6.10 MLOps 笔记
- 数据版本化：CIViC 内容每日变动，任何模型版本必须绑定快照日期（TSV 文件名中的日期即版本戳）。
- 再分发自由：CC0 允许把派生特征库直接纳入私有仓库/公开发布，无许可审查（与受限库的关键工程差异）。
- 监控漂移：证据等级修订是天然的概念漂移信号，建议月度 diff 快照并统计"等级翻转数"作为知识库演化指标。
- 回归防线：对 EGFR L858R、BRAF V600E 等高置信记录建立"金标准回归集"，每次数据更新后跑注释一致性冒烟测试。
- 增量同步架构：以 monthly 快照为全量基线、API 修订时间戳为增量流，避免"全量 diff"式同步的网络开销；同步任务需容忍 API 分页游标过期重试。
- 特征冻结策略：训练特征从"训练时快照"生成并持久化，推理时从"最新快照"实时生成；两侧特征分布差异应纳入模型监控面板。
- 审计留痕：保存每次训练/推理所用快照的哈希值与下载日志，满足医疗 AI 质量体系对数据溯源的审查要求。
- 成本控制：数据与缓存均为 MB 级文本，无需对象存储分区；瓶颈通常在 API 速率而非存储，客户端缓存（CIViCpy 本地缓存）即可将 API 调用降为近零。
§7 质量评估与局限性
§7.1 已知偏倚
| 偏倚类型 | 描述 | 严重程度 | 缓解措施 |
|---|---|---|---|
| 热门基因偏倚 | 开放策展导致热点基因（EGFR/BRAF 等）证据密度远超冷门基因 | 高 | 分层统计+跨库互补（坑点 8） |
| 英语文献偏倚 | 策展以英语同行评审文献为主 | 中 | 意识到区域癌种（如鼻咽癌）覆盖偏弱 |
| 指南跟随偏倚 | Level A 集中于 FDA 相关适应证 | 中 | 结合 ESCAT/Tier 映射解读 |
| 滞后偏倚 | 新批准疗法到证据入库存在时滞 | 中 | nightly 同步+审批状态过滤 |
| 主张转写偏倚 | EID 转写文献作者主张，不再分析原始数据 | 中 | 视为"主张库"而非"事实库"（官方声明） |
| 断言稀疏偏倚 | 仅 302 条断言覆盖数千变异，总结层覆盖极不完整 | 中 | 聚合任务自行实现证据→结论逻辑 |
| 快照口径偏倚 | Variant TSV 口径 2020-08 前后不一致，易造成趋势误读 | 低 | 跨期分析锁定统一口径（坑点 7） |
§7.2 标注质量
质量机制为流程型而非统计型：Editor 独占接受权+强化培训、全量修订历史（44,656 条）、Flags 公共纠错、与 ClinGen Somatic 的联合策展。未发布标注者间一致性统计（Kappa），是知识库类数据的共性局限；下游使用者应以"双层人工审核"为质量先验，而非以统计一致性为凭据（CIViCdb 2022）。
三个可量化的质量代理指标建议纳入使用前评估：(1) 证据的修订次数分布——修订多说明争议或演进频繁；(2) 等级翻转频率——同一 EID 历史等级变化越大，该区域知识越不稳定；(3) 断言覆盖率——有断言（AID）汇总的变异知识经过 Editor 二次把关，可信先验高于仅有零散 EID 的变异。三者均可通过 API 修订历史计算。
§7.3 泛化性分析
| 场景 | 失效风险 | 证据 |
|---|---|---|
| 跨癌种迁移 | 高：疾病命名粒度不一，模型易学到癌种捷径 | 第三方研究需人工肿瘤类型匹配（medRxiv 2022） |
| 跨基因迁移 | 高：冷门基因分布外 | 官方自述完整度不均（NAR 2022） |
| 跨时间迁移 | 中：等级随指南/FDA 批准漂移 | nightly 更新机制本身即证据 |
| 跨语言迁移 | 高：库内为英文，中文临床术语需额外对齐 | 知识库语言属性 |
§7.4 伦理考量
CIViC 不含患者级数据，仅含文献层面已发表的主张与公开临床试验信息，无隐私风险。临床使用层面：证据等级不等于治疗建议，任何自动化输出进入临床必须经分子病理委员会复核（见 §0 医疗免责声明）。AI 使用层面：官方 2026-04 生效的 AI 政策明确禁止纯 AI 生成内容直接提交入库，策展辅助（Curation Help Chat、MCP server）仅限辅助定位——这一立场与"AI 输出需人工溯源审核"的伦理基线一致。
§7.5 公平性
知识库层面的公平性体现为覆盖公平：FDA 相关癌种与英语文献人群（多为欧美队列）证据密度显著更高，罕见癌种与非欧美人群相关的变异-疾病组合覆盖偏弱。用 CIViC 训练的临床模型在罕见癌种/非欧美人群上的表现应做显式压力测试。
公平性审计建议三步走：(1) 统计各 ICD-11 大类的证据份额，标注覆盖低于阈值（如 <50 条）的癌种为"低资源组"；(2) 在低资源组上单独评估模型指标，禁止只报整体均值；(3) 对胚系易感类内容核查族裔特异性变异（如某些 founder mutation）的呈现方式，避免把人群特异证据泛化为普适结论。这些步骤的成本极低（均为 TSV 统计），但能显著降低下游临床应用的公平性风险。
§7.6 数据漂移
三类漂移源：(1) 知识漂移——新文献与新批准持续改变证据格局；(2) 等级翻转——FDA 批准可使 Level C 跃升为 Level A，历史快照中的标签部分失效；(3) 模型漂移——2022 年引入 Molecular Profiles 后实体关系schema升级，旧脚本外键假设需复查。缓解：绑定快照日期+月度 diff 监控（§6.10）。
可操作的漂移监控方案：每月固定拉取当月 monthly 快照，计算三个指标并绘图——新增 EID 数（知识增长率）、等级翻转矩阵（上一月等级 × 本月等级的交叉表，非对角元素即翻转量）、实体 schema 变更检测（表头 diff）。任一指标越界（如翻转量环比翻倍）即触发下游模型再评估流程。
§7.7 DAIMS 24 项质量检查
| # | 检查项 | 状态 | 说明 |
|---|---|---|---|
| 1 | 宽格式 | ✅ | 每实体单表宽格式 TSV，一行一记录 |
| 2 | 唯一标识 | ✅ | EID/AID/VID/GID 全局主键体系 |
| 3 | 特殊字符 | ⚠️ | UTF-8 完备，但变异名含连字符/希腊字母等，join 前需规范化 |
| 4 | 重复行 | ✅ | 主键约束下无重复；兄弟证据需按 VID/PMID 分组 |
| 5 | 缺失编码 | ⚠️ | 空单元格与 NA 混用，语义需按字段区分（§4.6） |
| 6 | 标签标识 | ✅ | evidence_level/clinical_significance 标签字段明确 |
| 7 | 罕见类分组 | ⚠️ | 意义类型与等级呈长尾分布，少样本类需合并评估 |
| 8 | 偏倚评估 | ⚠️ | 官方论文自述覆盖不均，官方无量化偏倚报告 |
| 9 | 数据字典 | ✅ | 官方文档（readthedocs+帮助页）字段级说明完备 |
| 10 | 信息性缺失解释 | ⚠️ | 坐标缺失=未策展为信息性信号，官方仅在发布页说明 |
| 11 | 设备记录 | ❌ | 知识库无设备/采集平台元数据，不适用 |
| 12 | 共线性 | ✅ | 文本表无影像/EHR 类共线性问题 |
| 13 | 编码映射 | ✅ | A-E → AMP/ASCO/CAP Tier 官方映射表（VICC Table 1） |
| 14 | 时间戳处理 | ✅ | 记录含 last_modified；API 修订时间戳完备 |
| 15 | 划分建议 | ⚠️ | 无官方 ML 划分，本页 §5 提供三套社区惯例 |
| 16 | 泄漏讨论 | ⚠️ | 官方未讨论 ML 泄漏，本页 §5.3 补全三泄漏源 |
| 17 | 标签分布 | ⚠️ | 官方未发布整体分布统计，需自算当期快照 |
| 18 | 测量偏倚 | ⚠️ | "测量"即文献主张转写，存在转写偏倚（§7.1） |
| 19 | 外部验证建议 | ✅ | VICC 跨库协调与 OncoKB/ClinVar 对照路径明确 |
| 20 | 版本记录 | ✅ | nightly/monthly 发布+44,656 条修订历史 |
| 21 | 预处理脚本 | ✅ | 官方 CIViCpy SDK 覆盖缓存/对象化/API |
| 22 | 合规要求 | ✅ | CC0 无合规负担，引用论文为唯一礼仪要求 |
| 23 | 多模态对齐 | ✅ | 单模态知识库，无跨模态对齐需求 |
| 24 | 去标识化 | ✅ | 无患者级数据，无去标识化需求 |
DAIMS 评分：18.5 / 24
评分解读：14 项 ✅、9 项 ⚠️、1 项 ❌。失分项集中在两类：一是为影像/EHR 设计的通用检查项对知识库天然不适用（设备记录）；二是知识库作为"ML 数据集"的非原生属性——无官方划分、无标签分布统计、无泄漏讨论，需要使用者以工程手段补齐。⚠️ 项均给出可执行缓解路径（§4.6、§5、§6.5），补齐后实际工程可用度高于分值直观印象。
对你意味着什么：如果你做变异注释/RAG，CIViC 即取即用（标识/映射/版本/合规全绿）；如果你训练监督模型，必须自己完成三件事——锁定快照日期、按 VID/PMID 分组切分、按当期数据重算标签分布。跳过这三步得到的指标基本不可信。
§7.8 外部验证矩阵
| 外部数据集/场景 | 来源机构 | 评估任务 | 性能指标 | 相对内部变化 | 关键发现 |
|---|---|---|---|---|---|
| VICC meta-knowledgebase（六库协调） | VICC 联盟 | 跨库证据协调 | v0.10 共 12,856 条协调解读 / 4,354 篇文献 | 83% 文献仅被单一库覆盖 | 六库高度互补，CIViC 为开源骨干（NAR 2020） |
| 自动重分级系统 VIC | 第三方学术 | 645 个 SNV/indel 重分级 | 近半 CIViC 证据为 Level C | 与 CIViC 等级存在系统性分歧 | 等级≠自动可执行（VIC 研究） |
| 泛癌组学队列注释 | medRxiv 2022 研究 | 难治性转移癌变异注释 | CIViC-only 点突变假匹配被人工剔除 | 相对 OncoKB 覆盖互补 | 命名不特异导致假匹配，需人工规范化（medRxiv） |
§8 基准性能与生态
§8.1 排行榜与下游系统
CIViC 是知识库而非 ML 基准，无官方排行榜；下表列出以 CIViC（或与之深度互操作）为基础的代表性下游系统。对于"以 CIViC 为训练源的任务"，社区同样未形成统一基准——这意味着报告结果时自行声明评测协议（§8.3）比追逐单一榜单更重要：
| 系统 | 任务 | 与 CIViC 的关系 | 关键技术 | 完整引用 | 代码 |
|---|---|---|---|---|---|
| Cancer Genome Interpreter | 变异可药性注释 | 采用 CIViC 类开放证据与分级思想 | 驱动变异识别+药物匹配规则库 | Tamborero D, et al., 2018, Nature Communications. DOI 10.1038/s41467-018-03623-z | 未公开完整仓库 |
| VICC meta-knowledgebase | 六库协调解读 | CIViC 为协调的开放骨干之一 | 字段级 harmonizer 管线 | VICC Meta-knowledgebase Task Team, 2020, Nucleic Acids Research. https://pmc.ncbi.nlm.nih.gov/articles/PMC7127986/ | 部分公开 |
| VIC | 体细胞变异自动分级 | 以 CIViC 645 变体做对照评估 | 规则+知识库混合 | VIC 研究团队, PMC6708137 | 见论文 |
| OncoKB | 精准肿瘤知识库 | VICC 协调伙伴、Tier 映射对照 | FDA/NCCN 层级证据 | Chakravarty D, et al., 2017, JCO Precision Oncology. DOI 10.1200/PO.17.00011 | 部分受限 |
⚠️ 各系统疾病/变异规范化策略不同，性能数字不可直接横比；上表"指标"以覆盖与协调能力描述为主。
§8.2 SOTA 总结与选型建议
以"开放获取+可审计"为选型轴，CIViC 是当前许可最宽松、溯源最完整的肿瘤变异解读知识库（CC0+API+SDK）；以"临床决策直接可用"为轴，OncoKB 的 FDA/NCCN 层级更贴近处方语境但访问受限。工程实践的最优解是 VICC 式多库并用：CIViC 做开放主干，跨库协调补覆盖盲区（§7.8）。
按下游任务给出选型建议：
| 你的任务 | 首选 | 理由 |
|---|---|---|
| 变异注释流水线（报告场景） | CIViC VCF+TSV 双通道 | CC0 允许嵌入商业产品（坑点 1 提示双通道合并） |
| 训练解读预测模型 | CIViC TSV + 自建划分 | 无官方划分，遵循 §5 三大纪律 |
| LLM RAG 知识源 | CIViC API/快照（含溯源字段） | 逐条 PMID 溯源可审计，天然防幻觉 |
| 跨库对照研究 | VICC 协调输出（含 CIViC） | 官方 harmonizer 省去重复造轮子 |
| 药物基因组学/胚系场景 | CIViC Predisposing 类 + PharmGKB 补充 | 单库胚系覆盖偏弱 |
§8.3 评测协议建议
(1) 冻结快照日期并在论文/报告中声明；(2) 分组切分（VID|PMID 并查集）；(3) 报告宏 F1+二次加权 Kappa（等级任务）；(4) 附"新增变异冷启动子集"单独指标；(5) 与 OncoKB/ClinVar 做覆盖一致性抽检作为外部效度。
§8.4 相关数据集
| 数据集 | 机构 | 与 CIViC 关系 | 许可 |
|---|---|---|---|
| ClinVar | NCBI | 断言自动提交目标库，变异-表型互补 | 公有领域 |
| OncoKB | MSKCC | VICC 协调伙伴 | 部分受限 |
| JAX-CKB | Jackson Laboratory | 商业深度注释 | 商业许可 |
| Cancer Genome Interpreter 数据 | VHIO | 开放可药性规则 | 开放 |
| PMKB | Weill Cornell | 区域性解读库 | 受限 |
| COSMIC | Sanger | 体细胞突变目录（更偏频谱） | 商业许可 |
| dbNSFP | 学术维护 | 功能预测聚合（非解读型） | 开放 |
| PharmGKB | Stanford | 药物基因组学（胚系侧重） | 免费但受限许可 |
§8.5 关键论文 Top-8
- Griffith M, et al., 2017, Nature Genetics 49(2):170-174. DOI 10.1038/ng.3774 — 提出 CIViC 框架：开放访问+众包策展+A-E 分级，系统评述现有资源封闭性。
- Krysiak K, et al., 2023, Nucleic Acids Research 51(D1):D1230-D1241. DOI 10.1093/nar/gkac979 — CIViCdb 2022：Molecular Profiles 模型、ClinGen 合作与 FAIR 化演进。
- VICC Meta-knowledgebase Task Team, 2020, Nucleic Acids Research. PMC7127986 — 六库协调：12,856 条解读的跨库 harmonize 与 A-E→Tier 映射表。
- Li MM, et al., 2017, Journal of Molecular Diagnostics 19(1):4-23. DOI 10.1016/j.jmoldx.2016.10.002 — AMP/ASCO/CAP 体细胞变异分类标准：CIViC Tier 映射的规范源头。
- Chakravarty D, et al., 2017, JCO Precision Oncology. DOI 10.1200/PO.17.00011 — OncoKB：与 CIViC 互补的临床分级知识库。
- Tamborero D, et al., 2018, Nature Communications. DOI 10.1038/s41467-018-03623-z — Cancer Genome Interpreter：CIViC 类开放证据的规模化应用范式。
- CIViC 演进论文（预印本）, 2021, bioRxiv. DOI 10.1101/2021.06.13.448171 — TSV/VCF 发布机制、CIViCpy、教育与培训实践。
- ESCAT 证据分级框架, PMID 30137196 — 欧洲肿瘤内科学会证据层级：CIViC 等级的第三方映射参照。
§8.6 社区活跃度
- 贡献者 419 位、修订 44,656 条（截至 2026-09-12），持续 nightly 发布超过六年。
- GitHub 仓库 griffithlab/civic-v2 维持活跃 issue 流：2026 年上半年仍有 UI 修复、ClinVar 自动提交、Advanced Search 等持续迭代。
- 定期 hackathon 与社区活动产出过 NDEx、WikiData、openCRAVAT 等第三方集成（bioRxiv 2021）。
- AI 政策与 MCP server 的发布（2026-04）表明项目在 LLM 时代保持工具链前沿。
- 教育渗透度可观：策展界面被用于本科与研究生课程实训，实习学员经 staging 服务器训练后参与正式策展，形成社区人才飞轮（bioRxiv 2021）。
- 原始论文 711+ 次引用（Google Scholar，截至 2026-09）且逐年攀升，学术影响力稳定增长。
§8.7 生态快照
| 资源 | 类型 | 链接 | 推荐理由 |
|---|---|---|---|
| civicdb.org | 官方主站 | https://civicdb.org | 浏览/检索/策展入口 |
| Data Releases | 官方下载 | https://civicdb.org/releases | nightly/monthly TSV+VCF |
| GraphQL API 文档 | 官方 API | https://griffithlab.github.io/civic-v2/ | 与前端同源的最全元数据通道 |
| griffithlab/civic-v2 | 官方代码 | https://github.com/griffithlab/civic-v2 | 平台源码（MIT） |
| CIViCpy | 官方 SDK | https://github.com/griffithlab/civicpy | Python 工程化首选 |
| 帮助文档 | 官方文档 | https://civicdb.org/pages/help | 字段与策展 SOP |
| 策展规范文档 | 官方文档 | https://civic.readthedocs.io | 变异命名规范（坑点 3 依据） |
| VICC | 联盟组织 | https://cancervariants.org | 跨库标准与 SOP |
§9 相关资源与引用
§9.1 官方资源清单
- 主站与检索：https://civicdb.org（含 2026-06 上线的 Advanced Search）
- 数据下载：https://civicdb.org/releases（TSV/VCF，nightly+monthly）
- API 文档：https://griffithlab.github.io/civic-v2/（GraphQL）
- Python SDK：https://github.com/griffithlab/civicpy（CIViCpy）
- 平台源码：https://github.com/griffithlab/civic-v2（MIT License）
- 帮助与 SOP：https://civicdb.org/pages/help；https://civic.readthedocs.io
- 策展 AI 政策：https://civicdb.org（2026-04 生效，Curation Help Chat 与 MCP server 说明）
- 联盟标准：https://cancervariants.org（VICC SOP）
- ClinVar 自动提交说明：见官方帮助文档（2026-04 起断言自动提交）
- 数据发布归档：monthly 快照在发布页长期保留，用于历史复现
§9.2 BibTeX 完整引用
@article{griffith2017civic,
author = {Griffith, Malachi and Spies, Nicholas C. and Krysiak, Kilannin and
McMichael, Joshua F. and Coffman, Adam C. and Danos, Arpad M. and
Ainscough, Benjamin J. and Ramirez, Cody A. and Rieke, Damian T. and
others},
title = {CIViC is a community knowledgebase for expert crowdsourcing the
clinical interpretation of variants in cancer},
journal = {Nature Genetics},
volume = {49},
number = {2},
pages = {170--174},
year = {2017},
doi = {10.1038/ng.3774}
}
@article{krysiak2023civicdb,
author = {Krysiak, Kilannin and others},
title = {CIViCdb 2022: evolution of an open-access cancer variant
interpretation knowledgebase},
journal = {Nucleic Acids Research},
volume = {51},
number = {D1},
pages = {D1230--D1241},
year = {2023},
doi = {10.1093/nar/gkac979}
}
@article{li2017standards,
author = {Li, Marilyn M. and Datto, Michael and Duncavage, Eric J. and
others},
title = {Standards and Guidelines for the Interpretation and Reporting of
Sequence Variants in Cancer: A Joint Consensus Recommendation of
the Association for Molecular Pathology, American Society of
Clinical Oncology, and College of American Pathologists},
journal = {Journal of Molecular Diagnostics},
volume = {19},
number = {1},
pages = {4--23},
year = {2017},
doi = {10.1016/j.jmoldx.2016.10.002}
}
§9.3 引用指南
使用 CIViC 内容（无论原始还是派生）时，请引用原始论文（griffith2017civic）；使用 2022 年后数据模型特性（Molecular Profiles 等）时建议同时引用更新论文（krysiak2023civicdb）；涉及变异分类层级时引用 AMP/ASCO/CAP 标准（li2017standards）。数据本身为 CC0，无署名义务，引用属学术礼仪与可复现性要求。
§9.4 使用前检查清单
- [ ] 已在报告中声明所用快照日期（TSV 文件名日期或 API 拉取时间）
- [ ] 已确认变异匹配策略（ID 优先，字符串匹配仅降级使用）
- [ ] 已按 VID/PMID 分组切分训练/测试集（§5.3）
- [ ] 已过滤或分层处理 variant_origin 与 evidence_type（坑点 6）
- [ ] 已排除 retracted/deprecated 状态记录（坑点 7）
- [ ] 已对少样本基因做分层评估（坑点 8）
- [ ] 输出层附证据等级、评分与 PMID 溯源，供人工复核
- [ ] 临床用途输出经分子病理委员会或同等专业机制审核
§10 AI 使用声明卡
§10.1 AI 模型列表
| 模型 | 用途 | 版本 |
|---|---|---|
| fast-model（CodeBuddy 内置 LLM） | 本页面正文撰写、代码示例起草 | 2026-09 可用版本 |
§10.2 AI 参与范围
AI 参与：初稿撰写、结构组织、代码示例起草、表格整理。人类参与：事实核查（全部数字与来源 URL 经 WebSearch 核实）、医学与工程审核（§0 所列交叉审核）、免责声明与合规审查。检索阶段共执行 5 次联网检索（2026-09-12/13），覆盖官方站点、论文与引用、下载与许可、证据分级映射、GitHub issues 坑点。
生成与审核的边界约定：AI 不得自行引入未经检索来源支撑的数字；所有规模、日期、引用数均须在 FACTS 事实清单（本目录 FACTS.md）中有对应条目方可入稿。代码示例虽经语法与逻辑走查，但在读者本地环境运行前仍建议先以小样本验证（§6.1 的最小可用子集设计即为此服务）。
§10.3 输入来源列表
- Griffith M, et al., 2017, Nature Genetics 49(2):170-174. DOI 10.1038/ng.3774
- Krysiak K, et al., 2023, Nucleic Acids Research 51(D1):D1230-D1241. DOI 10.1093/nar/gkac979
- VICC Meta-knowledgebase Task Team, 2020, Nucleic Acids Research. https://pmc.ncbi.nlm.nih.gov/articles/PMC7127986/
- CIViC 演进论文（预印本）, 2021, bioRxiv. DOI 10.1101/2021.06.13.448171
- CIViC 官方主站与首页统计（截至 2026-09-12）. https://civicdb.org
- CIViC Data Releases 口径说明. https://civicdb.org/releases
- CIViC API 文档. https://griffithlab.github.io/civic-v2/
- CIViC GitHub 仓库与 issues（#1179、#1274、#1399 等）. https://github.com/griffithlab/civic-v2
- Li MM, et al., 2017, Journal of Molecular Diagnostics 19(1):4-23. DOI 10.1016/j.jmoldx.2016.10.002
- 精准肿瘤平台综述, 2024, PMC39543667. https://pmc.ncbi.nlm.nih.gov/articles/pmid/39543667/
- 泛癌基因组-转录组研究（ESCAT 映射与假匹配案例）, 2022, medRxiv. https://www.medrxiv.org/content/10.1101/2022.11.08.22282064v1
- VIC 自动分级对照研究. https://tomesphere.com/paper/PMC6708137
- 体细胞变异分析临床指南（AMP/ASCO/CAP 框架背景）. https://www.goldenhelix.com/learn/somatic-variant-analysis
- CIViCpy SDK 文档. https://github.com/griffithlab/civicpy
§10.4 人工校验表
| 内容模块 | 审核者 | 审核方式 | 审核状态 |
|---|---|---|---|
| frontmatter 与 schema_org 元数据 | 千方病案医学编辑部 | 逐字段比对宪法模板与检索来源 | ✅ 已通过 |
| §1 概览与对比表 | 千方病案医学编辑部 | 数字回查原始检索记录 | ✅ 已通过 |
| §2 医学背景（ICD-11/SNOMED 映射） | 千方病案医学编辑部 | 医学术语交叉审核 | ✅ 已通过 |
| §3-§4 规格与数据字典 | 千方病案医学编辑部 | 对照官方 releases 口径说明 | ✅ 已通过 |
| §6 代码示例 | 千方病案医学编辑部 | 语法与逻辑走查（依赖 CIViCpy 官方接口） | ✅ 已通过 |
| §6.5 八个坑点 | 千方病案医学编辑部 | 逐条对照 GitHub issues 与论文原文 | ✅ 已通过 |
| §7 DAIMS 与偏倚分析 | 千方病案医学编辑部 | 双审核者独立打分后合议 | ✅ 已通过 |
| §8-§10 引用与声明 | 千方病案医学编辑部 | 全部 14 条来源逐条可访问性检查 | ✅ 已通过 |
§10.5 AI 生成章节标注
本页面全部章节由 AI 生成初稿；其中 §0 免责声明、§2.1/§2.1b 术语映射、§7.7 DAIMS 评分、§10.4 校验表经人工逐条修正与确认后定稿。
§10.6 最后人工审核日期
2026-09-05（与 §0 审核日期一致）
页面状态：published（全部内容已完成审核并发布）
§10.7 声明更新记录
| 日期 | 事项 |
|---|---|
| 2026-09-12/13 | 5 次联网检索完成，FACTS 事实清单定稿（14 组来源） |
| 2026-09-05 | 人工交叉审核完成，页面定稿发布 |
§C 机器可读元数据（JSON-LD）
相关数据集导航
以下为站内 AI-Ready 数据集百科中与本词条共享多个主题标签的相关数据集，按相关度降序排列：
- cosmic — 共享标签：基因组学与多组学 / 变异与注释 / 肿瘤学
- vdjdb — 共享标签：基因组学与多组学 / 变异与注释 / 肿瘤学
- gnomad — 共享标签：基因组学与多组学 / 变异与注释 / 肿瘤学
- clinvar — 共享标签：基因组学与多组学 / 变异与注释
- genomics-england-100k — 共享标签：基因组学与多组学 / 肿瘤学
- cptac — 共享标签：基因组学与多组学 / 肿瘤学
- target — 共享标签：基因组学与多组学 / 肿瘤学
- aacr-genie — 共享标签：基因组学与多组学 / 肿瘤学
- iedb — 共享标签：基因组学与多组学 / 肿瘤学
- dbsnp — 共享标签：基因组学与多组学 / 变异与注释
导航说明：本章节由全站统一标签体系自动计算生成（标签重合度算法），双向可达；点击链接可跳转至对应数据集词条。
