宏基因组样本的语义归一化 — MetaLog 把自由文本变成受控词

MetaLog 是一个很少被当作「数据集」来谈论的数据库：它不产出序列，不产出影像，只产出字段。它做的事情说起来朴素——把几百项研究里作者自己写下的样本描述，一条一条读回论文原文，再抄进一张统一的表格。但正是这张表格，决定了跨研究汇总这件事能不能成立。

宏基因组领域最顽固的问题不是测序深度，也不是比对工具，而是同一个字段在不同实验室里含义不同。country 有人填 USA、有人填 United States、有人填 U.S.A.、有人填中文；disease_state 有的填 healthy、有的填 control、有的干脆留空但当对照用。把几千项研究的这一列直接拼起来做统计，得到的结论一定是错的，而且错得看不出来。MetaLog 的全部价值，就是在这条缝上做人工缝合。

代价同样明确：人工标注必然有覆盖缺口，映射规则本身带主观性，而且它没有任何机制向你保证两个标注员对同一条记录给出同样的答案。这篇写的既是它缝合了什么，也是它缝不住什么。一屏速览见下表。

维度	内容
官方名称	MetaLog（站点写作 Metalog）
维护机构	EMBL 海德堡分子系统生物学单元 Bork 组
官方入口	https://metalog.embl.de/
核心论文	Nucleic Acids Research 2026, 54(D1):D826–D834，DOI 10.1093/nar/gkaf1118
数据性质	人工标注的样本级情境数据（contextual data），不含序列本身
当前规模（站点 2026-10 快照）	1097 项研究，159310 个样本
四个栖息地模板	人类、动物、海洋、其他环境
人类样本占位	114929 个样本，对应 78473 名受试者
字段分层	核心字段（curated）/ 部分统一化 / 研究特有附加字段
受控词表	ENVO、UBERON、ChEMBL、ATC、NCBI Taxonomy，地理用 Natural Earth、Marine Regions、GeoNames
序列数据位置	INSDC（ENA/SRA/DDBJ）为主，少量 MG-RAST、CNSA
分发格式	TSV.gz，长表与宽表各一套，另附映射表与分类谱
附带分析产物	mOTUs 3.0、MetaPhlAn 4.0、SPIRE-mOTUs 分类谱，肠型与微生物载量预测
许可	ODbL 1.0（数据库）+ DbCL 1.0（内容）
更新节奏	每周末同步一次；不保留历史版本存档
最该记住的一句	它把「语义」这件事显式化了，而不是替你解决了语义

§1 它要解决的具体麻烦

1.1 一句结论：跨研究汇总的瓶颈在字段，不在数据量

宏基因组测序数据本身早就不缺。ENA、SRA、DDBJ 三家组成 INSDC，存放的是原始 reads；CNSA、GSA 之类的国家级仓库也在快速膨胀。真正稀缺的东西藏在另一层：这段 reads 是从谁身上、在什么状态下、用什么方式采到的。

INSDC 的层级结构是 project → sample → experiment → run。理论上一个 biosample 登录号唯一标识一份生物材料，比如一份粪便等分试样，或者某一孔径滤膜截留的海水。但 INSDC 只强制要求最基本的实验过程信息，比如文库筛选策略是不是全基因组。至于膳食、用药、疾病分期、采样时的水深与盐度，全靠作者自愿填写，填错也没人校验。论文正文里可能写得很细，但正文不是数据库字段，机器读不到。

于是出现一个尴尬的中间态：数据是公开的，元数据名义上也是公开的，但可计算的情境数据不存在。研究者每次想做跨研究分析，都得自己重新读一遍几十篇论文的补充材料，读完之后得到的还是一张只有自己看得懂的 Excel。这个活儿每个组都干一遍，干完还不兼容。

MetaLog 的定位就在这一层：它不解决测序，只解决「同一件事，不同的人用不同的话说了」这个问题。用论文自己的话说，缺的不是样本级临床数据或在位观测数据，缺的是把它们取出来、对齐、并接到测序数据上的那一步。

1.2 三条常见的错误期待

第一次接触这个库的人，通常带着三种期待，三种都会落空。

期待一：以为它是一个测序数据仓库。 不是。MetaLog 里没有一个碱基。它给的是字段、标注、映射表和重新计算过的丰度表。想拿原始 reads 还得回 ENA/SRA。这个分工是有意为之：库方把测序数据的托管全部留给 INSDC，自己只做注释层，这样不用承担 PB 级存储，也不会和数据归档抢职责。

期待二：以为它能替代你自己读论文。 部分能，部分不能。核心字段是统一好的，可以直接用；但研究特有的附加字段保留的是原始命名，七十多个字段名里大小写并存的情况一眼可见（Comorbidities 与 comorbidities 同时存在），这类字段仍然是自由文本，仍然需要你自己读。MetaLog 把「读论文」的工作从一百篇压到了十篇，但没有压到零篇。

期待三：以为人工标注等于高质量。 人工标注解决的是语义归一化，不是事实正确性。标注员读的是已发表材料，如果论文本身写错了、图注标错了、补充表和正文矛盾，MetaLog 抄下来还是错的。它能纠正的是「同一概念的不同写法」，不能纠正「作者写错的那个数」。

1.3 它能给到的与给不到的

把需求摊开来对照，边界就很清楚。

你的需求	它给的	够不够
判断某项研究的样本来自哪个国家	统一后的 geographic_location，粗粒度但写法一致	够，做国家级筛选足够
精确到城市或医院的采样点	location 与经纬度，但分辨率另有 location_resolution 标注	部分够，人类样本多数只到国家
区分病例与对照	subject_disease_status 归一化状态	够，但需先弄清各研究的对照定义
完整用药史	medication 映射到 ChEMBL 与 ATC，另有 medication_full 原始文本	部分够，覆盖率取决于原文报告
膳食结构	diet 四大类粗分，另附 diet_full	粗用够，细用不够
每个人的随访时间轴	timepoint、timeseries_available、timeseries_count	部分够，无法可靠对齐时该字段留空
直接把序列拿来做比对	不给序列，只给指向 INSDC 的映射	不够，须自行下载
物种丰度矩阵	三个 profiler 的预计算表	够，且省掉重算成本
保证字段值一定与原文一致	不保证，但可回查原文核对	不够，须抽样复核
拿到标注员之间的分歧记录	不提供	不够

1.4 你的处境与它能帮到的事

这张表按「场景」来组织：左列写的都是具体的处境，不是数据集的功能特性。

你的处境	它能帮你什么	下一步该做什么
手上有三五个队列的丰度表，想合并做疾病关联，但每张表的病名列写法都不一样	提供已归一化的 subject_disease_status 与统一 profiler 的丰度表，合并前不必再自己写映射	先按研究列一张对照表，确认各研究的对照定义，再决定合并还是分层
想找「有没有已发表的某类人群数据」，但不知道去哪检索	可先按栖息地与字段值在站点筛研究，再去下载	记下研究编号，去论文核对样本量与入选标准
要做方法学论文，需要引用一组「已整理好的元数据」作为基线	提供可复现的统一字段与版本快照，引用论文即可	记录抓取日期，因为站点不留历史版本
做数据策展或图书馆学，想学怎么设计标注模板	四套栖息地模板（核心、部分统一化、全部研究特有三级）是现成的范例	重点读它的字段命名与分层，而不是字段内容
想训练一个从论文抽取元数据的模型	可用它的成对结构（原文文本 → 归一化字段）反推任务定义	注意它不公开标注过程日志，无法直接当监督信号
只想拿物种丰度做个快速探索	直接下载 MetaPhlAn 4.0 或 mOTUs 3.0 表，比自行跑管线快得多	读完下载页的缺失清单，避免把「没跑出来」当成「不存在」

1.5 一句话判断

如果你的问题里出现「跨研究」三个字，MetaLog 大概率能把你的准备时间从几个月压到几天；如果你的问题只在一个队列内部，用它反而是绕远路。

1.6 不适合谁：四条边界

不适合只做单队列分析的人。 单队列的元数据就在你自己手上，MetaLog 的统一字段对内部一致性没有帮助，反而多一层间接。你需要的是一张干净的样本表，不是一个跨库索引。

不适合把元数据当临床数据用的人。 人类样本字段里没有任何个体级的诊断编码、检验值、用药剂量、住院记录。bmi 有，subject_disease_status 有，但这些是摘要级别量。想做需要精细协变量的分析，得去要原始队列数据。

不适合需要完整时间序列建模的人。 时间点字段存在，但研究之间对「第 0 天」的定义不统一，且不少研究明确因为无法可靠对齐而把该字段留空。做纵向建模时，缺失不是随机的。

不适合要做严格流行病学推断的人。 样本的选择不是概率抽样，来自哪个国家、哪类人群，取决于谁做过研究、谁上传了数据。用它算患病构成比、算国家间差异，属于把便利样本当总体。

§2 数据构成与规格

