信息速览

数据集名称HLCA — 人类肺细胞图谱 AI-Ready Wikipedia

数据类型49 个公开数据集整合,240 万+ 细胞 × 28,024 基因,486 名捐献者,61 种细胞类型标签,15 种疾病注释,CC BY 4.0 开放下载

规模486 名捐献者（HLCA core 107 名健康肺捐献者）

接入方式Human Cell Atlas — Lung Biological Network（Helmholtz Munich 等机构联合） url: https://github.com/LungCellAtlas/HLCA

AI 就绪度

数据集封面

HLCA — 人类肺细胞图谱 AI-Ready Wikipedia

INFOBOX


数据集名称	Human Lung Cell Atlas（integrated HLCA v1.0/v1.1）
英文全称	Human Lung Cell Atlas
别名/简称	HLCA、integrated HLCA、HLCA core、HLCA full（extension）
疾病分类	呼吸系统疾病多病谱（ICD-11：RA01 COVID-19 / CB03.2 特发性肺纤维化 / 2C25 支气管或肺恶性肿瘤等，共 15 种疾病注释）
SNOMED CT	840539006 COVID-19（其余疾病与细胞类型经 Cell Ontology CL: 术语注释，详见 §2.1b）
数据模态	单细胞 RNA 测序（scRNA-seq）+ 单核 RNA 测序（snRNA-seq）+ 细胞类型注释 + 人口学/临床元数据
AI 任务类型	细胞类型注释与标签迁移、参考映射、批次整合、罕见细胞类型识别、疾病共享细胞态发现、基因模块建模、GWAS 细胞类型归因
样本总数	2.4M+ 细胞 / 486 名捐献者 / 49 个数据集（core：584,944 细胞 / 107 名捐献者 / 14 个数据集 / 166 个组织样本）
数据大小	full 参考 embedding 2.4 GB（h5ad）；core 全量计数矩阵副本 17.35 GiB（CELLxGENE Census，截至 2024-02）
数据格式	AnnData h5ad / Seurat rds / CELLxGENE Census
许可证	CC BY 4.0（遵循 HCA Data Release Policy；少数源数据集 EGA 受控）
访问级别	开放（整合对象免费下载；少数源研究原始数据需 EGA 申请 + DAA）
DUO 标签	NRES, GRU
语言	英文
首发日期	2022-03-10（bioRxiv 预印本）/ 2023-06-08（Nature Medicine 正式发表）
最后更新	2023-05-10（HLCA v1.1：参考 embedding 与 GitHub 文档更新）
发布机构	Human Cell Atlas Lung Biological Network（Helmholtz Munich / UMCG Groningen / Northwestern 等多机构联合）
官方主页	https://github.com/LungCellAtlas/HLCA（landing page）/ https://data.humancellatlas.org/hca-bio-networks/lung/atlases/lung-v1-0
下载地址	https://cellxgene.cziscience.com/collections/6f6d381a-7701-4781-935c-db10d30de293（CELLxGENE）/ https://zenodo.org/record/7599104（模型与 embedding）
DOI	10.1038/s41591-023-02327-2（论文）/ 10.5281/zenodo.7599104（模型与 embedding）
引用次数	762+（Google Scholar，截至 2026-09）
AI 就绪度评分	⭐⭐⭐⭐（4/5）— 官方参考模型 + 多入口自动映射 + 全流程复现脚本；扣分项：无官方训练/测试划分、基因 counts 未批次校正、少数源数据需 EGA 申请
页面状态	published

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

医学审核：[千方病案医学编辑部] 交叉审核：§2 医学背景（呼吸系统疾病分类、ICD-11/SNOMED 双映射）、§7 偏倚分析（人群代表性、批次与技术混杂）。
数据工程审核：[千方病案医学编辑部交叉审核] 医疗 AI 数据工程师，审核范围：§4 DAIMS 数据字典、§5 数据划分策略、§6 预处理 Pipeline 和坑点。
审核日期：2026-09-05

医疗免责声明：本页面提供的医学信息仅供研究和教育目的，不构成医疗建议、诊断或治疗方案。数据集的医学描述基于公开发表的文献，未经逐一临床验证。任何基于该数据集训练的 AI 模型在应用于临床决策前，必须经过独立的临床验证和监管审批。

技术免责声明：本页面的代码示例、预处理建议和基准性能数据基于公开资料整理，不保证在特定环境下的准确性和适用性。使用者应自行验证代码安全性和数据预处理流程的正确性。千方病案医数集不对因使用本页面信息而导致的任何直接或间接损失承担责任。

数据使用合规：使用本页面描述的数据集前，请务必阅读并遵守数据集原始许可协议。HLCA 整合对象以 CC BY 4.0 开放提供；其纳入的少数源研究原始数据由 EGA 等档案受控管理，需另行申请并签署数据使用协议（DAA）。DUO 标签仅供参考，具体使用限制以数据集官方协议为准。

§1 数据集概览

§1.0 30 秒速览

这是什么？ HLCA（Human Lung Cell Atlas，人类肺细胞图谱）是一个把过去十年几十项人类肺单细胞研究"拼"到一起的大型参考图谱：49 个公开数据集、486 名捐献者、超过 240 万个细胞，覆盖鼻、上下气道与肺实质，健康与疾病并存（Sikkema et al., 2023, Nature Medicine）。它提供了第一份由 6 位独立肺专家共识形成的 61 种细胞类型统一"词典"。

为什么重要？ 单个研究通常只有少量捐献者，且各家对细胞类型的命名互相打架。HLCA 用 scANVI 把 14 个健康肺数据集整合成 core 参考，再用 scArches 把 35 个疾病数据集映射上去，让任意新数据可以"对号入座"，快速获得跨研究一致的细胞标签与疾病解读框架（HCA Lung Atlas 页）。

我能用它做什么？ 给你的肺单细胞数据做自动注释与标签迁移；发现未知或受疾病影响的细胞状态；分析年龄、性别、BMI、吸烟与气道位置相关的基因模块；把 GWAS 肺疾病风险位点归因到具体细胞类型；或把它当作单细胞整合与注释方法的基准数据（GitHub README）。

§1.1 技术摘要

HLCA 的构建分两步。第一步，研究团队收集了 14 个数据集（11 个已发表 + 3 个未发表）的健康肺 scRNA-seq 数据与统一化的技术、生物学、人口学元数据，共 107 名个体、166 个组织样本；样本解剖位置被投影到一条 0（近端鼻/气道）到 1（远端肺实质）的一维公共坐标框架（CCF）上；团队用 scANVI 将这些数据整合为 HLCA core，并基于原始注释加 6 位独立肺专家的注释达成共识重注释，产出 61 种细胞身份标签、5 个注释层级（从 coarse 到 fine）及匹配的共识 marker 基因（Nature 正文）。第二步，35 个包含肺疾病供者的后续数据集经 scArches "手术"映射到 core 上，继承共识标签与整合嵌入，形成约 2.3M 细胞的 full HLCA（HCA Atlas 页）。映射同时输出每个细胞的标签迁移不确定性，用于识别潜在新细胞态与疾病受累细胞（scArches 教程）。需要特别注意：HLCA 只对低维嵌入做了批次校正，基因 counts 本身未做批次校正（HCA Atlas 页）。

「液滴型 + 平板型」「细胞 + 单核」的组合意味着计数深度、基因检出与质控分布都存在系统性差异——这既是 HLCA 覆盖多种组织与供者状态的代价，也是它作为整合基准的价值：任何整合与映射方法都会在这些真实协议差异上被检验。使用者应把 assay 字段当作一等公民纳入分析设计，而不是事后补录的注释。

从数据工程视角看，HLCA 的发布形态是一套「数据 + 模型 + 文档」三件套：CELLxGENE 侧提供可直接分析的全量对象；Zenodo 侧提供带 md5 校验的参考 embedding 与 scANVI 模型资产（Zenodo DOI 页）；GitHub 侧提供逐字段元数据说明（HLCA_metadata_explanation.csv）与全流程复现脚本（HLCA_reproducibility 仓库）。三件套相互独立、各自可版本锁定，下游既可以「只借标签体系」，也可以把整条映射流水线全部复用——这是它区别于一般单细胞数据发布的关键设计。

§1.2 战略价值

维度一：作为"普通话词典"的参考价值。 单细胞领域最贵的问题不是算力而是标注口径——同一群细胞在 10 篇论文里有 10 个名字。HLCA core 的 61 标签 × 5 层级共识注释为整个肺单细胞社区提供了可对齐的命名标准，预印本口径下原数据集中 59% 的细胞被修正了注释（bioRxiv 预印本）。任何新的肺数据集只要映射到 HLCA，就能继承这套标签体系，大幅降低跨研究比较的成本。共识注释还附带匹配的 marker 基因，让标签可以被独立验证而不只是「权威口径」。

维度二：作为人口尺度图谱的统计功效。 486 名捐献者带来的多样性（年龄 10-76 岁、60% 男性/40% 女性、65% 欧洲血统、52% 从不吸烟等，见 §2.4）让单个研究不可能回答的问题变得可回答：与年龄、性别、BMI、吸烟相关的基因模块，以及沿近端-远端轴变化的基因程序（Nature 正文）。同时，把 15 种疾病的数据映射到同一健康参考上，使跨疾病共享病理状态（如 SPP1+ 促纤维化巨噬细胞）的识别成为可能。

维度三：作为工程范式的可复现价值。 HLCA 的发布链条（预印本 → v1.0 → v1.1 → Census 快照，见 §1.4）每一步都有可锁定的版本资产：Zenodo 提供文件 md5、GitHub 文档随版本更新、Census 提供固定维度快照（584,944 × 28,024）。对需要在生产环境使用参考图谱的团队而言，这种「论文—代码—模型—数据」四位一体的发布方式本身就是可借鉴的工程模板（Zenodo DOI 页）。

§1.3 同类数据集横向对比

数据集	规模	组织/阶段	标注	与 HLCA 的差异化
HLCA（Sikkema 2023）	2.4M+ 细胞 / 486 捐献者 / 49 数据集	健康与病肺（15 种疾病）；年龄 10-76 岁	6 专家共识，61 标签 × 5 层级	首个大型整合参考；自带 scANVI/scArches 映射体系
Travaglini et al. 2020（"HLCA"同名前作）	约 75,000 细胞 / 58 种细胞群	健康成人肺与血	多路注释，含解剖定位	更小更早，专注解剖定位；缩写撞车需分辨（见坑点 1）
Human fetal lung cell atlas	12 名胎儿供者 / 8 发育阶段	胚胎期肺（受孕后 5-22 周）	14 大类 / 144 亚型	覆盖发育窗口，与 HLCA（10-76 岁）互补不重叠
HBCA（Human Breast Cell Atlas）	800,000+ 细胞 / 55 捐献者	成人乳腺	11 大类 / 41 亚群	同为器官级参考图谱，器官不同，常并列为参考范式

选型提示：做肺研究直接用整合版 HLCA；引用文献时先核对年代与规模（约 75,000 细胞 → Travaglini；2.4M+ 细胞 → Sikkema）；发育期问题交给 fetal atlas。三者的详细区分见坑点 1。

§1.4 版本时间轴

时间	版本/事件	说明
2022-03-10	bioRxiv 预印本（doi:10.1101/2022.03.10.483747）	早期规模口径：46 个数据集 / 220 万细胞 / 444 名个体；59% 细胞重注释
2023-03-30	Nature Medicine 接收	规模扩展至 49 数据集 / 240 万细胞 / 486 名个体
2023-05-10	HLCA v1.1（GitHub 文档与 Zenodo embedding 更新）	HLCA_full_v1.1_emb.h5ad（2.4 GB）上线，surgery 模型齐备
2023-06-08	Nature Medicine 正式发表（v1.0）	DOI 10.1038/s41591-023-02327-2，成为 HCA 官方 Lung Atlas v1.0
2024-02-02	CELLxGENE Census 快照	core 584,944 × 28,024 副本（17.35 GiB）进入 Census 生态

