信息速览

数据集名称N3C 美国新冠队列协作平台 AI-Ready Wikipedia | 千方病案医数集

数据类型OMOP CDM 5.3.1,约 225 亿行,700 万+ COVID 阳性,84 个医疗系统,飞地内 SQL/Python/R 分析,申请审核获取

规模约 2,285 万名患者（Release 184，截至 2024-10）

接入方式National Center for Advancing Translational Sciences (NCATS), NIH url: https://ncats.nih.gov/n3c

AI 就绪度

数据集封面

N3C 美国新冠队列协作平台 — 最大规模新冠真实世界 EHR 飞地 AI-Ready Wikipedia

INFOBOX


数据集名称	National COVID Cohort Collaborative (N3C) Data Enclave
英文全称	National COVID Cohort Collaborative（现更名 National Clinical Cohort Collaborative）
别名/简称	N3C、N3C Data Enclave、N3C Clinical、NIH COVID-19 Data Enclave
疾病分类	新冠感染全疾病谱（ICD-11：RA01 COVID-19 / RA01.0 病毒确认 / 9C81 Post COVID-19 Condition / CA40 肺炎 / 1G40 脓毒症等多系统疾病）
SNOMED CT	840539006 COVID-19 / 840533007 SARS-CoV-2 / 1119302008 Post COVID-19 condition / 840544004 SARS-CoV-2 vaccination（详见 §2.1b）
数据模态	结构化 EHR（OMOP CDM 5.3.1）、纵向时序（就诊/检验/生命体征）、自由文本（临床笔记 NLP 衍生）、外部链接数据（CMS claims、死亡率、病毒变异）
AI 任务类型	COVID 表型分类、严重度预测、死亡/住院预测、Long COVID（PASC）识别与亚型聚类、疫苗有效性评估、再感染分析、临床 NLP 信息抽取、药物有效性真实世界研究
样本总数	22,854,489 名患者 / 746,939 名死亡患者 / 700 万+ COVID 阳性 / 84 个医疗系统（Release 184，截至 2024-10）
数据大小	225 亿+ 行 OMOP 数据（官方未公开字节大小；约 1,120 行/患者，2022-01 时点）
数据格式	OMOP CDM 5.3.1（Palantir Foundry 飞地内数据集；不可下载）
许可证	NCATS N3C Data Use Agreement（飞地内受控使用，按 DUR 项目范围授权）
访问级别	申请审核（机构 DUA + 注册 + NIH 安全培训 + 人类受试者培训 + DUR 经 DAC 审批）
DUO 标签	HMB, DS, IRB, GS, PUB（按 DUO 框架归纳，实际以 NCATS DUA 条款为准）
语言	英文
首发日期	2020-09-01（Data Enclave 正式开放）
最后更新	滚动更新；可核实 Release 193（2025-05-16），数据服务日期至 2025-03
发布机构	NIH 国家转化科学促进中心（NCATS），联合 CTSA Program hubs、IDeA-CTR、CD2H
官方主页	https://ncats.nih.gov/n3c
下载地址	无下载通道（飞地内访问 https://unite.nih.gov ；数据不可导出）
DOI	10.1093/jamia/ocaa196（主设计论文）
引用次数	500+（Scopus，经 OUCI 检索，截至 2026-09）
AI 就绪度评分	⭐⭐⭐（3/5）— OMOP 标准统一、表型版本化、溯源完备；扣分项：数据不可下载、必须飞地内分析、无官方 ML 划分、访问门槛高
页面状态	published

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

医学审核者：千方病案医学编辑部交叉审核：§2 医学背景（ICD-11 与 SNOMED CT 映射、新冠临床任务定义、Long COVID 金标准描述）、§7 偏倚分析。

数据工程审核者：千方病案医学编辑部交叉审核：§4 DAIMS 数据字典（OMOP 核心表、macrovisit 聚合）、§5 数据划分策略、§6 飞地内预处理 Pipeline 和坑点。

审核日期：2026-09-05

审核方式：交叉审核

利益冲突声明：千方病案医数集与 NIH、NCATS、Palantir Technologies 及各 CTSA 中心无任何商业利益关联。本页面不销售 N3C 数据访问权限，仅提供 AI 就绪指南与学术信息服务。编辑者未接受 NIH、NCATS 或 Palantir 的任何形式资助。

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

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

数据使用合规：使用本页面描述的数据集前，请务必阅读并遵守数据集原始许可协议。N3C 要求用户所在机构与 NCATS 签署 DUA、完成 NIH 信息安全与人类受试者培训、提交 Data Use Request 并经 Data Access Committee 审批。DUO 标签仅供参考，具体使用限制以数据集官方协议为准。

§1 数据集概览

§1.0 📌 30 秒速览

这是什么？ N3C（National COVID Cohort Collaborative）是 NIH 国家转化科学促进中心（NCATS）在 2020 年疫情最紧急的时刻，把全美国几百家医院的电子病历汇聚到一个安全"数据飞地"里形成的超级队列。截至 2024-10 的可核实版本，它覆盖 22,854,489 名患者、225 亿行以上数据，是世界上最庞大的新冠电子病历数据资源之一（NLM 数据档案）。所有患者的病历被统一翻译成 OMOP 标准格式，研究者登录进飞地就能用 SQL、Python、R 直接分析。

为什么重要？ 疫情早期，美国的患者数据散落在各个医院的系统里，谁也看不全。N3C 用法律协议（DUA）、隐私保护记录链接（PPRL）和 Palantir Foundry 平台，第一次在美国实现了患者级、全国性、近实时的 EHR 联合分析。它产出了第一个循证的 Long COVID 定义（Pfaff 2022, Lancet Digital Health），推动了 Paxlovid 联邦政策，并回答了疫苗有效性等关键问题。到 2025 年，已有 4,300 名研究者在上面发表了 296 篇论文（Current Opinion 綜述）。

我能用它做什么？ 你可以构建全国性的新冠感染、再感染、住院与 Long COVID 队列，训练严重度预测与表型识别模型，做疫苗/药物的真实世界有效性研究，或在临床笔记 NLP 衍生数据上开发信息抽取算法。但请记住：数据不可下载，一切分析必须在飞地内完成，且你的研究问题必须与获批的 DUR 范围一致。

§1.1 技术摘要

N3C 的技术本质是一个"多源异构 EHR → 统一 OMOP 飞地"的国家级数据工程。参与站点以 Data Transfer Agreement 约定，按周上传数据；四个源数据模型（ACT 2.0、PCORnet 5.1、TriNetX、OMOP）经约 5,000 项语法映射与语义映射统一转换为 OMOP CDM 5.3.1，每个站点管线含 200 万+ 项变换并全程自动记录数据溯源（Haendel 2021, JAMIA）。COVID 阳性患者按版本化表型（如 v3.3）识别，非阳性对照按约 1:2 比例纳入；患者日期在上传前随机平移，邮编截断，构成 Level 2/3 两级去标识化数据。平台层由 Palantir Foundry（unite.nih.gov）承载，提供 SQL/Python/R 分析工作台、ATLAS 可视化与版本化代码库，并经 PPRL 与 CMS claims、死亡率、病毒变异谱等 30+ 外部数据集链接（ASPE 2025 报告）。

从研究者视角，N3C 的数据流可拆成四段可操作管线：

队列构建（官方表型）：用版本化 SQL 把 person 表 + 检测/诊断事件折叠成"阳性/阴性/不明"三态与 COVID index date；
特征工程（概念集 + 时序）：在 visit/measurement/condition/drug 上用概念集白名单抽取并重采样成规则事件表；
分析执行（飞地内 PySpark/OHDSI）：在此层面跑模型、做站点分层 CV（§5）；
结果导出（受控）：只输出聚合表、图与代码，经出口审查后带出飞地。

理解这四段能帮你把"申请飞地"和"规划分析"拆开并行推进——前两段在设计 DUR 时就要想清（你申请的数据层级与 Release 决定你能建什么队列），后两段是进入飞地后的纯工程。

§1.2 战略价值

维度一：疫情应急基础设施的范式样本。 N3C 证明了在 8 个月内把法律、治理、ETL、隐私和平台五条战线同时打通的可能性：2020-09-01 飞地开放时距离项目启动仅约半年（NDSU 入门文件）。它沉淀的 DUA 模板、用户行为准则、共享治理工作流已被后续联邦数据项目复用，2023 年其治理体系被系统总结为可复制的社会技术合作模型（Suver 2023, J Clin Transl Sci）。对研究"如何构建下一代暴发应对数据平台"的团队而言，N3C 本身就是研究对象。

维度二：Long COVID 研究的事实上主战场。 RECOVER 计划以 N3C 为 EHR 支柱：Pfaff 等人 2022 年在 Lancet Digital Health 上基于 97,995 名成人患者与三家 Long COVID 门诊数据，用机器学习建立了首个循证 Long COVID 识别模型；后续的再感染特征（Hadley 2024, Communications Medicine）、风险因素（Hill 2022）、疫苗对 Long COVID 的保护作用均依赖该平台。对于想进入 PASC/Long COVID AI 建模的研究者，N3C 是目前唯一同时具备规模、纵向深度与表型工具链的公开受控资源。

维度三：真实世界证据的政策影响力。 N3C 上的 Paxlovid 真实世界研究直接支撑了联邦用药政策调整；孕妇疫苗有效性研究（Qin 2024, BMJ Public Health）为高危人群接种策略提供了全国性证据。这类"数据 → 研究 → 政策"的完整闭环在开放学术数据集中极为罕见，也意味着在此平台上的模型审计与偏差分析工作具有超越论文的直接公共价值。

给你的一句话价值判断：N3C 的真正稀缺性不在"更多数据"（那只是量变），而在三点制度性红利——全国一致的 OMOP 标准（省去你跨系统清洗的巨大成本）、飞地内嵌的可审计代码生态（研究过程自带可复现 DNA）、以及对 Long COVID 这一仍在演化病种的前沿表型资产。如果你要研究的问题恰好落在"多中心、需纵向、面向美国人群、关乎疫情遗留负担"，N3C 通常是绕不开的最优选项；反之，若你只需单中心深表型或能接受较小规模，它较重的申请与飞地约束未必划算。

§1.3 同类数据集横向对比

数据集	规模	模态	访问方式	与 N3C 的差异化
N3C	2,285 万患者 / 225 亿+ 行	多系统 EHR（OMOP）+ 文本 NLP + CMS 链接	飞地内申请审核，不可下载	全国 50 州、版本化表型、Long COVID 工具链最全
MIMIC-IV	约 25.7 万成人住院	单中心 ICU 全维度	PhysioNet 凭证申请，可下载	深度远超 N3C 但仅一家医院；N3C 胜在广度与人群外推
All of Us	数十万深表型参与者	EHR + 基因组 + 问卷 + 可穿戴	受控工作台申请	有基因组与纵向随访，但 COVID 专项表型与规模不及 N3C
OneFlorida+	约 2,000 万佛罗里达居民	州域 EHR+claims	数据分类分级审核	区域深度网络，可作为 N3C 结果的州级外部验证
OpenSAFELY	约 5,800 万英国人	NHS 全国民 EHR	安全飞地、代码公开	类似飞地哲学但限于英国；适合跨国对照研究
TriNetX	全球 1 亿+ 患者	商业化 EHR 网络	商业许可	商业封闭模型；N3C 为非营利联邦资产且方法学透明

§1.4 版本时间轴

时间	里程碑	说明
2020-07	项目获 NCATS U24TR002306 资助	JAMIA 设计论文 2020-08 即被接收（Haendel 2021）
2020-09-01	N3C Data Enclave 正式开放	首批数据与治理文件同步公开（NDSU 文件）
2021-01	medRxiv 临床特征论文	34 个医学中心、1,926,526 名患者的首次全国描述
2022-01	69 个 hub 站点、1,070 万人、120 亿行	OHNLP NLP 基础设施同步亮相（OHDSI 报告）
2022-05	Lancet Digital Health Long COVID 论文	飞地规模达 1,500 万+ 患者、580 万+ 阳性（2022-09 口径）
2022-08 至 2023-03	L3C Long COVID 挑战赛	50 万美元奖金，Synapse 托管（NIH webinar）
2024-10	Release 184	22,854,489 患者、746,939 死亡（NLM 档案）
2025-05-16	Release 193	2026 年发表的研究仍在引用该版本（World J Hepatol 2026）
2024 起	更名 N3C Clinical 并扩建多飞地	N3C Cancer / Renal / Education / Covid 分域扩展（Utah CTSI）

