信息速览

数据集名称BV-BRC — 一千七百万个病原基因组，九成是病毒

数据类型17,061,503 个基因组,8,955,936,565 条基因组特征,869,000,661 条专项基因,17,634,751 条 AMR 记录,免注册 API,FTPS 分发,持续更新

规模不适用（病原基因组库，无个体患者记录；含 2,237,561 条监测样本与 148,106 条血清学结果，但不含可识别个人身份的信息）

接入方式BV-BRC（Bacterial and Viral Bioinformatics Resource Center，University of Chicago） url: https://www.bv-brc.org/

AI 就绪度

BV-BRC — 一千七百万个病原基因组，九成是病毒 AI-Ready Wikipedia

INFOBOX

字段	内容
数据集名称	BV-BRC（Bacterial and Viral Bioinformatics Resource Center）
英文全称	Bacterial and Viral Bioinformatics Resource Center — a resource combining PATRIC, IRD and ViPR
别名/简称	BV-BRC、bv-brc.org、PATRIC 后继者、IRD/ViPR 后继者
疾病分类	不适用（跨病原体；覆盖 24 个细菌属的重点病原 + 20 个病毒科，含流感、SARS-CoV-2、结核、埃博拉、寨卡等）
SNOMED CT	不适用；无疾病本体索引，病原体用 NCBI Taxonomy（2,730,056 个分类单元）
数据模态	基因组组装与注释特征、核苷酸/蛋白序列、AMR 表型（实验+预测）、专项基因（六类）、通路与子系统、蛋白结构映射、蛋白互作、表位与表位实验、血清学、监测样本、SARS-CoV-2 刺突变异月度统计
AI 任务类型	抗性基因型→表型预测、病毒谱系分类与谱系增长率估计、核心基因组 MLST 分型、表位免疫原性预测、毒力因子识别、泛基因组构建、宏基因组物种分类
样本总数	17,061,503 个基因组（病毒 15,634,461 / 细菌 1,382,093 / 古菌 37,454 / 真核 9）；8,955,936,565 条注释特征；869,000,661 条专项基因；17,634,751 条 AMR 记录
数据大小	API 分页返回，无单文件总包；FTPS 按基因组分目录，单基因组含 9 类文件
数据格式	JSON（API）、FASTA（`.fna`/`.faa`/`.ffn`/`.frn`）、GFF、Tab 分隔（`.features.tab`/`.pathway.tab`/`.spgene.tab`/`.subsystem.tab`）
许可证	站点未显式声明数据许可；NIH/NIAID 资助（U24AI183849），按 BRC 惯例公开可用，商用建议直接联系团队
访问级别	开放（public 数据免注册免凭证；私有工作区需账号）；FTPS 强制加密，明文 FTP 已停用
DUO 标签	官方未发布 DUO 标注；公开数据部分等效 GRU（一般研究用途），含人体相关字段需注意
语言	英文（全部字段、文档、API 描述）
首发日期	2019 年（PATRIC + IRD + ViPR 三家合并）；PATRIC 本身始于 2004 年 NIAID BRC 项目
最后更新	持续更新；站点版本 3.59.14，API 版本 1.9.3（2026-10-22 实测）
发布机构	University of Chicago（牵头）/ JCVI / University of Virginia / Fellowship for Interpretation of Genomes
官方主页	bv-brc.org
下载地址	API: bv-brc.org/api/doc/；FTPS: `ftps://ftp.bv-brc.org/`
DOI	数据集级无 DOI；引用论文 doi:10.1093/nar/gkac1003（NAR 2023, PMID 36350631）
引用次数	主引用论文被引 1,206 次（Google Scholar，2026-10 查询）；官方页面自报累计引用 29,340
AI 就绪度评分	⭐⭐⭐⭐（4/5）— 有真 API、31 个数据类型、字段文档齐全、免注册；扣分项：AMR 九成是预测值、CheckM 只覆盖 8.2%、元数据填充率参差、无显式数据许可
页面状态	published

§0 E-E-A-T 信任声明与免责声明

医学审核者：千方病案医学编辑部（感染病与临床微生物方向）交叉审核：§2 病原基因组与耐药表型的临床前提、§7 偏倚与伦理分析。
数据工程审核者：千方病案医学编辑部医疗 AI 数据工程师，审核范围：§4 字段字典、§5 泄漏分析、§6 解析 Pipeline 与 8 个坑点。
审核日期：2026-10-22

医学免责声明：本页面内容仅供研究与教育使用，不构成医疗建议、诊断或治疗方案。BV-BRC 的 AMR 表型中九成以上是算法预测值（§4.4 有精确定量），不能用于临床用药决策。任何用于患者的耐药判断，必须来自经认证实验室的药敏试验（AST）。

技术免责声明：本页面的全部规模数字取自 2026-10-22 至 10-23 对 BV-BRC 官方 API 的实时计数（读取 Content-Range 响应头）。BV-BRC 是持续更新的库，没有版本快照，因此这些数字在你阅读时已经变化——变化速度约为每日数千至数万条基因组。文档站里"as of July 2024"之类的数字与本条目数字必然不一致，原因见 §7.7。

数据使用合规：BV-BRC 没有像 MGI 那样写明 CC BY 4.0。站点只有 © Copyright 2023 | The BV-BRC Team. 与一份隐私政策，没有开放数据许可声明。本条目据此如实写为"许可未显式声明"，而不是替它编一个 CC 许可。它的资助方是 NIH/NIAID（Grant U24AI183849），按 BRC 项目惯例数据应当公开可用；但要商用，请联系团队确认，这是唯一负责任的做法。

§1 数据集概览

§1.0 📌 30 秒速览

这是什么？ 2019 年，NIAID 把三件事焊成了一件事：PATRIC（细菌）、IRD（流感）、ViPR（病毒病原）。焊点是一个统一的数据模型——基因组、特征、序列、专项基因、通路、表位、血清学、监测，全部挂到同一套 genome_id 上。焊完之后的产物就是 BV-BRC。它的定位不是"又一个基因组库"，而是传染病研究的一站式工作台：查数据、跑 BLAST、建进化树、做基因组组装与注释、比对蛋白结构、训练耐药预测模型，都在同一个站点、同一套 ID 体系里。

规模有多大？ 17,061,503 个基因组——但请立刻记住这个分解：病毒 15,634,461（91.6%），细菌 1,382,093（8.1%），古菌 37,454，真核 9。注释特征是 8,955,936,565 条（89.6 亿），专项基因 869,000,661 条（8.69 亿），AMR 记录 17,634,751 条。这个形状不是生物学决定的，是新冠疫情决定的——详见 §2.4。

我能用它做什么？ 三类真实用途：① 训练耐药预测模型——但只能用那 1,285,111 条实验室测定记录（7.3%），剩下 16,300,395 条是 AdaBoost 预测值，拿它当标签等于拿模型输出训练模型（§5.2 会把这个坑讲透）；② 病毒谱系与暴发追踪——spike_lineage（114,478 条）与 spike_variant（670,741 条）是现成的月度增长率与流行率序列；③ 构建病原知识图谱——六类专项基因（抗性/毒力/药靶/人同源/转运/必需）已经由 BLASTP 统一注释到全部细菌基因组上，这份"统一口径"本身就是稀缺资产。

§1.1 技术摘要

BV-BRC 的技术骨架可以概括成三句话：一套统一数据模型、三条注释管线、两个访问通道。

一套统一数据模型。 31 个数据类型（/api/doc/ 列举），全部以 JSON 暴露。核心枢纽是 genome（基因组），所有其它表——genome_feature（特征）、genome_sequence（序列）、genome_amr（耐药）、sp_gene（专项基因）、subsystem（子系统）、pathway（通路）——都通过 genome_id 挂回来。这种"星形"结构使得任意两张表可以 join，代价是所有查询都要过一遍 genome 这张 1,706 万行的表。

三条注释管线。 细菌与古菌走 RASTtk（SEED 子系统投影 + Prodigal/Glimmer 基因调用 + tRNAscan-SE + PhiSpy 原噬菌体 + PubMLST 分型）；病毒走 VIGOR4，但只覆盖十类病毒（流感 A/B/C、SARS-CoV-2、西尼罗、寨卡、基孔肯雅、东方马脑炎、RSV、轮状、肠道病毒、拉沙）——官方原文：“For other viruses, the original GenBank annotations are propagated.” 噬菌体走 PHANOTATE。这三条管线是 BV-BRC 最值钱的部分，也是最容易被误解的部分："BV-BRC 重注释了所有基因组"这句话，对病毒侧绝大部分是假的。

两个访问通道。 ① HTTP API（/api/{data_type}/，版本 1.9.3），免注册，支持 RQL 与 Solr 两种查询语言，支持 limit / cursor 分页，总数通过 Content-Range: items 0-1/<total> 响应头给出——这是本条目全部规模数字的来源；② FTPS（ftp.bv-brc.org），已强制加密，明文 ftp:// 停用，按基因组 ID 分目录，每个基因组 9 类文件。

§1.2 战略价值

维度一：它把"三个互不相通的病原库"变成了一个 ID 空间。 在 2019 年之前，做流感的人用 IRD，做结核的人用 PATRIC，做埃博拉的人用 ViPR，三套 ID、三套注释、三套查询语法。合并的直接收益不是数据变多，而是同一套 genome_id 可以横跨细菌与病毒做联合分析。这种"横向打通"的价值在新冠病毒出现后被放大到极致：SARS-CoV-2 的基因组、它的刺突变异、它的血清学反应、它的监测样本，第一次落在同一个数据库里。

维度二：六类专项基因的"统一口径"是稀缺资产。 抗性、毒力、药靶、人同源、转运、必需基因——这六类注释在别的地方也有，但分散在 CARD、VFDB、DrugBank、TCDB 等十几个专库里，各自只覆盖自己关心的物种。BV-BRC 做的事是：用 BLASTP 把这十几个库的参考蛋白统一投射到全部 138 万个细菌基因组上。结果是 869,000,661 条"特征 × 属性"赋值。这份数据的好处是口径一致、可以直接做跨物种比较；坏处是所有赋值都是同源投射，不是实验验证（§7.1 会说明这意味着什么）。

维度三：它有一份完整的"基因型 → 表型"配对，量级在百万级。 这是做监督学习的人最想要的形状：输入是基因组序列，输出是"这个菌对这个药是敏感还是耐药"。BV-BRC 的 genome_amr 表就是这个形状，而且它明确区分了证据来源（evidence 字段有 Laboratory Method 与 Computational Method 两个值）。绝大多数论文在报告耐药预测准确率时，都没有说清楚自己用的是哪一部分——本条目 §5.2 会把这件事拆到底。

§1.3 同类资源横向对比