本节先把结构讲清楚，再给字段字典，最后用一条记录走完全程。规模数字都带来源与时点，使用者不要把不同页面的数字混着用。

2.1 分层设计：为什么同一个样本会有三种字段

MetaLog 的字段不是平的，而是三层。理解这三层，比记字段名重要得多。

第一层是核心字段（curated metadata）。这是库方承诺的、每个样本都应该有的、跨研究可比的字段集合。它在四个栖息地模板下各自定义：人类模板关心人口学、疾病状态、用药；动物模板关心宿主物种与圈养状态；海洋模板关心滤膜孔径与盐度；环境模板关心深度、pH、年均温与年均降水。这一层是提供给批量分析用的。

第二层是部分统一化字段（partially harmonised）。这类字段只在部分研究里有，且统一化程度较低，通常带一个 _full 后缀的原始文本列并排存在。diet 与 diet_full、medication 与 medication_full、subject_disease_status 与 subject_disease_status_full 都是这个模式。统一列给你做分组，原始列给你回查。

第三层是研究特有附加字段。这一层完全不做跨研究统一，保留各研究自己的命名习惯。下载页对这类字段只提供长表，不提供宽表，原因写得很直白：宽表里会有大量半空的列。人类样本的附加字段有七十来个，从 bristol_stool_scale 到 donor_d28 都有，全都只在少数研究里出现。

三层结构对应三次下载选择。只下 core 是最省事的，下 extended 多一层可比字段，下 all 才能拿到全部细节但也最难用。

层	人类样本字段量级	下载文件体积（长表）	宽表是否提供	主要用途
核心字段	二十余个	约 20 MB	提供	批量筛选与合并分析
含部分统一化	再加一层 _full 列	约 22 MB	提供	需要原始文本回查分组
含全部研究特有	再叠七十余个	约 32 MB	不提供	单个研究的深挖

2.2 字段与记录的完整字典

下表按栖息地模板列出核心字段。这是本库最关键的一份清单：任何跨研究分析，能用的就是这些列。

字段名	含义	人类	动物	海洋	环境	统一化来源
environment_material	源材料	✓	✓	✓	✓	ENVO / UBERON
environment_feature	源材料所属的环境特征	✓	✓	✓	✓	ENVO
geographic_location	国家或海区	✓	✓	✓	✓	Natural Earth / Marine Regions
latitude / longitude	采样坐标	✓	✓	✓	✓	原始值
location	地名描述	✓	✓	✓	✓	GeoNames 部分支持
location_resolution	位置信息分辨率	✓	✓	✓	✓	自定义分级
sample_alias	原始样本别名	✓	✓	✓	✓	原始值
artificial	人工或特殊处理标记	✓	✓	✓	✓	自定义
filtration_lower_threshold_um	采集滤膜孔径		✓	✓	✓	原始值
filtration_upper_threshold_um	预滤膜孔径		✓	✓	✓	原始值
subject_disease_status	疾病状态	✓	✓			自定义受控取值
age_years / age_category	年龄与年龄段	✓	仅年龄			分箱规则
sex	性别	✓	✓			自定义
bmi	体质指数	✓				原始值
height_cm / weight_kg	身高体重	✓	✓			原始值
medication	用药	✓	✓			ChEMBL + ATC
diet	膳食	✓	✓			四大类粗分
intervention	干预类型	✓	✓			自定义
smoker	吸烟状态	✓				自定义
type_of_birth	分娩方式	✓				自定义
timepoint	距首次采样天数	✓	✓			相对天数
timeseries_available	是否有时间序列	✓	✓			布尔
host	宿主物种		✓			NCBI Taxonomy
strain	品种或品系		✓			原始值
captivity_status	圈养状态		✓			自定义
housing_lab / provider	饲养实验室与来源		✓			原始值
pooled_individuals	混样个体数		✓			原始值
depth_meters	水深			✓	✓	原始值
elevation_meters	海拔				✓	原始值
salinity	盐度			✓		原始值
temperature	温度			✓	✓	原始值
pH	酸碱度				✓	原始值
mean_annual_temperature	年均温				✓	气候数据集
mean_annual_precipitation_mm	年均降水				✓	气候数据集
protocol_label	采样方案标签			✓		原始值
sampling_platform	采样平台			✓		原始值
sampling_station	采样站位			✓		原始值
sample_alias	原始样本别名	✓	✓	✓	✓	原始值

这张表能读出一件事：统一化最深的维度是位置与材料，最浅的维度是临床细节。位置之所以能统一，是因为有 ENVO、Natural Earth、Marine Regions 这些现成本体可用；临床细节之所以浅，是因为「疾病状态」这件事在医学上没有一套各方都接受的分级，只能靠库方自己定一套受控取值。

2.3 一条记录的完整解剖

下面是一条人类样本记录在长表里的样子。长表一行是一个样本的一个字段，所以一个样本会展开成二三十行。字段值按官方长表的结构给出，具体值替换为一条典型记录的形态。

#-- 长表结构：每行一个 sample_id × field_name × value 三元组
metalog_sample_id	study_accession	field_name	value
MS-000123	ERP012345	subject_disease_status	healthy
MS-000123	ERP012345	disease_status_original	healthy control
MS-000123	ERP012345	age_years	34
MS-000123	ERP012345	age_category	adult
MS-000123	ERP012345	sex	female
MS-000123	ERP012345	bmi	22.4
MS-000123	ERP012345	geographic_location	Denmark
MS-000123	ERP012345	location_resolution	country
MS-000123	ERP012345	latitude	55.676
MS-000123	ERP012345	longitude	12.568
MS-000123	ERP012345	environment_material	feces
MS-000123	ERP012345	environment_feature	human-associated habitat
MS-000123	ERP012345	timepoint	0
MS-000123	ERP012345	artificial	no
MS-000123	ERP012345	medication	none

转成宽表就是一行：

#-- 宽表：每行一个样本，列即字段；空列大量存在
metalog_sample_id	study_accession	subject_disease_status	age_years	age_category	sex	bmi	geographic_location	location_resolution	timepoint	artificial
MS-000123	ERP012345	healthy	34	adult	female	22.4	Denmark	country	0	no

这两个格式的取舍决定了很多后续麻烦。长表适合「按字段筛」，也适合做字段级统计，因为不存在空列；宽表适合直接套进 R 或 pandas 做矩阵运算，但列数太多时读入会很重，且人类模板宽表与全字段长表之间的字段集合并不相同。

再看映射表。它才是把 MetaLog 接回公共归档的桥：

#-- 映射表（sequencing_db_mapping_latest.tsv.gz）字段示意
metalog_sample_id	external_sample_accession	run_accession	experiment_accession	database
MS-000123	SAMN01234567	SRR1234567	SRX1234567	SRA
MS-000123	SAMN01234567	SRR1234568	SRX1234568	SRA
MS-000456	ERS987654	ERR1111111	ERX1111111	ENA

注意第一行的样本出现了两个 run。一个生物样本可以被多次测序，这在纵向研究里非常常见。更麻烦的是反方向：某些作者把不同生物样本上传到同一个 biosample 登录号下，也有的把同一个样本拆成多个登录号上传。库方的处理是用自己的标识符贯穿全库，再用映射表把混乱的外部落号对齐过去。论文里说这一步靠 Mash 距离聚类辅助判断，遇到无法判定归属的情况（比如粪菌移植）就整组剔除。

2.4 四个栖息地的规模构成

站点统计页给出的分项如下。这里的数字都来自 2026 年 10 月的快照，与论文投稿时点的口径不同，后文会专门解释这个差额。

类别	样本数	占全部样本比例（约）	说明
人类	114929	七成二	含肠道、口腔、皮肤、阴道等部位
环境（土壤、沉积物、淡水等）	27076	一成七	模板字段最少，统一化最依赖原始值
动物	11243	百分之七	含实验室小鼠与野生动物
海洋	6062	百分之四	唯一以海区而非国家为地理单位
全部样本	159310	百分之百	对应 1097 项研究

人类样本内部还有一层拆分：114929 个样本对应 78473 名受试者。样本数大于人数，差额来自纵向随访——一名受试者可能贡献多个时间点的样本。这个差额本身就是一项信息：它说明本库里相当一部分人类数据是有时间维度的，不是横断面。

论文摘要给出的则是另一组数：人类 80423 个（其中肠道 66527 个）、动物 10744 个、海洋 5547 个、其他环境 23455 个，合计约十二万。站点一年多之后涨到接近十六万，增量主要来自持续纳入新研究。这个增长速率对使用者的意义是：任何引用都必须带抓取日期，否则复现不了。

2.5 与同类资源的字段差异

把 MetaLog 和几个近邻放在一起看，各自的分工很清楚。

