dplyr 中 `_each()` 系列函数的弃用与移除:`summarise_each()` / `mutate_each()` 的迁移指南

原创2026-10-13 11:35:411,607 阅读
文章标签:数据分析

dplyr 中 _each() 系列函数的弃用与移除:summarise_each() / mutate_each() 的迁移指南

导读

summarise_each()、mutate_each() 以及它们带下划线的标准求值(SE)版本 summarise_each_()、mutate_each_(),是 dplyr 早期用于"对多列批量应用函数"的 API。自 dplyr 0.7.0 起它们被标记为已弃用(deprecated),并在当前开发版本(1.2.1.9000)中正式失效(defunct):任何调用都会立即抛出指引性错误,提示改用 across()。本文以 defunct-each.md 中记录的出错快照为骨架,结合 R/defunct-each.R 的实现、test-defunct-each.R 的测试以及 vignettes/colwise.Rmd 的官方历史说明,完整讲解这批函数被移除的原因、确切的报错行为,以及如何把旧代码一行行迁移到 across()。

一、快照文档记录了什么:_each() 家族的全部报错形态

defunct-each.md 是 dplyr 测试体系中的**快照(snapshot)**文件:testthat 的 expect_snapshot() 会把一段代码的完整输出(包括错误信息)固化到 .md 文件中,用于回归验证错误信息长期稳定。该文件覆盖了 _each() 家族的 6 个函数调用,是本文讨论的权威事实来源:

调用 报错信息
summarise_each() ! `summarise_each()` was deprecated in dplyr 0.7.0 and is now defunct. i Please use `across()` instead.
summarise_each_() ! `summarise_each_()` was deprecated in dplyr 0.7.0 and is now defunct. i Please use `across()` instead.
mutate_each() ! `mutate_each()` was deprecated in dplyr 0.7.0 and is now defunct. i Please use `across()` instead.
mutate_each_() ! `mutate_each_()` was deprecated in dplyr 0.7.0 and is now defunct. i Please use `across()` instead.
summarize_each()(美式拼写别名) ! `summarise_each()` was deprecated in dplyr 0.7.0 and is now defunct. i Please use `across()` instead.
summarize_each_()(美式拼写别名) ! `summarise_each_()` was deprecated in dplyr 0.7.0 and is now defunct. i Please use `across()` instead.

几个值得注意的细节

  1. 报错信息中的函数名以当时传入的名字为准:summarise_each() 报出 summarise_each(),而美式拼写 summarize_each() 同样报出 summarise_each()。这是因为美式别名在源码里就是直接指向英式函数的,见下文源码分析。
  2. 所有报错都含两个要素:主消息 `xxx()` was deprecated in dplyr 0.7.0 and is now defunct,以及次要提示 i Please use `across()` instead.。! 前缀是主要错误,i 前缀是引导性提示(bullets),这是 rlang 条件系统的标准输出格式。
  3. 测试使用 expect_snapshot(error = TRUE):对应 test-defunct-each.R 第 1-9 行,error = TRUE 表示快照预期捕获抛出的错误,从而把"调用即报错"固化成了契约——将来如果某个函数悄悄恢复可用,或者错误信息变化,CI 都会失败。

二、源码实现:each_defunct() 与 6 个占位函数

整个 _each() 家族的"已失效"行为,在 R/defunct-each.R 中只由两段代码完成。

2.1 统一的报错工厂 each_defunct()

each_defunct <- function(fun) {
  lifecycle::deprecate_stop(
    when = "0.7.0",
    what = fun,
    with = "across()"
  )
}

核心是 lifecycle 包的 deprecate_stop():与 deprecate_warn()(只警告)不同,它会直接中止执行并抛出错误,是"已彻底移除"这一阶段的标志性工具。三个参数分别是:

  • when:弃用发生的时间点,此处为 "0.7.0"(2017 年 6 月发布的 dplyr 0.7.0,见 NEWS.md 第 160 行);
  • what:被调用且已失效的函数名,即 "summarise_each()"、"mutate_each()" 等;
  • with:推荐的替代方案,统一为 "across()"。

lifecycle 包在 DESCRIPTION 的 Imports 中声明为 lifecycle (>= 1.0.5),说明这是 dplyr 内部弃用/失效治理的标准基础设施。

2.2 6 个函数全部是"空壳"

summarise_each <- function(tbl, funs, ...) { each_defunct("summarise_each()") }
summarise_each_ <- function(tbl, funs, vars) { each_defunct("summarise_each_()") }
mutate_each    <- function(tbl, funs, ...) { each_defunct("mutate_each()") }
mutate_each_   <- function(tbl, funs, vars) { each_defunct("mutate_each_()") }
summarize_each <- summarise_each
summarize_each_ <- summarise_each_