资源	定位	规模	与 BV-BRC 的关系
NCBI GenBank / RefSeq	原始序列存档	全物种，规模最大	BV-BRC 的上游。BV-BRC 的基因组从这里进，重注释后加值
Ensembl Bacteria	细菌基因组浏览	数万至数十万	侧重比较基因组学，不做耐药表型
PATRIC（已并入）	细菌 BRC	—	BV-BRC 的细菌侧前身，2020 年最后一篇独立论文后并入
IRD / ViPR（已并入）	流感 / 病毒 BRC	—	BV-BRC 的病毒侧前身
VEuPathDB	真核病原体与媒介	十余个物种	同属 NIAID BRC 项目的姊妹库，互补不重叠
CARD	耐药基因参照库	数千基因	BV-BRC 专项基因的上游来源之一（另有 NDARO、ARDB）
VFDB	毒力因子参照库	数千基因	同上（另有 Victors、PATRIC_VF）
GISAID	病毒序列共享	千万级	需注册与数据使用协议；BV-BRC 是开放的替代，但病毒覆盖广度不如
IMPC / MGI	小鼠功能	单物种	完全不同的物种维度，无重叠
本条目之外	—	—	站内已收录的 `ncbi-virus` 类条目与 BV-BRC 病毒侧有部分重叠，但 BV-BRC 多了统一重注释与专项基因投射

选型建议：要"原始序列、最大广度"→ GenBank；要"统一注释、可比较、带耐药表型"→ BV-BRC；要"真核病原体"→ VEuPathDB；要"最新病毒序列、最快更新"→ GISAID（但需接受其条款）。BV-BRC 的独特位置是"已加工的、跨界的、免注册的"这三件事的交集。

§1.4 版本时间轴

时间	事件
2004	NIAID 设立 BRC 项目，PATRIC 是最早一批
2008	RAST 服务器发表（BMC Genomics 9:75）
2012	NMPDR 并入 PATRIC，带入 SEED 与 RAST
2015	RASTtk 发表（Sci Rep 5:8365）
2016	PATRIC/RAST 耐药预测论文（Sci Rep 6:27930）
2019	BV-BRC 成立：PATRIC + IRD + ViPR 三家合并
2020	PATRIC 最后一篇独立 NAR 论文（D606-D612）
2023-01-06	BV-BRC 主引用论文（NAR 51:D678-D689）
2026-10-22	站点版本 3.59.14，API 版本 1.9.3（本条目实测）

§1.5 典型应用场景

场景一：耐药预测模型的训练与诚实评估。 正确做法是只取 genome_amr 中 evidence = Laboratory Method 的 1,285,111 条，按基因组而不是按行划分训练/测试集（同一菌株的多条药物记录必须同侧），并且按 testing_standard（CLSI / EUCAST）分层报告。详见 §5.2 与 §6.3。

场景二：病毒谱系增长监测。 spike_lineage 表给出每个 Pango 谱系逐月的 prevalence 与 growth_rate，spike_variant 给出刺突变异的月度全球统计。这两个表是"现成的时序面板"，不需要自己从序列重算。

场景三：跨物种毒力因子比较。 sp_gene 里 property = Virulence Factor 的记录（约 1.87 亿条）已经用统一 BLASTP 投射到全部细菌基因组，可以直接做"哪些毒力因子在哪些属里普遍存在"的矩阵分析。

场景四：表位与血清学的联合分析。 epitope（301,723 条）+ epitope_assay（1,033,903 条）+ serology（148,106 条）三张表可以拼出"某个表位在哪些宿主、用哪种实验、得到什么滴度"的完整链路，这是疫苗设计的常用起点。

§2 病原基因组学与耐药的生物学前提

§2.1 覆盖范围：24 个细菌属 + 20 个病毒科

BV-BRC 首页的导航栏本身就是一份覆盖清单，而且它是人工选定的重点病原，不是"全部细菌"：

细菌侧（24 个重点属）：Acinetobacter、Francisella、Bacillus、Helicobacter、Bartonella、Listeria、Borreliella、Mycobacterium、Brucella、Pseudomonas、Burkholderia、Rickettsia、Campylobacter、Salmonella、Chlamydia、Shigella、Clostridium、Staphylococcus、Coxiella、Streptococcus、Ehrlichia、Vibrio、Escherichia、Yersinia。另有 “All Bacteria” / “All Archaea” 入口，覆盖全部 138 万细菌与 3.7 万古菌。

病毒侧（20 个病毒科）：Adenoviridae、Orthomyxoviridae、Asfarviridae、Paramyxoviridae、Bunyaviricetes、Parvoviridae、Caliciviridae、Picornaviridae、Coronaviridae、Pneumoviridae、Filoviridae、Polyomaviridae、Flaviviridae、Poxviridae、Hepadnaviridae、Reovirales、Hepeviridae、Rhabdoviridae、Herpesvirales、Togaviridae。另有 “Featured Viruses”：Bacteriophages、Lassa、Dengue、Measles、Ebola、Monkeypox、Enteroviruses、SARS-CoV-2、Hepatitis C、Zika、Influenza A。

这份清单的读法：24 个细菌属对应的是"生物防御 + 公共卫生 + 抗生素耐药"三个议程的交集（炭疽、鼠疫、兔热病、结核、霍乱、伤寒、MRSA……），20 个病毒科对应的是"高致病性 + 大流行潜力"。这不是一份"微生物学大全"，是一份威胁清单。理解这一点，才能理解为什么古菌只有 37,454 条、真核只有 9 条——它们不在这份威胁清单上。

§2.2 为什么耐药表型如此重要，以及它有多难

抗微生物药物耐药（AMR）是这份数据库最被高频使用的部分，原因很直接：如果能在测序后几小时内从基因组预测出耐药谱，就不必等 48-72 小时的培养药敏。这对败血症这类"每小时死亡率都在上升"的场景是决定性的。

但这件事在生物学上有三道坎，BV-BRC 的数据形状正是这三道坎的直接投影：

坎一：耐药机制是异质的。 有的是单基因（如 mecA 导致甲氧西林耐药），有的是多位点累积（如结核的耐药需要逐步积累 rpoB、katG、inhA 等突变），有的是外排泵上调（调控区突变，不在编码区），有的是质粒水平转移（同样的基因在不同菌里表型不同）。这意味着一个统一的分类器无法覆盖所有机制。

坎二：表型本身是连续量被离散化的结果。 真实的药敏是 MIC（最小抑菌浓度，单位 mg/L），折点（breakpoint）由 CLSI 或 EUCAST 定义。同一个 MIC 值在 CLSI 下可能判"耐药"、在 EUCAST 下判"敏感"。BV-BRC 的 genome_amr 表同时保存了 measurement_value（原始 MIC）和 resistant_phenotype（判定结果），并且有 testing_standard 字段记录用的是哪套折点——这是它做得对的地方，但也是最容易被使用者忽略的地方（§6.5 坑点 4）。

坎三：阴性样本的定义是模糊的。 “敏感"可以意味着"确实没有耐药机制”，也可以意味着"有耐药机制但没表达"。前者可以用序列预测，后者不能。"没测过"和"测了是敏感"在数据里必须分开——BV-BRC 用 resistant_phenotype 是否有值来区分，Nonsusceptible 单独作为一个类别（2,867 条），这个细节说明策展方意识到了问题。

§2.3 从"基因"到"表型"：BV-BRC 是怎么做的

BV-BRC 的做法分两层，两层必须分开看：

第一层：同源投射（不走模型）。 把所有 CDS 的蛋白序列用 BLAT + BLASTP 比对到参照库——CARD、NDARO、ARDB、DrugBank、TTD、TCDB、VFDB、Victors、RefSeq 人类蛋白。命中即赋值。这一层的结果落在 sp_gene 表，共 869,000,661 条。它是"这个基因像某个已知的耐药基因"，不是"这个菌耐药"。

第二层：AdaBoost 分类器（走模型）。 官方基因组注释协议原文：“Antimicrobial resistance is projected for a select group of genera based on a Adaboost machine learning”。这一层的结果落在 genome_amr 表，evidence = Computational Method，共 16,300,395 条，每条的 computational_method_performance 字段里还附带该模型的 Accuracy / F1 / AUC。

两层的关系是本条目最重要的一条工程判断：第一层是特征，第二层是预测。做监督学习时，第一层的输出可以作为输入特征，但第二层的输出绝对不能当标签。而 BV-BRC 把两者放在同一张 genome_amr 表里，只靠 evidence 一个字段区分——如果你不读这个字段，你的"真实标签"里有 92.4% 是别人的模型输出。§5.2 会把这件事量化。

§2.4 数据来源人群：谁在提交，为什么形状是这样

BV-BRC 的"人群"是测序项目，不是人。理解它的形状，必须理解测序的驱动力：

驱动力	后果
COVID-19 大流行（2020-2023）	SARS-CoV-2 基因组海量提交，直接造成病毒侧 15,634,461 条、其中 10,282,177 条标 Complete
公共卫生监测网络（ PulseNet、Genomic Epidemiology 等）	沙门、大肠、李斯特等食源性病原积累大量近缘分离株
NIAID 测序中心	生物防御清单上的病原（炭疽、鼠疫、兔热）有专门投入
文献策展	官方明写：“PATRIC searches literature for large published AMR studies and assembles corresponding genomes using the reads available in the SRA database”
单个课题组提交	零散、元数据质量最参差

这个形状的直接后果（用实测数字说明）：

病毒占 91.6%，但这不代表病毒比细菌重要，只代表病毒测序便宜、疫情驱动强。
细菌侧 Partial 状态为 0，病毒侧 Partial 有 4,448,787 条——同一个字段名在两个域下的语义不同（§4.1）。
细菌样本里 isolation_source 填充率 43.7%，且高频值是 mouse gut metagenome（249/2,000）、fecal sample（186）、human gut（98）——肠道宏基因组显著过采样，环境与农业病原被低估。
细菌样本里 host_name 前三名是 Homo sapiens（253）、Mouse（249）、Human, Homo sapiens（147）——注意后两个其实是同一个东西的两种写法，这是 §6.5 坑点 6 的原始证据。

§2.5 为什么"命名"在这里也是核心价值

病原体数据的命名混乱程度远超一般数据集，BV-BRC 在这件事上做了实体归一化，但只做到了七成：

物种层：用 NCBI Taxonomy 的 taxon_id 做主键，taxon_lineage_ids 与 taxon_lineage_names 给出完整谱系（Viruses > Duplodnaviria > Heunggongvirae > Uroviricota > Caudoviricetes > ...）。这一层是干净的。
菌株层：genome_name 是自由文本，形如 Escherichia coli str. K-12 substr. MG1655 或 Klebsiella pneumoniae strain VRCO0337——“str.” / “strain” / 无前缀三种写法并存。
宿主层：host_name 与 host_scientific_name 双字段，但 host_name 里混着俗名（Mouse）、学名（Homo sapiens）、组合写法（Human, Homo sapiens）。
药物层：antibiotic 是小写自由文本，样本 4,000 条里出现 115 种拼法，trimethoprim/sulfamethoxazole 这类复方还带斜杠。
折点标准：testing_standard 里 CLSI 与 clsi 并存（1,401 vs 157）——同一标准的两种大小写。

