简介：ukbtools 是一套专为英国生物库（UK Biobank）数据处理设计的 R 语言工具包，面向从事遗传流行病学、生物信息学及队列研究的科研人员与分析者。该包能够将 UKB 程序下载并解密后的多个数据文件自动折叠整合为单一数据集，并对字段代码变量赋予有意义名称，极大提升预处理效率；同时提供 ICD 诊断代码检索、样本子集探索和遗传元数据收集等功能，降低了 UKB 数据的上手门槛。压缩包共 91 个文件、3.49MB，以 R 源码（.r）和帮助文档（.rd）为主体，辅以示例数据（.rda）、CSV 数据表、SVG/PNG 可视化素材以及 Markdown 说明与 vignette 教程，附带测试脚本，便于学习原理和二次开发。目前已有 4530 人浏览学习，适合正在开展 UKB 队列研究、需要完成数据清洗与表型提取的 R 用户参考复用。
1. ukbtools是什么：给UKB数据一个顺手的操纵台
英国生物库（UK Biobank，UKB）的研究数据拿到手，第一感觉往往是“这根本不是一张表”：字段按ID平铺，实例和数组把同一指标拆成好几列，缺失码从-1到-3都有，遗传关系文件又是另一个格式。很多分析还没开始，就卡在数据整理上。ukbtools就是为这个痛点设计的R包：它把UKB的tab/csv文件读成规整的数据框，把字段编码还原成可读标签，还能顺带处理亲属关系、主成分这些遗传侧信息。它不是建模工具，而是建模前最值得先跑通的数据整理层。如果你用R做UKB数据研究，这个包值得花半天把流程捋顺。
2. UKB数据到手先别急着跑：字段编码与三种缺失码，读不对后面全白搭
2.1 UKB核心数据结构：tab/csv与Field ID的对应关系
UKB的数据发布格式看起来有点绕，但本质不复杂。最常见的是.tab和.csv两种文本文件，虽然扩展名不同，实际都是表格文本。每个文件按Field ID组织列，比如f.31.0.0表示字段31（性别）的实例0数组0，f.21022.0.0是招募年龄，f.48.0.0是腰围。字段ID是整个UKB数据的“坐标系”，你在数据字典里查到的每一个指标，最后都要落到这个命名规则上。对新手来说，最反直觉的是同一个字段可能有多列：随访多次的指标会拆成f.字段ID.实例.数组多个变体，实例表示第几次采集，数组表示同一次采集里的重复测量。
ukbtools在这个环节做的第一件事，就是把f.48.0.0这种晦涩列名翻译成可读名。它依赖数据字典HTML文件来建立Field ID和字段名之间的映射，读取后列名会变成类似waist_circumference_f48_0_0的形式，字段名和ID都保留。这样你在代码里筛选时既可以用描述性的字段名，也可以按ID精确匹配，不用自己在两种语言之间来回翻译。我拿到新数据的第一件事，永远是先确认数据字典版本和tab文件批次是否一致，版本错位会导致列名映射全乱。
2.2 缺失码不只是NA：-1、-3、-7的区别与处理
UKB最坑的地方在于缺失值不是NA，而是用一组负数编码表示不同类型的缺失。用户在数据字典里经常看到-1表示“不知道”，-3表示“拒绝回答”，-7表示“没有数据”，还有-121这类表示“数据不适用”的特殊码。如果你不做任何处理直接丢进统计模型，这些负数会被当成真实测量值参与计算，出来的结果完全不可信。
常见做法是先把这些特殊值统一转成NA。我的习惯是用dplyr的mutate_if或者na_if批量处理，但要注意不是所有负值都是缺失码。有些字段本身允许负值存在，比如某些生化指标的相对变化量，所以转换前必须对照数据字典确认。ukbtools没有强制替你转换所有缺失码，它只是保留原始值，把“哪些码代表缺失”的决策权留给你。这是设计上的克制，但很多新手会误解为包有bug，实际上是自己在读数据前少做了一步编码映射。
2.3 安装与载入：ukbtools的依赖和最小启动命令
安装ukbtools和普通R包没有区别，它托管在CRAN上，依赖项主要是dplyr、tidyr这些常用包。如果你在某个隔离环境里跑，安装前先确认这几个依赖能正常解析。最小启动命令如下：
# 安装并载入ukbtools install.packages("ukbtools") library(ukbtools) # 查看包内导出的函数，确认安装成功 ls("package:ukbtools")安装后第一件事不是急着读数据，而是跑一遍ls("package:ukbtools")看看可用函数清单。正常情况下你会看到ukb_df、ukb_context、ukb_genetic_relatedness、ukb_pca等核心函数。这一步能确认包版本与依赖没有冲突，避免后续在数据读取半途才报错。ukbtools对R版本有要求，老旧版本可能装不上，遇到编译错误先升级R到4.x再试。
3. 用ukbtools操纵数据：从ukb_df到字段筛选与编码还原
3.1 ukb_df：把一个几GB的tab文件变成干净数据框
ukb_df是包里的主力函数，负责把大文件读成R数据框。它需要的三个输入是你从UKB数据门户下载的文件：主数据文件（.tab或.csv）、数据字典（.html）、编码文件（.txt）。调用方式如下：
# 读取UKB主数据文件，结合字典和编码文件解析列名与值标签 df <- ukb_df( path = "ukb42432.tab", ukb_dict = "ukb42432.html", ukb_coding = "ukb42432.txt" ) # 查看数据框维度与列名样本 dim(df) head(names(df), 20)逻辑说明：ukb_df读取主文件后，先用字典文件把f.字段ID.实例.数组格式的列名替换成“字段名_字段ID_实例_数组”格式，再用编码文件把部分字段的原始编码映射为可读标签。返回值是普通data.frame，可以直接喂给dplyr或ggplot2。注意它不会自动把缺失码转成NA，这一步要自己做。
参数说明：path指向主数据文件路径；ukb_dict指向HTML格式的数据字典；ukb_coding指向txt格式的编码映射文件。三个文件必须来自同一批次下载，混用不同批次会导致列名错位。如果只传path，ukb_df也能读，但列名会保留原始ID形式，丧失可读性。
3.2 字段筛选：按Field ID和正则筛列，控制内存
UKB主文件动辄几GB，把全部列读进内存并不明智。我的习惯是先看数据字典，把要用的Field ID列成清单，再用正则或ID前缀筛列。ukb_df没有提供独立筛选参数，但可以在读取前用data.table::fread的select或colClasses控制要读入的列，再传给ukb_df处理。不过更整洁的流程是先把文件读进来，再用dplyr按列名模式筛选：
# 读取后用正则筛选需要分析的字段：性别、出生年份、招募年龄、腰围 library(dplyr) df_small <- df %>% select(matches("sex_f31|birth_year_f34|age_recruitment_f21022|waist_f48")) # 查看筛选后保留的列 names(df_small)逻辑说明：matches()接受正则表达式，把列名里包含指定字段ID或字段名的列全部选中。筛选后数据框大幅缩小，后续处理速度和内存占用都会改善。
参数说明：正则里的竖线是“或”关系，注意字段ID前的f前缀要和ukb_df转换后的列名格式一致。如果列名格式不同，先names(df)看一下实际的样子再写正则。更稳妥的方式是用ends_with("_0_0")筛选实例0数组0的主记录列，避免误纳入后续随访的重复测量列。
3.3 编码值还原与一致性检查：ukb_context与编码映射
UKB很多字段的取值是编码，比如吸烟状态用1表示当前吸烟、2表示既往吸烟、3表示从不吸烟。这些编码的含义都记录在数据字典里，但读进R后你看到的就是一堆数字。ukb_context函数能帮你快速查看某个字段在字典里的上下文，包括字段名、类型、编码说明和所在位置：
# 查看"sex"字段在字典中的上下文信息 ukb_context("sex", ukb_dict = "ukb42432.html") # 查看"smoking_status"字段的编码说明 ukb_context("smoking_status", ukb_dict = "ukb42432.html")逻辑说明：ukb_context解析HTML字典文件后，返回与字段名匹配的所有条目，包括字段ID、实例数、值和编码说明。它是排查“这列到底是什么”的第一去处，比翻网页快得多。
参数说明：第一个参数是字段名或字段ID的字符串，ukb_dict指向同一份字典文件。如果字段名查不到，试试传Field ID数字，例如ukb_context(31, ukb_dict = ...)。编码还原这一步，我一般会在ukb_context确认编码含义后，用dplyr::recode把数字标签替换成因子或字符串，但保留原始数字列作为备份，避免后续分析需要数值型变量时还要再转回去。
4. 探索UKB数据：把遗传侧和表型侧打通的关键操作
4.1 ukb_genetic_relatedness：读入并核查亲属关系矩阵
UKB的遗传数据里附带一份亲属关系文件，记录任意两个样本之间的亲缘系数。做关联分析前必须先排除高亲缘关系的样本，否则统计检验的独立性假设会被破坏。ukbtools的ukb_genetic_relatedness函数可以直接读入这份文件并转换格式：
# 读入UKB亲属关系文件 rel <- ukb_genetic_relatedness( ukb_data = df, relatedness_file = "ukb42432_rel.txt" ) # 查看前几行结构 head(rel)逻辑说明：ukb_genetic_relatedness把亲属关系文件解析为矩阵或长表格式，并与你已有的表型数据框按样本ID对齐。对齐这一步很重要，因为主数据里的样本ID顺序与遗传文件里的ID顺序不一定一致。
参数说明：ukb_data是你已经读入的表型数据框，必须包含样本ID列；relatedness_file是从UKB门户下载的亲属关系文件路径。读入后可以用subset(rel, kinship_coefficient > 0.0884)筛掉三度以内的亲属，这个阈值是UKB官方推荐的标准做法。如果文件非常大，读入时注意内存占用，考虑在系统层面加内存上限或先用命令行工具做一次ID过滤。
4.2 主成分数据的关联方法：直接读文件还是自己跑PCA
UKB遗传数据通常附带计算好的主成分（PC）文件，用于校正群体分层。ukbtools提供了ukb_pca函数读取这个文件，用法很直接：
# 读取UKB主成分文件 pcs <- ukb_pca("ukb42432_pca.txt") # 查看主成分列名与前几行 head(pcs)逻辑说明：UKB官方提供的PC文件已经过严格质控，直接用要比自己跑PCA可靠得多。自己算PCA还要涉及LD剪枝、染色体筛选等流程，容易在细节上翻车。
参数说明：ukb_pca接受PC文件的路径，返回一个数据框，前几列是样本ID和变异解释比例，后面是PC1到PC10等主成分值。拿到PC后，按样本ID左连接回表型数据框即可，连接时注意ID类型一致。PC1到PC10通常作为协变量放进回归模型，但如果你的人群结构复杂，考虑加入PC20甚至PC40，具体看你的样本组成和曼哈顿图的表现。
4.3 基础可视化与表型分布：绘图之前先做一次全量字段扫描
在投入建模之前，我会花一段时间做探索性可视化，确认每个变量的分布、缺失比例、异常值。ukbtools本身不提供绘图函数，但它整理出的干净数据框可以直接配合ggplot2使用。关键技巧是先做一次字段扫描，把所有变量的缺失比例和唯一值数量列成一张表：
# 计算每个变量的缺失比例和唯一值数量 library(tidyr) scan_results <- df %>% summarise(across(everything(), list( missing_pct = ~mean(is.na(.)) * 100, n_unique = ~n_distinct(.) ))) %>% pivot_longer(everything(), names_sep = "_", names_to = c("var", "stat"), values_to = "value") %>% pivot_wider(names_from = stat, values_from = value) # 筛选缺失率高于20%的字段 scan_results %>% filter(missing_pct > 20)逻辑说明：这段代码用across对每一列计算缺失率和唯一值数，再用两次透视把结果整理成长表。缺失率高的字段要么剔除，要么谨慎插补，不能直接丢进模型。
参数说明：names_sep = "_"依赖列名里没有多余下划线，如果你的字段名本身包含下划线，这个分隔逻辑会出错。更稳妥的做法是先names(df)检查一遍，或者用separate手动指定位置分割。唯一值数量能帮你发现“假数值型”变量——比如某个字段虽然读进来是数字，但只有两三个不同取值，那它本质是分类变量。
5. 避坑：ukbtools最常见的5个坑与排查方法
5.1 读入后样本ID变成了科学技术法
现象：样本ID列读进来后显示为1.234568e+14，和原始ID对不上，连接遗传数据时全部匹配失败。
原因：R默认把长整型数值读成double，UKB的样本ID是18位左右的长整数，超过double的精度上限后尾数被截断。
解决：在ukb_df读取前先用data.table::fread指定ID列为字符型，再传给后续处理。比如fread("ukb42432.tab", colClasses = list(character = "eid"))，把样本ID列强制按字符串读入。如果你已经读进来了，用format(df$eid, scientific = FALSE, trim = TRUE)转回字符串也来得及。
5.2 内存直接爆掉，R会话被杀
现象：几GB的tab文件读完，R直接卡死或报“cannot allocate vector of size”。
原因：ukb_df默认把所有实例和数组的列全部展开成宽表，列数膨胀到几千列，内存占用远超文件体积。
解决：先想清楚这次分析需要哪些Field ID，用fread的select参数只读需要的列，再丢给ukb_df。如果必须全量读，考虑在服务器上用data.table处理而不是本地笔记本。另一个办法是分批读取：用ukb_df分别读入几个子文件，最后cbind合并，但前提是样例顺序一致。
5.3 字段名对不上，字典里查得到但数据框里没有
现象：ukb_context查某个字段的说明正常，但在names(df)里找不到对应列。
原因：字段可能在字典里定义了多种实例或数组，而你下载的数据只录入了部分实例；或者字段名里的连字符、空格被R转换成了点号，导致匹配失败。
解决：用grep("字段名", names(df), value = TRUE)做模糊搜索，先看实际列名格式。再用ukb_context核对字段ID和实例范围，如果确认是你的下载子集不包含该实例，就改用其他实例的列。
5.4 缺失码没有转成NA，模型把-1当真实值
现象：回归模型跑出来的系数方向和之前文献完全相反，查看数据发现“缺失”实际是-1、-3这类负数。
原因：ukb_df不会自动转换缺失码，这是有意设计。新手容易忽略这一步，导致负值进入统计模型。
解决：写一个函数把特定缺失码批量转成NA，建议先对照数据字典确认哪些码代表缺失。不要盲目把所有负值都转NA，部分字段的负值有实际含义。
5.5 亲属关系矩阵文件读入后是全零或维度不匹配
现象：ukb_genetic_relatedness读入后得到的是空矩阵或维度与样本数不符。
原因：亲属关系文件里的样本ID格式与主数据可能不一致，比如一个是18位数值，一个是带前导零的字符；或者文件路径指向的是不完整的下载文件。
解决：先用readLines或fread直接预览文件头几行，确认ID格式。如果格式不一致，统一转成字符型再去掉前导零。如果文件本身不完整，重新下载后再试。
6. 进阶：用ukbtools写一个可复用的UKB数据处理流程
当你在多个UKB子课题间切换时，最怕的是每个项目都从读原始文件开始，重复踩一遍坑。我的习惯是把读数和清洗流程封装成一个脚本，参数化字段清单，输出统一的结构化数据，这样每个新课题只用改字段列表就能复用。
# 自定义函数：输入字段ID向量，输出清洗后的数据框 load_ukb_subset <- function(field_ids, tab_files, dict_file, coding_file) { # 用fread只读指定列，ID列按字符读 cols <- c("eid", paste0("f.", field_ids, ".0.0")) raw <- data.table::fread(tab_files, select = cols, colClasses = list(character = "eid")) # 用ukb_df解析列名 df <- ukb_df(path = tab_files, ukb_dict = dict_file, ukb_coding = coding_file) # 批量把常见缺失码转成NA df <- df %>% mutate(across(where(is.numeric), ~ifelse(. %in% c(-1, -3, -7, -121), NA, .))) return(df) } # 调用示例 my_fields <- c(31, 34, 21022, 48, 52) data_clean <- load_ukb_subset(my_fields, "ukb42432.tab", "ukb42432.html", "ukb42432.txt")这段流程把三件事固定下来：列筛选、列名解析、缺失码转换。字段ID和文件路径全部参数化，新项目来了只改my_fields和文件名即可。它不能替代你理解数据结构，但能减少重复劳动，让精力集中在分析本身。我的教训是：第一次拿到UKB数据时，我习惯一股脑把整份文件读进来先看一眼，结果内存耗尽、列名混乱，走出这个坑靠的是先查字典再动手。后来把上面这套流程固化下来，出错率明显下降。希望帮到你。
本文还有配套的精品资源，点击获取
