dplyr `do()` 函数弃用指南:报错语义、分组实现与 `reframe()` / `nest_by()` 迁移路径
dplyr do() 函数弃用指南:报错语义、分组实现与 reframe() / nest_by() 迁移路径
do() 是 dplyr 早期版本中"对每组执行任意操作"的通用动词,自 dplyr 1.0.0 起被标记为 superseded(已取代)。本文以 dplyr 仓库中的 快照测试、函数文档 和 源码实现 为依托,系统讲解 do() 的调用规则、五种典型报错的底层触发逻辑,以及如何用 reframe()、nest_by()、pick() 等现代 dplyr 语法无损迁移旧代码。
1. do() 的定位:为什么它被标记为 superseded
do() 的官方文档标题是 "Do anything"(见 man/do.Rd),它允许你在每个分组上执行任意表达式,是 dplyr 中最"不设限"的动词之一。但从 dplyr 1.0.0 开始,它被官方标记为 superseded(已取代),理由是:
do()的语法从来都没有真正与 dplyr 的其他部分融为一体("its syntax never really felt like it belonged with the rest of dplyr")。
从源码看,R/deprec-do.R 中的通用入口函数会在每次调用时显式发出阶段信号:
do <- function(.data, ...) {
lifecycle::signal_stage("superseded", "do()")
UseMethod("do")
}
即每次调用 do() 都会通过 lifecycle 机制提示你该函数已被取代。在 NEWS.md 的早期版本记录中也能看到它的演进轨迹(如 "do() is superseded in favour of summarise()"),而在 1.0.0 的发布说明中,官方明确给出了替代组合:
原 do() 用法 |
官方推荐替代 | 说明 |
|---|---|---|
| 无名参数(单参数,返回数据框) | reframe() 或 summarise() |
返回多行、多列 |
| 命名参数(结果存入列表列) | nest_by() + mutate() |
逐组嵌套建模 |
用 . 引用当前分组 |
pick() |
访问"当前组"的数据 |
下面逐一展开这三条迁移路径,并深入 do() 的底层实现与报错语义。
2. do() 的核心调用规则:命名参数与无名参数二选一
根据 man/do.Rd 的参数说明,do() 接受一个数据框 .data 和任意表达式 ...:
- 如果表达式是命名的(如
mod = lm(...)),结果会被存储为一个新的列(列表列); - 如果表达式是未命名的,则必须返回一个数据框;
- 可以使用
.引用当前分组的数据; - 命名参数与无名参数不能混用。
这套规则的判定逻辑集中在源码的 named_args() 辅助函数中(R/deprec-do.R):
named_args <- function(args, error_call = caller_env()) {
# Arguments must either be all named or all unnamed.
named <- sum(names2(args) != "")
if (!(named == 0 || named == length(args))) {
msg <- "Arguments must either be all named or all unnamed."
abort(msg, call = error_call)
}
if (named == 0 && length(args) > 1) {
msg <- glue("Can only supply one unnamed argument, not {length(args)}.")
abort(msg, call = error_call)
}
named != 0
}
可以看到,这里对参数结构施加了两条硬性约束:
- 参数要么全部命名、要么全部无名——混用直接报错;
- 无名参数最多只能有一个——因为一个无名表达式的求值结果将被按行绑定(
bind_rows())成输出数据框,多于一个无名参数无法确定输出结构。
这两条规则正是快照测试中两条核心报错的来源(详见第 4 节)。
3. 三种数据类型的实现:do() 的方法分派
do() 是一个 S3 泛型,仓库中为四类对象实现了方法(R/deprec-do.R):
| 方法 | 作用对象 | 关键行为 |
|---|---|---|
do.NULL() |
NULL |
直接返回 NULL |
do.data.frame() |
未分组数据框 | 无名参数求值后校验必须是数据框;命名参数打包为列表列 |
do.grouped_df() |
分组数据框 | 逐组求值,无名结果按行绑定、命名结果存入列表列 |
do.rowwise_df() |
逐行数据框 | 逐行求值,current_row() 用活动绑定(active binding)暴露当前行 |
3.1 分组数据框:. 代词与活动绑定
对分组数据框,do() 的核心实现是(R/deprec-do.R):
- 通过
group_rows()拿到每组对应的行索引; - 用
ungroup()得到适合子集化的"无分组版本"数据框; - 构造数据掩码(data mask),其中
.是一个活动绑定(active binding),每次访问都会解析到当前组group_data<a href="https://link.gitcode.com/i/4d63370e6aebcb141244afc63e6719fb" target="_blank">index[[_i]], , drop = FALSE]([R/deprec-do.R); - 以双层循环遍历每个分组 × 每个参数,用
eval_tidy()在掩码中求值(R/deprec-do.R); - 求值过程中带有进度条(
Progress),计算超过 2 秒才会显示。
对未命名结果,输出经由 label_output_dataframe() 处理:先校验每个分组的返回值都是数据框,再统计各组行数,把分组标签按行数重复后与结果 bind_cols(),最后重建为 grouped_df(R/deprec-do.R)。
对命名结果,则由 label_output_list() 把每个命名表达式的结果作为列表列写入,并转为 rowwise 数据框(R/deprec-do.R)。
3.2 未分组数据框与 rowwise
- 未分组数据框(R/deprec-do.R):无名参数直接求值并校验
inherits(out, "data.frame"),否则抛出Result must be a data frame, not ...;命名参数则逐个求值并as_tibble(.name_repair = "minimal")打包。 - rowwise 数据框(R/deprec-do.R):
current_row()返回当前行的lapply(..., "[[", 1)结果,do()会为每一行求值每个参数,同样支持命名/无名两种模式。
4. 快照测试逐条解读:do() 的五种"有意义报错"
仓库中的快照文件 tests/testthat/_snaps/deprec-do.md 完整记录了 do() 在非法调用下产生的五条错误消息(对应测试位于 tests/testthat/test-deprec-do.R),它们都通过 expect_snapshot() 固化,作为回归保护的基准。逐条解读如下:
4.1 无名参数超过一个
Error in `do()`:
! Can only supply one unnamed argument, not 2.
触发代码:do(df, head, tail)。两个无名参数直接命中 named_args() 中 named == 0 && length(args) > 1 的分支(R/deprec-do.R)。
4.2 未分组数据框的无名结果不是数据框
Error in `do()`:
! Result must be a data frame, not numeric.
触发代码:do(ungroup(df), 1)。这是 do.data.frame() 分支对单组结果的即时校验(R/deprec-do.R),错误消息中的 not numeric 由 fmt_classes() 动态拼出实际类型。
4.3 分组数据框中部分组的结果不是数据框
Error in `do()`:
! Results 1, 2, 3 must be data frames, not numeric.
触发代码:do(df, 1)。对分组数据框,do() 先对每组求值,再在 label_output_dataframe() 中统一校验(R/deprec-do.R):消息列出所有"不合格"的组编号(1, 2, 3),并给出第一个坏结果的类(numeric)。do(df, "a") 触发同类错误,只是类名变为 character:
Error in `do()`:
! Results 1, 2, 3 must be data frames, not character.
4.4 命名与无名参数混用
Error in `do()`:
! Arguments must either be all named or all unnamed.
触发代码:do(df, x = 1, 2)。这正是 named_args() 第一道检查的分支(R/deprec-do.R):x = 1 已命名、2 未命名,混合使用直接中止。
这些快照既是对用户输入的友好提示,也揭示了 do() 的两大设计约束(单无名参数、命名/无名二选一)——理解它们,才能理解为什么现代 dplyr 用 reframe() 取代了这套机制。
5. 迁移路径详解:从 do() 到现代 dplyr
man/do.Rd 的示例部分给出了完整的旧写法 → 新写法对照,这里逐例展开。
5.1 无名参数 → reframe() 或 slice_head()
by_cyl <- mtcars |> group_by(cyl)
# 旧写法:无名参数 + `.`
by_cyl |> do(head(., 2))
# 新写法(通用):
by_cyl |> reframe(head(pick(everything()), 2))
# 新写法(取前 n 行的特例):
by_cyl |> slice_head(n = 2)
这里 . 对应替换为 pick()。从 R/pick.R 的实现看,pick() 在 data-masking 上下文中会被展开为 tibble(...) 形式的列选择,等效于 do() 里通过活动绑定暴露的"当前组数据"。
5.2 直接引用变量 → summarise()
# 旧写法
by_cyl |> do(mean = mean(.$vs))
# 新写法:分组上下文中变量可直接引用
by_cyl |> summarise(mean = mean(vs))
这是因为 dplyr 的 data-masking 机制下,summarise() 会自动按组屏蔽(mask)变量,无需像 do() 那样手动写 .$vs。
5.3 命名参数(逐组建模)→ nest_by() + mutate()
do() 最经典的场景是"逐组拟合模型并存进列表列",nest_by() 提供了更结构化的替代:
# 旧写法
models <- by_cyl |> do(mod = lm(mpg ~ disp, data = .))
# 新写法
models <- mtcars |>
nest_by(cyl) |>
mutate(mod = list(lm(mpg ~ disp, data = data)))
models |> summarise(rsq = summary(mod)$r.squared)
nest_by() 的实现(R/nest-by.R)把每组数据打包成名为 data 的列表列并转为 rowwise 数据框,然后由 mutate() 逐行拟合模型。从 R/nest-by.R 的文档看,df |> nest_by(x, y) 等价于 df |> group_by(x, y) |> nest() 的紧凑写法,天然适合逐组建模流水线。
5.4 模型结果整理 → reframe(broom::tidy(...))
# 旧写法:手工把模型对象拆成数据框
models |> do(data.frame(
var = names(coef(.$mod)),
coef(summary(.$mod)))
)
# 新写法:用 broom 统一整理模型结果(需安装 broom 包)
models |> reframe(broom::tidy(mod))
从 NEWS.md 的说明可知,官方将"每组返回任意行数"的能力整体移入 reframe(),因为 reframe() 与 summarise() 的两点区别正是迁移的核心依据:
reframe()每组可以返回任意行数,而summarise()每组只能缩减为一行;reframe()始终返回未分组数据框,而summarise()的结果可能仍是分组或 rowwise 结构(R/reframe.R)。
6. 实战迁移检查清单
结合上面的源码分析与快照测试,迁移旧 do() 代码时可按以下清单自查:
- 无名参数、返回单行摘要 →
summarise(); - 无名参数、每组返回多行(如
head()、intersect()、broom::tidy())→reframe(); - 仅取每组的头部/尾部若干行 →
slice_head()/slice_tail(); - 命名参数、逐组建模 →
nest_by()+mutate(mod = list(...)),再用summarise()/reframe()汇总; - 原来用
.$var引用列 → 直接写var(data-masking 自动屏蔽)或pick()完成"当前组"的数据选取; - 确认没有混用命名/无名参数、没有多个无名参数——这两条
do()的硬性约束在新语法中不再存在,迁移后代码更自由也更直观。
7. 小结
do() 作为 dplyr 1.0.0 之前的"万能分组动词",其无名参数单发、命名/无名二选一的语法约束在 R/deprec-do.R 的 named_args() 中体现得淋漓尽致,五种典型报错则被 tests/testthat/_snaps/deprec-do.md 的快照测试完整固化。随着 dplyr 引入 reframe()、nest_by()、pick() 三件套,官方推荐的迁移路径覆盖了 do() 的全部使用场景,且语义更清晰、约束更少、结果结构更可预期。升级到 dplyr 1.0.0+ 的项目,应优先按第 5 节的对照表完成迁移,逐步淘汰 do() 调用。