这一节的实用结论：BV-BRC 给了你 70% 的归一化，剩下 30% 必须自己做。这 30% 恰恰是最容易在建模时被忽略、然后在特征工程阶段悄悄毁掉结果的部分。

§2.6 质量标准的边界：BV-BRC 保证什么、不保证什么

它保证	它不保证
所有 public 细菌/古菌基因组用同一套 RASTtk 注释	病毒侧注释口径统一（只有十类走 VIGOR4，其余沿用 GenBank）
每条 AMR 记录标注了证据来源（实验 / 计算）	实验证据的折点标准一致（CLSI / EUCAST / AGSP / WHO-TB 混用）
每个基因组有唯一 `genome_id` 且跨版本稳定	`genome_id` 永久有效（实测 `201969.4`、`83333.1` 已查不到）
元数据来自 GenBank / BioProject / BioSample + 人工策展	元数据字段填充率一致（`sequencing_depth` 仅 5.5%）
六类专项基因用统一 BLASTP 投射	专项基因是实验验证的（全部为同源投射）
CheckM 完整度/污染度以标准工具计算	每个基因组都有 CheckM 值（只有 8.2%，且病毒侧为 0）

§3 数据库规格与通道抉择

§3.0 三条通道，各有各的坑

通道	用途	优点	坑
HTTP API（`/api/{type}/`）	查询、计数、按条件抽样	免注册、31 个类型、总数直接给在响应头	`eq` 带空格值恒返回 0；`select` 不能是唯一子句；GET/POST 行为不一致
FTPS（`ftp.bv-brc.org`）	批量下载序列与注释文件	按基因组分目录，结构清晰	明文 FTP 已停用，老脚本全部失效；主机名 `ftp.bv-brc.org` 与 `ftp.bvbrc.org` 两种写法并存
CLI（`p3-*`）	脚本化工作流	可组合、可批量	需 pip 安装；本质是 API 的封装，API 的坑它全继承

选型建议：只要计数或采样，用 API；要全部序列，用 FTPS；要可复现的批量流程，用 CLI 但必须自己加重试与校验。不要试图用 API 下载全库序列——那会是 1,706 万次请求。

§3.1 31 个数据类型的地图

按 /api/doc/ 的官方列举，加本条目实测的记录数：

类型	记录数	类别
`genome_feature`	8,955,936,565	核心：注释特征
`feature_sequence`	4,625,634,543	核心：特征序列（MD5 去重）
`subsystem`	1,926,780,679	核心：SEED 子系统赋值
`pathway`	1,842,961,207	核心：通路赋值
`sp_gene`	869,000,661	核心：专项基因
`genome_sequence`	287,001,098	核心：复制子序列
`ppi`	55,600,858	互作
`protein_structure`	32,167,507	结构（PDB 映射）
`genome_amr`	17,634,751	表型（重点）
`taxonomy`	2,730,056	参照
`sequence_feature_vt`	2,264,514	变异型
`surveillance`	2,237,561	监测
`epitope_assay`	1,033,903	免疫
`spike_variant`	670,741	SARS-CoV-2
`epitope`	301,723	免疫
`serology`	148,106	血清学
`spike_lineage`	114,478	SARS-CoV-2
`misc_niaid_sgc`	10,784	结构基因组中心靶标
`bioset`	6,632	表达
`experiment`	920	表达
`antibiotics`	97	参照（小但关键）
`structured_assertion`	0	已定义、当前为空
`genome`	17,061,503	核心：基因组
`strain` / `genome_typing` / `genome_amr` 等其余	按需	—

注意 structured_assertion 为 0。数据字典里描述它是"机器可读的断言，如’该基因导致环丙沙星耐药’，带证据码与引用"——听起来正是做知识图谱最想要的表，但它现在是空的。这是一条必须写进数据集卡片的负面事实：“承诺的能力尚未填充”。

§3.2 下载预算与实测吞吐

本站沙箱实测（2026-10-22，单连接）：

操作	实测	含义
单次 API 查询（`limit(1)`，只取头）	0.6-1.5 秒	计数查询可以高频，但建议间隔 ≥0.4 秒
单次 API 查询（`limit(3000)` 全字段）	8-20 秒，响应 3-5 MB	这是抽样的实际粒度上限
`limit(4000)`（`genome_amr` 实验子集）	约 12 秒	更大的 `limit` 会超时
FTPS 单基因组目录	9 个文件，数 MB	按需取，不要整库镜像

预算结论：如果只是"抽样分析 + 统计形状"，20-40 次 API 请求足够，总耗时在 2 分钟内。如果要全库统计，不要自己拉——用 Content-Range 做条件计数，把聚合下推到服务端，这比拉数据快三个数量级。

§3.3 版本机制：持续更新，没有快照

BV-BRC 与 MGI、IPD 不同，没有可引用的版本快照。站点版本号（3.59.14）是软件版本，不是数据版本。这带来三个实际后果：

今日数字明日失效。本条目写的 17,061,503 在写作时是准确的，但它是流动的。
论文里的"BV-BRC 数据"无法复现，除非同时记录采集日期与查询语句。本条目 §9.3 给出的脚本会自动记录时间戳，就是为了这件事。
训练集/测试集划分必须钉在某个导出文件上，不能"下次再从库里拉一遍"。正确做法是一次性导出带 MD5 的快照（§6.4）。

§3.4 技术栈与溯源链

层	实现	可验证性
上游数据	NCBI GenBank / RefSeq、SRA、BioProject、BioSample、PDB、GEO	有 accession 可回溯
注释	RASTtk（细菌/古菌）、VIGOR4（十类病毒）、PHANOTATE（噬菌体）	源码全在 GitHub：`SEEDtk/RASTtk`、`JCVenterInstitute/VIGOR4`、`deprekate/PHANOTATE`
数据入库脚本	`github.com/BV-BRC/bvbrc_data`（Perl）	官方文档逐项给出脚本路径，如 `getGenomesGenbank.pl`、`rast2solr.pl`、`specialtyGenes.pl`、`uploadPPI.pl`
服务层	HTTP API 1.9.3 + Solr 后端	报错信息里直接暴露 `org.apache.solr` 类名
前端	站点 3.59.14	页面右上角渲染

这一层是本条目评分给到 4/5 的主要理由：从原始数据到入库脚本到注释工具，全链路开源可审计。在生物数据库里这是少数派。

§4 记录结构与字段字典

§4.1 四类核心对象与它们的关系

BV-BRC 的对象模型是星形，中心是 genome：

                    ┌─ genome_feature（89.6 亿）
                    ├─ genome_sequence（2.87 亿）
   genome ──────────┼─ genome_amr（1,763 万）
   （1,706 万）      ├─ sp_gene（8.69 亿）
                    ├─ subsystem（19.3 亿）
                    └─ pathway（18.4 亿）

四类核心对象必须分清：

genome（基因组）= 一次组装。主键 genome_id，格式 taxon_id.version（如 511145.12）。同一个物种可以有几百个 genome_id——每个测序分离株一个。
genome_feature（特征）= 一个注释单元。CDS、rRNA、tRNA、重复区、CRISPR。主键 feature_id，形如 RefSeq.166.48.WRNC01000073.source.1.6870.fwd 或 PATRIC.637909.5.NC_013798.CDS.1879462.1880271.rev。注意前缀 RefSeq. 与 PATRIC. 是两套注释来源。
sp_gene（专项基因）= 一个"特征 × 属性"赋值。同一个 feature_id 可以同时是"抗性基因"和"转运体"，就会有两条记录。
genome_amr（耐药记录）= 一个"基因组 × 药物"表型。注意粒度在 genome 层，不在 feature 层——这点非常重要：表型是菌株级的，基因型是特征级的，两者之间是多对多。

这是本条目第一个必须记住的结构事实：genome_amr 的粒度是 (菌株, 药)，sp_gene 的粒度是 (菌株, 特征, 属性)。做"从基因型预测表型"时必须先聚合到菌株级（把该菌所有抗性基因聚成一个集合），否则会产生一个菌株对应几十行、每行只有部分基因的畸形训练样本。

§4.2 genome 表：114 个字段里真正有用的 20 个

实测全库 genome 记录含 114 个字段（含 _version_）。下面只列与本条目论证相关、且填充率可核的部分：

字段	类型	全库填充率	用途	陷阱
`genome_id`	string	100%	主键，`taxon.version`	不是永久有效（实测有查不到的 ID）
`genome_name`	string	100%	显示名	自由文本，`str.`/`strain`/无前缀混用
`superkingdom`	string	100%	界	只有 4 个值，但分布极偏（病毒 91.6%）
`taxon_id`	int	100%	NCBI 分类号	—
`genome_status`	string	~99.9%	组装状态	`Partial` 为病毒独有；`Contig` / `HighQuality` 等值不存在
`genome_quality`	string	62.6%	Good / Poor	只有两个值；另 37.4% 无此字段
`genome_length`	int	100%	总长（bp）	—
`cds`	int	100%	CDS 数	与 `patric_cds` / `refseq_cds` 不同源，可能不等
`contigs`	int	100%	contig 数	细菌样本中位 70，碎片化严重
`checkm_completeness`	float	8.2%	CheckM 完整度	病毒侧 100% 为空，不能跨域平均
`checkm_contamination`	float	8.2%	CheckM 污染度	同上
`hypothetical_cds_ratio`	float	100%	无功能注释 CDS 占比	细菌样本中位 0.47
`coarse_consistency`	float	100%	注释一致性（0-100）	官方定义模糊，只说"大规模注释一致性指标"
`fine_consistency`	float	100%	注释一致性（细粒度）	同上
`isolation_source`	string	43.7%	分离来源	自由文本，`feces`/`Faeces`/`fecal sample` 并存
`host_name`	string	92.6%	宿主	俗名/学名/组合混用
`collection_year`	int	88.4%	采集年	小样本内 99.9% 为空，全库与小样本行为不一致
`geographic_location`	string	91.8%	地理位置	国家/地区/自由文本混用
`sequencing_depth`	float	5.5%	测序深度	极稀疏
`assembly_accession`	string	6.1%	NCBI 组装号	极稀疏，追溯困难
`antimicrobial_resistance`	array	1.1%	耐药汇总	数组，形如 `["Susceptible","Resistant"]`

§4.3 组装状态的语义分歧

这是 BV-BRC 最容易被误读的一组数字。genome_status 分域统计：