版本选择经验：正文分析与映射默认用 v1.1 资产（Zenodo）与 CELLxGENE 当前对象；复现 2024 年前后的第三方结果时改用 Census 快照锁定维度；引用数字时按 §1.4 口径注明版本。

§1.5 典型应用场景

新数据自动注释：将自有肺单细胞数据经 scArches 映射到 HLCA core，一次获得 5 个层级的共识标签与不确定性估计（scArches 教程）。
跨疾病共享病理状态发现：在 full HLCA 上识别 COVID-19、肺纤维化与肺癌共有的 SPP1+ 促纤维化单核细胞来源巨噬细胞态（论文摘要）。
人口学协变量建模：利用 486 名捐献者的人口学多样性，估计年龄、性别、BMI、吸烟相关基因模块及近端-远端轴基因程序（Nature 正文）。
GWAS 细胞类型归因：将肺疾病遗传风险信号映射到 HLCA 细胞类型上，定位疾病相关细胞（Nature 正文）。
方法基准测试：作为大规模整合/注释方法的公共基准（core 584,944 × 28,024），被整合方法评测研究采用（基准研究数据集描述）。
教学与图谱范式研究：HLCA 是「如何建造一个器官级参考图谱」的活教材，配套方法论论文与全公开复现脚本，适合作为图谱工程的参考实现来研读。

§2 医学背景

§2.1 ICD-11 疾病编码映射

HLCA 的疾病注释以源研究的疾病标签为准，其中经同行评审文献明确验证的三类代表性疾病与 ICD-11 对应如下：

疾病标签（HLCA）	ICD-11 编码	ICD-11 中文名	备注
COVID-19	RA01	COVID-19（病毒已确认）	疫情催化了 HCA 肺网络的数据整合（机构新闻稿）
Pulmonary fibrosis（含 IPF）	CB03.2	特发性肺纤维化	属弥漫性实质性肺疾病大类
Lung carcinoma	2C25	支气管或肺恶性肿瘤	肺癌组织学亚型依源研究注释
normal（健康对照）	无编码	—	core 全部为健康肺组织

full HLCA 共包含 15 种疾病注释与 4 类组织（HCA Atlas 页），其余疾病编码随源研究标签，可在 CELLxGENE 元数据的 disease_ontology_term_id（MONDO 本体）中逐条追溯（Census 元数据结构）。使用建议：涉及具体病种的结论时，先在下载对象中按 disease 字段实际取值核对病种清单，再落笔——不同分发渠道的疾病标签粒度可能随源研究注释而异。

§2.1b SNOMED CT 与细胞本体映射

HLCA 的细胞类型标签在 CELLxGENE 分发中以 Cell Ontology（CL:）术语编码，疾病以 MONDO 编码，构成"疾病（ICD-11/SNOMED/MONDO）+ 细胞（CL）"双层本体映射：

标签	ICD-11 / MONDO	SNOMED CT / CL 编码	术语
COVID-19	RA01	SNOMED CT 840539006	COVID-19 (disorder)
健康对照	—	MONDO 对应 PATO 正常态	normal
alveolar macrophage（肺泡巨噬细胞）	—	CL:0000583	alveolar macrophage
macrophage（巨噬细胞）	—	CL:0000235	macrophage
monocyte（单核细胞）	—	CL:0000576	monocyte
T cell（T 细胞）	—	CL:0000084	T cell
B cell（B 细胞）	—	CL:0000236	B cell
NK cell（自然杀伤细胞）	—	CL:0000623	natural killer cell
endothelial cell（内皮细胞）	—	CL:0000115	endothelial cell
fibroblast（成纤维细胞）	—	CL:0000057	fibroblast
ciliated cell（纤毛细胞）	—	CL:0000064	ciliated cell
goblet cell（杯状细胞）	—	CL:0000160	goblet cell
epithelial cell（上皮细胞）	—	CL:0000066	epithelial cell

完整 61 标签 × 5 层级的对应关系由官方发布（GitHub README）；逐细胞的 ontology term id 可在下载对象的 obs 层直接读取（Census 元数据结构）。

§2.2 疾病与组织背景简介

肺是一个细胞类型高度多样的器官：气体交换发生在远端肺泡，而近端气道依赖纤毛细胞与杯状细胞完成清除与黏液分泌，不同取样位置（鼻、支气管、肺实质）的细胞构成差异巨大——这正是 HLCA 引入 1D 近端-远端坐标框架的原因（Nature 正文）。full HLCA 覆盖的疾病谱以感染性（COVID-19）、纤维化性（肺纤维化/ILD 类）与肿瘤性（肺癌）三大类为代表。跨疾病分析发现，SPP1+ 促纤维化的单核细胞来源巨噬细胞同时出现在 COVID-19、肺纤维化与肺癌中，提示一条共享的病理细胞程序（论文摘要）。需要强调：HLCA 是研究型资源，其疾病数据为公开研究的整合，不代表临床流行病学分布。

从组织学看，HLCA 的注释体系按 compartment 组织细胞类型（上皮、免疫、内皮、基质等，官方 Figure 1 口径），不同取样位置的细胞构成差异显著——远端肺实质以 AT 细胞与肺泡巨噬细胞为主，近端气道则富集纤毛与杯状细胞，鼻黏膜另有独立构成。这一「位置 × 细胞类型」的结构正是 1D CCF 坐标存在的意义：它让「近端-远端基因模块」这类位置相关分析成为可能。疫情背景同样是理解该图谱的钥匙：2020 年初全球肺单细胞社区为研究 COVID-19 快速集结为 HCA 肺网络，随后演变为全谱系数据整合工程（机构新闻稿）。

§2.3 临床/研究任务定义

任务类型	在 HLCA 语境下的定义	输入/输出
细胞类型注释（label transfer）	将新数据的细胞映射到 core 参考并迁移 5 层级共识标签	输入：raw counts h5ad；输出：每细胞标签 + 不确定性
新细胞态/疾病态发现	利用映射不确定性高亮与参考健康细胞不符的细胞群	输出：候选未知细胞态、疾病受累细胞
批次整合	将 49 个来源数据集对齐到统一低维嵌入	输出：batch-corrected embedding + UMAP
协变量基因模块分析	估计年龄/性别/BMI/吸烟/解剖位置相关的表达程序	输出：细胞类型 × 协变量的基因模块
GWAS 归因	将肺疾病遗传风险与细胞类型表达特征关联	输出：疾病-细胞类型关联
层级选择	在 5 个注释层级（coarse → fine）中为下游任务选择合适粒度	输入：映射结果；输出：层级化标签

§2.4 患者人群表

HLCA core 的人群构成（统一化元数据口径，Nature 正文）：

维度	分布	说明
来源	14 个数据集（11 已发表 + 3 未发表）	107 名个体 / 166 个组织样本
年龄	10-76 岁	无胚胎/胎儿样本（发育期数据见独立 fetal atlas，见坑点 1）
性别	男性 60% / 女性 40%	—
血统（统一化）	欧洲 65% / 非洲 14% / 混合美洲 2% / 混合 2% / 亚洲 2% / 太平洋岛屿 0.4% / 未注释 14%	非洲与美洲混合血统、亚洲人群代表性有限
吸烟状态	从不 52% / 曾吸 16% / 当前 15% / 未注释 17%	—
BMI	20-49	—
就医类型	健康肺组织供者（手术/捐赠来源）	core 全部为 normal

full HLCA 在 core 之上加入 35 个疾病数据集的供者（累计 486 名），疾病组的人口学构成随各源研究而异，逐字段说明以官方元数据字典为准（GitHub）。

§2.5 临床价值定位

HLCA 的直接价值在科研与转化侧：为医生与科学家提供理解健康与疾病肺生物学的中央资源，新疾病数据可映射到 HLCA 上加速解读，被视为实现完整 Human Cell Atlas 里程碑上的首个大型器官级参考（机构新闻稿引述）。它不直接产出临床诊断，但为疾病机制假设（如跨疾病共享纤维化程序）、药物靶点细胞定位与生物标志物发现提供细胞级地图。对医院与药研场景，HLCA 的典型用法是「先映射、再比较」：把自有疾病数据映射到统一健康参考上，从而在与文献可比的坐标系中寻找疾病特异细胞态。

§2.6 金标准对照表

属性	HLCA 的做法	性质
划分方式	core（14 数据集/107 人）训练参考模型；extension（35 数据集）作为映射查询	参考/查询结构，非 train/test
标注方式	原始作者标签 + 6 位独立专家逐类共识重注释	人工 + 共识
标注者资质	6 位独立肺单细胞领域专家	领域专家
一致性机制	跨 5 个层级的共识标签与匹配 marker 基因	多层级收敛
解剖坐标	1D 近端-远端 CCF（0-1）	结构性设计
标签层级	5 个层级（coarse → fine）按需选用	结构性设计
参考模型	scANVI 参考模型 + scArches 手术适配器（Zenodo 固定版本）	可复用模型资产

§3 数据集规格

§3.0 版本抉择矩阵

你的需求	推荐版本	大小	理由
给新数据做标签迁移/注释	core 参考 embedding + 模型（Zenodo 7599104）	2.4 GB（emb）+ 10.6 MB（模型）	只需参考嵌入即可 scArches 映射，省时省内存（scArches 教程）
健康肺人群分析（年龄/性别/BMI/吸烟模块）	core（CELLxGENE）	584.9k 细胞副本	core 为完全整合+共识注释的健康参考
跨疾病共享态/疾病研究	full（CELLxGENE）	约 2.3M 细胞，15 种疾病	含疾病数据与迁移标签
方法基准测试（整合/注释算法）	core Census 副本	17.35 GiB	维度固定（584,944 × 28,024），快照可复现（截至 2024-02）
浏览式探索/教学	CELLxGENE 交互页	0（在线）	无需下载即可探索 core 与 full
R/Seurat 工作流	HCA Atlas 页 rds 下载	与 h5ad 同内容	不想引入 Python 环境的团队

§3.1 数据模态详情

HLCA 是纯转录组单细胞资源，同时纳入单细胞（scRNA-seq）与单核（snRNA-seq）两类测序研究（GitHub README），液滴型与平板型两种主流实验协议并存（论文 Methods 口径）。每个细胞携带：raw counts（存于 adata.raw.X）、归一化层、批次校正后的低维嵌入与 UMAP、5 层级细胞类型标签及迁移不确定性；每个供者携带统一化的人口学（年龄/性别/血统/BMI/吸烟）与技术（平台/协议/取样位置）元数据；每个样本携带 1D 近端-远端 CCF 坐标。逐层说明见 §4.1 字段字典。

§3.2 按子集样本数统计表

子集	细胞数	捐献者	数据集数	组织数	疾病数	来源
HLCA core	584,944（CELLxGENE 口径 584.9k）	107	14（11 已发表+3 未发表）	3	0（全部 normal）	Nature 正文 / HCA Atlas 页
HLCA full（extension）	约 2.3M（论文口径 2.4M+）	486（累计）	49（14+35）	4	15	HCA Atlas 页
基因维度	28,024（genes）	—	—	—	—	Census 数据页
组织样本（core）	166	—	—	—	—	Nature 正文
预印本口径（对照）	约 220 万	444（累计）	46	—	—	bioRxiv

引用提醒：46/444/220 万为 2022 年预印本口径，正式发表版为 49/486/240 万+；两者出现在不同文献中，引用前先确认版本（详见 §1.4 时间轴与坑点 1）。

§3.3 数据格式表