§1.5 典型应用场景

Long COVID（PASC）识别与亚型发现：结合 ICD-10 U09.9、门诊记录与 ML 表型，构建数万至十万级 PASC 队列，做风险预测与症状聚类。
疫苗与药物真实世界有效性：利用 Delta/Omicron 分期与 CMS 链接数据，做目标试验模拟与阴性对照校准。
再感染与重症预警模型：以检验确认的再感染为结局，跨变种的时变协变量建模。
联邦化临床 NLP：在 OHNLP 框架与合成文本语料上开发/评测症状抽取规则，不接触原文即可复现（Liu 2023, JAMIA）。
数据平台社会技术研究：治理、伦理、公平性与政策影响研究可直接引用其公开治理文档与仪表盘。

不同角色的进入方式差异明显，可据此判断自己是否适合使用 N3C：

角色	用 N3C 做什么	门槛提示
临床研究者	Long COVID、疫苗/药物、孕期/儿科专项	需 DUA + IRB 决定函（若 L3），临床问题驱动最顺
数据科学家/ML 工程师	表型、预测、NLP、跨期外推	需精通 OMOP/OHDSI 与飞地内 PySpark；本地习惯要先改
流行病学家	真实世界有效性、偏倚控制方法	重点关注检测确认偏倚与家庭自测局限（§7.1）
计算社会学/政策研究者	健康差异、治理机制研究	可用公开仪表盘 + 治理文档，甚至不必申请患者级数据
医学生/教学	方法学演示、课堂作业	用 Level 1 Synthetic 即可，最快上手

关键取舍一句话：N3C 的数据质量、治理与人群广度是一流的，但它的**“飞地内、不可下载、按项目授权”**属性决定了它适合"做一项全国级队列研究或方法学论文"，不适合"快速上手跑 demo"或"做需要本地多次迭代的竞赛刷分"——后者请优先考虑可下载的开源 EHR（如 MIMIC）。

§2 医学背景

§2.1 ICD-11 编码映射

N3C 的诊断事件来自站点 ICD-10-CM 编码（含新冠专用 U07.1、U09.9 等紧急编码），经 OMOP 词汇表映射后可跨分类系统检索。下表给出核心疾病在本数据集语境下的 ICD-11 对应。

疾病/概念	ICD-11 编码	ICD-11 中文名	在 N3C 中的角色
COVID-19（病毒确认）	RA01.0	2019 冠状病毒病，病毒已确认	阳性病例主编码之一（U07.1 的 ICD-11 对应）
COVID-19（病毒未确认）	RA01.1	2019 冠状病毒病，病毒未确认	仅有临床诊断、无检测记录的病例
Post COVID-19 Condition	9C81	新冠后状况（Long COVID）	ICD-10 U09.9 的 ICD-11 对应；PASC 结局定义
肺炎	CA40	肺炎	重症并发症主轴之一
脓毒症	1G40	脓毒症	住院重症结局定义常用组分
2 型糖尿病	5A11	2 型糖尿病	高危合并症/风险因素
慢性阻塞性肺疾病	CA22	慢性阻塞性肺疾病	高危合并症/风险因素
急性呼吸窘迫综合征（ARDS）	5A77	急性呼吸窘迫综合征	危重结局指标

§2.1b SNOMED CT 映射

标签	ICD-11	SNOMED CT 码	术语
COVID-19	RA01	840539006	Disease caused by Severe acute respiratory syndrome coronavirus 2
SARS-CoV-2（病原体）	RA01	840533007	Severe acute respiratory syndrome coronavirus 2 (organism)
Post COVID-19 condition	9C81	1119302008	Post COVID-19 condition
SARS-CoV-2 疫苗接种	—	840544004	Vaccine product containing only Severe acute respiratory syndrome coronavirus 2 antigen
SARS-CoV-2 抗体检测	—	840535000	Antibody to SARS-CoV-2 (substance)

注：OMOP concept_id 与上述编码的映射经 OHDSI ATHENA/ATLAS 词汇表完成；N3C 研究者通常以 concept set 方式引用而非直接书写源码（World J Hepatol 2026 的 concept set 实践）。

§2.2 疾病简介与流行病学

COVID-19 由 SARS-CoV-2 引起，临床谱从无症状感染到急性呼吸窘迫综合征、多器官衰竭与死亡。美国 CDC 数据显示疫情呈多波次流行（原始株、Alpha、Delta、Omicron 及其亚型），不同波次的重症发生率、检测可及性与主导毒株差异显著——这正是 N3C 把"病毒变异谱数据"纳入飞地外部库、并把变种分期（pre-Delta/Delta/Omicron）作为标准分析分层的原因（National Academies 研讨会记录）。除急性期外，约相当比例的感染者出现持续 3 个月以上的多系统症状，即 Post COVID-19 Condition（PASC/Long COVID）：N3C 团队在 2021-10 即识别出约 10 万例可能病例、2022-05 超 20 万例（NIH 新闻稿）。N3C 队列本身覆盖 84 个医疗系统、50 个州，人群比普查更种族多样，但偏向城市学术医疗中心（Sidky 2023, BMC Med Res Methodol）；约 15% 为儿童患者（Current Opinion 2025）。

N3C 文献把疫情划分为三个主导毒株分期，这既是病毒流行学事实，也是数据集内建的"时间分析轴"——每个分期对应不同的检测强度、住院风险与疫苗接种背景：

变种分期	大致时间（美国主导期）	对 N3C 分析的含义	代表研究
Pre-Delta（原始株/Alpha）	2020-03 至 2021-06	检测以 PCR 为主，感染识别最完整；疫苗逐步铺开	Qin 2024 有效性基线期
Delta	2021-07 至 2021-12	重症率高，突破性感染开始出现	孕妇重症 aHR 0.65（Qin 2024）
Omicron 及亚型	2021-12 起	家庭抗原检测普及、感染检出率下降、再感染高峰	再感染最多期（Hadley 2024）

Long COVID（PASC）在 N3C 中呈现为多系统症状群。Pfaff 2022 的 ML 分析显示，识别信号集中于乏力、呼吸困难、心悸、味觉嗅觉障碍、"脑雾"等神经认知主诉与医疗利用变化；N3C+RECOVER 的聚类研究进一步把患者分为具有不同器官系统负担的亚型（Reese 2022）。对建模者的提示是：Long COVID 在数据里不是单一编码（U09.9 采用滞后且稀疏），而是"编码 + 门诊 + 症状模式 + 利用度变化"的复合信号。

§2.3 临床任务定义

任务类型	定义	在 N3C 中的实现路径
筛查	识别感染/PASC 高风险人群	版本化 COVID 表型 + U09.9/门诊标签 + ML 补充识别
诊断	区分急性感染、再感染与 Long COVID	检验（NAAT/抗原）+ 诊断码 + 时间窗逻辑
分级/严重度	无症状 → 门诊 → 住院 → ICU → 死亡	WHO 严重度分层（medRxiv 2021）+ 住院/吸氧/机械通气记录
预后	死亡、再住院、Long COVID 发生	生存分析与时变协变量模型，CMS/死亡率数据增强

§2.4 患者人群

维度	描述
来源	84 个美国医疗系统（CTSA hubs、IDeA-CTR 及合作医院），覆盖 50 州（截至 2025，Current Opinion 2025）
时间跨度	服务日期 2017-07-05 至 2025-01-31（Release 184；日期已按患者平移）
年龄	无官方年龄上限；含成人（核心分析 ≥18 岁）与儿童（约 15%）
性别/种族	女性占比略高（Long COVID 队列约 62.8% 为女性，Hill 2022）；比普查更种族多样（Black 占比高于普查，Asian 偏低）
就医类型	住院、急诊、门诊、远程医疗、药房记录混合
病例构成	COVID 阳性约 900 万（2025 口径）；非阳性对照按约 1:2 比例纳入

需要澄清的"人群≠样本框"三个误区：

N3C 不是简单随机样本：它是由"与贡献系统交互且触发新冠表型/对照采样"的患者组成的实用队列，而非人群概率样本——据此做患病率外推须谨慎。
阴性对照是设计组分而非"健康人群"：对照是有 SARS-CoV-2 检测但为阴性的患者，通常因就医行为而被采样，其患病负担高于一般人群，不能当作无病参照系。
患者总量会随 Release 波动：同一患者在多个系统、多次版本间重复计数会改变总量统计，跨论文比较时务必锁定同一 Release 与统计口径（§6.5 坑点 3/6）。

§2.5 临床价值

N3C 的临床价值集中在三点：其一，把"单家医院的观察"升级为"全国性的证据"，使 Paxlovid 有效性、疫苗对 Long COVID 的保护力等结论具备跨系统稳健性；其二，纵向回溯至 2018 年的基线数据允许控制感染前状态，这是多数调查型 Long COVID 研究做不到的；其三，CMS claims 链接补足了 EHR 看不到的院外处方与死亡终点，使"处方是否被取药、患者是否死亡"这类硬终点可核查（National Academies 记录）。

人群维度的三个务实提醒：

年龄谱完整但儿童专项样本相对少：成人分析 ≥18 岁为主，儿童约占 15%（Current Opinion 2025）——做儿童 Long COVID 需自行确认样本量是否支撑细分亚组。
种族构成利于差异研究但要防"可及性混淆"：Black 人群占比高于普查，这对差异研究是优势；但低检测可及性社区的"检测少"易被误读为"感染少"（§7.5）。
站点匿名化限制地理叙事：站点用匿名编号，做"某州表现如何"需 L3 + 地理编码 IRB 授权；城市 vs 农村叙事建议引用 Anzalone 2024 的既有结论而非自行推导。

§2.6 金标准表

维度	内容
划分	无官方 ML 划分；社区惯例按患者/站点分组划分，按变种分期做时间外推验证
标注方式	规则化表型（版本化，N3C GitHub 公开逻辑）+ 弱监督 ML（Long COVID）+ 门诊锚定标签
标注者	Phenotype & Data Acquisition 工作流的多机构专家共识；Domain Team 持续修订
性质	真实世界回顾性队列；标签为"推断标签"而非前瞻性金标准，需敏感性分析支撑

§3 数据集规格

§3.0 版本抉择矩阵

N3C 的"版本"有两层：数据层级（Level 1/2/3） 与 数据发布版本（Release 编号）。选层级之前先回答"你的需求"：

你的需求	推荐层级	数据内容	理由
教学、代码演示、方法预开发	Level 1 Synthetic	统计相似的人工合成数据，无真实患者	无 PHI、审批最快，公民科学家亦可申请
全国性描述性研究、生态比较	Level 2 De-identified	去除 17 项 HIPAA 直标、日期平移的患者级数据	国内外研究者可申请；无需本地 IRB 决定函（按机构政策）
需要精确日期间隔、邮编地理分层的研究	Level 3 LDS	保留日期与邮编的有限数据集	仅限美国机构；必须上传 IRB 决定函
可复现方法学论文	任意层级 + 固定 Release	在 DUR 中锁定 Release 编号（如 193）	表型与数据随发布版本变动，锁定才能复现

层级描述依据 NCATS DUR 表格与 Nemours 访问指南；不同时期治理文档对层级的划分口径略有差异（如聚合层是否单列），以现行 DUA 为准。

§3.1 模态详情