状态	全库	病毒	细菌
Complete	10,355,240	10,282,177	71,364
WGS	1,459,565	189,330	1,228,206
Partial	4,448,791	4,448,787	0
Plasmid	15,692	—	—
Deprecated	769,008	702,579	65,412

三个必须指出的现象：

① Complete 的定义在病毒与细菌之间完全不同。 病毒基因组只有几千到几十万 bp，一条序列就能"完整"；细菌基因组通常 2-7 Mb，要拼成一条完整染色体需要大量测序与人工完成（finishing）。所以病毒侧 10,282,177 条 Complete 与细菌侧 71,364 条 Complete 是两件不同的事。全库"Complete 占 60.7%"这个数字，说的主要是病毒。

② Partial 是病毒独有的状态，细菌侧为 0。原因是病毒常按节段（segments）提交，单个节段标 Partial。这意味着跨域的"完整度"统计必然失真。

③ Deprecated 有 769,008 条，占 4.5%。这些是已废弃但仍在库里的记录。任何查询默认都包含它们——必须显式加 ne(genome_status,Deprecated) 才能排除。这是 §5.2 的第一个泄漏点。

§4.4 genome_amr 表：全文最重要的一张表

genome_amr 共 17,634,751 行。字段分两组，按 evidence 互斥：

公共字段：id / genome_id / genome_name / taxon_id / antibiotic / resistant_phenotype / evidence / public / date_inserted / date_modified / _version_

仅 Computational Method 有：computational_method（值恒为 AdaBoost Classifier）、computational_method_performance（形如 Accuracy:0.931, F1 score:0.935, AUC:0.950）

仅 Laboratory Method 有：laboratory_typing_method、measurement、measurement_sign、measurement_value、measurement_unit、testing_standard、testing_standard_year、pmid

证据分层（全库精确计数）：

`evidence`	行数	占比
`Computational Method`	16,300,395	92.4%
`Laboratory Method`	1,285,111	7.3%

表型分层（全库精确计数）：

`resistant_phenotype`	行数
Susceptible	6,427,758
Resistant	2,519,345
Intermediate	19,832
Nonsusceptible	2,867

实验子集的技术细节（n=4,000 样本）：

字段	分布
`laboratory_typing_method`	Broth dilution 1,889 / Disk diffusion 678 / Agar dilution 598 / 空 593 / MIC 242
`measurement_unit`	空 2,631 / mg/L 1,310 / mm 59
`testing_standard`	空 1,410 / CLSI 1,401 / EUCAST 647 / clsi 157 / AGSP 74 / WHO-TB 58
`pmid` 填充	80.0%
不同 `antibiotic` 拼法	115

这四条硬事实合起来说明一件事：即使只取那 7.3% 的实验数据，它仍然不是"干净的监督学习数据集"——4,000 条里 593 条没说用什么方法、2,631 条没有单位、1,410 条没说用哪套折点、20% 没有文献出处。真正可用于严格建模的子集，规模要再打一个对折。这是本条目给出的最重要的一条实践判断。

§4.5 sp_gene 表：六类专项基因

sp_gene 共 869,000,661 行。property 六类，property_source 记录具体来源库：

`property`	近似计数	来源库（`property_source` 实测值）
Transporter	381,194,357	`Transporter: TCDB`
Virulence Factor	186,757,605	`Virulence Factor: Victors` / `: VFDB` / `: PATRIC_VF`
Drug Target	111,371,755	`Drug Target: DrugBank` / `: TTD`
Antibiotic Resistance	96,045,608	`Antibiotic Resistance: CARD` / `: NDARO` / `: ARDB` / `: PATRIC`
Human Homolog	4,159,176	NCBI RefSeq 参考人类基因组
Essential Gene	1,620,793	BV-BRC 代谢模型 + FBA

⚠️ 计数方法必须声明：eq(property,Antibiotic Resistance) 这类带空格的等值查询在该 API 上恒返回 0——%20、+、POST body、in() 四种编码全部试过。上表用 and(keyword(A),keyword(B)) 近似，已验证命中记录的 property 确为目标值，但理论上是文本搜索而非精确等值，末位数字不可信。这是本轮实测发现的一个真实 API 缺陷（§6.5 坑点 2）。

一条记录长什么样（真实样本）：

{
  "feature_id": "PATRIC.637909.5.NC_013798.CDS.1879462.1880271.rev",
  "genome_id": "637909.5",
  "genome_name": "Streptococcus gallolyticus UCN34",
  "patric_id": "fig|637909.5.peg.1797",
  "refseq_locus_tag": "GALLO_1807",
  "gene": "racE",
  "product": "Glutamate racemase (EC 5.1.1.3)",
  "property": "Essential Gene",
  "property_source": "Essential Gene: PATRIC",
  "evidence": "FBA",
  "function": "Essential gene, predicted using metabolic flux-balance analysis in LB media",
  "source": "PATRIC"
}

注意 evidence: "FBA" 与 function 里的 “predicted using metabolic flux-balance analysis in LB media”——必需基因全部是代谢通量分析预测，不是实验敲除验证。而且"in LB media"这个限定极重要：换培养基，必需基因集合会变。这条信息藏在自由文本里，字段层面看不出来。

§4.6 三个"小而关键"的参照表

antibiotics（97 条）：字段含 canonical_smiles / inchi_key / cas_id / pubchem_cid / molecular_formula / molecular_weight / atc_classification / pharmacological_classes / mechanism_of_action / synonyms / description。

pharmacological_classes 是带前缀的字符串数组，形如 "Established Pharmacologic Class [EPC]: Cephalosporin Antibacterial"。要做药物类别特征，必须先切掉前缀。mechanism_of_action 里还嵌着 HTML 锚点（<a class="pubchem-internal-link" href="...">），直接读会得到一堆标签。

taxonomy（2,730,056 条）：NCBI 分类单元快照，用于把 taxon_id 翻成学名与谱系。

sp_gene_ref（参照库本身）：专项基因的"母本"，记录每个参照蛋白的药物关联与文献。这张表是理解 sp_gene 为什么可信/不可信的关键——它是 BLASTP 的靶子。

§5 检索、抽样与泄漏分析

§5.0 BV-BRC 上能做的六类检索

检索类型	端点	示例
条件计数	`GET /api/{type}/?{cond}&limit(1)` 读 `Content-Range`	见 §9.3
条件抽样	`GET /api/{type}/?{cond}&limit(3000)`	本条目所有分布统计
多字段投影	`GET /api/{type}/?eq(...)&select(a,b,c)`	必须先有一个过滤条件，否则 400
文本搜索	`keyword(word)`	用于绕开带空格 `eq` 的缺陷
ID 批量	`POST /api/{type}/` + `in(genome_id,(...))`	POST 通道对长查询更稳
游标翻页	`cursor(*)` → 读 `X-Cursor-Mark`	大结果集遍历

§5.1 抽样策略：三个层次，三种偏倚

层次一：随机抽样（limit(n) 无排序）——最省事，但默认顺序是 genome_id 字典序，而 genome_id 是 taxon_id.version，所以字典序抽样等价于按分类号排序抽样。实测：limit(3000) 抽到的前几条全是 1540xxx 段，全是病毒。这不是随机抽样。 要真正随机，必须加 sort(+genome_id) 之外的随机性或先按条件分层。

层次二：分层抽样（先按 superkingdom / genome_status 分层）——这是本条目用的方法。代价是每层都要单独请求，且层内仍然受字典序影响。

层次三：按属性过滤抽样（and(exists(checkm_completeness),gt(checkm_completeness,89))）——用于"只分析高质量基因组"。这一层最容易出陷阱：一旦加了质量过滤，你分析的就不再是"BV-BRC 的基因组"，而是"BV-BRC 里那 8.2% 有 CheckM 值的基因组"，而这 8.2% 本身是非随机子集（都是较新提交的、走 CheckM 流程的）。

§5.2 四类真实泄漏，按危害排序

泄漏一（最严重）：把计算预测当真实标签。

这是 BV-BRC 特有的、也是最容易被忽略的泄漏。genome_amr 17,634,751 行里，16,300,395 行（92.4%）是 AdaBoost 模型输出。

后果：如果你写 SELECT * FROM genome_amr 建立训练集，你的"标签"里有九成是另一个模型对同一批特征的预测结果。而那个模型的输入正是你准备用作特征的同一批注释（sp_gene 的 CARD/VFDB 命中）。这构成特征与标签共享同一信息源——模型会学到"完美"的准确率，然后在真实实验数据上崩塌。

正确做法：WHERE evidence = 'Laboratory Method'，样本量从 1,763 万降到 128.5 万。这个筛选必须写进任何论文的方法部分。

泄漏二：同一菌株的多条药物记录被分到训练集与测试集两侧。

一个菌株对 10 种药有 10 条记录。若按行划分，同一菌株的 5 条进训练、5 条进测试，模型只需记住"这个菌株的模式"就能答对。实测：实验子集 4,000 行涉及的不同 genome_id 数远小于 4,000——菌株重复极高。

正确做法：按 genome_id 做 GroupKFold，绝不允许同一 genome_id 跨侧。

泄漏三：近缘菌株跨侧（克隆暴发）。 同一暴发事件的分离株基因组几乎相同。按菌株划分仍不够——需要用 cgMLST（cgmlst_hc5 / cgmlst_hc20 等字段）或 ANI 聚类后按簇划分。BV-BRC 恰好提供了 cgmlst_hc0 到 cgmlst_hc100 八个层级的聚类 ID，正是为这件事准备的——但这八个字段只在 11% 的细菌基因组上有值（样本实测）。

泄漏四：时间泄漏。 用 2020 年之后的数据训练、预测 2018 年——在监测场景下这是致命的。collection_year 全库填充 88.4%，但小样本内实测 99.9% 为空，说明该字段的填充高度依赖提交来源，不能假设它可用。

§5.3 结构泄漏：从字段命名本身推断出的信息

genome_amr 的两个字段直接泄漏了答案：

computational_method_performance（形如 Accuracy:0.931, F1 score:0.935, AUC:0.950）——只有计算预测行有。看到这个字段非空，就知道 evidence 是计算值。
laboratory_typing_method / measurement_value——只有实验行有。

更隐蔽的：antibiotic 的取值分布本身携带信息。计算预测只对"模型训练过的属 × 药"组合生成，所以某条记录存在与否就暗示了该菌属是否有可用模型。这是"缺失即信息"的经典案例——处理缺失值时如果把"无记录"当"敏感"，会系统性高估敏感率。

§5.4 一个不该做的划分：按 `superkingdom` 切

表面上看"用细菌训练、病毒测试"是个漂亮的泛化实验。实际上这个划分没有意义，因为：

病毒侧没有 CheckM 值、没有 assembly_accession（6.1% 是全库平均，病毒侧更低）、Partial 状态定义不同。
病毒侧注释绝大多数来自 GenBank 原始注释，而细菌侧是 RASTtk 重注释——标签的生成过程都不一样。
AMR 数据几乎全在细菌侧（antibiotic 概念对病毒基本不适用）。