格式	内容	获取渠道
AnnData h5ad	raw counts + 归一化层 + 整合嵌入 + UMAP + 元数据	CELLxGENE 下载 / CELLxGENE Census
Seurat rds	同上内容的 R 对象（raw counts 在 seurat_object@assays$RNA@counts）	HCA Atlas 页提供（HCA Atlas 页）
参考 embedding h5ad	HLCA_full_v1.1_emb.h5ad（2.4 GB，core+extension 嵌入与元数据）	Zenodo 7599104
参考模型压缩包	scANVI 参考模型（10.6 MB）+ surgery 模型（181.2 MB）+ 基因顺序表（45.1 kB）	Zenodo 7599104（DOI 页）
元数据字典 CSV	HLCA_metadata_explanation.csv（逐字段说明）	GitHub 仓库 docs 目录（GitHub）
源研究原始数据	各源数据集原始测序数据（部分受控）	GEO 16 系列 / EGA 4 编号（bioRxiv Data availability）

§3.4 存储大小明细

对象	大小	口径与来源
HLCA_full_v1.1_emb.h5ad	2.4 GB	Zenodo 文件列表（DOI 10.5281/zenodo.7599104）；scArches 教程口径 2.3 GB
HLCA_reference_model.zip	10.6 MB	同上
HLCA_surgery_models.zip	181.2 MB	同上
基因顺序 CSV	45.1 kB	同上
core 全量矩阵（Census 副本）	17.35 GiB	Open Problems 数据页，截至 2024-02-02

磁盘预算建议：映射场景（embedding + 模型包）预留 ≥8 GB；重分析场景（core + full 全量对象）预留 ≥64 GB 并另备工作空间；任何场景都不建议把 17.35 GiB 的 Census 副本放进容器镜像层——挂载外部卷更稳。

§3.5 标注方式

标注分三层：其一，各源数据集的原始作者注释；其二，6 位独立肺专家的独立注释输入；其三，二者融合的共识重注释，最终形成 61 种细胞身份标签与匹配的共识 marker 基因（Nature 正文）。预印本口径显示原数据集中 59% 的细胞在共识重注后修正了注释（bioRxiv）。疾病数据的标签不是重新注释，而是由 core 经 scArches 映射迁移而来，并附逐细胞不确定性（HCA Atlas 页）。

对使用者而言，核心判断是：core 内的共识标签可信度最高（专家共识产物）；extension 内的标签是「core 给的」，其可信度要用映射不确定性来度量。两层标签不要等权使用，更不要混在同一组统计口径里。

§3.6 标注者资质与一致性

共识注释由 6 位独立肺单细胞专家完成（HCA Atlas 页）；注释结果以 5 个层级（coarse → fine）发布，允许使用者按置信需求选择层级。团队的对应/资深作者包括 Helmholtz Munich 的 Fabian J. Theis 与 Malte D. Luecken、Northwestern 的 Alexander V. Misharin、UMCG 的 Martijn C. Nawijn 等（机构新闻稿）。官方未发布逐标签的标注者间一致性系数，使用高细粒度层级的标签时应结合 marker 基因自行抽检。实操建议：研究类分析用中间层级（平衡粒度与稳定性），探索性分析可下探到最细层级寻找新亚群，跨研究比较默认用 coarse 层级以保证标签收敛。

§3.7 采集周期

HLCA 为既有研究的整合：core 的 14 个数据集中 11 个已发表、3 个为未发表新数据（Nature 正文），整合工作于 2020 年疫情初期由 HCA 肺网络启动（机构新闻稿），2022-03-10 以预印本发布，2023-06-08 正式发表。逐数据集的采样时间以各源研究为准，未在主文中统一给出；这一「跨研究时间跨度」也是版本敏感分析（时间戳处理，DAIMS #14）被标 ⚠️ 的原因。

§3.8 地域覆盖

数据由欧美多机构协作产生（Helmholtz Munich、UMCG Groningen、Northwestern、Duke、Stanford 等，作者列表）；core 捐献者统一化血统以欧洲为主（65%），非洲血统 14%，亚洲 2%，14% 未注释（Nature 正文）。在使用时应将 HLCA 视为"欧美人群偏重的肺参考"，跨人群外推需谨慎（见坑点 7）。另需区分「机构所在地」与「捐献者血统」：前者决定采集与处理流程（技术效应），后者是人口学变量（生物效应），两者在偏倚分析中应分开讨论。

§3.9 实验平台与协议

源研究覆盖多种取样方法（支气管镜刷检/活检、手术肺组织等）、实验协议与测序平台（液滴型与平板型并存、单细胞与单核并存），团队为部分数据集提供了统一的测序数据处理流水线（GitHub scRNAseq_pipelines，论文 Methods 口径）。逐细胞的 assay 元数据（含 EFO 术语编码）随对象分发（Census 元数据结构）。对整合敏感的下游任务（如批次校正效果评估），建议把 assay 与 batch 两个字段同时纳入分析设计，避免把协议效应误读为生物学效应。

§3.10 深度溯源链

层级	内容	载体
论文层	Sikkema et al., Nature Medicine 2023（DOI 10.1038/s41591-023-02327-2）	出版页
代码层	全流程脚本与 notebook（HLCA_reproducibility）	GitHub
数据层	CELLxGENE collection / Census 快照（截至 2024-02-02）	CELLxGENE
模型层	Zenodo 7599104（v1.1 embedding + 模型，含 md5）	Zenodo
源研究层	16 个 GEO 系列 + 4 个 EGA 编号（GSE135893、GSE143868、EGAS00001004082 等）	bioRxiv Data availability

溯源链使用方式：复现论文结果从代码层进入；引用规模数字从论文层进入；锁定分析环境从模型层（Zenodo md5）进入；追溯某个细胞的出身则沿「数据层 → 源研究层」逐级下钻（dataset_id → GEO/EGA 编号）。

§4 数据结构

§4.0 目录树

以"Zenodo 模型包 + CELLxGENE 数据"组合落盘为例，解压/下载后的目录结构如下：

hlca/
├── data/
│   ├── HLCA_core.h5ad                        # core：584,944 细胞 × 28,024 基因（CELLxGENE 下载）
│   ├── HLCA_full.h5ad                        # full：约 2.3M 细胞，15 种疾病（CELLxGENE 下载）
│   └── HLCA_full_v1.1_emb.h5ad               # 2.4 GB 参考 embedding（Zenodo 7599104）
├── model/
│   ├── HLCA_reference_model.zip              # scANVI 参考模型，10.6 MB（解压后）
│   ├── HLCA_surgery_models.zip               # scArches surgery 适配器，181.2 MB（解压后）
│   └── HLCA_reference_model_gene_order_ids_and_symbols.csv   # 参考模型基因顺序表，45.1 kB
├── docs/
│   └── HLCA_metadata_explanation.csv         # 官方逐字段元数据说明
└── queries/
    └── my_lung_sample.h5ad                   # 你自己的查询数据（raw counts in .X）

说明：data_root 即 hlca/；§6 代码中的路径拼接均以该目录为根；最小可用子集是 HLCA_full_v1.1_emb.h5ad + 模型包（映射场景，共约 2.6 GB）。

注意：CELLxGENE 下载的两个全量对象与 Zenodo 的 embedding 是三份独立文件；树中 HLCA_core.h5ad 与 HLCA_full.h5ad 为命名示意，实际文件名以下载页面为准。三份文件的角色分工见坑点 2。

§4.1 DAIMS 字段字典

字段名	类型	说明	示例值	AI 用途	观测误差	信息性缺失编码	取值范围
cell_type	category	共识细胞类型标签（5 层级之一）	Alveolar macrophages	分类标签、监督训练	专家共识误差；细层级更易分歧	无	61 种标签 × 5 层级
cell_type_ontology_term_id	category	CL 本体术语编码	CL:0000583	跨数据集对齐、知识图谱	—	无	CL: 术语集
tissue_ontology_term_id	category	组织本体编码	UBERON:0002048	标准化组织对齐	—	无	UBERON 术语集
assay_ontology_term_id	category	实验协议本体编码	EFO:0009922	协议分层、批次设计	—	无	EFO 术语集
donor_id	category	捐献者标识	donor_XX	donor 级划分防泄漏	—	无	486 个唯一值
tissue	category	取样组织	lung parenchyma	位置分层分析	取样部位记录粒度不一	无	3-4 类（core/full）
disease	category	疾病标签（MONDO 编码伴随）	pulmonary fibrosis	疾病态分析	迁移标签而非重注释（extension）	normal 表示健康	15 种疾病 + normal
development_stage	category	发育阶段（HsapDv 本体）	adult	阶段过滤	—	无	以成人为主（10-76 岁）
sex	category	生物学性别	female	协变量建模	—	少量 NA	male/female
self_reported_ethnicity	category	自报血统（HANCESTRO 编码）	european ancestry	公平性分析	自报口径差异	NA（core 14%）	HANCESTRO 术语集
assay	category	测序协议（EFO 编码）	10x 3’ v2	批次变量、协议分层	—	无	液滴型/平板型多协议
batch	category	批次标识（组织+供者+协议组合口径）	10x_XX_donor_YY	整合与回归变量	口径上下文相关	无	逐数据集自定义
anatomical_position（CCF）	数值	1D 近端-远端坐标（0 近端 → 1 远端）	0.42	位置相关基因模块	投影估计误差	部分样本缺失	[0, 1]
core_or_extension	category	层级标识（core/full-extension）	core	分层评估	—	无	core / extension
obsp knn_connectivities / knn_distances	稀疏矩阵	scArches 映射后 KNN 图	—	标签迁移、流形分析	依赖映射质量	—	n_cells × n_cells
obsm X_pca	数值矩阵	PCA/整合嵌入	—	下游模型输入	已批次校正（仅嵌入层）	—	n_cells × 嵌入维数
layers counts / normalized	稀疏矩阵	原始计数与归一化层	—	差异表达、重归一化	counts 未批次校正	—	584,944 × 28,024（core）
dataset_id	category	源数据集标识	—	溯源与 study 级划分	—	无	49 个唯一值
is_primary_data	bool	是否为原始测序数据（非计算派生）	True	区分 primary 与 derived 细胞	—	无	True/False
soma_joinid	int64	Census 全局细胞唯一 ID	—	快照级追踪	—	无	Census 编号域

字段语义的官方逐条解释见 HLCA_metadata_explanation.csv（GitHub docs 目录）与 Census 元数据结构页。

§4.2 标签分布

HLCA 的标签体系为 61 种细胞身份标签 × 5 个层级（GitHub README），按上皮、免疫、内皮、基质等 compartment 组织（官方 Figure 1 口径）。健康 core 中免疫与上皮细胞占比高，基质与内皮次之；full HLCA 因纳入疾病数据，巨噬细胞谱系（含 SPP1+ 促纤维化态）与成纤维细胞谱系的相对占比随疾病构成变化。逐标签精确计数随下载渠道与版本略有出入，建议以到手对象执行 adata.obs.cell_type.value_counts() 实测为准——本 Wiki 不引用未经核实的逐类计数。

两个层级下的标签分布差异本身就是研究对象：core 的分布反映健康肺的细胞构成，full 的分布反映「疾病数据可得性」——后者由 35 个源研究的采样策略决定，不是人群患病率。做任何占比类推断前，先回到这个区别。

§4.3 关键统计

统计项	数值	来源
总细胞数	2.4M+（full）	论文摘要
core 细胞 × 基因	584,944 × 28,024	Census 数据页
捐献者	486（core 107）	Nature 正文
组织样本（core）	166	同上
细胞类型标签	61 种 × 5 层级	GitHub README
疾病注释	15 种	HCA Atlas 页
数据集	49（core 14 + extension 35）	同上
预印本口径细胞数	约 220 万	bioRxiv
预印本口径数据集/捐献者	46 / 444	同上
专家注释人数	6 位独立肺专家	HCA Atlas 页
标签迁移不确定性	逐细胞输出	scArches 教程

§4.4 数据层级

HLCA 的天然层级为 研究（study）→ 捐献者（donor，486）→ 组织样本（sample，core 166）→ 细胞（cell，2.4M+）。与影像数据不同，单细胞数据没有"序列/切片"层；等价的风险单元是 donor 与 sample——任何模型评估都应在 donor 或至少 sample 级别上划分，防止同一供者的细胞同时出现在训练与测试集（详见 §5.3）。