模态	内容	标准化方式	备注
结构化 EHR	人口学、就诊、诊断、用药、检验、生命体征	OMOP CDM 5.3.1	核心模态，四源 CDM 统一映射
纵向时序	每患者约 1,120 行事件（2022-01 口径），回溯至 2018	OMOP 事件表 + macrovisit 聚合	行/患者为站点均值，方差极大
临床文本衍生	症状/体征 NLP 抽取结果	OMOP NOTE/NOTE_NLP	原文不出站，采用联邦式 NLP + 合成语料（Liu 2023）
外部链接数据	CMS claims、死亡率、病毒变异、环境、SDOH	PPRL 哈希链接	飞地内置 30+ 外部数据集库
疫苗接种记录	站内记录 + 州登记系统补充	OMOP immunization/observation	覆盖不均，见 §6.5 坑点 7
操作/设备暴露	手术操作、吸氧装置等	OMOP procedure/device_exposure	呼吸机设置等扩展仅部分站点提交
人口学与 SDMH 扩展	种族、民族、语言、社会决定因素	OMOP person/observation	健康差异研究的基础特征层

§3.2 子集样本数

子集	规模	来源口径
全体患者	22,854,489	Release 184（NLM 档案）
COVID 阳性	约 900 万（2025 口径）；700 万+（NCATS 页口径）	World J Hepatol 2026 / NCATS
死亡患者	746,939	Release 184
Long COVID 可能病例	10 万+（2021-10）→ 20 万+（2022-05）	NIH 新闻稿
PASC 病例-对照研究队列	8,325 vs 41,625	Hill 2022
孕妇疫苗研究队列	301,107（孕妇）/ 934,337（育龄接种者）	Qin 2024
CMS claims 链接	1,000 万+ 人，84 系统	ASPE 2025

§3.3 数据格式

组件	格式	说明
核心数据	OMOP CDM 5.3.1 关系表	person、visit_occurrence、condition_occurrence、drug_exposure、measurement、observation、procedure_occurrence、device_exposure、note 等
查询界面	Palantir Foundry / Atlas / N3C Query Explorer	SQL 为主，Python/R Code Builder 可用
外部数据	OMOP 化或 CSV 投影	死亡率、变异谱等独立数据集，可经 data_provenance 关联
NLP 语料	合成文本 CSV（开源样例）	仅开放合成/脱敏样例，真实文本不出飞地

格式层的操作提示：因为数据在 Foundry 而非文件系统，你的"格式"通常是 Spark DataFrame / SQL 表，而非 CSV/Parquet 文件（虽然 Foundry 内部以 Parquet 存储并可物化）。这带来两个习惯转变：一是尽量用 SQL/Spark 下推替代 pandas 全表载入；二是表名以"数据集引用"而非路径出现（§6.1 的 DATA_ROOT）。OMOP 生态的 Atlas/Achilles 工具在飞地内通常可用，能直接帮你跑数据画像与质量测试——这是熟悉 OHDSI 栈的团队最大捷径。

§3.4 存储大小

官方未公开全量字节大小。可量化的代理指标是行数增长轨迹——它同时反映了平台从疫情应急到常态化运营的扩张：

时点	患者数	COVID 阳性	数据行数	来源
2021 中（承包商报告）	680 万	220 万	78 亿	CIC 拨款摘要
2022-01（OHDSI 报告）	1,070 万	380 万	120 亿	OHDSI
2022-09（L3C 挑战赛）	1,500 万	580 万	175 亿	NIH webinar
2022-05 前后（NIH 新闻稿）	1,300 万	近 500 万	—	NIH
NCATS 官方页（截至 2025-08 检索）	—	700 万+	225 亿+	NCATS
Release 184（2024-10）	22,854,489	—	—	NLM 档案
2025（综述口径）	近 2,300 万	约 900 万	120 亿+ 临床观测	Current Opinion 2025

参照同类 OMOP 飞地规模，全量分析建议按"数 TB 级表存储 + 数十 TB 级集群内存"预估资源，但该估计不构成官方数字。飞地内原型开发应先用站点抽样子集（百万行级），确认逻辑后再放大到全量 Spark 作业。

§3.5 标注方式

N3C 的"标注"是版本化规则表型 + 弱监督机器学习的组合：COVID 阳性由 N3C 表型（如 v3.3）定义，逻辑组合 SARS-CoV-2 检验阳性与"强阳性"诊断码，全部逻辑公开于 N3C GitHub 并随 Release 演进；Long COVID 采用 ICD-10 U09.9/Long COVID 门诊锚定 + ML 扩展识别（Pfaff 2022）；阴性对照由表型自动纳入（约 1:2 比例）。没有人工逐例标注的金标准标签层。

表型体系的主要组件：

表型组件	定义逻辑	标注性质	更新机制
COVID 阳性（cases）	NAAT/抗原阳性检验 OR 强阳性诊断码组合	规则推断（版本化）	随检验/编码实践迭代
阴性对照（controls）	有 SARS-CoV-2 检测记录且非阳性，按 1:2 比例采样	规则推断	随 cases 同步更新
Long COVID（PASC）	U09.9 编码 OR Long COVID 门诊；ML 扩展识别	规则 + 弱监督 ML	RECOVER 计划持续修订
严重度分级	WHO 分层：门诊/住院/吸氧/ICU/死亡	规则推断	medRxiv 2021 定义沿用
疫苗接种状态	站内免疫记录 + 州登记链接	规则推断（已知不完整）	登记系统接入变化

§3.6 标注者资质与一致性

表型由 Phenotype & Data Acquisition 工作流制定，成员包括各站点医学信息学家、统计学家与临床专家，经多轮公开评审（治理文档发布于 Zenodo 征求意见）；Long COVID ML 表型的外部锚定来自三家专科门诊的医生诊断；NLP 规则集由 OHNLP 协作组（Mayo、UMN、UKY 等）专家标注合成语料，跨机构 F1 为 0.876/0.706/0.694（arXiv 2110.10780）。无统一的标注者间一致性 κ 报告——这是使用推断标签时必须自己补做的敏感性分析。

§3.7 采集周期

参与站点按每周上传节奏提交数据（National Academies 记录），管线在源数据更新后 20 分钟内即可完成刷新（OHDSI 报告）；整合后的飞地以编号 Release 发布（如 v141 于 2023-09-14、v184 于 2024-10、v193 于 2025-05-16），研究者在论文中必须注明所用 Release 与访问日期。

§3.8 地域覆盖

覆盖美国 50 个州（2023 年时点为 49/50 州、69 站点；2025 年为 84 系统），站点以城市学术医疗中心为主，农村居民代表性不足（Sidky 2023）。贡献机构以匿名编号提供，地理关联分析需 Level 3 LDS + IRB 授权。

对"全国代表性"要有精确理解：N3C 覆盖全国 50 州≠均匀代表 50 州。它是站点网络的全美投影——站点集中于 CTSA hubs 与 IDeA-CTR 覆盖的学术系统。正因如此，N3C 文献一边强调其人群多样性强于单中心，一边明确警告农村与基层医疗场景的外推需专项处理（城乡差异已有 Anzalone 2024 专文，可作 cite 而非自行假定）。做空间分层时，请把"站点覆盖盲区"当作独立分层，而非把站点当作均匀样本。

§3.9 设备规格

N3C 是 EHR 数据集，不含原始设备信号（无监护仪波形、无影像 DICOM）。与设备相关的信息以 OMOP device_exposure（如吸氧装置）与部分站点自愿提交的呼吸机设置扩展数据形式存在，覆盖站点不均，使用前须核对站点贡献列表（covid.cd2h.org/dtas）。

对需要"呼吸机天数、氧合装置级别"这类重症细节的研究，N3C 的能力边界要提前认清：基础 device_exposure（是否吸氧、是否上呼吸机）覆盖面相对好；但呼吸机参数（FiO₂、PEEP 轨迹）这类精细信号仅部分站点以"扩展数据"提交，且多数只覆盖住院重症段。若你的模型需要细粒度通气数据，优先考虑单中心深表型 ICU 集（如 MIMIC-IV）做算法开发，再考虑用 N3C 做全国外推验证——两者是互补而非替代关系。

§3.10 深度溯源链

N3C 的溯源体系是其最大卖点之一：每站点 200 万+ 项变换、跨站点 5,000 项语法映射全部自动记录；任何研究者看到的字段都能回溯到"哪个源站、哪个源模型字段、经过哪版管线"（OHDSI 报告）。源数据模型与日期平移范围作为元数据随数据提供；管线版本化使得论文可以精确声明"Release N + 表型版本 M"的双重锁定。

关于表结构的说明：N3C 遵循 OMOP CDM 5.3.1 的关系模型，没有为 COVID 单独建非标表——所有新冠信息以标准概念落在通用表中，用 concept_id 与相对日期表达。这降低了学习门槛（OMOP 生态文档海量），但也要求研究者在起飞前做一次"概念集设计"：把 U07.1/U09.9/检验/疫苗等目标翻译成一组稳定的 OMOP concept_id 并公开（World J Hepatol 2026 实践）。

与可下载开源 EHR（如 MIMIC）的差异：MIMIC 提供扁平 CSV 与现成 concepts，下载后可立即本地迭代；N3C 是飞地内的关系数据库 + Foundry 工作台，没有"一张表一个 CSV"的文件形态。前者的工程负担在下载与存储，后者的工程负担在概念集设计与飞地内 SQL/Python 连接。若你已有 OMOP/OHDSI 经验，N3C 的迁移成本会显著低于从零研究者。

§4 数据结构

§4.0 目录树

数据不可下载，但在飞地工作区内呈现为如下逻辑结构（概念示意，实际路径以你 DUR 授权的 Project Space 为准）：

N3C Enclave Workspace (unite.nih.gov)
├── datasets/
│   ├── N3C_RELEASE_193_OMOP/            # 核心数据集（按 Release 物化）
│   │   ├── PERSON/
│   │   ├── VISIT_OCCURRENCE/
│   │   ├── CONDITION_OCCURRENCE/
│   │   ├── DRUG_EXPOSURE/
│   │   ├── PROCEDURE_OCCURRENCE/
│   │   ├── MEASUREMENT/
│   │   ├── OBSERVATION/
│   │   ├── DEVICE_EXPOSURE/
│   │   ├── NOTE/                        # 临床笔记表（NLP 衍生）
│   │   ├── NOTE_NLP/                    # NLP 抽取结果
│   │   ├── DEATH/
│   │   └── DATA_PROVENANCE/             # 站点/管线溯源元数据
│   ├── external/
│   │   ├── mortality/                   # 死亡率增强
│   │   ├── viral_variants/              # 病毒变异谱
│   │   ├── cms_claims/                  # CMS 链接数据（PPRL）
│   │   └── environmental/               # 环境/SDOH 扩展
│   └── phenotype/                       # 版本化 COVID/Long COVID 表型
├── projects/
│   └── <你的 DUR 项目空间>/
│       ├── code/                        # SQL/Python/R 代码库（版本化）
│       ├── analysis/                    # 转换与输出
│       └── review/                      # 出口审查工作流
└── dashboards/                          # 公共队列仪表盘（只读）

§4.1 DAIMS 字段字典

核心 OMOP 表字段（8 列：字段名/类型/说明/示例值/AI 用途/观测误差/信息性缺失编码/取值范围）：