这类划分测出来的不是"跨域泛化能力"，是"两套不同数据处理流程的差异"。

§6 AI 就绪指南

§6.1 最小可用 Pipeline

① 定任务 → ② 选子集（关键是 evidence 筛选）→ ③ 按 genome_id 分组
        → ④ 特征构造（聚合到菌株级）→ ⑤ GroupKFold
        → ⑥ 分层报告指标 → ⑦ 钉死快照

import requests, pandas as pd, hashlib, json

BASE = "https://www.bv-brc.org/api"

def fetch(dtype, cond="", limit=3000):
    """统一入口：cond 里必须自带过滤条件（select 不能是唯一子句）"""
    url = f"{BASE}/{dtype}/?{cond}&limit({limit})" if cond else f"{BASE}/{dtype}/?limit({limit})"
    r = requests.get(url, timeout=120)
    r.raise_for_status()
    return pd.DataFrame(r.json())

# ② 只取实验测定的 AMR（这一步是整条 pipeline 的分水岭）
amr = fetch("genome_amr", "eq(evidence,Laboratory%20Method)", limit=4000)

# ③ 按菌株聚合：一个菌株一行，药物-表型做成集合
grp = amr.groupby("genome_id").agg(
    n_drugs=("antibiotic", "nunique"),
    resistant=("resistant_phenotype", lambda s: set(s[s == "Resistant"].index)),
    standards=("testing_standard", lambda s: set(x for x in s if x)),
)

# ④ 特征：取该菌株的专项基因集合（抗性 + 毒力）
features = {}
for gid in grp.index[:200]:
    sp = fetch("sp_gene", f"eq(genome_id,{gid})", limit=500)
    features[gid] = set(sp["property"].dropna())

# ⑤ 分组划分（示例：按 genome_id 前 2 位分桶，仅示意"同菌不跨侧"）
grp["fold"] = grp.index.str.split(".").str[0].astype(int) % 5

注意 eq(evidence,Laboratory%20Method) 必须用 %20 编码——直接写空格会返回 0 行（§6.5 坑点 2）。这是本条目实测踩到的第一个坑。

§6.2 DataLoader 与批组织

病原基因组数据的批组织有一个特殊约束：序列长度差异极大。病毒基因组中位 607 bp（样本实测），细菌中位约 2.96 Mb——差 5,000 倍。同一个 batch 里混病毒与细菌等于浪费 99.98% 的 padding。

策略	适用	说明
按 `superkingdom` 分桶	必须	病毒/细菌绝不混批
按 `genome_length` 分位数分桶	推荐	每桶长度差异 ≤2 倍
按 `contigs` 数分桶	可选	contig 数中位 70，长尾明显
固定窗口切片	推荐（细菌）	把基因组切成 4-8 kb 窗口，避免超长序列

§6.3 评价指标：为什么不能只看 micro-F1

AMR 表型严重不平衡（Susceptible 6,427,758 vs Resistant 2,519,345，约 2.55:1）。在这个比例下：

micro-F1 会被多数类主导，"全判敏感"就能到 71.8%。
必须报告 per-drug 的 macro-F1，因为不同药物的耐药率差异极大（有的药耐药率 <5%，有的 >50%）。
必须按 testing_standard 分层报告：CLSI 与 EUCAST 对同一 MIC 的判定不同，混在一起报告会掩盖系统性偏差。
必须报告"新颖耐药"子集的性能：在时间划分下，测试集里会出现训练集从未见过的耐药基因，这才是真实场景。

§6.4 MLOps：把快照钉死在数据集里

BV-BRC 没有版本快照（§3.3），所以快照必须自己做：

import hashlib, json, datetime

def snapshot_manifest(queries: dict, out="bvbrc_snapshot.json"):
    """记录每个查询的确切 URL、执行时间、返回行数、响应体 MD5"""
    man = {"captured_at": datetime.datetime.now(datetime.UTC).isoformat(),
           "site_version": "3.59.14", "api_version": "1.9.3", "queries": {}}
    for name, url in queries.items():
        r = requests.get(url, timeout=180)
        man["queries"][name] = {
            "url": url,
            "n_rows": len(r.json()) if r.text.startswith("[") else 0,
            "content_range": r.headers.get("Content-Range"),
            "md5": hashlib.md5(r.content).hexdigest(),
        }
    json.dump(man, open(out, "w"), indent=1)
    return man

Content-Range 一定要记进 manifest。它是同一条查询在不同时间点唯一可比的东西——行数会变，但"当时服务端说有这么多"这个事实可以被引用。

§6.5 八个坑点（全部有实测依据）

坑点 1 · 类别：工程陷阱 — `select` 不能是查询串里的唯一子句

问题：想只取几个字段以减小响应体，写 ?select(genome_id,genome_name)，返回 400。

症状：

{"msg": "org.apache.solr.search.SyntaxError: Cannot parse '()': Encountered \" \")\" \") \"\"", "code": 400}

解决：

简单：select 单独用时只允许一个字段：?select(genome_id) 正常。
进阶：多字段必须先在串里放一个过滤条件：?eq(superkingdom,Bacteria)&select(genome_id,genome_name) 正常返回。规律是"select 不能是主查询位置"。
SOTA：不追求减体积，直接取全字段（单条约 1.5 KB），在本地用 pandas 选列。省下的流量远小于踩坑的时间。

参考：API 文档 RQL 运算符表；本站实测 2026-10-22。

坑点 2 · 类别：工程陷阱 — 带空格的值做 `eq` 恒返回 0

问题：eq(property,Antibiotic Resistance)、eq(evidence,Laboratory Method) 都返回 0 条，但库里明明有。

症状：Content-Range: items 0-0/0，HTTP 仍是 200——没有报错，只给你空结果。

解决：

简单：换 keyword() 组合：and(keyword(Antibiotic),keyword(Resistance))，能出结果（但那是文本搜索，末位不可信）。
进阶：两个表行为不一致——genome_amr 用 %20 编码有效（eq(evidence,Laboratory%20Method) 返回 1,285,111 行），sp_gene 用 %20 无效（仍 0）。必须逐表验证。
SOTA：所有"带空格的枚举值"先用 limit(1) 拉一条真实记录，读出字段的确切字节，再用该字节做 URL 编码。不要凭视觉判断空格是还是 \u00a0。

参考：genome_amr 与 sp_gene 两表实测对比，2026-10-22。

坑点 3 · 类别：工程陷阱 — `genome_id` 不是永久有效

问题：拿一篇 2015 年论文里的 genome_id 去查，返回空。

症状：eq(genome_id,201969.4) → items 0-0/0；eq(genome_id,83333.1) → 同；但 eq(genome_id,511145.12) 与 573.10001 正常。

解决：

简单：注册表里有 Deprecated 状态的 769,008 条记录，查不到不代表不存在——可能已废弃或编号变更。
进阶：用 alias / p2_genome_id 字段做二次查找；BV-BRC 保留了"旧 ID → 新 ID"的映射字段（样本填充率 15.4%）。
SOTA：把 accession（genbank_accessions，填充 99.6%）而不是 genome_id 作为外部 join 键。accession 才是跨库稳定的锚点，genome_id 只是库内的。

参考：实测四个 ID 的命中情况，2026-10-22。

坑点 4 · 类别：标签理解 — 同一 MIC 在 CLSI 与 EUCAST 下是两个标签

问题：把 resistant_phenotype 当唯一真值训练分类器，模型在某些菌药组合上表现异常。

症状：testing_standard 字段里 CLSI（1,401）与 clsi（157）并存，且空值有 1,410 条（占 35%）。

解决：

简单：按 testing_standard 分层报告指标，至少能看出差异在哪。
进阶：只用有明确标准的记录（CLSI + EUCAST，共 2,205/4,000 = 55%），把 clsi upcase 合并。
SOTA：不用离散标签，改用 measurement_value（原始 MIC）+ 标准折点表自己重算标签。BV-BRC 保存了原始 MIC 和单位（mg/L），这是它做得对的地方——别浪费这个信息。

参考：genome_amr 实验子集 n=4,000 实测分布，2026-10-22。

坑点 5 · 类别：数据泄漏 — 92.4% 的 AMR 标签是模型预测值

问题：写 SELECT * FROM genome_amr 建训练集，模型在内部验证上 AUC 0.98，上线后崩到 0.6。

症状：训练集里 computational_method_performance 字段非空的行占九成，这些是另一个 AdaBoost 模型对同一批注释的预测。

解决：

简单：WHERE evidence = 'Laboratory Method'，样本量从 1,763 万降到 128.5 万。
进阶：还要排除"该基因组的所有 AMR 记录都是计算值"的菌株——它们意味着该菌属根本没有实验数据，模型在这些菌上学到的是分类器的偏好。
SOTA：把 sp_gene 的抗性基因命中作为特征（这是合法的），把 genome_amr 的实验记录作为标签，两者严格分离。BV-BRC 把这两层放在不同表里，本来就是这个设计意图——只要你记得去读 evidence。

参考：genome_amr 全库 evidence 分层精确计数（16,300,395 vs 1,285,111），2026-10-22。

坑点 6 · 类别：预处理陷阱 — `host_name` 里同一个宿主有多种写法

问题：按 host_name 做宿主分布统计，Homo sapiens 与 Human 被算成两类。

症状：细菌样本 2,000 条里，Homo sapiens 253、Human, Homo sapiens 147、Human 108——合计 508 条是同一件事。

解决：

简单：用 host_scientific_name（NCBI 规范学名）代替 host_name。
进阶：host_group（human / avian / swine / equine / other mammal）是已经粗分好的桶，填充率约 60%（样本 2,000 中 40.8% 缺失），适合做粗粒度分析。
SOTA：自建映射表 + host_scientific_name 做主键，host_name 只作补充。同类的还有 isolation_source 的 feces / Faeces / fecal sample。

参考：细菌高质量样本 n=2,000 的 host_name 分布，2026-10-22。

坑点 7 · 类别：偏倚陷阱 — `hypothetical_cds_ratio` 中位 0.47，一半特征是"未知功能"

问题：用"基因功能"做特征建模型，发现一半样本的特征向量里全是 hypothetical protein。

症状：细菌样本（含 CheckM 值、n=3,000）hypothetical_cds_ratio 中位 0.47，>30% 的占 79.7%。

解决：

简单：把 hypothetical_cds_ratio 本身作为一个特征（它反映了研究充分程度，可能是有效的混淆变量）。
进阶：只用 sp_gene 命中的特征（它们有明确功能），接受召回率下降。
SOTA：把"注释缺失"当缺失机制处理（MNAR，missing not at random）——一个基因被标成 hypothetical，往往是因为它不在 SEED 子系统里，而"不在子系统里"本身就是信息。