一个实用推论：sample 级聚合（每样本数千细胞量级）常是「统计功效 vs 泄漏风险」的折中点——比细胞级稳健，比 donor 级保留更多样本量；若做推断统计，donor 级仍是金标准口径。

§4.5 缺失值与信息性缺失

core 元数据中的缺失以 NA 显式标注并具有信息性：血统未注释 14%、吸烟状态未注释 17%（Nature 正文）；extension 数据集的 core 无关字段（如疾病相关列）在 core 子集中整列为空，scArches 教程即通过删除全空列完成 core 子集清理（scArches 教程）。处理建议：人口学缺失勿用众数填补（会伪装偏倚）；建模时以显式"未知"类别保留，或做敏感性分析（§7.1）。

另外注意：Census 副本的 obs 字段与 CELLxGENE 原始对象可能存在细节差异（如 soma_joinid 为 Census 注入字段），跨渠道合并前先建立字段映射表并做小样本对拍。

§5 划分与使用建议

§5.1 官方划分

HLCA 不提供传统 train/test 划分——它的"官方结构"就是 core（健康参考，scANVI 整合）+ extension（35 个疾病数据集，scArches 映射） 两层（HCA Atlas 页）。做监督任务时需要自行构建划分。

把 core/full 双层结构当作「官方划分」使用时，一个稳妥的模式是：在 core 内做方法开发与调参，在 extension（疾病数据）上做迁移能力评估，最后用全新的外部数据做终验——三层递进，逐级收紧。

§5.2 社区惯例划分

划分口径	切分单元	回答的问题	适用场景
donor 级留出	donor_id	对新供者泛化准不准	监督任务默认口径
study 级留一	整个数据集	对新实验室/协议泛化准不准	泛化能力声明
映射式评估	查询数据集整体	与参考图谱契合度如何	注释/标签迁移任务

社区通行的做法即上述三类：donor 级按 donor_id 分组划分训练/测试集，是单细胞文献的默认防泄漏口径；study 级留一整个数据集做外推测试，检验跨实验室泛化，代价是批次效应会拉低表观性能；映射式评估用 scArches 把查询数据映射后核对标签准确率与不确定性，scArches 教程即以 Delorey 数据集样本为查询示例（教程）。三种口径回答的问题不同，论文成果报告建议至少覆盖前两者。

§5.3 泄漏风险（重点）

donor 级泄漏：同一供者的数千个细胞高度相关，随机细胞级划分会让模型"背下"供者而非学到生物学，指标虚高。务必 donor 级分组划分。
映射-评估闭环泄漏：若查询数据本身参与了参考模型的训练（或与 core 源研究同源），再用映射准确率报告泛化性能，属于自我引用。新研究应使用与 49 个源研究无重叠的数据做评估。
疾病变量吸收：官方明确建议不要把疾病状态当作 batch 变量输入映射——这会从嵌入中移除疾病特异效应，使下游疾病分析失效（mapping 仓库 README）。同理，也不要把 subject 当 batch。
版本错配：用 v1.0 参考训练、v1.1 参考评估（或反之）会让指标失去意义；任何对比实验都应锁定同一参考版本并在报告中声明。

§5.4 交叉验证建议

donor 级分组 K 折（K=5）是稳健起点；跨层级（coarse → fine）分别报告指标能暴露细粒度标签的不稳定；对稀有细胞类型建议做分层抽样并报告每类支持度，避免被宏观准确率掩盖。若用交叉验证做超参选择，fold 的切分变量（donor 而非细胞）必须与最终评估一致，否则会把「调参泄漏」引入最终指标。

§5.5 外部验证建议

优先选择与源研究无重叠、协议异质的公开肺数据集（如教程使用的 Delorey 数据样本，scArches 教程）；报告指标时同时给出标签迁移准确率与不确定性分布，并注明映射所用参考版本（v1.0/v1.1）以保证可复现。报告模板建议固定为五要素：参考版本 + 查询数据描述 + 评估层级 + donor 级指标 + 不确定性分布，方便后续研究复算。

§6 AI 就绪指南

§6.0 云端快速启动

最省事的入口是在线探索与自动映射，无需本地环境：CELLxGENE 提供 core 与 full 的交互浏览与下载（CELLxGENE collection）；FASTGenomics 提供浏览器内的自动化 HLCA 映射（FASTGenomics）；Azimuth 与 CellTypist 提供备选映射/标签迁移入口（GitHub README）。本地深度定制时再走 §6.1-§6.4 流程。

入口	形态	适合人群
CELLxGENE 交互浏览	在线可视化 + 下载	想先看数据的所有人
FASTGenomics 自动映射	在线流水线	无 GPU/无代码环境的用户
Azimuth / CellTypist	在线映射/标签迁移	快速参考（论文未验证路径）
本地 scArches 流水线	代码（本节其余部分）	生产环境与定制分析

§6.1 快速上手

代码预期目录结构：以 hlca/ 为 data_root，hlca/data/ 放 h5ad 数据，hlca/model/ 放模型包，hlca/queries/ 放查询数据（§4.0 目录树）；data_root 由环境变量 HLCA_ROOT 指定，代码内所有路径均 os.path.join(HLCA_ROOT, ...) 拼接；最小可用子集 = HLCA_full_v1.1_emb.h5ad（参考嵌入）+ 你的查询 h5ad。

import os
import scanpy as sc

HLCA_ROOT = os.environ.get("HLCA_ROOT", "hlca")
emb_path = os.path.join(HLCA_ROOT, "data", "HLCA_full_v1.1_emb.h5ad")

# 参考 embedding：包含 core（健康参考）与 extension（疾病扩展）
adata_ref = sc.read_h5ad(emb_path)
print(adata_ref)            # 观察规模与 obs 字段

# 只取 core 作为映射参考（参考模型在 core 上训练）
adata_core = adata_ref[adata_ref.obs["core_or_extension"] == "core"].copy()
# 删除 extension 专有、在 core 中全空的 obs 列（官方教程同款清理）
adata_core.obs = adata_core.obs.dropna(axis=1, how="all")
print(adata_core.shape)     # 预期约 584,944 细胞

预期输出要点：载入 v1.1 embedding 后，obs 中应能找到 core_or_extension 字段；core 子集行数应为 584,944 附近（不同快照可能有微小出入）；若该字段缺失，说明拿到的不是 v1.1 embedding 文件——回到坑点 2 核对文件身份。

§6.2 数据获取

渠道	内容	大小	适用
CELLxGENE collection	core（584.9k）与 full（约 2.3M）h5ad	数 GB 量级	探索 + 全量矩阵
Zenodo 7599104	embedding（2.4 GB）+ 模型（10.6 MB）+ surgery 模型（181.2 MB）+ 基因表（45.1 kB）	约 2.6 GB	映射与标签迁移
CELLxGENE Census	core 副本 584,944 × 28,024（17.35 GiB，截至 2024-02）	17.35 GiB	程序化拉取、复现快照
HCA Atlas 页	h5ad/rds 下载入口与说明	—	R/Seurat 用户
GitHub LungCellAtlas/HLCA	landing page + 元数据字典 CSV	<1 MB	文档与答疑（issue 入口）

# 方式一：Zenodo 固定版本（推荐用于映射，版本可锁）
mkdir -p hlca/data hlca/model && cd hlca
curl -L -o data/HLCA_full_v1.1_emb.h5ad \
  https://zenodo.org/record/7599104/files/HLCA_full_v1.1_emb.h5ad
curl -L -o model/HLCA_reference_model.zip \
  https://zenodo.org/record/7599104/files/HLCA_reference_model.zip
curl -L -o model/HLCA_reference_model_gene_order_ids_and_symbols.csv \
  https://zenodo.org/record/7599104/files/HLCA_reference_model_gene_order_ids_and_symbols.csv
# 校验 md5（Zenodo 页面提供：emb 文件 md5 4aa9167707141dd884ff0202b3ab1205）
md5sum data/HLCA_full_v1.1_emb.h5ad

# 方式二：CELLxGENE Census 程序化获取（core）
import cellxgene_census

with cellxgene_census.open_soma() as census:
    adata = cellxgene_census.get_anndata(
        census,
        organism="Homo sapiens",
        obs_value_filter='dataset_id == "hlca"',  # HLCA 数据集标识
    )
print(adata.shape)   # 584,944 × 28,024（截至 2024-02 快照）

少数源研究的原始测序文件为 EGA 受控访问（如 EGAS00001004082、EGAS00001004344），需提交申请并签署 DAA（bioRxiv Data availability）；对绝大多数下游任务，整合对象已足够。

EGA 受控数据的申请流程一般为四步：其一，在源研究文献或 Data availability 声明中定位 EGA 编号；其二，在 EGA 注册账号并提交数据访问申请，说明研究用途；其三，签署数据访问协议（DAA）并等待数据访问委员会（DAC）批准；其四，获批后下载。已知受控编号包括 EGAS00001004082、EGAS00001004344、EGAD00001005064、EGAD00001005065；再次强调：使用 HLCA 整合对象本身不需要走该流程。

§6.3 预处理全流程

HLCA 自身的整合已完成"归一化 + HVG + scANVI 整合"；使用者的预处理重点在两件事：查询数据对齐参考（映射场景），以及 counts 层的规范使用（重分析场景）。映射场景可以跳过 QC（官方流水线已处理参考侧数据）；对自有新数据，映射前做基础 QC 仍是好习惯。

# ---- 步骤 0（可选）：查询数据基础 QC ----
adata_q.var["mt"] = adata_q.var_names.str.startswith(("MT-", "mt-"))
sc.pp.calculate_qc_metrics(adata_q, qc_vars=["mt"], percent_top=None,
                           log1p=False, inplace=True)
print(adata_q.obs[["n_genes_by_counts", "total_counts", "pct_counts_mt"]].describe())
# 经验判断（需按协议校准）：基因数过低提示空液滴/死细胞，mt% 过高提示细胞质量差。
# 注意：HLCA 混合了液滴/平板、细胞/单核协议，QC 阈值不可一刀切，逐 dataset 检查更稳。

QC 之后的取舍原则：QC 过滤只应作用于你自己的查询数据，不要回头「清洗」HLCA 参考侧——参考的细胞构成已被专家共识注释背书，私自过滤会破坏映射语义。

import scipy.sparse as sp
import pandas as pd
import scanpy as sc

# ---- 步骤 1：载入查询数据，检查 .X 必须是 raw 整数 counts ----
adata_q = sc.read_h5ad(os.path.join(HLCA_ROOT, "queries", "my_lung_sample.h5ad"))
adata_q.X = sp.csr_matrix(adata_q.X)
assert (adata_q.X[:50, :50].data % 1 == 0).all(), ".X 必须是原始整数 counts"

# ---- 步骤 2：删除 obsm/varm 防止下游报错（官方教程同款） ----
del adata_q.obsm
del adata_q.varm

# ---- 步骤 3：基因对齐——按参考模型基因顺序重排，缺失基因补零 ----
gene_order = pd.read_csv(os.path.join(
    HLCA_ROOT, "model", "HLCA_reference_model_gene_order_ids_and_symbols.csv"))
# 官方教程提供按 ensembl id / gene symbol 两种对齐方式；缺失基因填 0

# ---- 步骤 4：设置 batch 变量（写入 adata.obs["dataset"]） ----
adata_q.obs["dataset"] = "my_study_1"   # 整个数据集作为一个 batch
# 注意：不要用 subject 作 batch；不要用疾病状态作 batch（§5.3）

# ---- 重分析场景（不映射、直接用 core counts） ----
adata_core_full = sc.read_h5ad(os.path.join(HLCA_ROOT, "data", "HLCA_core.h5ad"))
adata_core_full.X = adata_core_full.raw.X      # raw counts 在 adata.raw.X（HCA 页口径）
sc.pp.normalize_total(adata_core_full, target_sum=1e4)
sc.pp.log1p(adata_core_full)
sc.pp.highly_variable_genes(adata_core_full, n_top_genes=3000)