字段	类型	说明	示例值	AI 用途	观测误差	信息性缺失	取值范围
person.person_id	Integer	患者唯一标识	12,345,678	分组键、防泄漏	跨站重复（无法链接同一人多系统）	无	全体患者
person.year_of_birth	Integer	出生年	1965	年龄特征	老年极端值偶有错误	NULL/0	1900-2025
person.gender_concept_id	Integer	性别概念	8,532（FEMALE）	分层公平性	站点录入差异	0 = 未知	OHDSI Gender 词汇
person.race_concept_id	Integer	种族概念	8,516（White）	偏倚评估	站点分类口径不一	0 = 未知	OHDSI Race 词汇
visit_occurrence.visit_start_date	Date	就诊开始（已平移）	2021-05-14	时序对齐	日期随机平移，绝对日期不可比	NULL 少见	2017-07 至今
condition_occurrence.condition_concept_id	Integer	诊断标准概念	3,731,10553（U09.9 映射）	表型/结局标签	U09.9 采用滞后	0 = 无映射	OMOP Condition 词汇
drug_exposure.drug_concept_id	Integer	药物 RxNorm 概念	1,737,328（Paxlovid 组分）	暴露定义	住院用药捕获差异	0 = 无映射	RxNorm
measurement.value_as_number	Float	检验/体征数值	12.4	特征、严重度	单位混乱（如 g vs kg）	NULL = 未测	连续值
measurement.unit_concept_id	Integer	单位概念	9,448（mg/dL）	单位归一	部分站点缺失	0 = 缺失	UCUM 词汇
note.note_nlp_concept_id	Integer	NLP 抽取概念	4,127,4314（症状）	文本特征	规则 F1 随站点 0.69-0.88	0 = 未抽取	OMOP 词汇
death.death_date	Date	死亡日期（已平移）	2022-01-03	结局标签	院外死亡漏检（需死亡率增强）	无记录 = 未在飞地内观测到	—
data_provenance.source_id	Integer	贡献站点匿名编号	42	站点分层/随机效应	机构身份匿名	无	1-100+

概念集设计速查（构建 COVID 特征/结局时的常见 OMOP 概念锚点；数值为示意，务必用 ATHENA/ATLAS 查实际 concept_id）：

目标概念	常驻表	检索建议	注意点
SARS-CoV-2 核酸检验阳性	measurement	NAAT concept set	抗体不作为感染证据（可能为疫苗接种/既往感染）
疫苗暴露	drug_exposure / observation	疫苗概念集 + 州登记链接	覆盖不均（§6.5 坑点 7）
COVID-19 诊断	condition_occurrence	U07.1 映射 concept set	仅诊断码索引日期可能不准
Long COVID / PASC	condition_occurrence	U09.9 概念集	采用滞后，需 ML 补充（§2.2）
合并症指数（Charlson/Elixhauser）	condition_occurrence	OHDSI 预置概念集	需在 index 前时间窗计算
症状（乏力/呼吸困难/脑雾）	note_nlp / observation	NLP 概念组	NOTE_NLP 覆盖站点有限

每次构建后做三件事：记录概念集版本、核对跨站点覆盖差异、与官方表型做交叉验证——概念集是 N3C 里最容易出错也最该被审稿人追问的地方（§6.5 坑点 4 相关）。

§4.2 标签分布

COVID 阳性与阴性对照按约 1:2 纳入（Sidky 2023），即阳性约占数据人数的 1/3；Long COVID 可能病例由 2021-10 的约 10 万增至 2022-05 的 20 万+；死亡 746,939（Release 184，占 3.3%）。注意这是"摄入设计比例"而非自然患病率——做患病率类推前必须校正。

§4.3 关键统计

指标	数值	时点/来源
患者总数	22,854,489	Release 184（NLM）
行/患者	约 1,120	2022-01（OHDSI）
站点数	84 系统 / 98 站点（不同口径）	2025（Current Opinion / World J Hepatol）
研究者数	4,300	2025（Current Opinion）
论文数	296	2025（同上）
外部数据集	30+	NCATS

§4.4 数据层级

患者 → （macrovisit 聚合的）就医过程 → 临床事件（诊断/用药/检验/操作）→ 事件属性（日期、值、单位、类型、来源站点）。N3C 特有的是第五层：溯源层——DATA_PROVENANCE 与站点元数据让每个事件可回溯到匿名站点与管线版本；以及第六层：外部链接层——经 PPRL 哈希链接的 CMS 与死亡率数据。分析时建议以 person 为分组单元、以 macrovisit 为暴露/结局窗口单元。

§4.5 缺失值与信息性缺失

缺失类型	机制	处理建议
检验未做	医疗决策未触发 → 非随机缺失（informative）	以"是否检测"指示变量显式建模
站点不采集	ETL 站点差异（如体重单位、疫苗登记）	用 data_provenance 站点级聚合诊断，站点分层
小格抑制	计数 <20 被抑制（LHC Profile 口径）	聚合层与患者层数字对不上时先查抑制规则
日期平移	隐私保护（每患者随机平移）	一律用相对时间（距 index 天数），禁用绝对日期
文本未抽取	NOTE_NLP 覆盖站点有限	区分"无记录"与"未抽取"两种 NULL

补充三类在真实 N3C 分析中反复出现的缺失陷阱，供建模者在写数据说明时逐条核对：

陷阱	现象	为什么会这样	设计反应
前导期缺失	2020-03 前"没有新冠事件"	表型只对检测/症状相关患者采样，2020 前为基线期而非空	基线期用于暴露前特征，勿把前导空当作"未感染"对照
随访截断	变种更迭后随访不完整	Omicron 期检测转家庭、就医减少	生存分析按 index 时间分层 + 截尾声明
出院后缺失	死亡/再入院被低估	EHR 只捕获本院事件；CMS 链接才补院外	结局用 CMS/死亡率增强子集做敏感性分析

§5 数据划分与使用建议

§5.1 官方划分

N3C 不提供官方训练/验证/测试划分——它本质是研究飞地而非竞赛数据集。唯一的"官方"切分逻辑是 L3C Long COVID 挑战赛的设计：Long COVID 与非 Long COVID 按 1:4 抽样、以 COVID index 日期后 4 周截尾（censored），训练与测试集分阶段替换（NIH webinar）。该设计可作为你的时间截尾参考。

§5.2 社区惯例与推荐划分

患者级分组划分：以 person_id 为组做 GroupShuffleSplit，杜绝同一患者事件跨集。
站点级外推划分：按匿名站点分组，留出整站做外推测试——这最接近"模型部署到新医院"的现实。
变种分期时间划分：以 pre-Delta / Delta / Omicron 分期为训练/验证/测试，是 N3C 文献的标配（Qin 2024、Hadley 2024）。

import pandas as pd
from sklearn.model_selection import GroupShuffleSplit

# 患者级特征表（飞地内物化后的 Parquet，字段见 §4.1）
patients = pd.read_parquet("N3C_RELEASE_193_OMOP/person_features.parquet")
gss = GroupShuffleSplit(n_splits=1, test_size=0.2, random_state=42)
train_idx, test_idx = next(gss.split(patients, groups=patients["person_id"]))
assert set(patients.iloc[train_idx].person_id).isdisjoint(
    set(patients.iloc[test_idx].person_id))  # 患者级零泄漏

§5.3 泄漏风险（重点）

泄漏通道	机理	症状	审计方法
跨站重复患者	同一人多系统记录不可链接	测试集出现近重复特征向量、AUC 异常偏高	特征空间近重复审计（欧氏距离 < 阈值）
macrovisit 窗口泄漏	入院后才知的信息进入早期特征	ICU 预测 AUC > 0.98 的"完美模型"	特征一律锚定 index 日期做时间截尾
表型-结局同源	COVID 阳性诊断码又充当结局标签成分	标签与特征共用编码，估计被高估	特征窗口剔除结局编码后重训
检测-结局相关	检验触发住院/诊断，反向因果	检验次数本身成为强"预测因子"	把检测次数当利用度协变量而非暴露
Release 内时间泄漏	未来 Release 补录早期事件	早期样本被"未来回填"污染	锁定单 Release，不跨 Release 混表

§5.4 交叉验证与外部验证建议

分层 CV 采用站点 × 变种分期双重分层：外层按分期做时间外推验证（pre-Delta 训练 → Omicron 测试），内层按站点留出做空间外推验证（留出整站）。方法学上可复用阴性对照与活性对照校准混杂控制（Sidky 2023）。

外部验证首选飞地内的 CMS 链接子集与死亡率增强数据——它们构成"真外部"的独立终点，且无需导出数据即可闭环（PPRL 已完成跨源去重）。跨数据集（如 OneFlorida+、MIMIC-IV）验证不可行——数据不能出飞地，只能在飞地内部构造"伪外部"的站点级留出与分期外推。若论文需要外部金标准支撑（如把 Long COVID ML 表型与三家门诊画像对拍），官方 Pfaff 2022 的"门诊锚定"设计是现成模板：先在锚定子集上校准，再全量外推。

§6 AI 就绪指南 ⭐

§6.0 云端快速启动

N3C 没有本地模式：唯一的运行环境是 N3C Data Enclave（Palantir Foundry，unite.nih.gov）。启动路径：

机构签署 DUA → 2. 注册飞地账号（需 ORCID + 2FA）→ 3. 完成 NIH 信息安全培训（约 60-90 分钟）与人类受试者培训（L2/L3 必需）→ 4. 提交 DUR → 5. DAC 审批（约 1 周，机构 DUA 备案则可能需数周）→ 6. 进入 Project Space，使用 Code Builder（Python）、R 或 SQL Workshop（Utah CTSI 流程）。

一个常见的误判是"今天提交明天就能看数据"。从 NDSU 官方 onboarding 时间线看，理想状态下法务与培训同步推进约需 1 个月；若机构 DUA 尚未备案或需 IRB 决定函，周期可拉到数月（NDSU 入门文件）。务实建议：把申请的六个步骤与建模立项并行启动，并在 DUR 里写明你希望访问的 Release 与层级，避免中途补交材料拖延。

飞地内的典型工程约束（对应你的技术选型）：

约束	影响	应对
数据不可下载导出	无本地训练/本地原型	一切代码在飞地 Code Builder 内开发与运行
软件上传须书面批准	不能随手装任意库	优先使用预置 OHDSI/PyTorch/scikit-learn 栈
患者级结果不可出飞地	只能带聚合/图/代码出	出口审查前置进流程设计
会话按 DUR 项目隔离	不同项目数据不互通	跨项目分析需另申请或合并到同一 DUR

§6.1 快速上手

以下代码假定：你的 DUR 已获批、Level 2/3 数据已授权、核心 OMOP 表已按 Release 193 物化为可查询数据集。DATA_ROOT 对应飞地内你的项目空间中物化数据集的逻辑路径——在 Foundry 中它是一个数据集引用而非文件系统路径。

# 目录预期：DATA_ROOT 下的 OMOP 表以 Parquet 形式可被 Spark/Python 读取
# data_root 拼接关系：DATA_ROOT = "<你的项目空间>/<物化数据集路径>"
# 最小可用子集：PERSON + CONDITION_OCCURRENCE + MEASUREMENT 三表即可跑通原型
from pyspark.sql import SparkSession

spark = SparkSession.builder.getOrCreate()          # Foundry 托管会话
DATA_ROOT = "N3C_RELEASE_193_OMOP"                   # 飞地内物化数据集引用名

person = spark.table(f"{DATA_ROOT}.person")
cond   = spark.table(f"{DATA_ROOT}.condition_occurrence")

# 构建 COVID 阳性患者清单：以检验确认优先，仅作示例骨架
covid_pos = cond.filter("condition_concept_id = 37311055")  # U07.1 映射概念（示例）
print(f"COVID 阳性（诊断码路径）: {covid_pos.select('person_id').distinct().count():,}")

真实研究应以官方 N3C 表型 SQL 为准（飞地 phenotype 目录内含版本化脚本），上例仅演示数据路径与表连接方式。

§6.2 数据获取

步骤	内容	耗时参考	依据
1	机构与 NCATS 执行 DUA	数周（机构法务）	DUA 文本
2	个人注册（ORCID、2FA）	1-3 天审批	Nemours 指南
3	NIH 信息安全培训 + 人类受试者培训（L2/L3）	半天	同上
4	提交 DUR（项目标题、250 词公开摘要、500 词计划）	DAC 审批约 1 周	Utah CTSI
5	L3 额外上传 IRB 决定函	依机构	NCATS DUR 表
6	DUR 一年有效，到期续期	—	同上

约束要点：Level 3 仅限美国机构研究者；公民/社区科学家只能申请 Level 1；数据不可下载、一切分析在飞地内；软件上传须经书面批准；项目必须与 DUR 声明范围一致（"dual use"限制的直接来源就是 DUA 的项目范围条款与 User Code of Conduct——不得将数据用于 DUR 之外的任何目的）。