参考：细菌高质量样本 n=3,000 的分布统计，2026-10-22。

坑点 8 · 类别：评估误用 — “Complete” 在病毒与细菌里不是一回事

问题：写"我们使用了 BV-BRC 中 1,035 万个完整基因组"，听起来规模宏大。

症状：这 1,035 万里 10,282,177 是病毒，细菌只有 71,364。病毒基因组几千 bp，一条序列就完整；细菌要 2-7 Mb 拼成一条染色体。

解决：

简单：分域报告，绝不给"全库完整基因组数"这个指标。
进阶：细菌侧改用 checkm_completeness >= 95 AND checkm_contamination <= 5 作为"可用"的判定，而不是 genome_status。
SOTA：明确区分三个概念——组装连续性（contigs / contig_n50）、组装完整度（checkm_completeness）、归档状态（genome_status）。三者回答三个不同问题。

参考：genome_status 分域交叉统计（§4.3），2026-10-22。

§6.6 反模式清单

反模式	为什么错	正确做法
用 `SELECT *` 取 `genome_amr` 当标签	92.4% 是预测值	加 `evidence = 'Laboratory Method'`
按行划分训练/测试	同一菌株跨侧	按 `genome_id` 分组 + cgMLST 聚类
用"全库完整基因组数"做卖点	病毒与细菌语义不同	分域报告
把 `Partial` / `Complete` 当质量指标	它们说的是归档状态，不是质量	用 CheckM + contig_n50
用 `host_name` 做宿主统计	一物多名	用 `host_scientific_name`
用 `antibiotic` 直接做药物 ID	115 种拼法	join `antibiotics` 表，或建映射
假设 `genome_id` 永久有效	有 76.9 万 Deprecated	用 `genbank_accessions` 做外部锚点
混批病毒与细菌	长度差 5,000 倍	按 `superkingdom` 分桶
只用 micro-F1 报告	不平衡 2.55:1	加 per-drug macro-F1
假设 `collection_year` 可用	小样本 99.9% 为空	先查填充率再用

§7 质量评估、DAIMS 与口径交叉核对

§7.1 记录级质量：BV-BRC 保证到什么程度

质量维度	实测证据	评价
标识符唯一稳定	`genome_id` 100% 填充；但 76.9 万 Deprecated，且有查不到的 ID	⚠️ 库内稳定，跨库不稳
注释一致性	细菌全走 RASTtk；病毒仅十类走 VIGOR4	❌ 分域不一致
组装质量可查	`checkm_completeness` 仅 8.2%，病毒侧 0%	❌ 覆盖极低
功能注释完整度	`hypothetical_cds_ratio` 中位 0.47	❌ 一半无功能
元数据完整度	`isolation_source` 43.7%、`sequencing_depth` 5.5%	❌ 稀疏
表型证据可溯	`evidence` 字段二分；实验行 80% 有 PMID	✅ 设计良好
原始 MIC 保留	`measurement_value` + `measurement_unit` + `testing_standard`	✅ 难得
代码可审计	RASTtk/VIGOR4/PHANOTATE + 入库脚本全在 GitHub	✅ 优秀
文档准确性	文档页数字停在 2017-2024，且与实时差 30-50%	❌ 严重滞后

§7.2 抽样声明：本条目数字的边界

必须显式声明，否则读者会把采样统计当全库：

数字	来源	是否全量
17,061,503 基因组、各数据类型记录数	API `Content-Range` 实时计数	✅ 全库精确值（2026-10-22）
`genome_status` 分域计数	同上，交叉条件计数	✅ 全库
`genome_amr` 的 16,300,395 / 1,285,111	同上，`eq(evidence,...)` 计数	✅ 全库
`resistant_phenotype` 四类计数	同上	✅ 全库
元数据字段填充（`isolation_source` 43.7% 等）	同上，`exists()` 计数	✅ 全库
CheckM 中位 99.5、contig 中位 70、hypo 中位 0.47	本地抽样 n=3,000（`and(exists(checkm),eq(superkingdom,Bacteria))`）	⚠️ 样本，非全量
`laboratory_typing_method` 分布、`testing_standard` 分布	本地抽样 n=4,000	⚠️ 样本
`host_name` / `isolation_source` 高频值	本地抽样 n=2,000	⚠️ 样本
`sp_gene` 六类计数	`and(keyword(),keyword())` 近似计数	⚠️ 量级可信、末位不可信
病毒基因组中位长度 607 bp	本地抽样 n=3,000	⚠️ 样本

抽样声明的作用是让读者知道哪些数字可以被引用为事实、哪些只能当量级。 本条目所有"全库精确值"都来自服务端计数（Content-Range），这是最可靠的方法；所有分布数字来自本地抽样，样本量在表中逐项标注。

§7.3 三个必须知道的生物学效度问题

问题一：基因组计数不是流行病学计数。 17,061,503 个基因组里，SARS-CoV-2 相关的一个毒株可能贡献上百万条近缘序列。用"基因组数"估计"病原体流行度"会严重失真——测序量与公共卫生投入成正比，不是与疾病负担成正比。

问题二：同源投射不等于功能验证。 sp_gene 的 869,000,661 条赋值全部来自 BLASTP 同源投射。一个蛋白和 CARD 里的某个抗性蛋白有 60% 相似度，会被标为"Antibiotic Resistance"——但它可能完全没有那个功能。这是所有同源投射法共同的局限，BV-BRC 在字段层面没有区分"高置信/低置信"。

问题三：必需基因是模型预测，且依赖培养基。 property = Essential Gene 的 162 万条记录，evidence 全部是 FBA，function 里写着"predicted using metabolic flux-balance analysis in LB media"。换一种培养基，必需基因集合会变。这个限定藏在自由文本里，字段层面看不出来。

§7.4 偏倚清单（可核查）

偏倚	证据	影响
病毒过度代表	病毒 15,634,461 / 细菌 1,382,093（11.3:1）	任何"全库"统计都被病毒主导
疫情驱动	病毒 Complete 10,282,177，多数为 2020-2023 提交	时间分布极端集中
肠道宏基因组过采样	细菌样本 `isolation_source` 高频值：mouse gut 249、fecal 186、human gut 98	环境/农业病原被低估
宿主偏人鼠	`host_name` 前三：Homo sapiens 253、Mouse 249、Human 147	动物宿主谱窄
实验室测试药物谱窄	实验子集 4,000 条仅 115 种拼法，以四环素/复方新诺明/阿米卡星为主	耐药结论不可外推到未测药物
地理粒度不一	`geographic_location` 混用国家/地区/自由文本	空间分析需手工归一
时间字段稀疏	`collection_year` 全库 88.4% 但小样本 99.9% 为空	时间划分不可靠

§7.5 数据完整性核查表

检查项	结果
主键唯一	✅ `genome_id` / `feature_id` / `id` 各自唯一
外键可 join	✅ 星形结构，全部挂 `genome_id`
枚举值受控	❌ `antibiotic` / `host_name` / `isolation_source` 均为自由文本
缺失有说明	❌ 缺失值不区分"未采集"与"不适用"
版本可追溯	❌ 无数据快照，仅软件版本号
单位一致	⚠️ `measurement_unit` 有 mg/L 与 mm，且 66% 为空
时间戳规范	✅ 全部 ISO 8601 带时区（`2016-12-02T00:49:58.943Z`）
许可明确	❌ 站点无开放数据许可声明

§7.6 DAIMS 24 项逐项评分

#	检查项	判定	依据
1	宽格式/长格式明确	✅	每表固定列，无嵌套宽表
2	唯一标识符	✅	`genome_id` 100% 填充且唯一
3	特殊字符处理	⚠️	字段含 HTML 锚点（`mechanism_of_action`）、斜杠（`trimethoprim/sulfamethoxazole`）
4	重复行	⚠️	同一 (菌株, 药) 可有多条不同证据记录，需按 `evidence` 去重
5	缺失编码统一	❌	空值、`None`、空数组三种形态并存
6	标签/标识符说明	✅	`/api/doc/{type}/` 逐字段说明（genome 页 68 KB）
7	罕见类别分组	⚠️	`Nonsusceptible` 仅 2,867 条，未合并
8	偏倚评估	⚠️	官方无偏倚声明；本条目 §7.4 自建
9	数据字典	✅	`docs/data_protocols/data_dictionary.html` 覆盖 31 类型
10	信息性缺失解释	❌	为何 `sequencing_depth` 只 5.5%？无说明
11	设备/平台记录	✅	`sequencing_platform`（46.9%）、`assembly_method`（39.6%）
12	共线性处理	❌	无多重共线性诊断或建议
13	编码映射	⚠️	`testing_standard` 里 CLSI/clsi 并存，无映射表
14	时间戳处理	⚠️	`collection_year` 88.4% 但对齐差；`date_inserted` 为提交时间非采集时间
15	划分建议	❌	无 train/test 划分指导（§5.2 的四类泄漏均无官方警示）
16	泄漏讨论	❌	完全无。92.4% 预测标签这件事只在字段层面体现，无任何文档警示
17	标签分布	⚠️	表型分布可查，但 `evidence` 分层比例无任何文档说明
18	测量偏倚	❌	无 CLSI/EUCAST 折点差异说明
19	外部验证建议	❌	无
20	版本记录	⚠️	有站点版本（3.59.14）与 API 版本（1.9.3），无数据快照
21	预处理脚本	✅	优秀：`github.com/BV-BRC/bvbrc_data` 逐项给出 Perl 脚本
22	合规要求	❌	无数据使用协议、无许可、无 DUO
23	多模态对齐	⚠️	序列/表型/结构/表位多模态都有，但无跨模态对齐说明文档
24	去标识化	✅	无患者标识；`collector_name` 为人员名但属公务记录

DAIMS 总分：14.0 / 24（58.3%）

判定	计数	得分
✅ 满足	6	6.0
⚠️ 部分满足	10	5.0
❌ 不满足	8	0

这个分数（58.3%）明显高于 MGI（45.8%）与 IPD（55% 区间），主要得益于三点：有真正的 API 与逐字段文档（#6、#9）、有完整预处理脚本链（#21）、时间戳规范（#14 部分）。扣分集中在"给 AI 用"这件事上：#15 划分建议、#16 泄漏讨论、#18 测量偏倚、#19 外部验证，四项全空——而 #16 恰恰是本条目认为最致命的（92.4% 预测标签无任何警示）。

§7.7 口径交叉核对矩阵（不是模型性能验证）

显式声明：本节不是模型性能验证，不提供任何 benchmark 数字。它做的是：把同一概念在不同来源下的数字并列，指出哪个该用在哪。把本节当"准确率"引用是误读。