资源	是否含原始序列	元数据是否人工统一	主体对象	与 MetaLog 的分工
ENA / SRA / DDBJ	含	否，作者自填	测序数据	MetaLog 的数据来源，二者互补
BioSample	否	否，仅最低要求	样本登记	MetaLog 的主要信息起点
MIMS 标准	否	是标准而非数据	字段定义	定义最小信息集，MetaLog 在其上扩展
SPIRE	衍生分析结果	共享同一套样本	功能与耐药注释	同一课题组的上游/下游，通过标识符相连
MGnify	含分析产物	部分自动化	微生物组分析管线	自动化程度高，人工校验少
GMrepo	否	是按表型整理	人类肠道	只做肠道，MetaLog 覆盖四类栖息地
curatedMetagenomicData	否	是	人体宏基因组 R 资源	以 R 包分发，MetaLog 以 TSV 分发

这张表最该注意的一行是 MIMS。很多人以为有了 MIMS 就不需要人工标注了，其实 MIMS 只是一份字段清单，规定「应该报告什么」，不规定「怎么填」。同一份 MIMS 表格，一百个课题组能填出一百种写法。这正是 MetaLog 存在的理由：标准定义字段，不定义取值。

§3 核心层 A：它到底是什么

3.1 一句话定位：一个注释层，不是数据仓库

把 MetaLog 放进整个宏基因组数据基础设施里看，它的位置非常明确：它位于归档之上、分析之下。上面是 INSDC 的原始 reads，下面是 SPIRE 的功能注释，它自己在中间，负责把「这段 reads 对应的生物材料是什么、来自谁、在什么条件下采集」这件事说清楚。

这个定位带来三个直接后果。第一，它的存储量很小，全部元数据加起来在百兆量级，一个普通笔记本就能装下；第二，它的价值与上游数据量几乎无关，而与其覆盖的研究数强相关——每多纳入一项研究，边际价值都比多存一 TB reads 高；第三，它的更新必须落后于上游，作者补交元数据、论文勘误、站点修正，都要靠人跟。

库方自己在关于页里说得很清楚：如果关心的研究不在 MetaLog 上，那多半还在待标注队列里。这句话透露的是产能约束——队列的长度由人工速度决定，而不是由数据可得性决定。

3.2 它只收什么，不收什么

纳入标准比很多人想的窄。

维度	收	不收	影响
测序类型	鸟枪法宏基因组（WGS）	扩增子（16S/18S/ITS）	大量经典微生物组研究不在其中
测序类型	鸟枪法宏基因组	宏转录组	无法做表达层面的跨研究比较
平台	Illumina 及兼容平台为主	长读长平台的系统性覆盖未见于官方说明	三代测序数据的样本可能缺位
栖息地	人类、动物、海洋、其他环境	无（四类之外暂不单列模板）	极端环境归入其他环境
归档	ENA、SRA、DDBJ 为主	少量 MG-RAST、CNSA 收录	中国提交的数据有一部分通过 CNSA 纳入
数据状态	已发表且有可用元数据	仅提交未发表、或元数据无从考证	未发表数据的样本基本不在库内

不收扩增子这一条影响最大。微生物组领域有大量经典队列用的是 16S，这些研究在 MetaLog 里查不到。如果你的文献池里 16S 占大头，MetaLog 能提供的帮助会被腰斩。

3.3 「MetaLog 标识符」为什么必须存在

这是本库设计里最容易被忽略、但用起来最先撞上的一个细节。

外行会想：既然样本都来自公共归档，那用 biosample 登录号当主键不就行了。库方的答案是不行，理由是双向的错配。一方面，同一个 biosample 登录号下可能被作者塞进了多个不同的生物材料；另一方面，同一份材料可能被拆成多个登录号提交。还有一种更隐蔽的情况：同一个受试者的多个时间点样本，被作者当成独立样本提交，没有做受试者内关联。

于是 MetaLog 自己维护一套标识符，并额外做一步受试者识别：用 Mash 距离对 reads 做聚类，按聚类形态人工判断哪些样本属于同一个人。这一步只有做了，纵向分析才可能；没做，timepoint 字段就只是一串孤立的数字。

代价是引入了一层间接。任何想从 MetaLog 回到原始数据的人，都必须走映射表，不能直接拿登录号拼接。这也是很多人第一次用就出错的地方。

§4 核心层 B：语义归一化的做工

4.1 归一化到底改了什么

用一个具体字段说清楚。geographic_location 在原始提交里可能是 USA、United States、U.S.A.、United States of America、美国 五种写法，来自同一批样本也可能混着写。MetaLog 的做法是把它们统一到 Natural Earth 的国家名，海区则统一到 Marine Regions 的 IHO 海区体系。

这一步看起来只是字符串清洗，实际上改变了后续所有分析的可行性。没有这一步，做国家层面 groupby 会得到五个互不相干的小组；有了这一步，才可能讨论「同一国家不同研究之间的差异」这种问题——而这正是领域里真正想问的问题。

更关键的是它同时提供了一个副产品：location_resolution。这个字段记录「这条位置信息精确到哪一级」。有的是国家，有的是城市，有的是精确坐标。没有这个字段，你会误以为所有 latitude/longitude 都是真实坐标，实际上很多是按国家质心填的，或者干脆是空的。

4.2 受控词表的三种来源

归一化不是一个动作，而是三种不同性质的技术，用途和风险各不相同。

来源类型	具体词表	用在哪些字段	风险
环境本体	ENVO	environment_material、environment_feature	本体演进，术语可能被废弃
解剖本体	UBERON	样本部位，如粪便、皮肤	覆盖以人兽为主，环境样本不适用
药物分类	ChEMBL、ATC	medication	多药并用时如何编码需人工判断
生物分类	NCBI Taxonomy	host	种级以上归类需人工决定层级
地理名录	Natural Earth、Marine Regions、GeoNames	geographic_location、location	地名变更与政治边界变化
自定义受控值	库方自定	subject_disease_status、diet、artificial	无外部标准可对照，主观性最强

最后一行是重点。前五类都有外部标准兜底：即使词表变了，至少有一个可追溯的版本。自定义受控值没有，它由库方定义，也只能由库方解释。artificial 这个字段就是一个典型例子：它标记的是 mock 群落、阴性对照、死后或古样本这类「不是普通生物样本」的情形。哪些算、哪些不算，判据在库方手里。

4.3 本体自身的不稳定，是一个真实存在的问题

论文对这一点的坦白值得单独拎出来。原文写：本体在持续演化，对全球栖息地的覆盖程度不一，无法总是提供精确匹配的术语；而且本体在变更时，可能会把广泛使用的术语标记为废弃，却不总给出明确的替代。

举的例子很能说明问题：ENVO 的 ENVO:00009003（human-associated habitat）被废弃了，而在此之前，它一直是 INSDC 里绝大多数人类宏基因组样本所用的栖息地标签。

这意味着什么？意味着 MetaLog 的一部分字段值在标注那一刻是对的，在几年后变成了历史遗留。使用者拿 2021 年的标注结果去做 2026 年的分析，必须知道这个字段当年映射到哪个版本。而库方不保留历史版本——关于页明确说不保留旧版存档。

这个组合（本体在变 + 库不留档）是使用 MetaLog 时最容易被低估的风险。它不是质量问题，而是时间性问题。

4.4 案例：丹麦那一列 country 怎么了

用一个具体例子把整条链路走一遍。这个案例在全文其余位置还会被反复引用。

设想你要回答一个问题：丹麦人群的肠道菌群里，拟杆菌门的相对丰度是不是比南欧高。这个问题听起来很平常，实际上是 MetaLog 这类资源最典型的用法。

第一步，你可能想直接去 ENA 按国家筛样本。这一步就会撞墙：ENA 的 country 字段是作者自填的，丹麦的样本可能写作 Denmark、DNK、Danmark，也可能写作 Copenhagen, Denmark，还可能写在 geo_loc_name 的一个复合字符串里，混着采集日期。直接做 GROUP BY country 得到的是几十个碎片。

第二步，换成 MetaLog。geographic_location 已经归一化成 Denmark，可以直接筛。但筛出来之后必须立刻看 location_resolution：如果这一列写的是 country，说明你只知道这些样本来自丹麦，不知道具体在哪；如果写的是 city 或更细，才有可能谈区域差异。

第三步，还要看研究分布。丹麦的样本大概率集中在少数几项研究里，而这少数几项研究的采样人群、年龄结构、膳食习惯都是特定的。你做出来的差异，很可能不是「丹麦 vs 南欧」，而是「某三项丹麦研究 vs 某五项南欧研究」。

第四步，丰度表这边也要对齐。三个 profiler 的覆盖样本数不同（mOTUs 与 MetaPhlAn 的可用样本量差了几千），必须用同一个 profiler 才能跨研究比较。

这四步里，MetaLog 只帮你做了第二步的一半——它把写法统一了，但没有、也不可能替你解决混杂。而绝大多数误用，恰恰是把第二步的成果当成了第四步的结论。§4.4 的案例在 §7.3 谈偏差、§9.2 谈流程、以及常见误读清单里还会再出现。

§5 核心层 C：怎么把它取到手

5.1 三条取数路径及其适用面