经 CELLxGENE Census 渠道获取的对象需做一次字段规整（部分字段为 Census 注入，与 CELLxGENE 原始对象命名不同）：

# ---- Census 渠道字段规整（跨渠道对齐） ----
# Census obs 注入字段：soma_joinid（全局细胞 ID）、dataset_id、tissue_general 等
# 保留分析所需字段并统一命名，避免与 CELLxGENE 原始对象合并时列名冲突
census_only_cols = ["soma_joinid", "dataset_id", "tissue_general", "is_primary_data"]
keep = [c for c in adata.obs.columns if c in census_only_cols
        or c.startswith(("cell_type", "donor", "tissue", "disease", "sex",
                         "assay", "self_reported"))]
adata.obs = adata.obs[keep]
# layers: Census 提供 counts 与 normalized 双层；确认 counts 为整数后设为 raw
adata.raw = adata[:, :].copy()

映射前自检函数——把坑点 5 的五项准备固化为代码，不通过即中止：

def validate_query_for_mapping(adata_q, gene_order_df):
    """映射前自检：返回问题清单，空列表表示通过。"""
    problems = []
    # 1) .X 必须是 raw 整数 counts
    vals = adata_q.X.data if sp.issparse(adata_q.X) else np.asarray(adata_q.X).ravel()
    if not (vals % 1 == 0).all():
        problems.append(".X 不是原始整数 counts")
    # 2) 基因覆盖（按 ensembl id 与 symbol 双口径检查）
    ref_genes = set(gene_order_df.iloc[:, 0].astype(str))
    if gene_order_df.shape[1] > 1:
        ref_genes |= set(gene_order_df.iloc[:, 1].astype(str))
    covered = ref_genes & set(map(str, adata_q.var_names))
    if len(covered) < 0.5 * len(ref_genes):
        problems.append(f"基因覆盖率过低: {len(covered)}/{len(ref_genes)}")
    # 3) batch 变量
    if "dataset" not in adata_q.obs.columns or adata_q.obs["dataset"].isna().all():
        problems.append("缺少 adata.obs['dataset'] batch 变量")
    # 4) obsm/varm 清理
    if len(adata_q.obsm) or len(adata_q.varm):
        problems.append("obsm/varm 未删除")
    return problems

<details>
<summary>查看：基于 scArches 的完整映射 + 标签迁移代码（约 40 行）</summary>

# 依赖（官方教程推荐）：scanpy>=1.9.3, scarches>=0.5.8, scvi-tools>=0.20.3
# 旧教程环境（scArches 0.3.5 + scvi-tools 0.8.1 + torch>=1.3,<=1.8）已过时，见坑点 4
import scanpy as sc
import scarches as sca

HLCA_ROOT = os.environ.get("HLCA_ROOT", "hlca")

# 1) 载入参考（core 子集）与查询（§6.3 已对齐基因）
adata_ref = sc.read_h5ad(os.path.join(HLCA_ROOT, "data", "HLCA_full_v1.1_emb.h5ad"))
adata_ref = adata_ref[adata_ref.obs["core_or_extension"] == "core"].copy()
adata_ref.obs = adata_ref.obs.dropna(axis=1, how="all")
adata_q = sc.read_h5ad(os.path.join(HLCA_ROOT, "queries", "my_lung_sample.h5ad"))

# 2) 加载 scANVI 参考模型（Zenodo 解压后目录）
ref_model_dir = os.path.join(HLCA_ROOT, "model", "HLCA_reference_model")
reference_model = sca.models.SCANVI.load_query_data(adata_q, ref_model_dir, freeze_dropout=True)

# 3) surgery：在查询数据上训练（建议 GPU；CPU 极慢）
reference_model.train(max_epochs=100, plan_kwargs={"weight_decay": 0.0})

# 4) 输出联合嵌入并迁移标签
adata_q.obs["pred_latent"] = None
query_latent = sc.AnnData(reference_model.get_latent_representation(adata_q))
query_latent.obs = adata_q.obs.copy()
neighbors_knn = sca.utils.knn_weights(reference_model, query_latent, "dataset")
query_latent.obs["cell_type_pred"] = neighbors_knn["cell_type"]["preds"]
query_latent.obs["cell_type_uncertainty"] = neighbors_knn["cell_type"]["uncertainty"]
print(query_latent.obs["cell_type_pred"].value_counts())

</details>

映射完成后的整合质量自检（承接坑点 6 的「不确定性不是错误率」）：

# ---- 步骤 5（可选）：映射后整合质量自检 ----
# unknown 比例（官方口径：不确定性过高者置 unknown，预印本方法阈值 0.2）
n_unknown = (query_latent.obs["cell_type_pred"] == "unknown").mean()
print(f"unknown 比例: {n_unknown:.2%}")
# 不确定性分位数：分布整体右移通常意味着查询数据与参考的协议/人群差异过大
print(query_latent.obs["cell_type_uncertainty"].quantile([0.5, 0.9, 0.99]))

§6.4 PyTorch DataLoader 完整代码

<details>
<summary>查看：AnnData → PyTorch Dataset / DataLoader（donor 级划分，约 50 行）</summary>

import os
import numpy as np
import scipy.sparse as sp
import torch
from torch.utils.data import Dataset, DataLoader, Subset
import scanpy as sc

HLCA_ROOT = os.environ.get("HLCA_ROOT", "hlca")

class HLCADataset(Dataset):
    """按需物化稠密批次的 AnnData 包装器；标签取指定层级的细胞类型。"""

    def __init__(self, h5ad_path, label_key="cell_type", label_level=None):
        self.adata = sc.read_h5ad(h5ad_path)
        self.adata.X = sp.csr_matrix(self.adata.raw.X
                                     if self.adata.raw is not None else self.adata.X)
        obs = self.adata.obs
        if label_level is not None and f"cell_type_level_{label_level}" in obs:
            label_key = f"cell_type_level_{label_level}"
        classes = sorted(obs[label_key].astype(str).unique())
        self.class_to_idx = {c: i for i, c in enumerate(classes)}
        self.labels = torch.tensor(obs[label_key].astype(str).map(self.class_to_idx).values)
        self.donor_ids = obs["donor_id"].astype(str).values

    def __len__(self):
        return self.adata.n_obs

    def __getitem__(self, idx):
        row = self.adata.X[idx].toarray().ravel()      # 单细胞基因 counts
        x = torch.tensor(np.log1p(row), dtype=torch.float32)
        return x, self.labels[idx]

def donor_split(dataset, test_ratio=0.2, seed=0):
    """donor 级划分：同一供者的细胞绝不同时进入训练与测试。"""
    rng = np.random.default_rng(seed)
    donors = np.unique(dataset.donor_ids)
    rng.shuffle(donors)
    n_test = max(1, int(len(donors) * test_ratio))
    test_donors = set(donors[:n_test])
    test_idx = [i for i, d in enumerate(dataset.donor_ids) if d in test_donors]
    train_idx = [i for i, d in enumerate(dataset.donor_ids) if d not in test_donors]
    return Subset(dataset, train_idx), Subset(dataset, test_idx)

if __name__ == "__main__":
    ds = HLCADataset(os.path.join(HLCA_ROOT, "data", "HLCA_core.h5ad"), label_level=1)
    train_ds, test_ds = donor_split(ds)
    train_loader = DataLoader(train_ds, batch_size=1024, shuffle=True, num_workers=4)
    test_loader = DataLoader(test_ds, batch_size=4096, shuffle=False)
    x, y = next(iter(train_loader))
    print(x.shape, y.shape, len(ds.class_to_idx))

</details>

设计要点：counts 经 log1p 后物化为稠密批次（稀疏矩阵随机访问代价高）；标签层级可参数化选择；donor_split 在 DataLoader 之前执行，保证采样器不跨集污染；若内存吃紧，可改用按 chunk 预转 float16 或在线读取 h5ad backed 模式。

§6.5 坑点 8 个

⚠️ 坑点 1：HLCA 缩写撞车——三个"肺细胞图谱"长得一模一样（分类：工程陷阱）

问题：检索 “HLCA” 会命中三个不同资源：Sikkema 2023 整合版 HLCA（本条目主角，2.4M+ 细胞）、Travaglini 2020 Krasnow 实验室版（约 75,000 细胞、58 种细胞群，站点 hlca.sf.czbiohub.org、UCSC Cell Browser 数据集 ID stanford-czb-hlca）、以及独立的 Human fetal lung cell atlas（胚胎期，12 名胎儿供者）。混用会让引用、数字与结论全部错位。
症状：下载到的对象只有约 75,000 细胞；论文里写 “486 名捐献者” 配的却是 Travaglini 的图；把 “5-22 受孕周” 当成 HLCA 覆盖范围（HLCA 实际为 10-76 岁，不含胚胎样本）。
解决：

简单方法：认准 GitHub landing page LungCellAtlas/HLCA 与论文 DOI 10.1038/s41591-023-02327-2；规模对不上 2.4M/486 即非整合版 HLCA。

进阶方法：CELLxGENE collection（6f6d381a-7701-4781-935c-db10d30de293）内的两个对象（core/full）才是整合版；检查 adata.shape 应为 584,944 × 28,024（core）。

SOTA 方法：在数据版本管理（DVC/LakeFS）中以 Zenodo DOI + md5 锁定文件身份，杜绝同名资源串台。
参考：hlca.sf.czbiohub.org；UCSC Cell Browser；基准研究对两数据集的区分描述。

⚠️ 坑点 2：core / full / embedding 三种"HLCA 文件"不是一回事（分类：工程陷阱）

问题：与 HLCA 相关的下载对象至少有三种：core 全量矩阵（584,944 × 28,024）、full 整合对象（约 2.3M 细胞）、以及 HLCA_full_v1.1_emb.h5ad（2.4 GB 参考 embedding）。最后者只是低维嵌入 + 元数据，不含全基因 counts；文件名里的 “full” 极具迷惑性。
症状：以为下载了全量数据，跑差异表达时报 adata.raw 为空或找不到基因；或者用 2.4 GB 的文件估算磁盘与内存预算，实际拉取 17.35 GiB 的全量副本时容器爆掉。
解决：

简单方法：下载前核对文件名与大小口径（embedding 2.4 GB vs core Census 副本 17.35 GiB）。

进阶方法：映射任务只需 embedding + 模型（Zenodo）；重分析任务拉 CELLxGENE 的 core/full 全量对象；Census 快照用于程序化复现。

SOTA 方法：构建数据清单（manifest）记录"文件 × md5 × 预期维度"，入仓校验。
参考：Zenodo 文件列表；Open Problems 数据页。

⚠️ 坑点 3：raw counts 藏在 adata.raw.X，且 counts 从未被批次校正（分类：预处理陷阱）

问题：HLCA 的整合只作用于低维嵌入；基因 counts 本身未做批次校正（官方明确提示）。分发对象中 adata.X 可能已是处理态，原始整数 counts 存于 adata.raw.X（h5ad 口径）或 seurat_object@assays$RNA@counts（rds 口径）。
症状：对 adata.X 做整数校验失败；在"归一化之上再归一化"导致分布畸变；差异表达与 marker 分析结果与文献明显不符。
解决：

简单方法：重分析前显式 adata.X = adata.raw.X，再走 normalize_total + log1p。

进阶方法：涉及跨批次比较时，只在官方提供的批次校正嵌入上做聚类/可视化，counts 层保留原始态供 DE 分析；不要自行对 counts 做二次"校正"。

SOTA 方法：用 scvi-tools 在 counts 层重训协变量感知模型（如需自定义协变量），并把 batch 变量口径（组织+供者+协议）固定下来复现官方口径。
参考：HCA Atlas 页 Batch Correction 说明。