概念	口径 A（官方文档页）	口径 B（API 实时）	口径 C（本方实测样本）	该用哪一个
基因组总数	文档未给总数	17,061,503	—	用 B。A 无此口径
细菌基因组	1,041,313（“As of July 2024”）	1,382,093	—	用 B；A 差 32.7%，是两年前的数字
病毒基因组	11,783,665（同）	15,634,461	—	用 B；同理
古菌	24,998（同）	37,454	—	用 B；差 49.8%
真核宿主	11（同）	9	—	用 B；这是唯一减少的
注释特征数	文档无	8,955,936,565	—	用 B
AMR 记录数	文档无	17,634,751	—	用 B
AMR 实验 vs 预测	文档只说"collected from BioSample、GIMS、publications"，不给比例	实验 1,285,111 / 预测 16,300,395	样本 4,000 条中实验占 31.7%（因按 evidence 过滤）	必须用 B 的比例（7.3% / 92.4%）。A 的描述会让人以为主要是实验数据
AMR 覆盖基因组	19,299（“As of October 2017”）	单 `Resistant` 表型就有 2,519,345 条	—	用 B 的量级；A 是 9 年前
通路数	147 个通路 / 2,820 个 EC（“As of October 2018”）	`pathway` 表 1,842,961,207 行	—	两个概念：A 是通路定义数，B 是"基因×通路"赋值数。不能并列比较
一致性注释	“8,731,247 条额外注释”（2017）	—	—	已过时，不引用
蛋白互作	55,600,858（2018）	55,600,858	—	两者相同——说明 PPI 自 2018 年未更新。这是重要发现
基因组质量	文档未定义 `Good`/`Poor` 阈值	Good 8,246,478 / Poor 2,432,789	—	用 B，但阈值不可知是硬伤
"完整"基因组	文档无	Complete 10,355,240（病毒 10,282,177 / 细菌 71,364）	—	必须分域引用，见 §4.3

这张表最重要的一行是"蛋白互作"：文档页写 55,600,858（“As of October 2018”），API 实时也是 55,600,858——完全一致。这说明 PPI 这张表自 2018 年以来一条都没更新过。而同一份文档里的基因组数字却涨了 32.7%。同一个"as of October 2018"标注下，有的表在更新、有的表冻住了——这是"文档日期"这个元信息本身不可信的证明。

§8 生态位与相邻资源

§8.1 它在 NIAID BRC 体系里的位置

NIAID 的 BRC 项目目前有两个中心（NAR 2023 原文）：

BRC	覆盖	代表
BV-BRC	细菌与病毒病原	本条目
VEuPathDB	真核病原体与媒介无脊椎动物	疟原虫、锥虫、利什曼、按蚊等

两者互补、不重叠。历史上曾有多家（PATRIC、IRD、ViPR、EuPathDB、VectorBase 等），2019 年合并为两个。这个合并逻辑值得注意：按"病原类型"而不是按"数据类型"划分，避免了同类数据在多个库之间重复策展。

§8.2 与本站已收录条目的衔接

本站条目	关系
`mgi`（#1341）	同为"参考型数据库"，但一个物种 vs 跨病原。MGI 是 CC BY 4.0，BV-BRC 无明确许可——构成许可梯度上的两个极端
`ipd-imght-hla`（#125）	免疫遗传学视角。BV-BRC 的 `epitope` / `serology` 表与 HLA 分型在下游（表位呈递）汇合
`dryad`（#124）	通用数据仓库 vs 领域专库，正好对照"通用 vs 专用"的取舍
`gtex` / `tcga` / `uk-biobank`	人类观察性数据 → BV-BRC 是"机制验证"侧的证据来源
`ncbi-virus` 类条目	病毒序列有重叠，但 BV-BRC 多了统一重注释与专项基因投射

一个跨条目的观察：MGI（CC BY 4.0，图片除外）→ BV-BRC（未声明）→ IPD-IMGT/HLA（CC BY-ND），构成一条清晰的许可收紧梯度。这个梯度不是随机的：越靠近"可再分发的成品数据"（如 HLA 的官方 flat 文件），许可越紧；越靠近"原始观测登记"（如小鼠表型注释），许可越松。做数据集组合时，这个梯度决定了哪些能打包、哪些只能引用。

§8.3 下游消费者：谁在用 BV-BRC

耐药预测研究：BV-BRC 是最常用的 AMR 训练数据源之一，因为它的 genome_amr 表把基因型与表型放在同一个 ID 空间。
病毒谱系监测：spike_lineage / spike_variant 被广泛用于 SARS-CoV-2 变异监测。
教学：官方有 Workshop 系列（JCVI、Chicago/Argonne 两地），并提供教学用 workspace 模板。
CLI 生态：p3-* 命令被集成进多个生物信息流水线（如 Bactopia 类工作流）。

§9 资源、引用与复现

§9.1 必读文献

Olson RD, et al. Introducing the Bacterial and Viral Bioinformatics Resource Center (BV-BRC): a resource combining PATRIC, IRD and ViPR. Nucleic Acids Res. 2023;51(D1):D678-D689. doi:10.1093/nar/gkac1003. PMID 36350631.（主引用）
Davis JJ, et al. The PATRIC Bioinformatics Resource Center: expanding data and analysis capabilities. Nucleic Acids Res. 2020;48(D1):D606-D612. doi:10.1093/nar/gkz943. PMID 31667520.
Brettin T, et al. RASTtk: a modular and extensible implementation of the RAST algorithm. Sci Rep. 2015;5:8365.
Davis JJ, et al. Antimicrobial resistance prediction in PATRIC and RAST. Sci Rep. 2016;6:27930.（AdaBoost 分类器的原始出处）
McNair K, et al. PHANOTATE: a novel approach to gene identification in phage genomes. Bioinformatics. 2019;35:4537-4542.
Aziz RK, et al. The RAST Server. BMC Genomics. 2008;9:75.

§9.2 关键链接

用途	链接
主页	https://www.bv-brc.org/
API 文档	https://www.bv-brc.org/api/doc/
数据字典	https://www.bv-brc.org/docs/data_protocols/data_dictionary.html
数据类型与来源	https://www.bv-brc.org/docs/data_protocols/data_types_sources.html
基因组注释协议	https://www.bv-brc.org/docs/data_protocols/genome_annotation.html
FTP 站点说明	https://www.bv-brc.org/docs/quick_references/ftp.html
使用量统计	https://www.bv-brc.org/docs/usage_metrics.html
系统数据说明	https://www.bv-brc.org/docs/system_documentation/data.html
代码仓库	https://github.com/BV-BRC
FTPS	`ftps://ftp.bv-brc.org/`

§9.3 复现本条目全部数字的脚本

#!/bin/bash
# bvbrc_probe.sh — 复现本条目全部"全库精确值"
# 原理：读 Content-Range 响应头，不做数据传输
BASE="https://www.bv-brc.org/api"
UA="Mozilla/5.0 (compatible; data-audit)"

count() {
  local label="$1" path="$2"
  local cr
  cr=$(curl -sS --http1.1 --max-time 90 -D - -o /dev/null -A "$UA" "$BASE/$path" 2>/dev/null \
       | grep -i "^Content-Range:" | tr -d '\r')
  printf "%-42s %s\n" "$label" "$cr"
  sleep 0.5   # 该 API 无速率限制文档，保守间隔
}

echo "=== 采集时间: $(date -Iseconds) ==="
count "genome_all"          "genome/?limit(1)"
count "genome_Bacteria"     "genome/?eq(superkingdom,Bacteria)&limit(1)"
count "genome_Viruses"      "genome/?eq(superkingdom,Viruses)&limit(1)"
count "genome_Archaea"      "genome/?eq(superkingdom,Archaea)&limit(1)"
count "genome_Complete"     "genome/?eq(genome_status,Complete)&limit(1)"
count "genome_Partial"      "genome/?eq(genome_status,Partial)&limit(1)"
count "genome_Deprecated"   "genome/?eq(genome_status,Deprecated)&limit(1)"
count "feature_all"         "genome_feature/?limit(1)"
count "spgene_all"          "sp_gene/?limit(1)"
count "amr_all"             "genome_amr/?limit(1)"
count "amr_Lab"             "genome_amr/?eq(evidence,Laboratory%20Method)&limit(1)"
count "amr_Comp"            "genome_amr/?eq(evidence,Computational%20Method)&limit(1)"
count "amr_Resistant"       "genome_amr/?eq(resistant_phenotype,Resistant)&limit(1)"
count "amr_Susceptible"     "genome_amr/?eq(resistant_phenotype,Susceptible)&limit(1)"
count "ppi_all"             "ppi/?limit(1)"
count "epitope_all"         "epitope/?limit(1)"
count "surveillance_all"    "surveillance/?limit(1)"
count "serology_all"        "serology/?limit(1)"
count "antibiotics_all"     "antibiotics/?limit(1)"
count "taxonomy_all"        "taxonomy/?limit(1)"

# 元数据填充率（exists 计数）
for f in isolation_source host_name checkm_completeness genome_quality \
         sequencing_depth assembly_accession biosample_accession collection_year; do
  count "filled_$f" "genome/?exists($f)&limit(1)"
done

抽样（分布统计用）：

import requests, collections
BASE = "https://www.bv-brc.org/api"

# 细菌高质量样本（有 CheckM 值）
r = requests.get(f"{BASE}/genome/",
    params={"q": "and(exists(checkm_completeness),eq(superkingdom,Bacteria))&limit(3000)"},
    timeout=180)
