dplyr `do()` 函数弃用指南:报错语义、分组实现与 `reframe()` / `nest_by()` 迁移路径

原创2026-10-12 13:11:331,708 阅读
文章标签:数据分析

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
}

可以看到,这里对参数结构施加了两条硬性约束:

  1. 参数要么全部命名、要么全部无名——混用直接报错;
  2. 无名参数最多只能有一个——因为一个无名表达式的求值结果将被按行绑定(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() 代码时可按以下清单自查:

  1. 无名参数、返回单行摘要 → summarise();
  2. 无名参数、每组返回多行(如 head()、intersect()、broom::tidy())→ reframe();
  3. 仅取每组的头部/尾部若干行 → slice_head() / slice_tail();
  4. 命名参数、逐组建模 → nest_by() + mutate(mod = list(...)),再用 summarise() / reframe() 汇总;
  5. 原来用 .$var 引用列 → 直接写 var(data-masking 自动屏蔽)或 pick() 完成"当前组"的数据选取;
  6. 确认没有混用命名/无名参数、没有多个无名参数——这两条 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() 调用。

登录后查看全文
dplyr