简介：R语言工具包ukbnmr专为UK Biobank中Nightingale NMR代谢组学数据设计，面向生物信息学与代谢组学研究者，用于解决原始NMR生物标志物字段提取、数据清洗与比值计算等常见问题。压缩包共19个文件，以7个R函数脚本、4个Rd帮助文档、2个Markdown说明文件为主体，另有命名空间、描述文件及示例数据等，完整包体仅18KB，结构紧凑且便于审阅。包内主要提供两个核心函数：extract_biomarkers()可提取NMR生物标志物并给出简短列名，同时将基线和首次重复评估的多重测量拆分至不同行；compute_nightingale_ratios()则用于计算168种生物标志物之间的比值。此外还附带nmr_info数据框，集中记录生物标志物的元信息，便于查询与注释。目前已有908人学习该资源，适合具备R语言基础并希望高效处理UK Biobank代谢组学数据的科研人员。
1. 项目概述与痛点拆解
1.1 ukbnmr是什么，为什么它值得被需要
先说结论：ukbnmr是一个专门用来处理UK Biobank（英国生物银行）中Nightingale Health NMR代谢组学数据的R语言工具包。很多人第一次听到这个名字，会以为它只是个“数据清洗小脚本”，但实际用下来你会发现，它更像是一把专门为UK Biobank NMR数据定制的瑞士军刀，解决了从原始数据文件到可分析数据集之间的所有脏活累活。
UK Biobank是目前全球规模最大的生物样本数据库之一，招募了约50万名40到69岁的中老年志愿者，采集了血液、尿液、唾液等生物样本，并长期跟踪健康结局。Nightingale Health的NMR（核磁共振波谱，Nuclear Magnetic Resonance）平台则是这套数据体系里非常重要的一环，它用高通量核磁共振技术，一次性测量血液样本中超过250种代谢物和脂蛋白相关指标，包括脂蛋白亚类颗粒浓度、脂肪酸组成、氨基酸、酮体、糖酵解相关代谢物等。
但问题来了——数据量大不等于数据好用。UK Biobank的NMR数据文件下载下来之后，命名规则复杂、字段有重复、不同批次间单位不一致、还有实例（instance）和阵列（array）这种多重结构，直接用Excel打开会疯掉，直接丢进模型也会出错。ukbnmr这个工具就是在这个背景下诞生的：它把Nightingale NMR数据从“厂商原始输出格式”转换成“统计软件友好型格式”，并且帮你完成变量名标准化、单位统一、质量控制等关键步骤。
1.2 这个工具适合谁来用
如果你是以下几类人之一，ukbnmr对你来说会很有价值：
- 做代谢组学、流行病学、遗传流行病学研究的科研人员，尤其是正在用UK Biobank数据发论文的人；
- 本身不是生物信息学背景，但需要在R环境里把Nightingale数据纳入自己的统计分析流程的临床研究者；
- 准备使用UK Biobank的NMR数据但还没搞懂它的文件结构和字段命名规则的新手；
- 需要复现别人论文中代谢物关联分析，但被原始数据的“脏乱差”折磨到怀疑人生的同学。
我自己的体验是：如果没有这类专门工具，光是把Nightingale NMR数据从UK Biobank下载、解析、清洗到能用于回归分析，至少得花掉两三个完整工作日。而用ukbnmr，这个过程可以压缩到一小时内，前提是你了解它的核心逻辑和边界。
2. 核心设计思路与方案选型解读
2.1 UK Biobank NMR数据的“性格”与坑
要理解ukbnmr为什么要这样设计，得先看看Nightingale NMR数据在UK Biobank里是怎么存储的。
简单说，UK Biobank的数据建模方式非常“数据库化”。每个指标（biomarker）都有唯一的字段ID（如“23400”代表载脂蛋白B，“23401”代表低密度脂蛋白颗粒总数等）。你要用这些数据做研究，通常需要经过以下步骤：登录UK Biobank的Access Management System（AMS）→ 申请数据集 → 下载数据包 → 把里面的表格按字段ID提取出来 → 对齐样本ID → 和其他表合并。
听起来不复杂，但实际操作中有几个容易踩坑的地方：
- NMR数据分了很多个批次（batch），而且有些参与者在不同时间点进行了重复测量（也就是instance 0和instance 1，对应首次访问和第一次随访），数据结构是“宽表+多行”混合形态；
- 变量命名有的是数字ID，有的是可读名称；但可读名称在不同文档里并不完全一致；
- 部分指标的单位不是标准的，例如某些脂肪酸是以总脂肪酸的百分比表示的，而某些脂蛋白浓度是摩尔浓度，不搞清楚直接比较会得出错误结论；
- 质控异常值、缺失值处理方式在不同研究组之间也各不相同，有些值在数据包里标记为“-1”或“负数”，这些不是真实值，而是异常/缺失标记。
2.2 为什么选择包的方式而不是“清理一次直接给个现成表”
你可能会想：既然数据格式那么复杂，为什么不直接提供一个已经清洗好的完整数据表让大家下载？
这里有个关键原因——UK Biobank的数据使用协议禁止未经授权的第三方直接分发已处理的核心数据表。数据必须由每个研究者自己从UK Biobank申请并下载。所以ukbnmr的作者选择了一个更合规、也更为实用的方案：不提供数据，只提供处理数据的工具。你用自己的账号从UK Biobank下载原始表格之后，运行这个R包，它在本地完成所有清洗和转化。数据始终只在你的电脑上流动，符合数据安全要求。
另一方面，从技术角度讲，不同研究者对数据的用途不同。遗传关联分析可能只需要“宽表”，而纵向重复测量建模则需要“长表”；有的人要原始浓度，有的人要对数转换值。与其强行统一所有人到一个固定格式，不如把“拆解、重命名、对齐”这个通用流程做成标准化函数，剩下的由研究者根据具体需求选择输出格式。
ukbnmr的主流程设计思路也很清晰：读取数据 → 识别字段 → 转换成一致性变量名 → 添加元数据属性 → 输出标准数据框。它不替你做统计建模，但保证你拿到手里的数据是干净、可解读、可合并的。
3. Nightingale NMR数据解析与实操要点
3.1 Nightingale平台能测出什么
Nightingale NMR检测平台本质上是一个基于核磁共振波谱的高通量代谢组学平台，能够在一个实验流程中同时定量测量多种代谢物。它的核心优势是通量高、重复性好、成本相对较低，适合大规模人群研究。
在实际应用中，Nightingale数据分成了几个大类：
- 脂蛋白亚类：包括14种不同大小和密度的脂蛋白亚类（从超大VLDL到小HDL），每种有颗粒浓度、脂质成分（总胆固醇、甘油三酯、磷脂、游离胆固醇等）和载脂蛋白信息；
- 脂肪酸与脂肪饱和度：如Omega-3、Omega-6、多不饱和脂肪酸、饱和脂肪酸等，通常以相对百分比表示；
- 小分子代谢物：包括氨基酸（如丙氨酸、谷氨酰胺、酪氨酸）、酮体（如β-羟基丁酸）、糖酵解相关代谢物（如葡萄糖、乳酸、丙酮酸）等；
- 炎症与临床标志物：如糖蛋白乙酰化（GlycA）等反映炎症状态的指标。
在使用这些数据时，有一个基本原则要记住：Nightingale NMR检测的是代谢物的整体信号，不是单个蛋白浓度。它和传统的基于抗体的免疫检测（如ELISA）原理不同。所以你在解释结果时，不能说“这个蛋白的绝对浓度如何如何”，而应该说“NMR信号反映的颗粒数量/性质如何如何”。这个细节在写论文时特别重要，审稿人很在意。
3.2 ukbnmr的字段映射机制
ukbnmr内部维护了一张“元数据映射表”，这是它最核心的资产之一。这张表把UK Biobank原生的字段ID、Nightingale原始的指标名、以及标准化的可读变量名三者之间做了对应。
举个例子，UK Biobank字段“23400”对应Nightingale的“ApoB”，在ukbnmr处理后你会得到一个名为“ApoB”的列；再比如“23454”对应的是“total fatty acids”，转换后变量名会是“TotalFA”。这种重命名的意义不仅在于可读性，更重要的是：当你把Nightingale数据和UK Biobank里的其他数据（比如遗传数据、问卷数据、临床结局数据）合并时，一个清晰、一致的命名体系可以避免大量低级错误。
这里有一个实操建议：在用ukbnmr处理之前，先下载UK Biobank的“Data Dictionary Showcase”里NMR相关的字段说明文档，对照看一下自己要挑哪些字段。ukbnmr不是无脑把所有字段都做成变量，它会自动检查每个字段是否被识别。如果在你的下载数据里出现了未知字段，包会给出警告而不是直接中断，这样你可以手动处理个别特殊情况。
3.3 长表、宽表与实例结构
很多人第一次下载UK Biobank的NMR数据后，都会疑惑为什么同一批人会有多行数据。这主要是因为instance的概念——instance 0是基线调查，instance 1是第一次重复访问（大约在首次访问后3到5年），少部分人还有instance 2和instance 3。每个instance可能都做了NMR检测，也可能没做。UK Biobank把这些信息存在同一个字段的不同instance里，但导出CSV时常常是“带重复ID的长表”或“多个后缀列的宽表”。
ukbnmr的处理方式是：默认会尝试解析这些instance信息，并为每个检测时间点生成相应的变量。如果你需要纵向分析（也就是利用重复测量的数据做变化轨迹分析），那么这种处理就非常方便；如果你只做基线横断面研究，也可以在后续代码里只保留instance 0的数据。
另一个概念是array（阵列），指实验室检测的物理批次分配。同一个人的同一份血液样本可能会被分配到不同的检测批次，形成了array 0、array 1等。绝大多数情况下分析只用到array 0的数据，但仍然需要知道它的存在。ukbnmr中有一个参数可以指定使用哪个array，少数情况下有人用array 1做敏感性分析或验证性分析。
4. 实操过程与核心环节实现
4.1 准备数据：从UK Biobank下载你需要的字段
这一步不是ukbnmr能帮你做的，但没有它后面全是空谈。登录UK Biobank AMS后，选择你要的数据集，在字段列表中勾选所有Nightingale NMR相关字段（通常以“NMR”或具体代谢物名称开头），以及你需要的协变量、结局字段。特别注意，尽可能把样本的“eid”（个体唯一标识符）也一起导出。
下载下来的文件通常是两个：一个CSV或制表符分隔的文本文件（包含所有请求字段的数据），一个HTML格式的字段信息文档。CSV通常非常大，几百MB甚至几个GB都有可能，建议用R的data.table包的fread函数来读取。fread在处理大文件时远比基础read.csv高效，内存占用也更可控。
4.2 安装并调用ukbnmr
ukbnmr目前主要通过GitHub分发，因为CRAN上不一定有正式版本。安装方式如下：
# 确保你有安装 devtools 或 remotes 包 install.packages("remotes") remotes::install_github("sormvey/ukbnmr")安装过程可能需要编译一些依赖项。如果你使用的是Windows系统，建议先装好Rtools；macOS则要确保Xcode Command Line Tools已安装。如果你在公司或学校机房用Windows电脑，权限受限时可能会遇到Rtools安装失败，这时候更省事的办法是用Docker配一个R环境，或者直接申请一台有管理员权限的Linux服务器跑分析。
安装完成后加载包：
library(ukbnmr)这里有个体验很好的细节：ukbnmr加载时会自动打印版本号和简短的说明，告诉你当前支持的Nightingale数据版本。不同版本的Nightingale数据字段稍有差异，确认版本匹配能避免后续一堆坑。
4.3 核心处理流程
ukbnmr的核心函数通常只需要一行代码就能完成绝大多数清洗工作。以“从原始UKB导出文件直接生成清洗后的数据框”为例：
# 假设你的UKB数据文件为 ukb_processed.csv nmr_data <- ukbnmr::load_ukb_data("ukb_processed.csv", format = "csv")这个函数的背后做了几件事：读取原始文件；检查并识别Nightingale字段；去除UKB数据表中常见的“-1”等缺失标记；把字段ID重命名为标准变量名；根据instance和array结构生成合适的列。
如果你下载的是RDS格式（通常在UKBiome数据通过某些后端导出时会产生），也可以直接读入：
ukb_df <- readRDS("ukb_data.rds") nmr_data <- ukbnmr::load_ukb_data(ukb_df)在拿到nmr_data之后，下一步通常是合成一个分析用的数据框。ukbnmr提供了函数可以输出不同粒度的数据，比如只保留你想要的一组代谢物：
selected <- ukbnmr::extract_biomarkers(nmr_data, biomarkers = c("ApoB", "LDL_P", "HDL_C", "GlycA"))这个extract函数的好处是，你不用记住每个变量的字段ID，只需要传入标准名称，它内部会自动查找。另外，函数会额外返回一个属性表，记录每个变量的单位、字段来源、是否经过QC标记等，这些信息在你写方法部分的时候非常有用。
4.4 变量名对照表的实际应用
许多人在用ukbnmr之前已经根据其他文献整理了自己的变量名单。这时，你可以用ukbnmr自带的元数据对象来核对：
# 查看所有支持的变量及对应UKB字段ID data("nmr_meta") head(nmr_meta)输出会包含几列：standard_name（标准变量名）、ukb_field_id（UKB字段ID）、nightingale_name（Nightingale原始名）、unit（单位）、category（代谢物分类）。我建议你把这张表保存下来，写论文的时候放在补充材料里，审稿人不问就不给，问了直接甩出来，非常实用。
我自己在复现别人论文时也常用这张表。有些论文用了Nightingale但没写清楚具体用了哪个字段ID，只要在表格里反向查询，就能解开这个谜题。这在meta分析和数据对比中几乎是救命的功能。
4.5 从清洗到建模的快速示范
假设你想做一个简单的关联分析：看ApoB与冠心病风险的关系。清洗完数据后，代码可以这样衔接：
library(survival) # 假设nmr_data已经是ukbnmr处理后的数据框 analysis_df <- nmr_data %>% filter(instance == 0) %>% select(eid, ApoB, age, sex, bmi) %>% left_join(outcome_data, by = "eid") cox_model <- coxph(Surv(time, status) ~ ApoB + age + sex + bmi, data = analysis_df) summary(cox_model)这个流程的核心价值在于：从原始UKB文件到analysis_df，中间少了大量手动改变量名、删缺失、处理负数标记的步骤，代码更短、更不容易出错。尤其是当你的变量从3个扩展到100个时，这种工程化处理优势会被放大到极致。
5. 常见问题与排查技巧实录
5.1 加载数据时提示“未知字段”怎么办
这个问题几乎每个人都遇到过。UK Biobank有时会小幅调整字段列表，或者你在下载时勾选了某些Nightingale新增字段，而ukbnmr的元数据映射表还没及时更新。遇到这种情况，先别慌。
第一步，查看包给出的警告信息里列出了哪些“未知字段”；第二步，去UK Biobank Showcase搜索这些字段ID，看它们到底是什么；第三步，检查你安装的ukbnmr版本是否过旧，到GitHub上看是否有更新版本。很多时候只是作者还没把新字段加进映射表，你可以在GitHub上提issue，作者通常会很快更新。
如果你的项目时间紧，没法等版本更新，也可以手动把未知字段加进数据框，按“原始列名”使用。但这种做法有风险，因为你丢掉了标准化命名带来的可追溯性，在撰写论文时容易出问题。
5.2 数据中有大量负值或“-1”标记
UK Biobank对无法检测或低于检测下限的值，有时会用负值表示。Nightingale平台本身也会对部分指标输出“低于检测限”的结果。
ukbnmr的处理策略一般是对这些值做缺失替换（即转为NA），但具体替换规则可能随指标不同而不同。我的建议是：用完包之后，务必亲自检查关键变量的描述性统计，看看有没有异常的负值、极端值。不要以为用过包就100%安全。举个例子，有些脂蛋白亚类在低浓度时变异很大，Nightingale平台给出的是估计值而非精确值，这类指标的解读要格外小心。
5.3 实例输出结构不符合预期
如果你预期得到一个人一行数据（宽表），但实际得到的是长表（一个人多行），多半是函数参数设置问题。ukbnmr提供了类似wide = TRUE/FALSE的参数，用来控制输出格式。纵向研究用长表，横断面研究用宽表。千万别弄反，否则后续合并遗传数据时匹配行数不对，连锁出一个大bug。
5.4 和其他数据源合并时样本量骤降
这是另一个高频问题。UK Biobank总样本量看似有50万，但NMR检测并不是所有人都做了。一部分人没有NMR数据，另一部分人只做了部分批次的检测。再加上你还要merge遗传数据、疾病结局、问卷信息，样本量从50万降到10万甚至8万都是正常现象。
实操建议：在项目开始前，先梳理清楚你要用的所有数据源各自的样本量和重叠量，提前评估统计效力。不要等分析做完了才发现样本量不够，那时候改起来代价极大。
6. 避坑心得与经验沉淀
我在用ukbnmr做实际项目的过程中，踩过几个值得拿出来说的坑，这里一并分享。
第一个是盲目信任默认参数。ukbnmr虽然开箱即用，但它有些参数的默认值是基于“大多数研究”场景设计的。比如对缺失值的处理方式、是否保留重复测量实例、QC标记的保留级别等，都需要你根据自己的研究问题来调整。如果你做的是遗传关联分析，通常只需要基线数据，那么把instance过滤写清楚就很重要；如果你做的是代谢物变化轨迹，那就要保留重复测量。没有一种参数设置能适配所有场景。
第二个是忽视了单位换算问题。ukbnmr输出的数据绝大多数都是原始单位，但你在和别人数据库合并或比较时，一定要看一眼单位。Nightingale的脂蛋白亚类浓度是mol/L级别，而传统生化检测的某些指标是g/L，这中间差了好几个数量级。不看单位直接对比，结果会荒谬到离谱。这类错误在论文投稿时暴露概率极高，审稿人一眼就能看穿。
第三个是关于Nightingale数据的“相对量”识别问题。脂肪酸数据很多是归一化的百分比，比如“omega-3占总脂肪酸的比例”，而不是血液中的绝对浓度。用这种数据进行关联分析时，解释结果要从“组成比例”的角度出发，不能简单说“某某物质升高了”。如果你对Nightingale平台的定量原理不够熟悉，建议先读一下平台的官方文件，至少要理解它测的是“信号”而不是“绝对质量”。
第四个经验是处理速度问题。UK Biobank原始文件大时，ukbnmr的加载函数可能在初期运行缓慢，主要是要把数百个字段逐个检查和重命名。处理几十万行、上千列数据时，等待时间可能长达几分钟，这是正常的。不要频繁重复运行加载函数。比较好的做法是：第一次加载后用saveRDS把清洗后的数据框保存为RDS格式，之后所有分析直接读取RDS，速度快得多。
saveRDS(nmr_data, "nmr_data_clean.rds") # 后续每次分析 nmr_data <- readRDS("nmr_data_clean.rds")这个小技巧能让你从“每次打开项目先等五分钟”的痛苦中彻底解脱出来。
最后再分享一个工作流层面的建议。建议将ukbnmr的处理步骤放在整个项目流程的最前端，清洗完成后立刻生成一份标记好日期和版本号的RDS文件，并尽可能在分析脚本里固定这个文件的路径。任何后续的分析脚本都从这个固定入口读数据，保证数据版本可追溯。你的合作者如果也使用同一份RDS文件，大家跑出来的结果就能完全一致，避免“我跑出来0.3你跑出来0.03”这种尴尬的复现问题。
我个人在实际使用中的体会是：ukbnmr把UK Biobank NMR数据从“部署门槛很高的数据源”变成了“随手能用的普通数据表”。它虽然不能帮你解决科学问题本身，但把从原始数据到统计模型这最后一段路铺得足够平整。如果你正计划用UK Biobank的Nightingale数据做研究，我建议你花一个下午把它的元数据对象读一遍，把支持变量清单打印出来贴在工位上，然后开始跑你的第一个关联分析。你会发现，真正让人头疼的往往不是统计，而是数据在你手里却用不起来的无力感。
本文还有配套的精品资源，点击获取