# 注意：requests 用 params 会把括号编码，实测该 API 对 `and(...)` 的编码敏感，
# 稳妥写法是直接拼 URL：
#   requests.get(f"{BASE}/genome/?and(exists(checkm_completeness),eq(superkingdom,Bacteria))&limit(3000)")
d = r.json()
print("n =", len(d))
for k in ("checkm_completeness", "contigs", "hypothetical_cds_ratio", "genome_length"):
    vals = sorted(x[k] for x in d if x.get(k) is not None)
    print(k, "median =", vals[len(vals)//2])
print("genome_status:", collections.Counter(x.get("genome_status") for x in d))

§9.4 BibTeX

@article{olson2023bvbrc,
  title   = {Introducing the Bacterial and Viral Bioinformatics Resource Center ({BV-BRC}):
             a resource combining {PATRIC}, {IRD} and {ViPR}},
  author  = {Olson, Robert D. and Assaf, Rida and Brettin, Thomas and Conrad, Neal and
             Cucinell, Clark and Davis, James J. and Dempsey, Donald M. and Dickerman, Allan and
             Dietrich, Emily M. and Kenyon, Ronald W. and Kuscuoglu, Mehmet and Lefkowitz, Elliot J. and
             Lu, Jian and Machi, Dustin and Macken, Catherine and Mao, Chunhong and
             Niewiadomska, Anna and Nguyen, Marcus and Olsen, Gary J. and Overbeek, Jamie C. and
             Parrello, Bruce and Parrello, Victoria and Porter, Jacob S. and Pusch, Gordon D. and
             Shukla, Maulik and Singh, Indresh and Stewart, Lucy and Tan, Gene and Thomas, Chris and
             VanOeffelen, Margo and Vonstein, Veronika and Wallace, Zachary S. and Warren, Andrew S. and
             Wattam, Alice R. and Xia, Fangfang and Yoo, Hyunseung and Zhang, Yun and
             Zmasek, Christian M. and Scheuermann, Richard H. and Stevens, Rick L.},
  journal = {Nucleic Acids Research},
  volume  = {51},
  number  = {D1},
  pages   = {D678--D689},
  year    = {2023},
  doi     = {10.1093/nar/gkac1003},
  pmid    = {36350631}
}

§10 复用边界与跨条目协作手册

§1 到 §9 讲的是"这个库本身长什么样"。这一节回答一个更实际的问题：当你要同时用好几个库时，BV-BRC 该被放在哪个位置——它不能做什么、和谁拼、拼的时候哪里会崩。

§10.1 一张"能拿它做什么"的决策树

问自己第一个问题：我要预测的是"分子"还是"表型"？

如果是分子层面（这个基因像不像抗性基因、这个序列属于哪个谱系、这个蛋白有没有同源结构），BV-BRC 是一线选择。理由：sp_gene 8.69 亿条记录把 CARD、VFDB、TCDB、DrugBank 的命中结果都投射到了同一套 genome_id + feature_id 空间，你不需要自己跑 BLAST 就能拿到"这个基因被哪些库认定为抗性基因"。这在开源世界里是独一份的——CARD 本身给的是参考序列，要投射到具体基因组上仍然要做比对；BV-BRC 已经把这一步做完了。

如果是表型层面（这个菌株耐不耐这个药、这个病人该不该用这个药），BV-BRC 是二线选择，一线应该是直接的药敏监测数据（如 GLASS、EARS-Net 这类表型登记）。原因在 §4.4 已经说透：17,634,751 条 AMR 记录里只有 1,285,111 条（7.3%）是实验测定的，再往下还只有约八成带 PMID、约六成说清了折点标准。真正能撑起严格监督学习的样本，规模在 50 万条以下，而且集中在少数几个属。用 BV-BRC 做临床药敏预测的合规性讨论，必须从这个数字出发，而不是从"1763 万条 AMR 记录"出发。

如果是流行病学层面（某个变异什么时候在哪里出现、流行曲线怎么走），BV-BRC 是补充证据而不是主证据。spike_lineage（114,478 条）与 spike_variant（670,741 条）是月度聚合统计，它们描述的是"提交到 BV-BRC 的序列里有多少是这个谱系"，而不是"人群里有多少感染"。分母不明——这是 GISAID 与 GenBank 都存在的同一类问题，BV-BRC 只是转发者，不解决它。

§10.2 跨库拼接：四个 ID 空间与三条断裂线

把 BV-BRC 与别的库拼起来时，会碰到四个不同的 ID 空间。它们不是都能互通：

ID 空间	稳定性	跨库可用性	用它在哪拼
`genome_id`（形如 `573.10001`）	低——76.9 万条已 `Deprecated`	只在 BV-BRC 内部有效	库内 join（`genome_amr` ↔ `sp_gene` ↔ `genome_feature`）
`genbank_accessions`	高，填充 99.6%	全行业通用	与 NCBI / ENA / GenBank 系拼接
`taxon_id`	高，填充 100%	NCBI Taxonomy 标准	与任何按物种组织的库（MGI、UniProt、GTDB）拼接
`biosample_accession`	中，填充 54.9%	BioSample 体系	与 SRA / ENA 的样本元数据拼接

断裂线一：genome_id 不能出库。 §6.5 坑点 3 已经实测过——201969.4 与 83333.1 查不到，511145.12 与 573.10001 查得到。这不是格式差异，是 ID 生命周期问题。所以任何"把 BV-BRC 的 ID 写进论文附录"的做法都有时效风险，而写 accession 没有。

断裂线二：biosample_accession 只填了 54.9%，剩下的 45.1% 拼不上 SRA。 而 SRA 是拿到原始测序读长的唯一途径。这意味着近一半的 BV-BRC 基因组你只能拿到注释与组装，拿不到原始数据——做"从 reads 重新组装"这类研究时，可用样本会直接腰斩。

断裂线三：taxon_id 虽然 100% 填充，但物种级 ID 与菌株级实体的粒度不匹配。 一个 taxon_id 对应成百上千个 genome_id。如果你的下游是按物种建索引（像 MGI 那样一个物种一个库），BV-BRC 的多对一关系会被压平，菌株间的耐药差异全部丢失。

§10.3 同一份病原数据在本站的三种形态

本站目前已收录的条目里，病原相关数据会以三种截然不同的形态出现，它们的训练用途完全不同，混用是最常见的跨条目错误：

形态一：参考型病原基因组库（本条）。 特征是"每个实体都有完整基因组 + 注释 + 表型"。适合做基因型→表型映射。它的偏倚是"哪些菌株被提交、被提交的菌株里哪些被测过药敏"——即 §7.4 讲的提交偏倚与检测偏倚。

形态二：人类宿主侧的观察性队列（如 gtex、uk-biobank、tcga 一类）。 特征是"每个个体有多维观测，病原信息只是其中一列"。适合做宿主易感性与结局关联。它的偏倚是"谁被纳入队列"——健康志愿者偏倚、幸存者偏倚。

形态三：免疫遗传学参考库（如 ipd-imght-hla）。 特征是"等位基因层面的参考序列 + 群体频率"。适合做表位呈递预测、供受体配型。它的偏倚是"哪些等位基因被分型得最细"——研究热度偏倚。

把三者拼起来做"病原—宿主—免疫"三段式模型时，最容易犯的错是：拿形态一里的菌株 ID 去形态二里找宿主，找不到就以为数据缺失。实际上两边的样本根本不在同一个采集框架里——形态一的菌株大多来自监测网络，形态二的个体来自前瞻队列，交集天然很小。这个交集小不是数据质量问题，是设计使然。

§10.4 许可梯度：决定"能打包"还是"只能引用"

§8.2 提过一条许可收紧梯度。把它展开成可执行的判断：

库	许可状态	能做什么	不能做什么
`mgi`	CC BY 4.0（图片除外）	打包、再分发、商用（署名）	不能暗示背书
`dryad`	逐数据集（多为 CC0 / CC BY）	逐个核查后打包	不能整站打包
`bv-brc`	未显式声明	学术研究、公开复用、引用	商用前必须联系团队确认
`ipd-imght-hla`	CC BY-ND	引用、原样使用	不能改作、不能拆分成训练集再分发

一条实践规则：做数据集组合时，最终包的许可由链条上最紧的一环决定。BV-BRC 处在"未声明"这一档，意味着任何包含它的组合包都处于法律灰区。这不是危言耸听——NIAID BRC 项目按惯例数据公开，但"惯例开放"与"书面许可"在法律上不是一回事。如果你要把 BV-BRC 的衍生物（比如自己算的特征矩阵）对外分发，先发一封邮件问清楚，比事后补救便宜。

§10.5 三个"不要在这个库上做"的研究

不要做一：用基因组数量做流行度或疾病负担指标。 病毒侧 15,634,461 个基因组里，绝大部分是 SARS-CoV-2 监测产物——它反映的是 2020-2023 年全球测序能力的爆发，不是病毒本身的生物学特征。用这个数字做时间序列分析，你测出来的是"测序投入曲线"，不是"疫情曲线"。同一条警告适用于细菌侧：1,382,093 个细菌基因组里 WGS 状态占 1,228,206，而提交集中在少数几个监测网络覆盖的属。

不要做二：跨域合并统计"平均质量"。 §4.3 与坑点 8 已经证明 Complete 在病毒与细菌下是两套定义（10,282,177 vs 71,364），Partial 是病毒独有（细菌侧 0），CheckM 完全跳过病毒（病毒侧 0 条有值）。任何"全库平均完整度"的分子分母都跨了两个不可比的总体。要报就分域报。

不要做三：把 PPI 表当活数据。 ppi 表 55,600,858 条，官方文档页标注"As of October 2018"，API 实时也是 55,600,858——一字不差。这说明这张表自 2018 年以来没有新增一条。同一份文档里的基因组数字却在这段时间涨了 32.7%。"同一文档里有的表在长、有的表冻住"这件事本身就是一条元信息：不要用文档的"as of"日期去推断任一具体表的时效，要逐表实测（方法见 §9.3）。

§10.6 一句话总结这一节

BV-BRC 的价值在于"把注释投射做完了"，不在于"提供了可训练的表型标签"。 把它当特征工厂，它极其好用；把它当标签来源，必须先过 evidence = 'Laboratory Method' 这道闸。跨库拼接时认 accession 不认 genome_id，许可上按最紧的一环算。在这三条之内用它，它能省掉你几个月的比对工作量；越过这三条，它会用一个漂亮但虚假的准确率把你送进沟里。

附录 A：本条目数字的一页速查

问题	答案
有多少个基因组？	17,061,503（病毒 15,634,461 / 细菌 1,382,093 / 古菌 37,454 / 真核 9）
有多少条注释特征？	8,955,936,565
有多少条专项基因记录？	869,000,661（转运 3.81 亿 / 毒力 1.87 亿 / 药靶 1.11 亿 / 抗性 0.96 亿 / 人同源 416 万 / 必需 162 万）
有多少条 AMR 记录？	17,634,751，其中实验 1,285,111（7.3%）、预测 16,300,395（92.4%）
有 API 吗？	有，而且很好用。31 个数据类型，免注册，`/api/{type}/`
总数怎么拿？	读响应的 `Content-Range: items 0-1/<total>`
有 FTP 吗？	有，但已强制 FTPS，明文 `ftp://` 停用
有版本快照吗？	没有。只有软件版本（3.59.14）与 API 版本（1.9.3）
许可能商用吗？	未声明。NIH 资助、按惯例公开，但需联系团队确认
注释统一吗？	细菌统一走 RASTtk；病毒只有十类走 VIGOR4，其余沿用 GenBank
组装质量能查吗？	`checkm_completeness` 只覆盖 8.2%，病毒侧为 0
最大的坑是什么？	92.4% 的 AMR 标签是模型预测值，不读 `evidence` 字段就会拿预测当标签
拿来做什么最合适？	耐药预测（只用实验子集）、病毒谱系监测、专项基因跨物种比较
绝对不能用来做什么？	临床药敏判断、用基因组数估流行度、把 `Complete` 当质量指标、混域统计完整度

最后更新：2026-10-22
数据采集：2026-10-22 至 2026-10-23（沙箱环境实测，全部数字带采集时点）