§6.3 预处理全流程

第一步：构建基础队列（SQL，飞地内）。 以官方表型锁定 COVID index；用 macrovisit 合并同次就医：

-- COVID index date：首条阳性检验或强阳性诊断，取较早者（示例骨架）
WITH index_events AS (
  SELECT person_id,
         MIN(clip_date) AS covid_index_date
  FROM covid_positive_events          -- 官方表型产物表
  GROUP BY person_id
)
SELECT p.person_id,
       e.covid_index_date,
       DATEDIFF(v.visit_start_date, e.covid_index_date) AS days_from_index
FROM index_events e
JOIN person p USING (person_id)
LEFT JOIN visit_occurrence v USING (person_id)
WHERE v.visit_start_date >= DATE_SUB(e.covid_index_date, 30)

第二步：单位与量纲清洗（Python）。 重点核 measurement 的 unit_concept_id；体重类变量按站点检查 g/kg 混用（ Bradwell 2022 修复算法的思路见 National Academies 记录）。

import pandas as pd

def normalize_weight(df: pd.DataFrame) -> pd.DataFrame:
    """按单位概念归一体重到 kg；g→kg 除以 1000。"""
    kg  = df.unit_concept_id == UNIT_KG
    g   = df.unit_concept_id == UNIT_G
    df.loc[g, "value_as_number"] = df.loc[g, "value_as_number"] / 1000.0
    df.loc[~(kg | g), "value_as_number"] = pd.NA   # 其余单位不臆测
    return df

第三步：时序特征化。 一律以 days_from_index 为时间轴；把检验/生命体征/用药事件重采样为规则时间网格（如 7 天窗），缺失留 NaN 并附加"是否检测"指示位（§4.5）。第四步：文本特征。 直接 join NOTE_NLP 的概念计数特征；若需自训 NLP，遵循联邦式流程——规则在飞地内各站执行，仅回传聚合评估指标（Liu 2023）。

§6.4 PyTorch DataLoader

在飞地内用 PyTorch 完全可行（Code Builder 支持自定义环境）。下例把患者的 OMOP 事件序列打包成固定长度概念序列，用于序列模型（表型/死亡预测）：

import torch
from torch.utils.data import Dataset, DataLoader
import pandas as pd

class N3CSequenceDataset(Dataset):
    """把 OMOP 事件表转为患者级概念 id 序列。
    预期输入：events.parquet 至少含 person_id / days_from_index /
    concept_id 两类列；SEQ_LEN 为最大回看天数窗口内的事件数上限。"""
    def __init__(self, events_path: str, labels_path: str,
                 seq_len: int = 256):
        self.events = pd.read_parquet(events_path).sort_values(
            ["person_id", "days_from_index"])
        self.labels = pd.read_parquet(labels_path).set_index("person_id")
        self.seq_len = seq_len
        self.index = self.events.groupby("person_id").indices

    def __len__(self):
        return len(self.index)

    def __getitem__(self, idx):
        pid = list(self.index.keys())[idx]
        ids = torch.tensor(
            self.events.iloc[self.index[pid]].concept_id.values[:self.seq_len],
            dtype=torch.long)
        if len(ids) < self.seq_len:                     # 尾部 padding = 0
            ids = torch.cat([ids, torch.zeros(self.seq_len - len(ids),
                                              dtype=torch.long)])
        y = int(self.labels.loc[pid, "label"])
        return ids, y

ds = N3CSequenceDataset("N3C_RELEASE_193_OMOP/events.parquet",
                        "N3C_RELEASE_193_OMOP/labels.parquet")
dl = DataLoader(ds, batch_size=128, shuffle=True, num_workers=4)

训练与验证的可复现骨架（飞地内 Code Builder 运行）：把 §5 的站点分层验证落到实处——数据加载与训练之间插入"按站点分组"的索引映射，杜绝跨站重复泄漏：

import numpy as np
from torch.utils.data import Subset

def make_site_folds(ds, df_site, k=5):
    """按站点做 k-fold：同一 person 只出现在一个 fold，跨站近重复靠源表去重控制。"""
    sites = df_site.set_index("person_id").reindex(list(ds.index.keys()))["source_id"]
    folds = []
    for _ in range(k):
        tr = sites.sample(frac=0.8, random_state=0).index
        folds.append((list(tr), list(set(sites.index) - set(tr))))
    return folds

# 训练主循环（示意）：空实现替换为你的优化器/损失
for epoch in range(3):
    for xb, yb in dl:
        # logits = model(xb)  # 概念 id 序列 → embedding → 分类头
        pass

飞地内 GPU 需单独申请配额；若仅 CPU，优先用 torch.set_num_threads 并减小 batch。序列模型的收益通常在 N3C 上有限（事件稀疏），建议先把 XGBoost 基线跑出来再做序列对照。

§6.5 坑点 8 个

⚠️ 坑点 1：家庭自测时代感染与再感染被系统性低估（分类：偏倚陷阱）

问题：居家抗原检测自 Omicron 期起普及，阳性结果从不进入 EHR；官方再感染研究明确承认由此低估再感染人数，且该偏差随时间不均匀（Hadley 2024）。
症状：再感染率在 Omicron 期"突然下降"或平台期；感染率曲线与社区 wastewater/CDC 估计脱节。
解决：

简单方法：把分析人群的感染窗口截断到 2022-12-31 前（官方做法），或以"需要医疗交互的结局"（住院、Long COVID 诊断）为终点。

进阶方法：敏感性分析按检测可及性分层（家庭检测可及性代理变量），对缺失检测做逆概率加权。

SOTA 方法：与 wastewater/血清阳性率外部数据在飞地内做三角验证，把检测概率建模为时变混杂。
参考：Hadley 2024, Communications Medicine, doi:10.1038/s43856-024-00539-2。

⚠️ 坑点 2：日期随机平移让"绝对日期"全部不可信（分类：预处理陷阱）

问题：每位患者的服务日期按站点策略随机平移（modest random date shifting）以保护隐私；不同患者的平移量不同，同一患者内部保持相对间隔。
症状：按日历月聚合的"疫情波次"特征失真；跨患者比较绝对日期出现荒谬结论（如 2020-04 的"高峰"分散数月）。
解决：

简单方法：一切时间特征改用相对时间（距 index 天数、住院第 N 天）。

进阶方法：需要真实日历时（如与变种流行期对齐），用官方提供的平移范围元数据 + 站点级聚合近似还原，或在 DUR 中申请 Level 3 以获取未平移的日期粒度逻辑说明。

SOTA 方法：以变种分期（由官方 epoch 表定义）替代日历时间做时变校正。
参考：N3C 治理论文（Suver 2023, J Clin Transl Sci）。

⚠️ 坑点 3：同一患者跨机构无法链接，重复计数污染评估（分类：数据泄漏）

问题：EHR 记录只在贡献站点内部链接；患者在多个系统就医时产生多条独立记录，官方研究明确说明无法跨院合并（Hadley 2024）。PPRL 仅用于对 CMS/死亡率等外部源链接，不跨贡献站点去重。
症状：罕见病"新发病例"数量虚高；患者级划分后测试集出现疑似同一人的近重复特征向量；模型在"跨站重复"子群上 AUC 异常。
解决：

简单方法：按 person_id 严格分组划分（§5.2），并在结果里报告"无法排除跨站重复"的局限。

进阶方法：在飞地内做模糊近重复审计（人口学 + 就诊轨迹相似度），把可疑重复对整体移入同一侧。

SOTA 方法：将分析单元升级为"人-站点对"（person-site dyad），或只使用 CMS 链接子集（PPRL 已完成跨源去重）。
参考：Hadley 2024 limitations 节；N3C PPRL 方法报告（ASPE 2025）。

⚠️ 坑点 4：表型版本漂移——你的队列定义会随 Release 改变（分类：标签理解）

问题：N3C COVID 表型持续迭代（如 v3.3），Long COVID 识别从纯 U09.9 编码演进到 ML 辅助；不同 Release 下同一逻辑返回的队列规模不同。
症状：论文复现时数字对不上；审稿人问"你用的哪个表型版本"；U09.9 队列在早期 Release 明显偏小（编码采用滞后）。
解决：

简单方法：在 DUR 与论文中锁定 Release 编号 + 表型版本（如 Release 193 + 表型 vX.Y），并在方法节引用 N3C GitHub 的对应 tag。

进阶方法：对两个相邻表型版本各跑一遍，报告队列重叠矩阵（Jaccard），证明结论对版本不敏感。

SOTA 方法：用官方 ML Long COVID 表型与 U09.9 定义分别做主分析与敏感性分析（Pfaff 2022）。
参考：N3C GitHub 表型仓库；Sidky 2023（表型版本 v3.3 引用方式）。

⚠️ 坑点 5：单位与站点 ETL 差异制造"幽灵异常值"（分类：预处理陷阱）

问题：各站点对同一变量的采集口径不同——官方举例：体重有的站按克、有的按千克记录，须算法修复（Bradwell 2022，转引自 National Academies 记录）；即使统一到 OMOP，站点 ETL 实现差异依然存在（Sidky 2023）。
症状：value_as_number 出现 70,000 kg 的"体重"；某实验室指标分布呈双峰；按站点分层后模型系数翻转。
解决：

简单方法：以 unit_concept_id 归一（§6.3 第二步），并对每变量做站点级分布审计（百分位对比表）。

进阶方法：参考值范围 + 合理生理区间双重校验，可疑记录置 NA 并保留指示位。

SOTA 方法：用 COMPASS/官方数据质量工具（Data Quality Dashboard、Achilles）跑站点级画像后再建模。
参考：Sidky 2023, BMC Med Res Methodol 23:46；JAMIA 2021 论文 Table 3 工具清单。

⚠️ 坑点 6：小格抑制与层级口径让数字"对不上"（分类：工程陷阱）

问题：公开仪表盘与档案对计数 <20 的小格抑制（LHC Profile 口径），Level 1/2/3 的可见粒度也不同；同一指标在聚合层与患者层常出现不一致。
症状：你的患者层计数与仪表盘差几十人；外部读者用仪表盘数字质疑你的论文；跨层级 join 后行数莫名变少。
解决：

简单方法：所有对外报告注明"患者层、Release N、未抑制"口径。

进阶方法：与官方仪表盘对数时，主动按抑制规则把 <20 的格子合并后再比较。

SOTA 方法：在方法节附上"数据对账表"（reconciliation table），列明层级、Release、抑制规则三要素。
参考：NLM LHC N3C Profile（counts less than 20 were suppressed）。

⚠️ 坑点 7：疫苗接种状态是出了名的脏字段（分类：偏倚陷阱）

问题：州/县疫苗登记系统接入程度参差，院外接种常缺记录；官方研究承认"无记录者被归为未接种"造成误分类，N3C 总体接种率低于 CDC 估计（MDPI Vaccines 2024、National Academies 记录）。
症状：疫苗有效性分析出现"接种者感染率更高"的荒谬方向；接种率地图与 CDC 数据系统性偏低；阴性对照（感染不可能影响既往接种）不通过。
解决：

简单方法：把接种状态当作带缺失的暴露做敏感性分析，而非二值真值。

进阶方法：使用官方"高度可信接种"标志（多源验证过的子集），并用阴性对照事件校准残余混杂。

SOTA 方法：目标试验模拟 + 边际结构模型处理时变接种与检测强度（参考 Qin 2024 的分期处理）。
参考：Brannock 2023（疫苗与 Long COVID）；MDPI Vaccines 12(3):289 limitations 节。

⚠️ 坑点 8：visit 粒度陷阱——住院时长与暴露窗口算错（分类：预处理陷阱）

问题：源 EHR 的一次住院常被拆成多条 OMOP visit 记录（转科、转院、账单拆分）；N3C 提供 macrovisit 聚合算法把"同一就医过程"合并，但很多研究者直接用原始 visit 计算住院时长或院内暴露，导致系统性偏差（Sidky 2023）。
症状：住院时长分布出现大量 1 天的"短住院"；remdesivir 暴露天数被截断；"出院后 48 小时内再入院"率异常高（其实是同次住院）。
解决：