可以清楚看到三点实现事实:

  • 函数签名被保留(tbl、funs、... / vars),因此旧代码调用时参数仍能对上,不会先因为参数不匹配报错,而是干净地进入 each_defunct();
  • 函数体内没有任何业务逻辑,纯粹是转交报错工厂;
  • 美式拼写 summarize_each 就是英式 summarise_each 的对象别名,所以快照文档中美式调用的错误信息仍然显示英式函数名。

同时,这 6 个函数仍通过 NAMESPACE 第 312-313、398-399、405-406 行导出(export(mutate_each)、export(summarise_each)、export(summarize_each) 等),意味着用户写 dplyr::summarise_each() 时命名空间解析成功、但调用即刻抛错——这正是"defunct"与"彻底删除"之间的中间状态。

2.3 文档元数据

R/defunct-each.R 顶部用 roxygen2 注释声明了整个函数族的 @name defunct-each、@keywords internal 以及 r lifecycle::badge("defunct") 徽章,生成的帮助页为 man/defunct-each.Rd。其描述明确写道:"mutate_each() and summarise_each() are deprecated in favour of the new across() function that works within summarise() and mutate().",即官方声明这两族函数已被 across() 取代。

三、为什么被移除:dplyr 多列操作 API 的三次迭代

要理解 _each() 为何被淘汰,需要回顾 dplyr 的演化历史。官方在 vignettes/colwise.Rmd 第 255-290 行专门讲述了这个过程:dplyr 处理"多列批量操作"经历了三次方案迭代。

3.1 第一代:_each() 函数(即本文主角)

最早的尝试正是 summarise_each() / mutate_each()。它解决"对每列应用同一函数"这一需求,但很快就显露出不足,被第二代方案取代,此后逐步弃用(0.7.0,2017)并最终失效。

3.2 第二代:_if() / _at() / _all() 作用域函数族

后续 dplyr 用 summarise_if()、summarise_at()、summarise_all() 这类"scoped variants"取代了 _each()。这一代功能更灵活,但在使用中暴露出新问题:函数数量成倍膨胀(每个动词都要配 3 个变体)、选择列的方式分裂为"按类型 / 按位置 / 全部",且 _at() 需要手动调用 vars() 引用变量名。

3.3 第三代:across()(现役方案)

across() 于 dplyr 1.0.0 引入并全面取代前两代。官方文档在 R/across.R 第 18-19 行明确写道:"across() supersedes the family of 'scoped variants' like summarise_at(), summarise_if(), and summarise_all()." 它一统了 _if/_at/_all 三种选择语义:

  1. 表达力更强:可以在同一个 summarise() 里叠加多个 across(),例如同时对数值列取均值、对因子列数水平、再追加行数 n();
  2. 函数面更小:dplyr 只需维护 across() 一个函数,而不是每个动词配 3 个变体;
  3. 选择语法统一:可同时按位置、按名称、按类型选择,还能组合出此前不可能的复合选择,如 across(where(is.numeric) & starts_with("x"));
  4. 告别 vars():不再需要手动加引号引用列名。

vignettes/colwise.Rmd 第 290 行还坦承,_each() 是开发团队"未能及早发现 across() 之前"的一个错误起步(false start),因为 across() 依赖三个当时的"新发现":data frame 列本身可以是 data frame(df-column)、汇总函数可以返回多列、以及"外层无名则解包 df 列"的约定。

四、迁移实战:把 _each() 旧代码改写为 across()

4.1 迁移规则

对于 summarise_each() 和 mutate_each(),迁移极其简单:把函数名整体替换为 across(),第一参数改为选择器,后续参数原样保留。官方转换法则(见 vignettes/colwise.Rmd 第 303-313 行)归纳为:去掉 _each() 后缀,改用 across(),其中:

  • 原 _each() 作用于全部非分组列,对应 across(everything(), ...);
  • 若要限定列,第一参数可用 tidy-select 选择器:c(col1, col2)、starts_with("x")、where(is.numeric)、everything()、all_of(vars) 等(用法示例见 R/across.R 第 103-170 行)。

4.2 典型迁移示例

以 iris 数据为例(across() 官方示例亦大量使用 iris,见 R/across.R 第 105 行起)。

场景 A:对全部列取均值

# 旧代码(现已报错)
df |> summarise_each(funs(mean))

# 新代码
df |> summarise(across(everything(), mean))