⚠️ 坑点 4：映射教程仓库已归档 + 依赖版本地狱（旧环境会随机打标签）（分类：工程陷阱）

问题：LungCellAtlas/mapping_data_to_the_HLCA 已被官方标注 Outdated/archived，教程迁移至 scarches 仓库；旧教程依赖组合（scArches 0.3.5 + scvi-tools 0.8.1 + torch ≥1.3,≤1.8）与新教程要求（scanpy ≥1.9.3、scarches ≥0.5.8、scvi-tools ≥0.20.3）互不兼容，且官方确认旧环境存在标签迁移 bug。
症状：label transfer 输出近似随机的细胞标签；conda 解依赖数小时失败；GPU 上 torch 与 CUDA 版本冲突。
解决：

简单方法：直接使用 scarches 官方教程的 hlca_map_classify.ipynb，按其版本要求建环境。

进阶方法：固定 scanpy==1.9.x, scarches>=0.5.8, scvi-tools>=0.20.3 于独立环境文件；若观察到随机标签，先升级包再重跑（官方确认旧版环境触发该 bug）。

SOTA 方法：CI 中加入"映射冒烟测试"（用教程自带 Delorey 样本子集跑通并断言标签分布非均匀），版本漂移即刻报警。
参考：mapping 仓库 README（已归档说明）；scArches HLCA 教程。

⚠️ 坑点 5：查询数据五项准备缺一不可（raw 整数 counts / 基因对齐 / batch 变量 / 删 obsm / GPU）（分类：预处理陷阱）

问题：映射前查询数据必须满足：.X 为原始整数 counts；基因按参考模型顺序对齐（缺失补零，顺序 CSV 在 Zenodo）；batch 变量写入 adata.obs["dataset"]；obsm/varm 需删除；映射建议 GPU（官方测试数据 4 核 9 GB 内存约 1 小时，含 UMAP，大数据集需更多）。
症状：训练报维度不匹配；基因名/ID 对不上导致大量零列；用 subject 或疾病状态当 batch 后，嵌入把个体效应或疾病效应"整没了"。
解决：

简单方法：按官方清单逐项自检（§6.3 步骤 1-4 覆盖全部五项）。

进阶方法：写映射前校验函数（整数断言 + 基因覆盖率报告 + batch 唯一值检查），不通过即中止。

SOTA 方法：把校验与映射封装为带版本参数的一键流水线（WDL/Nextflow），参考侧锁 Zenodo md5，查询侧锁 h5ad 哈希。
参考：mapping 仓库 README；scArches 教程。

⚠️ 坑点 6：映射不确定性不是"错误率"——高不确定性里藏着新发现（分类：评估误用）

问题：scArches 映射为每个细胞输出标签迁移不确定性；研究设计用它来高亮"与参考不符"的细胞——可能是新细胞态或疾病受累细胞（预印本口径：不确定性高于 0.2 的细胞被置为 unknown）。把高不确定性细胞当作低质量数据丢弃，等于扔掉了图谱的差异化价值。
症状：过滤后"干净"数据里罕见细胞类型消失；疾病组的不确定性高峰被当作质量问题；unknown 群体从未被二次分析。
解决：

简单方法：保留 uncertainty 列；按"低不确定性（<0.4）vs 高不确定性（>0.4）"分组做差异表达（官方疾病 signature 分析口径）。

进阶方法：对高不确定性簇做 marker 富集与亚聚类，标注"候选新态"而非删除；报告不确定性分布而非只报准确率。

SOTA 方法：将不确定性作为 OOD 检测信号纳入监控，跨数据集对比其稳定性。
参考：bioRxiv 预印本方法部分；GitHub README 用途说明。

⚠️ 坑点 7：人群偏倚——65% 欧洲血统、14% 未注释、无胚胎样本（分类：偏倚陷阱）

问题：core 捐献者血统以欧洲为主（65%），14% 未注释；年龄 10-76 岁以成人为界，不含胚胎/胎儿样本；性别 60% 男性。用 HLCA 给非欧美人群或发育期样本做标签迁移时，参考分布与目标分布错位。
症状：亚洲人群数据映射后整体不确定性偏高；把胎儿肺数据映射到 HLCA 得到大面积 unknown；跨人群差异表达被误读为疾病效应。
解决：

简单方法：映射前检查目标数据的人群构成，报告中注明参考的人群口径；发育期数据改用专门的 fetal lung atlas。

进阶方法：按 self_reported_ethnicity 分层评估标签迁移质量；对未注释群体做敏感性分析。

SOTA 方法：跨人群研究采用"先映射再校准"两段式，或构建包含目标人群的联合参考。
参考：Nature 正文 Fig.2a 人群构成；基准研究对 fetal atlas 的区分。

⚠️ 坑点 8：细胞级随机划分 + 疾病当 batch——双重泄漏制造虚假好成绩（分类：数据泄漏）

问题：单细胞数据中同一 donor 的细胞高度相关，细胞级随机划分会让模型记住宿主；同时官方明确不建议把疾病状态作为 batch 变量——两者叠加会让"分类器"学到供者指纹与被擦除的疾病信号之外的残留捷径。
症状：测试集准确率 0.95+ 但换一个实验室的数据瞬间崩塌；疾病组与hc对照组在嵌入里不可分，但分类器准确率却很高（靠供者聚类作弊）。
解决：

简单方法：donor 级分组划分（§6.4 的 donor_split），batch 变量只放协议/组织口径。

进阶方法：study 级留一（leave-one-study-out）评估跨实验室泛化；对预测结果按 donor 聚类检查是否有供者记忆。

SOTA 方法：同时报告 donor 级与 study 级两组指标，并附每类支持度与不确定性分布，作为单细胞模型的标准汇报格式。
参考：mapping 仓库 README 的 batch 建议；§5.3 泄漏清单。

§6.6 数据增强（安全/危险）

类别	操作	判断
归一化重标定（normalize_total + log1p）	标准流程	✅ 安全
使用官方批次校正嵌入做聚类/可视化	不触碰 counts	✅ 安全
donor 级采样加权（稀有供者过采样）	划分前做，且只作用于训练集	✅ 安全
基因随机 dropout 模拟测序深度变化	单细胞 counts 对零值敏感，会破坏分布	❌ 危险
跨 donor 混合/打乱标签	制造不存在的细胞态	❌ 危险
基因排列置换（permutation）	破坏基因共变结构（基因模块分析的根基）	❌ 危险
使用官方嵌入坐标作为下游模型输入	已批次校正、官方口径一致	✅ 安全
把映射不确定性当伪标签参与训练	不确定性是置信度不是类别语义	❌ 危险

§6.7 模型推荐表

任务	推荐模型/工具	理由与官方背书
标签迁移（映射注释）	scArches + scANVI 参考模型	论文采用并验证的技术路径（HCA Atlas 页）
自动化在线映射	FASTGenomics HLCA 应用	官方提供的浏览器端自动映射（GitHub README）
备选映射	Azimuth	官方列出（论文未采用该路径验证）
备选标签迁移	CellTypist（Human_Lung_Atlas 模型）	官方列出（论文未采用该路径验证）
批次整合复现/再训练	scvi-tools（scANVI）	core 整合的原生框架
差异表达/基因模块	scanpy + diffxpy	论文方法链同源工具
无标签整合基线	scVI（scvi-tools）	scANVI 的无监督底座，可用于查询数据自建参考
整合质量评测	scIB 指标族	整合方法基准研究的通用指标族（基准研究）

§6.8 硬件需求表

场景	内存	GPU	依据
在线探索	—	—	CELLxGENE 浏览器
加载参考 embedding（2.4 GB）	≥16 GB	不需要	文件 2.4 GB，物化后约 2-3 倍内存
scArches 映射（测试规模）	≥9 GB（4 核约 1 小时）	强烈建议	mapping 仓库 README
scArches 映射（大规模查询）	≥32 GB	建议（否则极慢）	官方注明大集合需更多资源
加载 core 全量矩阵（17.35 GiB 副本）	≥64 GB	不需要	Census 副本大小

硬件选型经验：映射是「小模型 + 大图」型负载，瓶颈在内存带宽与 UMAP 计算，4 核 CPU 也能在测试规模跑通（官方口径约 1 小时）；重分析（DE、模块）是纯内存型负载，按「数据物化体积 ≈ 文件体积 × 2-3 倍」估算内存即可。

§6.9 评估指标代码

import numpy as np
from sklearn.metrics import f1_score, balanced_accuracy_score

def label_transfer_report(obs, pred_key="cell_type_pred", true_key="cell_type",
                          group_key="donor_id"):
    """donor 级聚合的报告：宏 F1 + 平衡准确率 + 不确定性分位数。"""
    y_true, y_pred = obs[true_key].astype(str), obs[pred_key].astype(str)
    macro_f1 = f1_score(y_true, y_pred, average="macro")
    bacc = balanced_accuracy_score(y_true, y_pred)
    unc = obs["cell_type_uncertainty"] if "cell_type_uncertainty" in obs else None
    print(f"macro-F1={macro_f1:.3f}  balanced-acc={bacc:.3f}")
    if unc is not None:
        print("uncertainty quantiles:", unc.quantile([0.5, 0.9, 0.99]).round(3).to_dict())
    # 按 donor 抽查：随机 5 名供者的逐类准确率，检查供者记忆
    for d in obs[group_key].dropna().unique()[:5]:
        m = obs[group_key] == d
        acc = (y_true[m] == y_pred[m]).mean()
        print(f"donor {d}: acc={acc:.3f} (n={m.sum()})")

def per_level_report(adata_mapped, levels=(1, 2, 3)):
    """跨注释层级分别报告迁移质量：细层级指标天然更低，需分层解读。"""
    for lv in levels:
        pred_col = f"cell_type_pred_level_{lv}"
        true_col = f"cell_type_level_{lv}"
        if pred_col in adata_mapped.obs and true_col in adata_mapped.obs:
            m = adata_mapped.obs[true_col].notna()
            f1 = f1_score(adata_mapped.obs.loc[m, true_col].astype(str),
                          adata_mapped.obs.loc[m, pred_col].astype(str),
                          average="macro")
            print(f"level {lv}: macro-F1={f1:.3f} (n={int(m.sum())})")

§6.10 MLOps 笔记

数据版本：以 Zenodo DOI（10.5281/zenodo.7599104）+ 文件 md5 锁定参考侧；查询数据入数据湖时记录哈希。
环境锁定：scanpy ≥1.9.3 / scarches ≥0.5.8 / scvi-tools ≥0.20.3 写入环境文件（坑点 4）；每次依赖升级跑映射冒烟测试。
分层版本标注：所有产出物（标签、嵌入、模型）注明所用 HLCA 版本（v1.0/v1.1）与 core/full 口径，避免跨版本混算。
不确定性监控：把迁移不确定性分布作为线上数据漂移指标（§7.6），分布右移即触发复核。
复现资产：官方全流程脚本在 HLCA_reproducibility 仓库，可直接挂入内部流水线做回归对拍。
跨渠道一致性：CELLxGENE 与 Census 两渠道的同名对象在字段上可能有细节差异（如 soma_joinid 为 Census 注入字段），合并前登记字段映射表并留审计日志。
指标基线：把首次映射的宏 F1、平衡准确率与不确定性分位数固化为基线，后续参考版本升级时做对照跑分。

§7 质量评估与局限性

§7.1 已知偏倚与缓解

偏倚类型	描述	严重程度	缓解措施
人群血统偏倚	core 统一化血统 65% 欧洲、14% 未注释，非洲 14%、亚洲 2%	高	分层评估；跨人群应用前做敏感性分析（坑点 7）
性别偏倚	男性 60% / 女性 40%	中	协变量建模时纳入性别；报告分层指标
吸烟状态缺失	17% 未注释，从不吸烟 52% 偏多	中	显式"未知"类别；缺失敏感性分析
技术混杂	49 个数据集的协议/平台/取样位置差异大	高	只用官方批次校正嵌入做跨批次比较；counts 层保留原始
疾病选择偏倚	15 种疾病由数据可得性而非患病率决定	中	下游结论限定为"数据集内比较"，不做流行病学外推
标签迁移压缩	extension 标签来自映射迁移而非重注释	高	高不确定性细胞单独成簇分析（坑点 6）
层级粒度偏倚	细层级标签分歧天然高于 coarse 层级	中	按任务选择层级并分层报告指标（§3.6）
发布渠道差异	CELLxGENE 与 Census 字段命名存在细节差异	低	建立字段映射表（§4.5）