MetaLog 没有 REST API。这点需要先说清楚，否则很多人会去找一个不存在的接口。它能提供的是静态文件下载，加上一个可浏览可检索的站点。三条路径各有各的适用面。

路径	形态	适合谁	不适合谁	稳定性
静态 TSV 批量下载	站点 downloads 页的 gz 文件	要做定量分析的人	只想找一两项研究的人	文件名固定，内容随周末同步变化
站点检索与浏览	HTML 页面，按栖息地、字段值筛选	探索性查找、核对单条记录	需要程序化调用的人	页面结构可能调整
本地自建	下载后灌进 DuckDB 或 PostgreSQL	反复查询、团队共享	一次性使用者	完全自主，但需自行处理版本

第三条是大多数团队最终会走的路。元数据总量在百兆级，装进本机没有任何压力，一旦落库，所有后续查询都可以用 SQL 表达，比每次重下文件省事得多。

5.2 下载并核对签名

先做最基础的一件事：把文件拉下来，确认它真的是你要的那份。

#-- 建工作目录，全部文件用最新快照命名带日期，便于以后复现
mkdir -p ~/metalog/data && cd ~/metalog/data
STAMP=$(date +%Y%m%d)

#-- 人类样本三档长表：核心、含部分统一化、含全部研究特有字段
curl -fL -o "human_core_long_${STAMP}.tsv.gz" \
  https://metalog.embl.de/static/download/metadata/human_core_long_latest.tsv.gz
curl -fL -o "human_extended_long_${STAMP}.tsv.gz" \
  https://metalog.embl.de/static/download/metadata/human_extended_long_latest.tsv.gz

#-- 标识符映射表：把 MetaLog 样本接回 ENA/SRA/BioSample
curl -fL -o "mapping_${STAMP}.tsv.gz" \
  https://metalog.embl.de/static/download/sequencing_db_mapping_latest.tsv.gz

#-- 解压前先记下哈希，写进分析日志，日后核对快照是否变动
sha256sum *tsv.gz | tee checksums_${STAMP}.txt
ls -lh

-f 参数不是可选项。不用它，站点返回一个 404 页面时 curl 会把错误页当数据存下来，后面解压才报错，排查方向会被带偏。

5.3 用 DuckDB 建一个可查询的本地镜像

文件下来之后，第一件事不是画图，是确认表长什么样。

#-- 读长表并统计字段覆盖，注意长表每行是一个 样本×字段
import duckdb

con = duckdb.connect("metalog.duckdb")
con.execute("""
    CREATE OR REPLACE TABLE human_long AS
    SELECT * FROM read_csv_auto('human_extended_long_20261026.tsv.gz',
                                delim='\t', header=true, all_varchar=true)
""")

#-- 表结构核对：列名必须与官方字段名逐字一致
print(con.execute("DESCRIBE human_long").fetchdf().to_string())

#-- 每个字段有多少样本填了值（长表天然不含空列，空值就是没有行）
cov = con.execute("""
    SELECT field_name,
           COUNT(DISTINCT metalog_sample_id) AS n_samples
    FROM human_long
    GROUP BY field_name
    ORDER BY n_samples DESC
""").fetchdf()
print(cov.head(30).to_string())

这段代码的第三段是本库最该先跑的一步。长表里「字段缺失」表现为「没有这一行」，而不是「这一格是 NULL」。如果不先数一遍每个字段的实际样本量，后面做任何合并都会在不知不觉中丢掉大量样本。

5.4 长表转宽表，以及那些必须保留的辅助列

宽表适合做矩阵运算，但从长表转的时候要小心：不要一上来就把辅助列扔掉。

#-- 只挑少数核心字段转宽表，全转会得到一张极稀疏的大表
cols = ["subject_disease_status", "age_years", "sex", "bmi",
        "geographic_location", "location_resolution", "timepoint", "artificial"]

con.execute(f"""
    CREATE OR REPLACE TABLE human_wide AS
    SELECT metalog_sample_id, study_accession,
           {", ".join(f"MAX(CASE WHEN field_name = '{c}' THEN value END) AS {c}" for c in cols)}
    FROM human_long
    GROUP BY metalog_sample_id, study_accession
""")

#-- 过滤：人工样本里混有 mock 群落与阴性对照，相对丰度分析前必须剔除
con.execute("""
    CREATE OR REPLACE TABLE human_real AS
    SELECT * FROM human_wide
    WHERE coalesce(artificial, 'no') NOT IN ('yes', 'true', '1')
""")

print(con.execute("SELECT COUNT(*) FROM human_wide").fetchone(),
      con.execute("SELECT COUNT(*) FROM human_real").fetchone())

artificial 这一列的过滤条件不能省。论文写得很明确：mock 群落与阴性对照保留在下载数据里，做相对丰度分析前必须自行剔除，因为这些实验处理会扰动物种丰度。很多人第一次用 MetaLog 做菌群分析时结果里出现莫名其妙的「菌种」，多半就是没做这一步。

5.5 把元数据和丰度表接起来

分类谱是分开下载的，接的时候两边样本集合不一样大。

#-- MetaPhlAn 4.0 仅物种层级的丰度表
con.execute("""
    CREATE OR REPLACE TABLE mp4 AS
    SELECT * FROM read_csv_auto('human_metaphlan4_species_latest.tsv.gz',
                                delim='\t', header=true, all_varchar=true)
""")

#-- 两边样本交集，是后面一切统计的分母
con.execute("""
    CREATE OR REPLACE TABLE joined AS
    SELECT m.*, p.*
    FROM human_real m
    JOIN mp4 p ON m.metalog_sample_id = p.sample_id
""")

n_meta = con.execute("SELECT COUNT(*) FROM human_real").fetchone()[0]
n_join = con.execute("SELECT COUNT(*) FROM joined").fetchone()[0]
print(f"metadata-only {n_meta} / joined {n_join} / lost {n_meta - n_join}")

那个 lost 数字一定要打印出来并且看一眼。它的构成很杂：有的是测序数据缺失，有的是管线还在跑，有的是样本本身就没拿到 reads。下载页专门列了缺失清单，用它可以区分「本该有却没有」和「研究本身就没做」。把「没跑出来」当成「这个样本不存在」，是跨研究分析里最常见的静默错误之一。

5.6 用 R 走官方示例的路子

官方提供了一个 R 教程，演示从下载数据到细菌-用药关联分析的全过程。想快速理解库的用法，跟着走一遍比自己摸索快。

#-- 只读需要的列，人类扩展长表体积不大但列很多
library(data.table)
long <- fread("human_extended_long_20261026.tsv.gz",
              select = c("metalog_sample_id", "study_accession",
                         "field_name", "value"))

#-- 取用药字段，看它是怎么被归一化的
med <- long[field_name == "medication"]
cat("有用药字段的样本数:", uniqueN(med$metalog_sample_id), "\n")
print(head(sort(table(med$value), decreasing = TRUE), 20))

#-- 每个研究的样本量，用来判断国家或疾病层面的组是否被少数研究支配
per_study <- long[field_name == "sex", .(n = uniqueN(metalog_sample_id)),
                  by = study_accession][order(-n)]
print(head(per_study, 20))

最后一段的意图值得说明。做任何分组统计之前，先看每个研究贡献了多少样本，是判断结论是否被少数研究绑架的最快办法。这一步不需要任何统计工具，一行 table 就够。

5.7 接回原始序列

需要 reads 的时候，走映射表，不要直接拼登录号。

#-- 从映射表取某个 MetaLog 样本对应的全部 run
zcat mapping_20261026.tsv.gz | awk -F'\t' 'NR==1 || $1=="MS-000123"' > one_sample.tsv
cat one_sample.tsv

#-- 拿到 run 号之后回 ENA 取 fastq 的下载清单
while IFS=$'\t' read -r sample ext run rest; do
  [ "$run" = "run_accession" ] && continue
  curl -fsSL "https://www.ebi.ac.uk/ena/portal/api/filereport?accession=${run}&result=read_run&fields=run_accession,fastq_ftp&format=tsv" \
    | tail -n +2
done < one_sample.tsv

这段脚本的输出会告诉你 fastq 在哪里。注意它可能有多个 run，也可能一个都没有——如果该样本在 MG-RAST 或 CNSA 提交，ENA 查不到，得换源。下载页明确说了这两种情况都存在。

§6 与库内条目的关系

6.1 关系图谱

把 MetaLog 放进千方医数集已有的条目网络里，它的邻居分三类。

邻居类型	代表条目	关系	什么时候该用邻居而不是 MetaLog
上游归档	ENA、SRA、BioSample	MetaLog 的样本来源	需要序列、需要看作者原始填写
同类整合库	curatedMetagenomicData、GMrepo v3、MGnify	都在做元数据统一，对象与手段不同	只在人体肠道、且要 R 生态时用 cMD
单研究队列	American Gut Project、CKM 肠道宏基因组	可能被 MetaLog 收录	只想用一个队列、需要个体级变量时
下游分析	SPIRE 相关资源	共享样本标识，提供功能注释	需要耐药基因、蛋白功能注释时
标准与本体	ENVO、Uberon 相关条目	MetaLog 使用其术语	需要理解某个字段取值的语义边界时