场景 B:对指定列做归一化变换

# 旧代码
df |> mutate_each(funs(. / max(.)), vars(x, y))

# 新代码
df |> mutate(across(c(x, y), ~ .x / max(.x)))

注意两个细节:一是 across() 直接用在 summarise() / mutate() 内部,不再需要外层包裹;二是 across() 的 ... 参数已被弃用(R/across.R 第 44-51 行),给函数传额外参数时要用 purrr 风格 lambda,例如 across(a:b, ~ mean(.x, na.rm = TRUE)),而不要写 across(a:b, mean, na.rm = TRUE)。

场景 C:对每列应用多个函数

# 新代码:named list 一次应用多个函数,.names 控制输出列名
df |>
  group_by(Species) |>
  summarise(
    across(starts_with("Sepal"), list(mean = mean, sd = sd), .names = "{.col}_{.fn}")
  )

其中 {.col} 代表所选列名、{.fn} 代表函数名(默认 NULL 时单函数情况等价于 "{.col}",多函数情况等价于 "{.col}_{.fn}",见 R/across.R 第 52-56 行)。

4.3 迁移中容易踩的坑

  • 分组列不会被选中:across() 不会选择分组变量,以避免在 summarise() / mutate() 中意外修改它们(R/across.R 第 29-31 行);
  • funs() 本身也已失效:旧代码里的 funs(mean) 是另一批弃用函数,迁移时直接写函数名或 lambda 即可,不要保留 funs() 包装;
  • 下划线版本(SE 版本)同样失效:summarise_each_()、mutate_each_() 这类带 _ 的"标准求值"函数,因 dplyr 全面转向 tidy evaluation(可通过 !!/{{ 等注入机制编程),已整体失效,见 R/defunct-lazyeval.R 第 6-18 行的说明——它们与 NSE 动词配合 vars()/.dots 使用的时代已经结束。

五、与相邻弃用体系的区分:_each vs _lazyeval vs 作用域函数

_each() 家族并非孤例,dplyr 维护着多个"已失效"函数族,理解它们的边界有助于准确判断旧代码的命运:

函数族 定义文件 替代方案 状态
summarise_each() / mutate_each() 及 _ 版本 R/defunct-each.R across() defunct(0.7.0 起弃用)
带 _ 后缀的 SE 动词(filter_()、arrange_()、count_() 等) R/defunct-lazyeval.R 同名 NSE 动词 + tidy eval defunct
_if() / _at() / _all() 作用域变体 R/colwise-funs.R 等 across() superseded(仍可用,只修关键 bug)
combine()、src_mysql()、tbl_df() 等 R/defunct.R vctrs::vec_c()、tbl()、tibble::as_tibble() 等 defunct(1.0.0 起)

从源码可以看出两种失效策略的区别:_each() 家族与 defunct-lazyeval 家族一样使用 deprecate_stop() 硬报错,调用即中止;而 _if()/_at()/_all() 尚处于 superseded 阶段,仅弃用未移除,旧代码仍能运行(参见 R/colwise-funs.R 中 deprecate_warn() 的用法与 NEWS.md 的相关记录)。如果你的旧脚本命中的是后者,则当前只是警告而非错误,但官方已明确不再为其添加新功能、只做关键 bug 修复。

六、如何验证你的代码库不再依赖 _each()

在新版本 dplyr 下运行任何旧脚本,凡是调用 summarise_each()、summarise_each_()、mutate_each()、mutate_each_()、summarize_each()、summarize_each_() 的地方都会立即得到本文开头表格中的错误。建议按如下流程排查:

  1. 全局搜索这 6 个函数名(包括 dplyr:: 前缀调用与 library(dplyr) 后的裸调用);
  2. 逐处按第四节规则改写为 across();
  3. 对照快照文档 defunct-each.md 确认:新代码不再产生任何 deprecated ... is now defunct 错误;
  4. 注意 summarize(美式)与 summarise(英式)两种拼写都要查——二者在 dplyr 中是等价别名,summarize_each 同样报错。

结语

_each() 家族的命运是 dplyr API 演进史的缩影:从 _each() 到 _if()/_at()/_all() 再到 across(),多列操作最终收敛到"一个函数 + tidy-select 选择器 + 函数列表"的简洁模型。对于仍在维护旧脚本的开发者,最直接的建议是:看到 defunct 报错不是坏事,它恰好告诉你标准答案——迁移到 across(),并参照 vignettes/colwise.Rmd 与 R/across.R 中的完整示例完成改写。

登录后查看全文
dplyr