§7.2 标注质量

标注质量由共识机制保障：6 位独立专家 + 原作者标签的收敛，产出 61 标签 × 5 层级（HCA Atlas 页）；预印本口径 59% 细胞修正注释说明原始标注问题普遍存在（bioRxiv）。局限：官方未发布逐标签的标注者间一致性统计；细粒度层级（第 4-5 层）的标签分歧天然更高，用前建议按 marker 基因抽检。实践上先在 coarse 层级确认大方向，再下探细层级——细层级标签适合发现新亚群，而非充当稳定分类的终点。

§7.3 泛化性评估

目标场景	失效风险	证据与建议
健康成人肺（欧美人群）	低	core 即为此设计，共识注释直接可用
非欧洲血统人群	中-高	亚洲 2%、非洲 14% 的覆盖有限（§2.4），映射不确定性需分层报告
儿童肺样本	中	年龄下界 10 岁，更低龄样本超出参考范围
胚胎/胎儿肺	极高（不适用）	HLCA 无胚胎样本；应改用 fetal lung atlas（坑点 1）
跨疾病映射	中	extension 标签为迁移所得，疾病特异新态需靠不确定性识别
单核测序数据（snRNA-seq）	中-低	图谱本身含单核研究；技术差异仍需 batch 变量覆盖
COVID-19 病程数据	低-中	extension 直接覆盖该病种；跨疾病共享态分析见 §7.8
肺癌组织	中	肿瘤特异态可能被标签迁移压缩，需结合不确定性成簇分析
老年样本	低	年龄上界 76 岁，覆盖老年区间

§7.4 伦理合规

HLCA 整合对象以 CC BY 4.0 开放，遵循 HCA Data Release Policy（HCA Atlas 页）；分发数据不含直接标识符，供者元数据为聚合级人口学变量。少数源研究的原始测序数据由 EGA 受控管理，需申请与 DAA（bioRxiv Data availability）。资助方包括 CZI（Seed Network grant CZF2019-002438）、NIH R01HL145372 与 DoD W81XWH-19-1-0416 等（Cambridge Apollo 存档）。二次分发时应保留 CC BY 4.0 的署名要求，引用原始论文并注明版本与下载渠道。

§7.5 公平性

公平性风险集中在血统与性别代表性（§7.1 前两行）。使用 HLCA 训练的模型在代表性不足群体上的性能衰减是可预期的；建议在任何面向部署的结论中，附上按血统/性别分层的标签迁移质量报告，并将 14% 血统未注释的样本作为独立组呈现。公平性问题的工程化表达是：把 self_reported_ethnicity 与 sex 纳入评估的切分层级，任何整体指标的提升都需在分层口径下复验不倒退。

§7.6 数据漂移

单细胞技术的协议迭代（多代 10x 试剂、新的单核流程）会让新数据相对参考产生漂移，表现为映射不确定性分布整体抬升。建议把不确定性分布（中位数/P90/P99，§6.9）作为漂移监控指标；漂移显著时优先检查协议差异，而非直接重训参考模型。排查顺序建议：先查 assay 构成变化，再查组织/取样位置构成，最后才怀疑生物学差异——单细胞数据里「细胞构成偏移」远比「表达水平漂移」常见。

§7.7 DAIMS 24 项评估

#	检查项	状态	说明
1	宽格式	✅	细胞 × 基因标准矩阵（AnnData），obs/var/obsp/obsm 结构清晰
2	唯一标识	✅	细胞条码 + donor_id + Census soma_joinid 三级标识
3	特殊字符	✅	标签与元数据为标准 ASCII/本体术语，无脏字符
4	重复行	✅	整合管线去重；Census 副本以 soma_joinid 唯一
5	缺失编码	⚠️	NA 编码一致但比例不低（血统 14%、吸烟 17%）
6	标签标识	✅	61 标签 × 5 层级 + CL 本体编码
7	罕见类分组	✅	论文明确演示稀有细胞类型的一致性恢复
8	偏倚评估	✅	§7.1 六类偏倚逐项列明
9	数据字典	✅	官方 HLCA_metadata_explanation.csv 逐字段说明
10	信息性缺失解释	✅	NA 具语义（未注释/不适用），§4.5 说明
11	设备记录	✅	assay/EFO 平台元数据随对象分发
12	共线性	⚠️	批次与协议变量高度纠缠，回归建模需先做共线诊断
13	编码映射	✅	CL/HsapDv/HANCESTRO/MONDO/EFO 全套本体编码
14	时间戳处理	⚠️	逐数据集采样时间口径不一，主对象未统一时间戳
15	划分建议	✅	§5 给出 donor/study 级划分与映射式评估三方案
16	泄漏讨论	✅	§5.3 三类泄漏风险（含官方 batch 禁忌）
17	标签分布	✅	§4.2 说明分布结构；精确计数以到手对象实测
18	测量偏倚	⚠️	液滴/平板、细胞/单核协议差异构成测量偏倚，未完全消除
19	外部验证建议	✅	§7.8 外部验证矩阵 + §5.5 建议
20	版本记录	✅	bioRxiv→v1.0→v1.1 时间轴 + Zenodo md5
21	预处理脚本	✅	HLCA_reproducibility 全流程脚本公开
22	合规要求	✅	CC BY 4.0 开放；少数源数据 EGA 受控已明示
23	多模态对齐	⚠️	纯转录组单模态；如需蛋白/空间模态需引入外部数据自行对齐
24	去标识化	✅	无直接标识符；供者元数据聚合级（§7.4）

DAIMS 评分：19.5 / 24

评分解读：19.5 分处于高质量研究型数据集区间。数据字典、本体编码、版本记录与预处理脚本四项达到教科书水准——这是少数"从数据到模型资产全链路公开"的单细胞资源；扣分集中在五项 ⚠️：缺失比例偏高（血统/吸烟）、批次-协议共线性、时间戳不统一、测量偏倚残留与单模态限制。没有 ❌ 项，说明不存在结构性硬伤。

对你意味着什么：如果你的任务是"给新肺数据打标签"，HLCA 基本即取即用——按 §6.3 的五项准备映射即可，重点盯不确定性分布；如果任务是"跨人群/发育期分析"，请直接按坑点 7 与 §7.3 降级预期或换参考；如果任务是"训练可部署模型"，务必 donor 级划分（坑点 8）并按 §7.5 输出分层报告。任何场景下都不要把 counts 当作已批次校正数据使用（坑点 3）。

§7.8 外部验证矩阵

外部数据集/场景	来源机构	评估任务	性能指标	相对内部变化	关键发现
Delorey 等数据样本（映射查询示例）	论文合作团队	标签迁移 + 不确定性估计	官方教程演示路径（教程含逐细胞标签与不确定性输出）	官方教程以查询数据完成完整映射闭环	教程验证映射流程可复现（scArches 教程）
COVID-19 数据集（extension 内）	HCA 肺网络	跨疾病共享态识别	定性：SPP1+ 促纤维化巨噬细胞在 COVID-19、肺纤维化、肺癌中共享	—	支撑跨疾病机制假设（论文摘要）
整合方法基准研究	方法学界	用 core（584,944 × 28,024）评测整合算法	指标随基准协议而异	—	core 已成为整合方法的公共基准（基准数据集描述）
Azimuth / CellTypist 入口	社区	备选标签迁移	官方注明未在论文中验证该路径	与 scArches 路径结论可能不一致	官方 README 明示验证状态差异（GitHub README）
Open Problems 基准注册表	方法学社区	HLCA 数据注册与基准挂接	—	—	该数据集页当前未挂接公开基准任务（注册表条目）

说明：HLCA 属参考图谱型资源，外部验证多以"映射可用性"与"下游发现复现"形式存在，而非单一排行榜指标；表中不列未经同行评审的数值。

§8 基准性能与生态

§8.1 排行榜：基于 HLCA 的代表性结果

HLCA 不是竞赛数据集，不存在传统意义的 SOTA 排行榜；下表列出有同行评审支撑的代表性研究/技术路径及其在 HLCA 上的产出形态。

序	研究/路径	产出形态	年份	关键技术	完整引用	代码
1	HLCA 本体构建	首个整合肺参考 + 共识注释体系	2023	scANVI + 专家共识重注释	Sikkema et al., 2023, Nature Medicine. DOI 10.1038/s41591-023-02327-2	GitHub
2	参考映射体系	新数据一键映射 + 标签迁移 + 不确定性	2021/2023	scArches 迁移学习	Lotfollahi et al., 2021, Nature Biotechnology. DOI 10.1038/s41587-021-01001-7	docs
3	跨疾病共享态	识别 COVID-19/肺纤维化/肺癌共享 SPP1+ 巨噬细胞态	2023	full HLCA 映射比较	Sikkema et al., 2023, Nature Medicine. DOI 10.1038/s41591-023-02327-2	同 1
4	层次化参考映射	构建与扩展细胞类型层级	2023	单细胞参考映射	Michielsen, Lotfollahi, Strobl, Sikkema et al., 2023, NAR Genomics and Bioinformatics 5(3):lqad070	—
5	图谱构建方法论	整合单细胞图谱的构建与使用考量	2025	方法论综述	Hrovatin, Sikkema et al., 2025, Nature Methods 22(1):41-57	—

⚠️ 数值不可直接比较说明：上表为"能力/产出"维度而非同一指标下的性能排序——HLCA 场景的评估口径（标签层级、查询数据、不确定性处理）在不同研究间不一致，直接比较 macro-F1 或准确率没有意义；评估协议见 §8.3。另注：HLCA 数据已注册于 Open Problems 基准生态，但该数据集页截至检索时（2026-09）未挂接公开基准任务（条目页）。

§8.2 SOTA 总结与选型建议

结论很朴素：映射标签迁移的默认路径是 scArches + 官方 scANVI 模型（论文验证路径）；需要浏览器端零代码时用 FASTGenomics；想用备选体系（Azimuth/CellTypist）时记得官方明示其未在论文中验证，结论应与主路径交叉核对。以 HLCA 为基准做整合方法评测时，固定 core（584,944 × 28,024）与同一快照，避免跨快照比较（Census 数据页）。选型速查：要「官方背书」选 scArches 路径；要「零门槛」选 FASTGenomics；要「复现基准」锁 Census 快照；要「R 生态」走 HCA 页的 rds 下载。

§8.3 评测协议

推荐协议四要素：其一，参考版本锁定（v1.0/v1.1 + Zenodo md5）；其二，查询数据与 49 个源研究无重叠声明；其三，评估层级声明（5 层级中报告哪层）；其四，指标组合（donor 级宏 F1 + 平衡准确率 + 不确定性分布，§6.9）。跨研究比较时附上查询数据规模与协议构成。协议之外的加分项：公开查询数据的预处理脚本、随机种子与硬件规格（映射性能对 CPU/GPU 敏感，见 §6.8），能显著提升他人复算成功率。

数据集	关系	规模	差异点
Travaglini et al. 2020（同名 HLCA）	同名前作	约 75,000 细胞 / 58 细胞群	健康肺+血，解剖定位导向（站点）
Human fetal lung cell atlas	互补（发育期）	12 名胎儿供者 / 8 阶段 / 144 亚型	受孕后 5-22 周（基准描述）
HBCA（乳腺参考图谱）	同范式	800,000+ 细胞 / 55 捐献者	器官不同，同为器官级参考
免疫 CITE-seq 多供者数据（基准用）	互补模态	90,261 细胞 / 13,953 基因 / 45 类	含 RNA+蛋白多模态（基准描述）