这张图里最需要注意的是「同类整合库」一行。curatedMetagenomicData 与 MetaLog 经常被拿来比较，但两者的分界其实很清楚：前者只做人体、以 R 包分发、强绑定 MetaPhlAn 与 HUMAnN 管线；后者做四类栖息地、以 TSV 分发、物种谱给三种选择。做纯人体肠道的机器学习，前者更顺手；要跨栖息地或跨 profiler 比较，后者更合适。

6.2 检索路径

库内检索时，MetaLog 的位置在「元数据层」而不是「数据层」。按这个思路找邻居会快很多。

你想找的	在库内的检索方向	典型误入
原始 reads	归档类条目，关键词核酸序列归档	在 MetaLog 里找 fastq
已整理的丰度矩阵	整合库类条目	以为 MetaLog 就是丰度库
某个具体队列的详细变量	单研究队列条目	用 MetaLog 的摘要字段代替原始变量表
字段的语义定义	本体与标准类条目	以为 MetaLog 自己定义全部术语
与疾病关联的现成结果	疾病-微生物关联库	把 MetaLog 当关联结论库

正文的 §6.1 与 §6.2 之所以单独立节，是因为 MetaLog 的定位容易被误认成一个「什么都有一点」的数据集。它其实非常专一：只做注释，不做别的事。

§7 质量评估与局限性

7.0 阅读本节前的一个前置校正

在给 MetaLog 打分之前，需要先校正一个默认假设：多数人评估数据库时，习惯把「规模大」当成「质量高」的一部分。对测序数据仓库来说，这个假设大致成立，样本越多统计功效越好。对注释库来说不成立，而且方向相反。

原因在于标注成本。MetaLog 要增加一个样本，代价不是多存几百兆，而是有人要把这篇文章的补充材料读一遍、把每个字段填进去、再核对一遍登录号有没有错配。这是线性成本，没有规模效应。因此当一个注释库的规模在涨，几乎必然意味着两种可能之一：要么投入的人力在增加，要么单条记录的标注密度在下降。

这个校正直接改变了评估口径：对注释库，该问的不是「覆盖了百分之多少」，而是「它标注的那部分，标注得多可靠，以及没标的那部分，缺失是怎么分布的」。用覆盖率给 MetaLog 打低分，等于用错尺子。同样地，把它的字段直接当成 ENA 字段的更准版本，也是一次误判——两者回答的是不同问题，前者回答「论文里说了什么」，后者回答「提交时填了什么」。凡是把这两者混为一谈的分析，结论都不可靠。

7.1 五维评分

按千方医数集的 DAIMS 框架，五个维度各给一个判断。

维度	评分	依据	扣分原因
可得性（Availability）	优	ODbL 开放，无需注册，静态文件直下	无 API，程序化访问需自建
完整性（Completeness）	良	四类栖息地模板齐备，核心字段有承诺	只收 WGS，扩增子与宏转录组全无
一致性（Consistency）	优	字段名、取值、本体映射统一	附加字段保留原始命名，大小写并存
可追溯性（Traceability）	良	映射表可回到 INSDC，论文记录来源	不提供标注日志，无法核对单条判断
可持续性（Sustainability）	良	机构稳定、周更、有论文支撑	不留历史版本，本体变更会侵蚀旧标注

五项里没有一项是「满分」，但也没有一项是硬伤。这种分布本身说明它是一个成熟但受限于人力模式的资源，而不是一个尚未完工的项目。

7.2 三个真正的质量变量

不看评分，只问三个具体问题，得到的判断更实用。

第一，标注的一致性有没有被量化。 论文没有报告标注员之间的一致性指标，也没有描述双人复核流程，只在作者贡献表里列出了多名承担数据策展的人员。这意味着使用者无法从官方渠道得知「同一条记录被两个人独立标注时会不会一致」。这不是指控，而是信息缺口：如果一篇方法学论文要用 MetaLog 当基准，这个缺口必须自己补。

第二，字段的可得率是否被披露。 有。论文举了几个例子：人类样本的年龄段字段覆盖率约九成一，动物样本的圈养状态约九成九，海水样本的水深为百分之百。但组合字段的可得率会骤降——论文举例说，同时要求精确年龄与 BMI 的研究只能用上一万七千多个样本。这个落差是关键信息：单字段看起来都不错，一交叉就所剩无几。

第三，错误修正通道是否通畅。 通畅。每个研究页面底部有链接，可以直接到 GitHub 仓库报错。这是一个低成本、可追溯的修正机制，比邮件反馈好得多。

7.3 已知的、可枚举的偏差

论文自己列出的局限，加上从字段结构能直接推出的偏差，可以枚举成一张表。

偏差	方向	机制	对分析的影响
覆盖偏差	遗漏已发表研究	人工标注产能有限	你的文献池与库内研究池不是同一个集合
测序类型偏差	系统性排除扩增子	纳入标准限定 WGS	大量经典 16S 队列缺席
地理偏差	偏向西欧与东亚	谁做研究谁上传数据	国家间比较实际是比较研究
字段可得性偏差	临床论文常缺用药	原文只报疾病不报治疗	用药相关分析的可分析子集大幅缩小
混杂剔除偏差	药物与疾病完全重合的组合被删	无法区分效应	某些病种在用药维度上整体缺席
位置精度偏差	人类样本多只到国家	原文保护隐私或未记录	距离类分析含不确定度
时间轴偏差	无法可靠对齐时留空	研究间随访定义不同	纵向分析的有效样本小于名义样本
对照定义偏差	各研究对照含义不同	原文未标准化	病例对照合并时效应量不可比

倒数第二、三行的机制值得再展开一句。「无法可靠对齐时留空」听上去是个谨慎的设计，但它造成的是非随机缺失：被留空的恰恰是那些随访设计复杂的研究，而简单的前后对照研究通常填得很完整。于是纵向分析会系统性地偏向简单设计。

§4.4 的案例在这里得到第一次延伸：那个丹麦研究的问题，在这一层会变成「你筛出来的丹麦样本，来自几项研究、这些研究的入选标准是否可比」。

7.4 外部验证矩阵

MetaLog 的正确性可以怎么被外部检验？下表列出几条可行路径，以及每条路径能证明什么。

验证路径	具体做法	能证明	不能证明
回查原文	随机抽若干记录对照论文补充表	抽取准确性	无法覆盖全部记录
对照 BioSample	同一登录号两边字段比较	提交与原文的差异所在	孰对孰错
复现分类谱	自行跑 mOTUs 对比下载表	管线结果可复现	元数据是否正确
跨库交叉	与 curatedMetagenomicData 对照	两边一致的字段可信度更高	两边都错时无法发现
分析合理性	用已知生物学关系做阳性对照	字段语义可用	字段本身的具体取值
官方勘误	通过 GitHub 报错并跟踪处理	修正通道有效	未被报告的错误

第三条路径有一个容易忽略的价值：如果自行重跑 mOTUs 能得到与下载表一致的结果，就说明至少 reads 选取、QC、人源 reads 去除这几步没有系统偏差。这间接支持了元数据的样本对齐是对的。

7.5 它为何能持续：靠的是上游无人替代的那一步

一个只做人工标注、没有测序资源、没有垄断数据的库，凭什么活了这么多年并且还在扩？答案在于它承接的是一项上游归档从制度上不承担、下游分析又没有动力重复做的工作。

INSDC 的职责是存档与分发，不是校验语义。它没有立场去判断作者写的 USA 与 United States 是不是同一个国家，更没有立场去读一篇论文的补充表然后替作者补字段。而单个研究组虽然需要归一化的元数据，但每做一次跨研究分析就重做一次映射，成本被无限重复摊销。MetaLog 把这项工作集中起来做一遍，就同时替所有下游省掉了这笔重复开销。

这个逻辑成立的前提有两个：一是人工成本可以被一个稳定机构长期吸收（EMBL 与基金支持解决了这一点）；二是它的产出能被学术引用体系认可（NAR 数据库专刊的一篇论文解决了这一点）。两个前提都在，它就能持续；任何一个断掉，它的扩展就会停。这也解释了为什么它的增长是线性的而不是爆发式的——制约它的从来不是需求，是手。

§8 生态位与历史

8.1 历史沿革

阶段	时间	标志	意义
起步	2010 年代末	作为 Bork 组内部跨研究分析的附属产物	最初为解决本组自己的元数据混乱
公开化	站点上线，逐步开放浏览与下载	从内部工具变成公共资源	接受外部报错，进入社区维护
与 SPIRE 对接	SPIRE 发布后	共享样本标识，可链到功能注释	从「只有元数据」变成「元数据 + 功能」
体系化	NAR 2026 论文	四模板、三层字段、周更机制成文	有了可引用的方法学描述
持续扩展	至今	从论文口径十二万涨到站点口径近十六万	增量稳定，未见平台期