简单方法：一切住院级分析先 join macrovisit 表，以合并后的入院-出院为窗口。

进阶方法：自检脚本：同一 macrovisit 内原始 visit 的间隔若小于 1 天即视为未合并残留，回炉重算。

SOTA 方法：以"住院过程"为生存分析单元做时变暴露（含转 ICU 时点），参考官方 remdesivir 研究的窗口定义。
参考：Sidky 2023（macrovisit aggregation algorithm）；N3C Enclave 官方术语表。

§6.6 数据增强

安全 ✅：概念 dropout（随机掩蔽低频概念 ID，提升鲁棒性）；时间抖动（在相对时间轴上 ±1 窗口平移，模拟记录延迟）；站点级重加权（缓解站点不平衡）；对 NOTE_NLP 特征做同义词概念组聚合。

危险 ❌：绝对日期扰动（会破坏平移后的相对时序一致性）；伪造实验室数值（插值会掩盖信息性缺失机制）；跨患者交换事件序列（破坏 person 内部相关结构）；任何试图"补全"死亡或感染状态的做法（结局必须以官方增强数据为准）。

为什么"补全感染/死亡"在 N3C 尤其危险：这些状态在飞地内本身就是不完整的（家庭自测、院外死亡漏检，见 §6.5 坑点 1 与 §4.5）。用插补或合成制造"完整结局"会给模型一个假的确定性信号——审稿人若发现你的结局是从"不完整观测"填出来的，结论会立即失去可信度。正确的做法是把不完整性显式暴露给模型：结局的"检测/记录缺失"本身要作为协变量或分层维度，而非被擦除（§4.5 表）。

§6.7 模型推荐

任务	推荐模型	理由
Long COVID 表型识别	XGBoost / 逻辑回归 + 规则特征	官方 Pfaff 2022 路线，可解释、审稿友好
死亡/重症预测	GRU / Temporal Transformer（概念序列）	事件序列稀疏、纵向深
PASC 亚型聚类	共识聚类 + UMAP	Reese 2022（N3C+RECOVER）路线
疫苗/药物有效性	边际结构模型 + 目标试验模拟	时变混杂标准解法
文本症状抽取	MedTagger 规则 + 弱监督微调	飞地内联邦式 NLP 标准栈（Liu 2023）
站点泛化评估	混合效应模型 / 站点留出	处理站点随机效应

选模型时的两个 N3C 特有判断：一是结局定义决定了模型上限——Long COVID 这类由推断标签定义的结局，误差主要来自标签噪声而非模型架构，换更强的模型往往收益递减；二是站点随机效应几乎必加——84 个系统的差异常被低估为残差，混合效应或站点留出报告会显著提升论文可信度。若预算有限，优先把精力投在 §5.4 的分层验证上，而非堆叠模型。

§6.8 硬件需求

资源	建议配置	说明
计算环境	飞地内 Foundry 托管 Spark/Python 集群	自带算力，无需自购
表操作	Spark SQL（亿级行 join）	尽量下推到 SQL 层
原型开发	抽样百万行子集 + 单核 Python	先跑通再放大
深度学习	飞地内 GPU 配额（按需申请）	大多数表型任务 CPU 足够
本地	仅代码与聚合结果（受出口审查）	数据与患者级结果不可出飞地

性能预算提醒：225 亿行全量 join 即使有 Spark 也会很昂贵。务实流程是"先窄后宽"——先用 2-5 个表（person + visit + 目标概念集）在子集上验证逻辑，确定队列后再放大到全量；概念集过滤（condition/drug/measurement 的 concept_id 白名单）应尽可能提前、尽可能激进，因为大多数表是围绕少数概念集旋转的。若你的查询让 Foundry 任务排队超过预期，多半不是平台问题而是过滤不够窄。

§6.9 评估指标代码

from sklearn.metrics import roc_auc_score, average_precision_score
from sklearn.calibration import calibration_curve
import numpy as np

def cohort_report(y_true, y_score, site_ids):
    """站点分层 AUROC/AUPRC + 校准，N3C 评估的最小闭环。"""
    out = {"AUROC_overall": roc_auc_score(y_true, y_score),
           "AUPRC_overall": average_precision_score(y_true, y_score)}
    for s in np.unique(site_ids):                       # 站点间离散度是关键
        m = site_ids == s
        out[f"AUROC_site_{s}"] = roc_auc_score(y_true[m], y_score[m])
    probs, obs = calibration_curve(y_true, y_score, n_bins=10)
    out["calibration_ece"] = float(np.abs(probs - obs).mean())
    return out

指标解读的 N3C 视角：不要只报一个总体 AUROC。因为在多中心、多分期结构下，总 AUROC 会掩盖"哪些站点/哪个分期拉了平均"。合理的报告是"总体 AUROC + 站点 AUROC 区间（min-max 或 IQR）+ 分期内 AUROC"，外加 ECE 校准误差。若某站点的 AUROC 显著低于总体，先查是不是该站概念集映射缺失（§6.5 坑点 5/8），再谈模型问题——数据洞通常先于模型问题出现。

§6.10 MLOps 笔记

双重版本锁定：代码库版本 + 数据 Release 编号必须同时出现在每次运行的日志里；表型版本是第三把锁。
可复现性：飞地内代码库（Foundry Repository）本身版本化，分析产物与代码绑定；论文投稿前按 N3C Attribution & Publication Policy 提交 attribution 声明与 Release/访问日期。
出口纪律：聚合结果出飞地前经出口审查；患者级结果永不出境；把"导出物 = 表格 + 图"写进项目 README。
再训练触发：N3C 数据每周更新、按 Release 发布——生产化模型需声明" trained on Release N"，换 Release 时重跑数据对账表（§6.5 坑点 6）。

一个推荐的飞地运行簿（runbook）骨架：

# scripts/runbook.py — 每次分析运行必跑
RUN_META = {
    "release": "N3C_RELEASE_193",      # 数据版本锁
    "phenotype": "n3c_phenotype_v3.3", # 表型版本锁
    "commit": "<foundry_repo_commit>", # 代码版本锁
    "data_level": "level_2",           # 层级锁
    "access_date": "2026-09-05",
}

def assert_locks():
    # 校验实际使用数据集与声明一致；不一致立即中止
    for k, v in RUN_META.items():
        assert f"{k}={v}" in open("runtime_manifest.log").read(), k
    print("LOCKED:", RUN_META)

生产级做法是把 RUN_META 写进产物元数据、随每个输出物（CSV/模型 artifact）一起出口，确保任何聚合结果都能回答审稿人三问：“哪个 Release、哪个表型、哪个代码版本？”

§7 质量评估与局限性

§7.1 已知偏倚

偏倚类型	描述	严重程度	缓解
入选偏倚	仅纳入与贡献站点有交互的患者；阴性对照按 1:2 摄入设计	高	用标准化发病率比校正；报告站点覆盖
检测确认偏倚	检测强度随就诊行为/时期变化；家庭自测漏检	高	检测指示变量 + 负对照校准（Sidky 2023）
错误分类偏倚	接种状态、U09.9、再感染定义误分类	中-高	敏感性分析 + 多定义并行（§6.5 坑点 4/7）
站点异质性	84 个系统的 ETL 与文档习惯差异	中	站点随机效应 + 单位归一（Bradwell 2022）
代表性偏倚	偏城市学术医疗中心；种族多样但不等于普查分布	中	分层报告 + 农村子群专项研究（Anzalone 2024）

§7.2 标注质量

COVID 表型由多机构专家共识维护并公开逻辑，透明度是同类数据集最高档；但标签本质是编码推断：U09.9 早期采用稀疏（National Academies 记录）、Long COVID ML 表型的锚定门诊仅三家。NLP 标签跨机构 F1 0.694-0.876（arXiv 2110.10780）。使用建议：把所有标签当"有噪声的银标准"，主分析 + 替代定义敏感性分析双轨并行。

不同标签的"噪声源"差异很大，务必对症处理：

标签	主要噪声来源	量化手段	缓解建议
COVID 阳性（检验路径）	假阳性罕见、检测时机偏倚	与诊断码路径做一致性分析	双路径联合定义
Long COVID（U09.9）	编码采用滞后、医生编码习惯不一	随时间/站点分布审计	用 ML 表型补充（Pfaff 2022）
Long COVID（ML 表型）	锚定门诊仅三家，外推误差	跨门诊一致性报告	在外部门诊子集再校准
死亡	院外死亡漏检	与 CMS/死亡率增强子集对拍	结局用增强数据做敏感性分析

§7.3 泛化性

场景	失效风险	证据
推广到农村/非学术医院	高	城市学术中心偏倚（Sidky 2023）
推广到非美国医疗体系	高	编码/付款/就医结构差异
Omicron 后期感染率估计	高	家庭自测漏检（Hadley 2024）
住院内药物有效性	中-高	住院用药捕获差异（Sidky 2023）
儿童 Long COVID	中	儿童占约 15%，样本量仍可观（Current Opinion 2025）
院内死亡/重症预测	低-中	EHR 采集完整、CMS/死亡率增强

§7.4 伦理

数据转移依 Johns Hopkins Reliance Protocol（IRB00249128）或站点个别协议；NIH 内部 IRB 认定使用飞地数据不构成人类受试者研究（45 CFR 46.102，Sidky 2023）。飞地受 Certificate of Confidentiality 保护，禁止再识别贡献机构与社区、禁止对部落身份做假设（User Code of Conduct，Suver 2023）。患者组织与社区代表参与治理（NCEG），发表须遵守 Attribution & Publication Policy。

伦理审查给研究者的三个落脚点：

审查点	内容	你的责任
数据来源合规	站点 DTA 与 IRB 转移协议完备	引用时注明 DTA/DUA 体系
社区不伤害	禁止识别社区、部落、机构	不发表可反推小群体的"识别性"聚合结果
再识别边界	L3 日期/邮编风险高于 L2	L3 输出前做小格再识别风险评估

飞地的"伦理护栏"同时是方法学护栏：因为研究者无法带出原始数据，任何声称"我可以核实你的患者个体"的说法都不成立——论文必须自带可审计的三锁（Release/表型/代码），把可复现性内建为第一公民。

§7.5 公平性

N3C 的种族构成比多数单中心队列更接近美国多元现实（Black 人群占比高于普查），这使健康差异研究成为其强项：农村 vs 城市住院死亡差异、Long COVID 诊断机会差异均有专文（Anzalone 2024）。但公平性分析必须警惕"检测可及性"混淆：低检测率的社区感染被系统性漏记，可能被误读为低感染。

做公平性审计时建议固定报告三件事：人口学分层性能（各种族/年龄/性别的 AUROC 与校准）、站点覆盖审计（哪些人口被哪些站点更好覆盖）、以及可及性混淆的敏感性分析（把检测密度当作协变量前后对比）。把这三样写进论文，公平性论述就从"声明"升级为"可核查证据"。

§7.6 数据漂移

N3C 的漂移是三层叠加的：病毒漂移（原始株→Delta→Omicron 的致病性与流行结构变化）、行为漂移（检测与就医行为随疫情阶段剧变）、编码漂移（U09.9 与疫苗登记逐步铺开）。任何跨期模型都应按变种分期评估并用时间外推验证；官方文献把分期分析视为默认协议（Qin 2024）。

三类漂移的具体信号与应对：

漂移层	表现信号	检测	缓解
病毒漂移	重症率、住院比例的跨期变化；模型校准随时间漂	按变种分期切分样本重训看指标漂移	分期作为显式协变量；时间外推验证
行为漂移	检测量、门诊量、就医结构剧变	月度就医/检测次数折线	只把需要医疗交互的结局当可靠结局
编码漂移	U09.9、疫苗记录、再感染编码随政策铺开	编码出现率随时间曲线	多定义并行 + 分期报告（Pfaff 2022）