§8.5 关键论文 Top 8

Sikkema, L., Ramírez-Suástegui, C., Strobl, D.C., et al. An integrated cell atlas of the lung in health and disease. Nature Medicine 29(6):1563-1577, 2023. DOI 10.1038/s41591-023-02327-2 —— HLCA 本体论文，确立 core/full 双层结构与共识注释。
Lotfollahi, M. et al. Mapping single-cell data to reference atlases through transfer learning. Nature Biotechnology, 2021. DOI 10.1038/s41587-021-01001-7 —— scArches，HLCA 映射体系的引擎。
Sikkema, L., Strobl, D., Zappia, L., et al. 预印本版本（bioRxiv 2022.03.10.483747）—— 保存早期口径（46 数据集/220 万细胞/59% 重注释），引用时注意与正式版区分。
Hrovatin, K., Sikkema, L., et al. Considerations for building and using integrated single-cell atlases. Nature Methods 22(1):41-57, 2025 —— 图谱构建与使用的系统性方法论。
Michielsen, L., Lotfollahi, M., Strobl, D., Sikkema, L., et al. Single-cell reference mapping to construct and extend cell-type hierarchies. NAR Genomics and Bioinformatics 5(3):lqad070, 2023 —— 参考映射的层级扩展方法。
Luecken, M.D., Zaragosi, L.-E., Madissoon, E., Sikkema, L., et al. The discovAIR project: a roadmap towards the Human Lung Cell Atlas —— 欧盟资助的肺图谱路线图，HLCA 的上游工程。
Travaglini, K.J. et al. A molecular cell atlas of the human lung from single-cell RNA sequencing. Nature, 2020（PMID 33208946）—— 同名前作，健康肺分子图谱的奠基性工作。
Muus, C., Luecken, M.D., Eraslan, G., Sikkema, L., et al. Single-cell meta-analysis of SARS-CoV-2 entry genes across tissues and demographics. Nature Medicine 27(3):546-559, 2021 —— 疫情期跨组织单细胞元分析，HLCA 团队的先导工作。

阅读顺序建议：先读 1（本体）与 2（映射引擎）建立核心认知，再读 4（方法论）获得全景视角；3（预印本）仅作版本对照使用，5-8 为方法链与历史脉络的补充。

§8.6 社区活跃度

HLCA 的社区以 GitHub issue 答疑（LungCellAtlas/HLCA）、HCA Lung Network 协调（网络协调人 Pascal Barbry、Martijn Nawijn、Jay Rajagopal、Nicholas Banovich，联络邮箱 lung@humancellatlas.org，HCA Atlas 页）与 CELLxGENE 生态为节点；论文引用 762+（Google Scholar，截至 2026-09）显示其已成为肺单细胞研究的事实参考。映射教程的维护迁移到 scarches 主仓库，社区提问优先走对应仓库 issue。版本维护节奏参考：v1.1 文档更新发生在正式发表前（2023-05），此后主版本保持稳定；重大变更会同步到 landing page 与 Zenodo，跟踪方式以 GitHub watch + Zenodo DOI 为准。

§8.7 生态快照表

资源	类型	链接	推荐理由
LungCellAtlas/HLCA	官方 landing page + 元数据字典	GitHub	一切入口的起点，issue 答疑区
HLCA_reproducibility	全流程复现代码	GitHub	论文脚本与 notebook 全公开
mapping_data_to_the_HLCA	映射教程（已归档）	GitHub	历史口径与 batch 建议（注意坑点 4）
scarches hlca_map_classify	现行映射教程	docs	官方现行推荐路径
Zenodo 7599104	模型与 embedding 存档	Zenodo	版本锁定（md5 齐备）
CELLxGENE collection	数据探索与下载	CELLxGENE	交互式探索 core/full
CELLxGENE Census（数据页镜像）	程序化获取	Open Problems 页	快照复现（截至 2024-02）
FASTGenomics HLCA	在线自动映射	FASTGenomics	零代码映射
scRNAseq_pipelines	测序处理流水线	GitHub	部分源数据集的统一处理
Azimuth	在线映射工具	https://azimuth.hubmapconsortium.org	官方列出的备选映射入口（论文未验证路径）
CellTypist	标签迁移模型库	https://www.celltypist.org/models	提供 Human_Lung_Atlas 参考模型（论文未验证路径）

§9 相关资源与引用

§9.1 官方资源清单

论文出版页（DOI 10.1038/s41591-023-02327-2）：https://doi.org/10.1038/s41591-023-02327-2
HCA Lung Atlas v1.0 官方页：https://data.humancellatlas.org/hca-bio-networks/lung/atlases/lung-v1-0
GitHub landing page（含元数据说明 CSV）：https://github.com/LungCellAtlas/HLCA
复现代码仓库：https://github.com/LungCellAtlas/HLCA_reproducibility
现行映射教程：https://docs.scarches.org/en/latest/hlca_map_classify.html
Zenodo 模型与 embedding（DOI 10.5281/zenodo.7599104）：https://zenodo.org/record/7599104
CELLxGENE collection：https://cellxgene.cziscience.com/collections/6f6d381a-7701-4781-935c-db10d30de293
FASTGenomics 在线映射：https://beta.fastgenomics.org/p/hlca
Azimuth：https://azimuth.hubmapconsortium.org
CellTypist（Human_Lung_Atlas 模型）：https://www.celltypist.org/models
测序处理流水线：https://github.com/LungCellAtlas/scRNAseq_pipelines
HCA 数据使用协议入口（Data Use Agreement）：见 HCA Atlas 页底部
开放获取全文 PDF（Groningen 机构库）：https://pure.rug.nl/ws/portalfiles/portal/699917653/s41591-023-02327-2.pdf
论文机构存档记录（Cambridge Apollo）：https://www.repository.cam.ac.uk/items/0a6d0606-5aa3-48fb-8427-32a0a4a8084b

§9.2 BibTeX 引用块

@article{sikkema2023integrated,
  author  = {Sikkema, Lisa and Ram{\'i}rez-Su{\'a}stegui, Ciro and Strobl, Daniel C. and Gillett, Tessa E. and Zappia, Luke and Madissoon, Elo and Markov, Nikolay S. and Zaragosi, Laure-Emmanuelle and Ji, Yuge and Ansari, Meshal and others},
  title   = {An integrated cell atlas of the lung in health and disease},
  journal = {Nature Medicine},
  volume  = {29},
  number  = {6},
  pages   = {1563--1577},
  year    = {2023},
  doi     = {10.1038/s41591-023-02327-2}
}

@article{lotfollahi2021mapping,
  author  = {Lotfollahi, Mohammad and Naghipourfar, Mohsen and Luecken, Malte D. and Khajavi, Min and B{\"u}ttner, Maren and Wagenstetter, Marco and Avsec, {\v Z}iga and Gayoso, Adam and Yosef, Nir and Interlandi, Marta and Rybakov, Sergei and Misharin, Alexander V. and Theis, Fabian J.},
  title   = {Mapping single-cell data to reference atlases through transfer learning},
  journal = {Nature Biotechnology},
  year    = {2021},
  doi     = {10.1038/s41587-021-01001-7}
}

@misc{hlca2023zenodo,
  author       = {Sikkema, Lisa and Luecken, Malte D. and the HLCA team},
  title        = {Human Lung Cell Atlas reference model, embedding and model extensions},
  year         = {2023},
  doi          = {10.5281/zenodo.7599104},
  howpublished = {Zenodo}
}

@article{sikkema2022preprint,
  author  = {Sikkema, Lisa and Strobl, Daniel and Zappia, Luke and Madissoon, Elo and Markov, Nikolay S. and Zaragosi, Laure-Emmanuelle and others},
  title   = {An integrated cell atlas of the human lung in health and disease},
  journal = {bioRxiv},
  year    = {2022},
  doi     = {10.1101/2022.03.10.483747}
}

§9.3 引用指南

引用本 Wiki 条目时请同时引用 HLCA 原始论文（Sikkema et al., 2023）；使用参考模型或 embedding 时建议一并引用 Zenodo DOI（10.5281/zenodo.7599104）以锁定版本；使用 scArches 映射时引用 Lotfollahi et al., 2021。区分版本：涉及"46 数据集/220 万细胞"的表述属预印本口径，正式版为"49 数据集/240 万细胞"。如需引用本条目的对比表或坑点分析，请以「千方病案医数集 HLCA 条目（2026-09-05 审核版）」表述，并注明所有原始数据与结论均出自上列官方来源。

§10 AI 使用声明卡

§10.1 AI 模型列表

本条目由大语言模型辅助撰写：初稿生成、结构组织与格式校验由模型完成；事实核查、数字溯源与医学审读由人工完成。

§10.2 AI 参与范围

AI 参与：§1-§9 文字初稿、表格整理、代码骨架生成、排版规范化。人工参与：检索来源甄别、全部规模数字与日期的逐条核对（对照 FACTS 事实清单）、§2 医学表述审读、§5.3/§7.1 泄漏与偏倚结论把关、免责声明核验。审核痕迹：FACTS 事实清单（FACTS.md）保存于同目录，逐条记录「事实 — 来源 URL」映射，供回溯与复核。

§10.3 输入来源列表

Sikkema et al., 2023, Nature Medicine. DOI 10.1038/s41591-023-02327-2（出版页）
同论文出版方 PDF（Groningen 机构库）
同论文预印本（bioRxiv 2022.03.10.483747）
HCA Lung Atlas v1.0 官方页（data.humancellatlas.org）
GitHub landing page（LungCellAtlas/HLCA）
映射教程仓库 README（mapping_data_to_the_HLCA）
scArches 官方教程（docs.scarches.org）
Zenodo 存档 DOI 页（10.5281/zenodo.7599104）
CELLxGENE Census 数据页镜像（Open Problems）
Cambridge Apollo 论文存档（repository.cam.ac.uk）
Helmholtz Munich/合作机构新闻稿（idw-online）
Duke Scholars 论文条目（scholars.duke.edu）
同名前作站点（hlca.sf.czbiohub.org）与 UCSC Cell Browser（cells.ucsc.edu）
Google Scholar 作者档案（引用数，截至 2026-09）
整合方法基准研究的数据集描述（ebolgo 镜像）
Groningen 研究门户条目（research.rug.nl）

§10.4 人工校验表

内容模块	审核者	审核方式	审核状态
frontmatter 与 schema_org	千方病案医学编辑部	逐字段比对模板与事实清单	✅ 已通过
§0 免责声明	千方病案医学编辑部	与金标准逐字比对 + 数据集合规适配	✅ 已通过
§1-§2 规模数字与医学表述	千方病案医学编辑部	对照论文摘要与 HCA 官方页逐条核对	✅ 已通过
§3-§4 规格与数据字典	千方病案数据工程组	对照 Zenodo/Census/官方文档核对	✅ 已通过
§5-§6 流水线与坑点	千方病案数据工程组	代码走查 + 官方教程口径比对	✅ 已通过
§7-§8 质量评估与生态	千方病案医学编辑部	DAIMS 逐项复核 + 引用完整性核对	✅ 已通过
§9-§10 资源与声明卡	千方病案医学编辑部	链接有效性 + 引用格式核对	✅ 已通过

§10.5 AI 生成章节标注

初稿由 AI 生成的章节：§1.1、§3.1、§6.3、§6.4、§6.9、§8.2；其余章节由 AI 辅助整理、人工主导撰写。全部章节均经人工事实核查后发布，无未审内容。

代码块（§6.1-§6.4、§6.9）在发布前经过静态走查与官方教程口径比对，但未在全部运行环境中逐一执行，使用时请以 §6.5 坑点为对照做冒烟验证。

§10.6 最后人工审核日期

最后人工审核日期：2026-09-05（与 §0 审核日期一致）

页面状态：published（全部内容已完成审核并发布）