这张表里唯一没有确切年份的是起步阶段。官方页面没有给出站点上线日期，论文也没有明确写首次发布年份。这一点必须诚实标注为未核实，而不是凭印象填一个数。

8.2 生态位：它在谁和谁之间

用一个更直白的说法：MetaLog 是宏基因组数据流通链条上的翻译层。

上游是 INSDC 与其国家级伙伴，负责存。下游是 SPIRE 这类功能注释系统，以及各类分析管线，负责算。中间本该有一层负责「说清楚这是什么」，但这层在制度上没有归属，长期靠各研究组自己临时解决。MetaLog 就是把这层补上了。

它和 MIMS 的关系也在这个框架里：MIMS 定义了「应该说清楚什么」，MetaLog 提供「已经说清楚了的那部分实例」。标准与实例之间的差距，就是这一层存在的空间。

8.3 竞争者为什么没有把它替掉

同类资源不少，但没有一个能完全替代它，原因在于各自的边界选择不同。

curatedMetagenomicData 选择只做人体，换来的是与 R 生态的深度整合；GMrepo 选择只做人类肠道，换来的是表型检索的便利；MGnify 选择自动化管线，换来的是吞吐量。MetaLog 选择的是「四类栖息地 + 全人工」，换来的是跨栖息地的语义一致，代价是产量。

这个选择意味着它永远不会是最大的那个库，但它很可能是唯一能让你把海水样本和粪便样本放在同一张表里做字段级比较的那个库。这个独特性就是它的护城河。

8.4 版本与快照的现实

使用 MetaLog 必须接受一个现实：没有一个叫「版本号」的东西。

文件名固定为 _latest，内容是每周末同步的结果。关于页明确说不保留历史版本存档，理由之一是有研究可能被要求撤下。这意味着你无法通过「下载 v1.2」来复现去年的分析，只能靠自己在下载时存下哈希与日期。

这个设计对使用者提出了额外要求：

场景	必须做的事	不做会怎样
论文里报告样本量	记录抓取日期与分项数	审稿人复现时数字对不上
长期维护的管线	把数据文件纳入版本管理	上游变动后结果漂移无从归因
团队协作	共用同一份哈希锁定的快照	两个人跑出不同结果
引用	引用论文，而非站点	站点无版本，引用无法定位

§9 使用指引

9.1 三种角色的路径

不同的人进 MetaLog 的门是不同的。

角色	首要目标	建议路径	大致耗时
临床或公共卫生研究者	找可比对的队列	站点按栖息地与疾病状态筛 → 读研究页 → 去论文核对入选标准	一两小时
生物信息工程师	搭一条可复现的管线	下载文件 → 建本地库 → 接丰度表 → 记录哈希	半天
数据策展与标准研究者	学字段设计	读四套模板 → 对比三层结构 → 读论文方法学	一天

第一类人最容易犯的错是跳过「去论文核对」这一步。MetaLog 的研究页只给摘要级信息，入选标准、排除标准、对照定义都在论文里，不看就会误判可比性。

第二类人最容易犯的错是不建本地库，每次分析都重下文件。一旦站点内容变了，以前的脚本就无法复现。

第三类人最容易犯的错是只看字段名不看取值。artificial 这个字段名看不出它包含 mock 群落与阴性对照，必须读文档。

9.2 一条最短的可用流程

把前面的代码串起来，形成一条从零到可分析数据集的最短路径。

#-- 一条最短路径：下载 → 落库 → 过滤 → 合并 → 记录
import hashlib, datetime, duckdb

SNAP = datetime.date.today().isoformat()
FILES = {
    "human": "human_extended_long_20261026.tsv.gz",
    "map": "mapping_20261026.tsv.gz",
    "mp4": "human_metaphlan4_species_latest.tsv.gz",
}

#-- 第一步：登记快照，这是复现的全部依据
manifest = {"snapshot_date": SNAP, "sha256": {}}
for key, path in FILES.items():
    with open(path, "rb") as f:
        manifest["sha256"][key] = hashlib.sha256(f.read()).hexdigest()
print(manifest)

con = duckdb.connect("metalog.duckdb")

#-- 第二步：长表落库，全部按字符串读入，避免数值解析把 9999 占位值洗成有效数字
con.execute(f"""
    CREATE OR REPLACE TABLE human_long AS
    SELECT * FROM read_csv_auto('{FILES["human"]}',
        delim='\t', header=true, all_varchar=true)
""")

#-- 第三步：转宽表并剔除人工处理样本
con.execute("""
    CREATE OR REPLACE TABLE human_wide AS
    SELECT metalog_sample_id, study_accession,
           MAX(CASE WHEN field_name='subject_disease_status' THEN value END) AS disease_status,
           MAX(CASE WHEN field_name='geographic_location' THEN value END) AS country,
           MAX(CASE WHEN field_name='location_resolution' THEN value END) AS loc_res,
           MAX(CASE WHEN field_name='artificial' THEN value END) AS artificial
    FROM human_long
    GROUP BY metalog_sample_id, study_accession
""")
con.execute("""
    CREATE OR REPLACE TABLE human_clean AS
    SELECT * FROM human_wide
    WHERE coalesce(artificial, 'no') NOT IN ('yes', 'true', '1')
""")

#-- 第四步：接丰度表，并如实打印损失
con.execute(f"""
    CREATE OR REPLACE TABLE analysis_set AS
    SELECT h.*, p.* FROM human_clean h
    JOIN read_csv_auto('{FILES["mp4"]}', delim='\t', header=true, all_varchar=true) p
      ON h.metalog_sample_id = p.sample_id
""")
total = con.execute("SELECT COUNT(*) FROM human_clean").fetchone()[0]
kept = con.execute("SELECT COUNT(*) FROM analysis_set").fetchone()[0]
print(f"clean={total} joined={kept} dropped={total - kept}")

#-- 第五步：在合并之前，先看研究层面是否均衡（对应 §4.4 的案例）
print(con.execute("""
    SELECT country, COUNT(DISTINCT study_accession) AS n_studies, COUNT(*) AS n_samples
    FROM analysis_set GROUP BY country ORDER BY n_samples DESC LIMIT 20
""").fetchdf().to_string())

最后一步的输出是这条流程的关键。如果某个国家只有一个研究贡献了绝大部分样本，那么任何「跨国差异」的结论都要打折。§4.4 的案例在整篇里被反复提起，原因就在这里：流程的最后一步不是统计，而是看你的样本是怎么来的。

9.3 引用方式

引用 MetaLog 有两层，别只做一层。

层	引用什么	用途
数据库本身	站点 URL 与抓取日期	数据来源与可复现性
方法学论文	Kuhn 等，Nucleic Acids Research 2026, 54(D1):D826–D834, DOI 10.1093/nar/gkaf1118	说明字段定义与标注方法的出处
上游数据	各研究原始论文	具体队列的解读与限制

如果只引论文不引站点日期，无法知道你用的是哪个快照；如果只引站点不引论文，也无法知道字段是怎么定义的。两层都做才算完整。

§10 AI 使用声明

维度	声明
本页的内容来源	官方站点 about、downloads 与四个 metadata 页面；NAR 论文摘要与全文的方法、局限段落
是否使用生成模型辅助	是，用于组织文本与代码示例；事实均回查官方页面
数字的处理方式	分「官方页面称」与「论文摘要称」两类标注，冲突处并陈
代码是否可运行	示例按官方文件结构编写，下载路径已核实可达；未在本页执行
已知的信息缺口	标注员人数、标注一致性指标、首次上线年份
是否做过全量统计	否，本页不含任何自行统计的分布数字
更新责任	站点每周末更新，本页数字对应 2026 年 10 月快照
使用建议	决策前回查官方页面，尤其是样本数与字段清单

常见误读（避坑清单）

这张表里每一条都在实际使用中造成过返工，按出现频率排序。

常见说法	实际	证据
ENA 里的 country 字段可以直接 groupby	不能。该字段是作者自填自由文本，同一国家有五种以上写法，且有复合字符串	论文方法段对人工统一化流程的描述
MetaLog 的样本数就是某一年论文里的那个数	不是。论文快照约十二万，站点快照接近十六万，且站点内部也有两套口径	站点 about 统计页与论文摘要并列可查
一个 MetaLog 样本等于一个 BioSample 登录号	不等同。库方明确因双向错配而自建标识符	官方 downloads 页对映射表的说明
disease_status 里的 healthy 就等于健康对照	不完全。各研究对照定义不同，有的纳入无症状携带者	论文关于对照与混杂的讨论
下载表里全是真实生物样本	不是。mock 群落与阴性对照保留在数据中，需自行过滤	论文局限性段落与 artificial 字段设计
没有分类谱说明这个样本不存在	不是。可能测序数据缺失、管线延迟或正在补跑	下载页的缺失清单与分项说明
人工标注过的数据可以直接当金标准	不能。标注只解决语义归一，不解决事实正确，且一致性未公开量化	论文未报告标注一致性指标
位置坐标可以拿来算样本间距	慎用。人类样本多为国家级精度，按国家质心填充时距离无意义	location_resolution 字段与论文局限性（d）
MetaLog 和历史版本可以调出来复现	不能。官方不保留旧版存档，被要求撤下的研究会被移除	about 页关于版本存档的说明
用 ODbL 数据可以随便改完闭源分发	改后的衍生数据库也要 ODbL（share-alike），只有分析结果不受限	官方 downloads 页的许可说明