一个实用原则：把每个跨期模型都当作部署到"下一个尚未出现的数据分布"的模型来对待——先训练于 pre-Delta+Delta，再用 Omicron 测试，据此报告真实的外推性能而非单一 AUROC。

§7.7 DAIMS 24 项评估

#	检查项	状态	说明
1	宽格式	⚠️	OMOP 长格式 EAV 结构，需自建宽表
2	唯一标识	✅	person_id 全局唯一；PPRL 支撑跨源链接
3	特殊字符	✅	OMOP 标准词汇表规范化
4	重复行	⚠️	跨站重复患者不可链接去重
5	缺失编码	✅	OMOP 0/NULL 惯例统一
6	标签标识	✅	版本化表型 + 公开逻辑
7	罕见类分组	⚠️	小格 <20 抑制影响罕见亚组分析
8	偏倚评估	✅	官方仪表盘 + 代表性研究公开
9	数据字典	✅	OMOP 官方字典 + N3C 词典
10	信息性缺失解释	✅	检测/就医行为缺失机制有文献支撑
11	设备记录	⚠️	device_exposure 覆盖站点不均
12	共线性	❌	无官方共线性处理，需自行 VIF/降维
13	编码映射	✅	ACT/PCORnet/TriNetX→OMOP 映射开源
14	时间戳处理	⚠️	日期平移：相对时间可用、绝对日期不可用
15	划分建议	✅	官方给挑战赛截尾范式，社区惯例成熟
16	泄漏讨论	✅	跨站重复与窗口泄漏在文献中被明确讨论
17	标签分布	✅	公共仪表盘持续披露队列构成
18	测量偏倚	✅	单位修复算法与 DQ 工具链齐备
19	外部验证建议	✅	CMS/死亡率/变异谱增强闭环
20	版本记录	✅	Release 编号体系严格
21	预处理脚本	⚠️	站点侧管线完备，研究者侧需自建
22	合规要求	✅	DUA/DAC/培训/CoC 全链路
23	多模态对齐	⚠️	文本 NLP 与结构化对齐受站点覆盖与平移限制
24	去标识化	✅	HIPAA 专家判定 + 日期平移 + 邮编处理

DAIMS 评分：19.5 / 24（16 项 ✅ ×1 + 7 项 ⚠️ ×0.5 + 1 项 ❌ ×0）

评分解读：19.5 的得分在 EHR 类数据集中属于第一梯队——治理、溯源、版本化与合规维度几乎满分，这源于其联邦资产属性与专职工程团队。扣分集中在三类固有限制：长格式结构（建模前必须自建特征宽表）、隐私工程带来的时间粒度损失（日期平移）、以及飞地模式决定的"最后一段路要自己走"（无官方划分与预处理脚本给研究者）。共线性处理空白是唯一的完全失分项，但这在 OMOP 生态里是常态而非 N3C 独有的缺陷。

对你意味着什么：第一，别指望"下载数据跑 notebook"——把 §6.2 的申请流程排进项目甘特图，DUA 法务周期常常比建模周期还长；第二，开工前先写三把锁（Release 编号、表型版本、代码库 commit）进你的分析模板；第三，把 §6.5 的坑点 1/2/3 当作设计约束而非事后补丁——时间截尾方案、相对时间轴、跨站重复审计应在队列定义阶段就定型；第四，共线性自检（VIF + 概念集去冗余）纳入标准 pipeline，因为 OMOP 概念集天然高度相关。

§7.8 外部验证矩阵

外部数据集/场景	来源机构	评估任务	性能指标	相对内部变化	关键发现
CMS claims 链接子集	CMS + N3C PPRL	治疗有效性交叉验证	一致性（PPRL 链接 1,000 万+ 人）	提升处方与死亡终点完整性	EHR+claims 弥补取药与院外死亡盲区（ASPE 2025）
三家 Long COVID 专科门诊	UNC/UC 家等	ML 表型外部锚定	模型识别者与门诊患者特征匹配	与门诊临床画像一致	第一个循证 Long COVID 定义（Pfaff 2022, Lancet Digit Health）
CDC 全国接种率	CDC	接种状态校准	总体接种率低于 CDC	揭示登记缺失	误分类需显式建模（MDPI Vaccines 2024）
美国普查/ACS	US Census	人群代表性	种族构成对比	更多样但偏城市	农村覆盖不足（Sidky 2023）
多机构 NLP 评测集	Mayo/UMN/UKY	症状抽取跨站泛化	F1 0.876/0.706/0.694	站点间衰减明显	联邦式 NLP 可行但需站点适配（arXiv 2110.10780）

§8 基准性能与生态

§8.1 排行榜与研究基准

N3C 没有持续性公开排行榜；最接近"基准"的官方活动是 L3C Long COVID Challenge（2022-08 至 2023-03，奖金池 50 万美元，评估含 AUPRC、Brier 分数、校准与可复现性维度，NIH webinar）。下表列出社区研究中最常被对标的已发表结果——注意各研究队列定义与 Release 不同，数值不可直接比较：

研究	任务	关键数字	年份	完整引用
Long COVID ML 识别	表型分类	97,995 成人训练锚定；10 万+ 可能病例	2022	Pfaff ER et al., Lancet Digital Health, 2022. doi:10.1016/S2589-7500(22)00098-0
PASC 风险因素	病例-对照	8,325 vs 41,625；女性/中年/住院者风险升高	2022	Hill E et al., medRxiv 2022.08.15.22278603. doi:10.1101/2022.08.15.22278603
Long COVID 亚型	无监督聚类	N3C+RECOVER 泛化亚型	2022	Reese JT et al., medRxiv 2022.05.24.22275398. doi:10.1101/2022.05.24.22275398
症状 NLP 抽取	信息抽取	跨机构 F1 0.876/0.706/0.694	2021/2023	Liu S et al., JAMIA, 2023. doi:10.1093/jamia/ocad134
孕妇疫苗有效性	生存分析	重症 aHR 0.65（Delta）/0.79（Omicron）	2024	Qin QC et al., BMJ Public Health, 2024. doi:10.1136/bmjph-2023-000770
再感染与 Long COVID	队列分析	Omicron 期再感染最多；Long COVID 多见于初次感染后	2024	Hadley J et al., Communications Medicine, 2024. doi:10.1038/s43856-024-00539-2

关于上表数值的读法：表中 aHR、F1、AUC 等指标来自不同的研究设计、不同 Release、不同表型版本与不同结局定义——它们回答的是不同的问题，把它们当作"方法学参照系"而非"可比较的排行榜分"。真正要比较两个 N3C 研究，必须三锁对齐（Release + 表型版本 + 结局定义）。例如孕妇疫苗研究中 Delta 期重症 aHR 0.65 与 Omicron 期 0.79 的差异，反映的是毒株与免疫背景变化，不是同一模型在两个时期跑出的性能差。

§8.2 SOTA 总结与选型建议

当前社区的"事实标准"做法是：XGBoost/逻辑回归 + 版本化表型特征做表型任务（可解释、可过审），深度序列模型用于死亡与重症预测，边际结构模型处理疫苗/药物时变混杂。除非你的贡献点是架构本身，否则不建议把算力花在刷点——N3C 研究的稀缺资源是表型严谨性与偏倚控制，不是模型容量。

具体选型时可把"文献实践成熟度"当作第一权重：

你的研究目的	推荐技术栈	复现难度	理由
Long COVID 识别	XGBoost / LR + 规则特征	低（Pfaff 2022 路线）	审稿友好、可解释、能直接做敏感性定义
PASC 亚型	共识聚类 + 外部锚定	中	N3C+RECOVER 亚型体系有现成标签语义
死亡/重症预测	GRU / Temporal Transformer	中-高	事件序列稀疏，序列模型收益有限但可加分
疫苗/药物有效性	边际结构模型 / 目标试验模拟	高（需谨慎的时变混杂控制）	结论的政策分量高，方法争议也大
跨期稳健性评估	分期留出 + 校准曲线	低	所有模型都应加，不可省

§8.3 评测协议

声明 Release + 表型版本 + 层级（Level 2/3）；2. 按患者分组划分，报告站点分层 AUROC/AUPRC；3. 时间外推（变种分期）+ 站点留出双轴验证；4. 阴性对照与活性对照校准混杂控制；5. 按 Attribution Policy 归档代码与 attribution 声明。L3C 挑战赛协议（截尾数据、四阶段评估维度）可作为 Long COVID 预测任务的模板（NIH webinar）。

把上述五步展开为可勾选的投稿前清单：

[ ] 方法节包含三锁声明（Release、表型版本、Level）
[ ] 队列构建 SQL/概念集已公开（GitHub 或飞地内共享）
[ ] 结果表含站点分层指标（报告离散度而非仅汇总 AUC）
[ ] 至少一项时间外推验证（训练于早期分期、测试于后续分期）
[ ] 结论核心指标有阴性对照校准或敏感性分析支撑
[ ] attribution 段落与资助号（U24TR002306）已写入致谢
[ ] 导出聚合物已通过出口审查并记录 RUN_META（§6.10）

数据集	关系	差异点
MIMIC-IV / MIMIC-III	互补（深度 vs 广度）	单中心 ICU 全量细节可下载；N3C 多中心不可下载
OneFlorida+	验证伙伴	州域网络，CDM 兼容
PCORnet / ACT / TriNetX	上游源模型	N3C 的输入网络之一
OpenSAFELY	平行体系	英国全国 EHR 飞地，代码全公开
All of Us	互补模态	基因组+问卷深表型，COVID 专项弱
4CE	历史对照	疫情初期美欧多中心 i2b2/OMOP 联盟

横向选型建议：选择数据集的第一步不是"哪个最好"，而是"你的问题需要广度还是深度"。要全国规模、跨系统外推、疫情期全景与 Long COVID 前沿表型——选 N3C；要逐分钟的 ICU 生理数据、护理记录、可本地反复调试——选 MIMIC-IV；要基因组与长期随访的深表型——选 All of Us。N3C 与其相关数据集的真实关系多为"互补拼图"而非"竞品替代"：一条常见研究路径是"用 MIMIC 调模型架构 → 用 N3C 做全国外推验证 → 用 OpenSAFELY 做跨国对照"。

§8.5 关键论文 Top 8

Haendel MA, Chute CG, Bennett TD, et al. The National COVID Cohort Collaborative (N3C): Rationale, design, infrastructure, and deployment. J Am Med Inform Assoc. 2021;28(3):427-443. doi:10.1093/jamia/ocaa196 — 项目宪法：治理、四源 CDM 统一到 OMOP 5.3.1、飞地架构的总设计书。
Pfaff ER, et al. Identifying who has long COVID in the USA: a machine learning approach using N3C data. Lancet Digit Health. 2022 — 首个循证 Long COVID ML 定义，RECOVER 计划的方法学基石。
Sidky GS, et al. Data quality considerations for evaluating COVID-19 treatments using real world data: learnings from the N3C. BMC Med Res Methodol. 2023;23:46. doi:10.1186/s12874-023-01851-3 — remdesivir 案例贯穿的数据质量与 macrovisit 实务。
Suver C, et al. The N3C governance ecosystem. J Clin Transl Sci. 2023;7:e252. doi:10.1017/cts.2023.681 — 治理/伦理/行为准则的社会技术全记录。
Liu S, Wen A, Wang L, et al. An open NLP framework for EHR-based clinical research: N3C case. JAMIA. 2023. doi:10.1093/jamia/ocad134 — 联邦式临床 NLP 工具链与合成语料方法。
Hadley J, et al. SARS-CoV-2 reinfections and Long COVID. Commun Med. 2024. doi:10.1038/s43856-024-00539-2 — 再感染分期特征与"家庭检测"局限性的官方坦白。
Qin QC, et al. COVID-19 vaccine effectiveness among pregnant people, N3C. BMJ Public Health. 2024. doi:10.1136/bmjph-2023-000770 — 分期疫苗有效性范式论文。
Bennett TD, et al. The N3C: clinical characterization and early severity prediction. medRxiv 2021. doi:10.1101/2021.01.23.21250257 — 早期全国临床画像与 WHO 严重度分层应用。