FAQ

Q1：MetaLog 和 ENA 的 BioSample 元数据是什么关系？
互补关系。BioSample 是作者自己填的提交记录，只受最低限度的 MIMS 约束，字段值不做语义校验；MetaLog 是第三方人工读回原文后重新填写的版本。同一个样本在两边可能对不上，那说明提交记录与原文不一致，而不是 MetaLog 抄错了。两边都该看，用途不同。

Q2：能不能只用 MetaLog 的元数据做统计分析？
能，但有几道必需的前置。人工样本里混着对照组与 mock 群落，必须按 artificial 剔除；跨研究合并要考虑研究层面的批次；合并前先看每个研究贡献了多少样本。MetaLog 不提供权重或抽样框，跨研究的设计仍要自己做。

Q3：MetaLog 可以直接反查原始测序文件吗？
通过映射表可以。下载页提供 MetaLog 标识符到 sample、run、experiment 的对照文件，一个外部登录号可能对应多个生物样本，反之亦然，所以必须走映射表而不能直接拼接登录号。少数样本在 MG-RAST 或 CNSA，需要换源。

Q4：MetaLog 的许可允许商用吗？
ODbL 1.0 允许商用，但有两个硬条件：署名，以及对衍生数据库采用相同许可。如果只是拿它做分析写论文，产出是结果而非衍生库，通常只需引用论文与站点。把整理后的元数据打包成自己的数据库对外提供，就要按 share-alike 处理。

Q5：为什么官方页面和论文里的样本数不一样？
时点不同。论文是投稿时的快照，站点每周末同步开发库。此外站点统计页与下载页给出的分项也存在几十到几百的差额，官方未说明差额构成。引用时必须注明快照日期，并说明采用的是哪一套口径。

Q6：MetaLog 提供物种丰度表吗？
提供，而且是统一重算的。可选 mOTUs 3.0、MetaPhlAn 4.0（全层级与仅物种两版）、SPIRE-mOTUs，另有成人粪便样本的肠型预测与微生物载量预测。部分样本因测序数据缺失或管线延迟暂时没有分类谱，下载页列出了缺失清单。

Q7：为什么我的样本筛出来只有几百个？
最常见的原因是把多个字段叠着筛。论文举例说，同时要求精确年龄与 BMI 时，可用的只剩一万七千多个样本。字段两两交叉就会急剧收缩。建议逐字段加条件，每加一个打印一次剩余样本量，找到断崖在哪一层。

Q8：同一个人的多次采样怎么识别？
库方用 Mash 距离聚类辅助识别，识别不了（如粪菌移植）就整组剔除。timeseries_available、timeseries_count、timeseries_duration 三个字段描述时间序列形态，但不能反过来据此重建个别受试者的轨迹。

Q9：字段名大小写混乱是数据质量问题吗？
不完全是。核心字段名是规范的下划线小写；附加字段保留各研究的原始命名，因此 Comorbidities 与 comorbidities 会并存。使用附加字段时必须先做一次大小写归一，否则会把同一概念当成两列。

Q10：可以把这个库当文献计量研究对象吗？
可以，但要知道它的研究集合不是文献全集。人工标注产能决定了它只能覆盖一部分已发表研究，用它统计「某个领域有多少研究」会系统性低估。做文献计量还是要用文献数据库。

Q11：如果我要的字段它没有，怎么办？
看附加字段。人类模板的附加字段有七十余个，从布里斯托大便分型到孕周都有，只是覆盖研究很少。如果附加字段里也没有，那就是原文没报，只能回论文或联系作者。

Q12：站点打不开或者下载失败怎么办？
先确认不是路径写错——下载文件的路径前缀是 /static/download/，不是根路径。再确认 curl -f 是否在报 404。若站点整体不可达，可考虑通过 Europe PMC 的论文补充材料了解结构，但数据本身只能从官方取。

术语表

术语	含义	与本库的关系
情境数据（contextual data）	样本在采集时的环境与宿主状态信息	MetaLog 的核心对象
鸟枪法宏基因组（WGS）	对样本全部 DNA 直接测序	MetaLog 唯一纳入的测序类型
扩增子测序	只测特定标记基因片段，如 16S	被明确排除
宏转录组	测样本中 RNA	被明确排除
INSDC	ENA、SRA、DDBJ 组成的国际合作体系	MetaLog 的主要数据来源
BioSample	INSDC 的样本登记层级	MetaLog 人工复核的起点
Biosample 登录号	样本登记的唯一标识	与 MetaLog 标识符不是一一对应
MIMS	宏基因组与环境序列的最小信息标准	规定字段清单，不规定取值
ENVO	环境本体	栖息地与材料字段的术语来源
UBERON	解剖本体	样本部位字段的术语来源
ChEMBL	生物活性分子数据库	单个药物的映射目标
ATC	解剖治疗化学分类系统	药物分组的映射目标
NCBI Taxonomy	生物分类命名体系	宿主物种字段的映射目标
受控词表	限定取值范围的术语集合	归一化的技术手段
本体废弃（obsolete）	术语被标记为停用	会导致旧标注与新标注不一致
栖息地模板	按样本类型定义的核心字段集合	人类、动物、海洋、环境四套
核心字段（curated）	每个样本都应有的可比字段	第一层，可直接跨研究使用
部分统一化字段	覆盖不全、统一程度较低的字段	第二层，常与原文字段并列
研究特有字段	保留原始命名的附加列	第三层，不做跨研究统一
长表	一行一个样本×字段	字段缺失表现为无行
宽表	一行一个样本，列即字段	便于矩阵运算，空列多
映射表	MetaLog 标识符与外部登录号的对照	接回原始序列的唯一入口
分类谱	各分类层级的相对丰度	由三个 profiler 预计算
mOTUs	基于标记基因的操作分类单元方法	分类谱来源之一
MetaPhlAn	基于标记基因的物种定量工具	分类谱来源之一
肠型	肠道群落的离散类型划分	仅成人粪便样本提供
微生物载量	单位样本中的微生物总量	仅成人粪便样本提供
占位值	用 9999 一类数值表示缺失	标注时被清理
artificial	标记人工或特殊处理样本	过滤对照组的关键字段
位置分辨率	位置信息精确到哪一级	判断坐标可用性的前提
快照日期	下载时的站点状态	复现与引用的唯一依据
ODbL	开放数据库许可，含 share-alike	本库的许可
DbCL	数据库内容许可	单条内容的许可
SPIRE	同课题组的宏基因组功能资源	与本库共享样本标识

附录 A：核心数字核对表

项	值	来源	来源层级
研究数	1097	站点 about 统计页	官方页面
全部样本	159310	站点 about 统计页	官方页面
人类样本	114929	站点 about 与下载页一致	官方页面
人类受试者	78473	站点 about 统计页	官方页面
动物样本	11243	站点 about 与下载页一致	官方页面
海洋样本	6062	站点 about 与下载页一致	官方页面
环境样本	27076	站点 about 与下载页一致	官方页面
论文口径人类样本	80423	论文摘要	论文
论文口径肠道样本	66527	论文摘要	论文
论文口径合计	约十二万	论文摘要分项相加	论文
人类核心长表体积	约 20 MB	下载页标注	官方页面
人类全字段长表体积	约 32 MB	下载页标注	官方页面
人类模板核心字段	二十余个	metadata 页面逐项计数	官方页面
人类模板附加字段	七十余个	metadata 页面逐项计数	官方页面
动物模板核心字段	26 个	metadata 页面逐项计数	官方页面
环境模板核心字段	17 个	metadata 页面逐项计数	官方页面
栖息地模板数	4	论文方法段	论文
人类年龄段可得率	约 91%	论文正文	论文
动物圈养状态可得率	约 99%	论文正文	论文
海水水深可得率	100%	论文正文	论文
站点最近更新	2026-10-13	metadata 页面页脚	官方页面
首次上线年份	未载明	官方页面与论文均未给出	未核实

附录 B：数字的来源分层

第一层：官方页面

站点 about 页的统计表、downloads 页的文件体积与样本分项、四个 metadata 页面的字段名与字段计数，都属这一层。这一层的特点是可直接复核，任何人打开页面都能看到。本页所有「样本数」「字段数」「文件体积」均出自此层。

同一层内部存在不一致：about 页统计表与 downloads 页的人类样本数一致，但研究数与论文口径差异明显。这类不一致不判对错，只按页面原文并陈。

第二层：论文摘要与正文

样本分项、字段可得率（九成一、九成九、百分之百）、组合字段可用样本量、四个模板的定义、本体的使用与废弃问题，出自 NAR 论文。这一层的可信度高但有时间戳：它是投稿时点的状态。

论文摘要与正文之间本身也有一处不一致：摘要给的人类样本数与正文数据库内容段给的不相同。原文未解释，本页按摘要口径引用，并在附录 A 中标注两层数字并存。

第三层：未核实

以下三项在官方页面与论文中均未找到明确表述：

项	状态	说明
首次上线年份	未核实	两处均未给出，本页不给推测值
标注员人数与复核机制	未核实	仅知有多名作者承担数据策展
标注一致性指标	未核实	论文未报告任何 kappa 类指标
长读长平台的系统覆盖	未核实	论文只提以 Illumina 及兼容平台为主
站点与下载页分项差额的构成	未核实	差额存在，官方未说明

附录 C：完整参考文献

1. Kuhn M, Schmidt TSB, Ferretti P, Głazek A, Robbani SM, Akanni W, Fullam A, Schudoma C, Cetin E, Hassan M, Noack K, Schwarz A, Thielemann R, Thomas L, von Stetten M, Alves R, Iyappan A, Kartal E, Kel I, Keller MI, Maistrenko O, Mankowski A, Nishijima S, Podlesny D, Schiller J, Schulz S, Van Rossum T, Bork P. Metalog: curated and harmonised contextual data for global metagenomics samples. Nucleic Acids Research, 2026, 54(D1): D826–D834. DOI: 10.1093/nar/gkaf1118. PMID: 41171125. PMCID: PMC12807751.
2. MetaLog 官方站点关于页：https://metalog.embl.de/about
3. MetaLog 官方站点下载页：https://metalog.embl.de/downloads
4. MetaLog 人类样本字段页：https://metalog.embl.de/metadata/human
5. MetaLog 动物样本字段页：https://metalog.embl.de/metadata/animal
6. MetaLog 海洋样本字段页：https://metalog.embl.de/metadata/ocean
7. MetaLog 环境样本字段页：https://metalog.embl.de/metadata/environmental
8. MetaLog 问题反馈仓库：https://github.com/grp-bork/metalog_issues
9. MetaLog 官方 R 教程：https://metalog.embl.de/static/metalog_tutorial/
10. SPIRE 数据库：https://spire.embl.de/
11. Environment Ontology (ENVO)：https://environmentontology.org/
12. UBERON 解剖本体：https://obophenotype.github.io/uberon/
13. ChEMBL 数据库：https://www.ebi.ac.uk/chembl/
14. ATC 分类系统（WHO）：https://www.whocc.no/atc_ddd_index/
15. NCBI Taxonomy：https://www.ncbi.nlm.nih.gov/taxonomy
16. Natural Earth：https://www.naturalearthdata.com/
17. Marine Regions：https://www.marineregions.org/
18. GeoNames：https://www.geonames.org/
19. GSHHG 全球自洽分层高分辨率地理数据库：https://www.soest.hawaii.edu/pwessel/gshhg/
20. Open Database License 1.0：https://opendatacommons.org/licenses/odbl/1.0/
21. Database Contents License 1.0：https://opendatacommons.org/licenses/dbcl/1.0/

附录 D：任务代码

如果目标是「用 MetaLog 做一次跨研究病例对照分析」，可以按下面这条命令链走。它把前面各节的要点串成一条可执行的路径。

#-- 任务：丹麦与西班牙成人粪便样本中，病例与对照的物种层面差异
set -euo pipefail
cd ~/metalog/data

#-- 1. 统计每个字段的实际样本量，找出哪些字段撑不起分组
python3 - <<'PY'
import duckdb
con = duckdb.connect("metalog.duckdb")
print(con.execute("""
    SELECT field_name, COUNT(DISTINCT metalog_sample_id) AS n
    FROM human_long GROUP BY field_name ORDER BY n DESC
""").fetchdf().head(20).to_string(index=False))
PY

#-- 2. 只保留两国成人粪便样本，并保留位置分辨率用于判断可信度
python3 - <<'PY'
import duckdb
con = duckdb.connect("metalog.duckdb")
con.execute("""
    CREATE OR REPLACE TABLE dk_es AS
    SELECT metalog_sample_id, study_accession, country, disease_status,
           loc_res, timepoint
    FROM human_wide
    WHERE country IN ('Denmark', 'Spain')
      AND coalesce(artificial, 'no') NOT IN ('yes', 'true', '1')
""")
print(con.execute("""
    SELECT country, study_accession, COUNT(*) AS n
    FROM dk_es GROUP BY 1, 2 ORDER BY 1, 3 DESC
""").fetchdf().to_string(index=False))
PY

#-- 3. 若某国样本集中在单一研究，先打印警告再决定是否继续
python3 - <<'PY'
import duckdb
con = duckdb.connect("metalog.duckdb")
df = con.execute("""
    SELECT country, COUNT(DISTINCT study_accession) AS n_studies, COUNT(*) AS n
    FROM dk_es GROUP BY 1
""").fetchdf()
for _, r in df.iterrows():
    flag = "WARN single-study" if r["n_studies"] == 1 else "ok"
    print(f"{r['country']}: studies={r['n_studies']} samples={r['n']} {flag}")
PY

第三段那个警告打印是本脚本的真正价值所在。两个国家的样本量可能相差十倍，但如果一国的数据全来自一项研究，这个比较在设计阶段就该被放弃。§4.4 的案例在这里被最后一回应了一遍：归一化解决的是写法，不是来源。

附录 E：如果只记五件事

第一，MetaLog 解决的是语义问题，不是数据量问题。它不给你序列，只给你一张把自由文本统一成受控取值的表。判断要不要用它，只问一句：你的分析是否跨研究。如果答案是否，它的价值会大幅缩水；如果答案是是，它几乎是你绕不开的一层。

第二，它的三层字段结构比字段内容更重要。核心字段可以直接用，部分统一化字段要用但要看覆盖，研究特有字段基本等于原始文本。混着用会出问题。

第三，三个必须做的前置动作：按 artificial 剔除对照与 mock，按 location_resolution 判断坐标能不能用来算距离，按研究看样本分布判断结论有没有被少数研究绑架。

第四，它没有版本号。文件名永远是 latest，内容每周末变，官方不留旧档。任何分析都必须自己记录快照日期与哈希。

第五，它最不可替代的一点是覆盖四类栖息地并且用同一套字段语言。这也是它永远做不大的原因：覆盖靠人手一份一份抄，抄不出规模效应。理解这一点，才能对它的规模有一个合理预期——不要指望某天它覆盖全部已发表研究，那一天不会到来，除非标注这件事本身被自动化。

编辑说明

核验时间：2026-10-26。核验方式：检索词「MetaLog metagenome metadata」定位到官方站点，随后直接抓取 about、downloads 与四个 metadata 页面的 HTML；论文走 Europe PMC 的 REST 接口按 DOI 取摘要与核心字段，正文方法段与局限段按 PMC 全文页读取。数字一律取自上述来源，未做任何自行统计，本页不含分布类统计、不含空值率交叉表、不含标签频次排序。

未覆盖与遗留：首次上线年份、标注团队规模、标注一致性指标三项在官方页面与论文中均未见明确表述，已在附录 B 标为未核实，未以推测值填充。站点统计表与下载页分项之间的几十到几百差额，官方未说明构成，本页只并陈不做判断。论文摘要与正文的样本数差异同理处理。

写作口径：正文所有单条判断均以官方页面或论文原文为据，「官方页面称」与「论文称」在必要处显式区分。代码示例按官方文件路径与字段名编写，未在本页实际执行，字段名以 metadata 页面的 field name 为准。

---

相关数据集导航

以下为站内 AI-Ready 数据集百科中与本词条共享多个主题标签的相关数据集，按相关度降序排列：

• bv-brc — 共享标签：基因组学与多组学 / 微生物组 / 公共卫生与流行病学
• ena — 共享标签：基因组学与多组学 / 微生物组 / 公共卫生与流行病学
• gbif — 共享标签：基因组学与多组学 / 微生物组 / 公共卫生与流行病学
• metasub — 共享标签：基因组学与多组学 / 微生物组 / 公共卫生与流行病学
• impc — 共享标签：基因组学与多组学 / 公共卫生与流行病学
• alphamissense — 共享标签：基因组学与多组学 / 公共卫生与流行病学
• gmrepo-v3 — 共享标签：基因组学与多组学 / 微生物组 / 公共卫生与流行病学
• hmp — 共享标签：基因组学与多组学 / 微生物组
• ckb — 共享标签：基因组学与多组学 / 公共卫生与流行病学
• mgnify — 共享标签：基因组学与多组学 / 微生物组

导航说明：本章节由全站统一标签体系自动计算生成（标签重合度算法），双向可达；点击链接可跳转至对应数据集词条。