§8.6 社区活跃度

截至 2025：4,300 名注册研究者、296 篇论文、84 个贡献系统、450+ 参与组织（含治理层面）；飞地内 400+ 个获批项目持续运行；Domain Teams（糖尿病、儿科、Long COVID 等）按兴趣自治，公开 office hours 与教程（Current Opinion 2025、NCATS、National Academies）。N3C 已进入"后疫情"扩展期：更名 N3C Clinical 并孵化 Cancer/Renal/Education 等新飞地，平台经验正被平移给下一个健康威胁（Utah CTSI）。

对社区生态的量化感知可以从三个角度建立：一是规模曲线——患者数从 2021 的 680 万增至 2024 的 2,285 万，研究者从 3,000 增至 4,300，显示平台仍在增长而非冻结；二是结构与机制——Domain Teams 的自治协作与每周 office hours 是飞地内"社区"的真实载体，新用户加入一个 Domain Team 能显著降低冷启动成本；三是外部影响力——Paxlovid 政策、Long COVID 定义、孕妇接种建议均直接或间接受 N3C 证据影响（National Academies 记录）。投稿者若在意审稿人眼中的"数据影响力"，这些都可作为 background 引用。需要留意的是：社区活跃度指标（论文数、研究者数）随口径与统计时点浮动，引用时务必注明出处年份。

§8.7 生态快照

资源	类型	链接	推荐理由
N3C 官方主页	门户	https://ncats.nih.gov/n3c	DUA/DUR/培训一站式入口
N3C Dashboard	公共仪表盘	https://covid.cd2h.org/dashboard	申请前摸清队列构成
Enclave 入口	平台	https://unite.nih.gov	获批后的唯一工作环境
N3C Phenotype（GitHub）	代码	https://github.com/National-COVID-Cohort-Collaborative	版本化表型逻辑的权威实现
OHNLP 工具链（GitHub）	代码	https://github.com/OHNLP/MedTagger	N3C NLP 标准栈组件
LHC N3C Profile	数据档案	https://lhncbc.nlm.nih.gov/CCOI/datasets/N3C/index.html	第三方可引用的规模快照
Data Partners 清单	治理	https://covid.cd2h.org/dtas	站点覆盖核对
Zenodo 治理文档库	文档	https://zenodo.org/communities/n3c	IRB 协议、归因与发表原则原文

§9 相关资源与引用

§9.1 官方资源

注册与申请：N3C 官网 → Enclave 门户；申请前先看 Data Access 指南与 DUA 文本。
教程与支持：N3C Tutorials（飞地内 Tutorial 项目）、N3C FAQ、社区 office hours；技术支持邮箱 NCATS_N3C@nih.gov。
数据质量：飞地内 Data Quality Dashboard、COMPASS 站点画像、LHC Profile 规模快照。
发表要求：Attribution & Publication Policy（飞地内最新版）；每篇论文须包含标准 attribution 段落、Release 编号与访问日期。

关键治理文档索引（申请与投稿阶段反复需要，建议收藏）：

文档	用途	入口
Data Transfer Agreement（DTA）	贡献机构与 NCATS 的数据移交约定	ncats.nih.gov/n3c 治理页
Data Use Agreement（DUA）	使用机构与 NCATS 的总体授权	DUA 文本
Data User Code of Conduct	用户基本行为准则（含禁止再识别）	ncats.nih.gov/n3c/resources
User/Community Guiding Principles	社区合作伦理框架	Zenodo N3C 社区
Attribution & Publication Policy	发表署名与数据引用规范	飞地内 / Zenodo
IRB Reliance Protocol	IRB00249128 转移依据	Zenodo
N3C Phenotype（GitHub）	版本化表型逻辑	github.com/National-COVID-Cohort-Collaborative
Data Partners 清单（DTAs/DUAs）	站点与协议方核对	covid.cd2h.org/dtas、covid.cd2h.org/duas

§9.2 BibTeX 引用

@article{Haendel2021N3C,
  author  = {Haendel, Melissa A. and Chute, Christopher G. and Bennett, Tellen D. and others},
  title   = {The National COVID Cohort Collaborative (N3C): Rationale, design, infrastructure, and deployment},
  journal = {Journal of the American Medical Informatics Association},
  year    = {2021},
  volume  = {28},
  number  = {3},
  pages   = {427--443},
  doi     = {10.1093/jamia/ocaa196}
}

@article{Pfaff2022LongCOVID,
  author  = {Pfaff, Emily R. and Madlock-Brown, Charisse and Baratta, Joseph M. and others},
  title   = {Identifying who has long COVID in the USA: a machine learning approach using N3C data},
  journal = {The Lancet Digital Health},
  year    = {2022},
  doi     = {10.1016/S2589-7500(22)00098-0}
}

@article{Sidky2023DataQuality,
  author  = {Sidky, Georgina S. and Bhatia, Aakash and Weng, Chunhua and others},
  title   = {Data quality considerations for evaluating COVID-19 treatments using real world data: learnings from the National COVID Cohort Collaborative (N3C)},
  journal = {BMC Medical Research Methodology},
  year    = {2023},
  volume  = {23},
  pages   = {46},
  doi     = {10.1186/s12874-023-01851-3}
}

@article{Suver2023Governance,
  author  = {Suver, Christine and Wilbanks, John and Lee, Adam M. and others},
  title   = {The N3C governance ecosystem: a model socio-technical partnership for the future of collaborative analytics at scale},
  journal = {Journal of Clinical and Translational Science},
  year    = {2023},
  volume  = {7},
  number  = {1},
  pages   = {e252},
  doi     = {10.1017/cts.2023.681}
}

@article{Liu2023NLP,
  author  = {Liu, Sijia and Wen, Andrew and Wang, Liwei and others},
  title   = {An open natural language processing framework for EHR-based clinical research: a case demonstration using the N3C},
  journal = {Journal of the American Medical Informatics Association},
  year    = {2023},
  doi     = {10.1093/jamia/ocad134}
}

@article{Hadley2024Reinfection,
  author  = {Hadley, Jordan and Mehta, Hemal and others},
  title   = {Insights from an N3C RECOVER EHR-based cohort study characterizing SARS-CoV-2 reinfections and Long COVID},
  journal = {Communications Medicine},
  year    = {2024},
  doi     = {10.1038/s43856-024-00539-2}
}

§9.3 引用指南

数据使用引用两件套：论文（Haendel 2021 为设计论文）+ 数据声明（attribution 段落注明 N3C Data Enclave、Release 编号、访问日期、资助号 U24TR002306 与 DTA 签署方）。N3C 要求在论文致谢中包含官方 attribution 文本（飞地内可复制），并在发表后按政策向社区登记出版物。

一个最小可用的数据声明模板（中英混排示意，英文投稿时替换为官方文本）：

The analyses described in this publication were conducted with data or tools accessed through the NCATS N3C Data Enclave (covid.cd2h.org/enclave) and supported by NCATS U24 TR002306. We used N3C Release 193（访问日期 2026-09-05，Level 2，表型版本见方法节）。本数据经去标识化处理，使用不构成人类受试者研究（45 CFR 46.102）；数据转移依 Johns Hopkins Reliance Protocol IRB00249128。

关于 DUO 标签的补充提醒：本页面 INFOBOX 中的 DUO 标签（HMB、DS、IRB、GS、PUB）为按 DUO 框架对 N3C 使用条款的归纳性转写，并非官方 DUO 机器可读声明——N3C 未在其 DUA 中发布结构化 DUO ontology。实际可执行约束以 DUA + User Code of Conduct 为准，不要仅凭标签做合规判断。历史上曾有研究者因把飞地数据用于 DUR 之外的目的而违反条款，务必以项目范围为准绳。

§10 AI 使用声明卡

§10.1 AI 模型列表

模型	用途	版本/说明
大语言模型（CodeBuddy）	本页面的资料整合、初稿撰写与格式化	fast-model，2026-09 生成
无其他 AI 模型参与数据集本身的生成	—	N3C 数据由医疗系统 EHR 原始采集

§10.2 AI 参与范围

AI 完成了：检索事实整理（FACTS.md）、章节结构组织、代码示例起草、表格与 JSON-LD 序列化。人类审核者完成了：医学内容交叉审核（§2、§7）、数据工程审核（§4、§6）、数字溯源核验（每个关键数字对应公开来源链接）、坑点真实性与合规性把关。AI 未访问任何 N3C 飞地内未公开数据。

§10.3 输入来源列表

Haendel MA, Chute CG, Bennett TD, et al. J Am Med Inform Assoc. 2021;28(3):427-443. doi:10.1093/jamia/ocaa196
Pfaff ER, et al. Lancet Digital Health. 2022. doi:10.1016/S2589-7500(22)00098-0（附 NIH 新闻稿）
Sidky GS, et al. BMC Med Res Methodol. 2023;23:46. doi:10.1186/s12874-023-01851-3
Suver C, et al. J Clin Transl Sci. 2023;7:e252. doi:10.1017/cts.2023.681（PMC10789985）
Liu S, et al. JAMIA. 2023. doi:10.1093/jamia/ocad134（附 arXiv 2110.10780）
Hadley J, et al. Communications Medicine. 2024. doi:10.1038/s43856-024-00539-2
Qin QC, et al. BMJ Public Health. 2024;2(1):e000770. doi:10.1136/bmjph-2023-000770
Hill E, et al. medRxiv 2022.08.15.22278603. doi:10.1101/2022.08.15.22278603
Reese JT, et al. medRxiv 2022.05.24.22275398. doi:10.1101/2022.05.24.22275398
Bennett TD, et al. medRxiv 2021（clinical characterization and early severity prediction）
NLM Lister Hill N3C COVID Profile（lhncbc.nlm.nih.gov，最后更新 2025-12-12）
NCATS N3C 官方页面（ncats.nih.gov）
NCATS N3C Data Use Agreement（ncats.nih.gov 文件）
ASPE FY2025 OS-PCORTF Annual Report Appendices（aspe.hhs.gov）
NIH L3C Long COVID Challenge Webinar（2022-09-21，nih.gov PDF）
National Academies Workshop Proceedings（nationalacademies.org）
MDPI Vaccines 2024;12(3):289. doi:10.3390/vaccines12030289
Current Opinion pediatric data science review（PMC12629321，2025）
OHDSI N3C NLP 报告（2022-01-25，ohdsi.org）
Utah CTSI / Nemours / NDSU N3C 访问指南（机构落地页）

§10.4 人工校验表

内容模块	审核者	审核方式	审核状态
§2 医学背景（ICD-11/SNOMED 映射、Long COVID 定义）	千方病案医学编辑部	与 WHO ICD-11 及 SNOMED CT 公开术语对照	✅ 已通过
§3 数据集规格（规模数字、Release 版本）	千方病案医学编辑部	与 NLM Profile、NCATS 页面、2025-2026 论文三方交叉比对	✅ 已验证
§4 数据结构（OMOP 表字典、DAIMS 字段）	千方病案医学编辑部	与 OHDSI OMOP CDM 5.3 官方文档交叉比对	✅ 已验证
§5 划分策略	千方病案医学编辑部	与 L3C 挑战赛协议及 N3C 文献惯例比对	✅ 已验证
§6 AI 就绪指南（访问流程、8 坑点）	千方病案医学编辑部	与 NCATS DUA、Hadley 2024、Sidky 2023、MDPI 2024 原文比对	✅ 已验证
§7-§8 质量/基准（DAIMS 24 项、外部验证）	千方病案医学编辑部	全部数字回查原始来源链接	✅ 已通过

§10.5 AI 生成章节标注

本页面全文由 AI 辅助生成初稿，§1.2、§2.5、§7.7 评分解读与"对你意味着什么"为 AI 综合判断性内容，已经人工复核事实依据；§10 为标准声明模块。

§10.6 最后人工审核日期

2026-09-05（与 §0 审核日期一致）

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

返回 AI-Ready 数据集