R 包中的数据弃用
Data Deprecation in R-package
在我的一个 R 包中，我有一些愚蠢的示例数据，我想将其删除。为此，我想按照常见的方式先弃用它，然后再取消它。
为了从 R 包中删除函数，我找到了这样的方法：
oldFunc <- function()
{
.Deprecated("newFunc")
}
其次是（比方说 6 个月）
oldFunc <- function()
{
.Defunct("newFunc")
}
再过 6 个月后，我可以从包中删除该功能。
但是，如何删除包中存储为 /data/myData.rda 并且还有一些 myData.Rd 描述的数据对象？
除了使用 .Deprecated 和 .Defunct 你还应该
- 从
data/ 中删除数据集。用户可以从 CRAN 获取存档版本
- 在NEWS/CHANGELOG
中添加备注
为了对以后的读者有所帮助，答案是对原问题下评论的总结。
好问题，遗憾的是我没有找到答案。
因此，我将分享我为解决此案而起草的内容。我知道它并不完美，但我希望它会有用和/或改进。
更新
所以在完成初稿（见下文）之后，我应用了一个看起来合理且足够好的解决方案的过程。
1。移动数据文件
第一步是将数据文件从其默认位置./data移动到另一个位置以避免其自动加载——即使它是一个懒惰的加载中。
目标位置是 ./data-raw 它是一个目录，按照惯例用于存储脚本和原始数据，以便能够更新或重现导出数据集的生产——更多信息在Data chapter of the book R packages.
我按照惯例使用 leg_ 前缀将其标记为 遗留数据集 。
$ mv ./data/my_data.rda ./data-raw/leg_my_data.rda
2。编写脚本来转换数据集
用于将数据集从旧格式转换为新格式的代码与旧数据集一起存储在./data-raw/my_data.R中。这将使 整个过程可重现 。
# my_data new version
library(tidyverse)
# Load legacy data -----
load("data-raw/leg_my_data.rda")
leg_my_data <- my_data
# Create the new dataset -----
# Perform here every change that has to be performed
my_data <- leg_my_data %>%
rename(cat = categ) %>%
arrange(categ)
# Write the new dataset ----
usethis::use_data(my_data, overwrite = TRUE, compress = 'xz')
源文件，新版本已上线！
source('./data-raw/my_data.R', echo=TRUE)
# ✓ Saving 'my_data' to 'data/my_data.rda'
# ● Document your data (see 'https://r-pkgs.org/data.html')
my_data
# A tibble: 10 x 2
# categ val
# <fct> <int>
# 1 a 9
# 2 a 6
# 3 a 4
3。秘方
在 ./R/my_package-package.R 文件中，创建一个 legacy_mode 函数 。如果用户出于兼容性原因需要使用数据集。
，此功能将是 用户加载数据集的先前（遗留）版本的一种方式
#' Load legacy version of datasets.
#'
#' Load legacy (previous) version of all the datasets for compatibility reason.
#' The environment where data will be loaded can be chosen.
#'
#' @param envdir the environment where the data should be loaded.
#' @param verbose should item names be printed during loading?
#'
#' @export
legacy_mode <- function(envdir = parent.frame(), verbose = TRUE) {
.Deprecated(msg = "This function replaces datasets with the previous (legacy) version for compatibility reason")
# TODO: To be improved to load a subset of datasets
paths <- sort(Sys.glob(c("data-raw/leg_*.rda", "data-raw/leg_*.RData")))
for (i in 1:length(paths)) {
load(paths[i], envir = envdir, verbose = verbose)
}
}
4。结果
所以现在您可以访问 默认情况下可用的新版本数据集和出于兼容性原因需要的旧版本 。如果使用旧数据，则会显示 正确的弃用消息 。
# The current version
head(my_data, 3)
# A tibble: 3 x 2
categ val
<fct> <int>
1 a 9
2 a 6
3 a 4
# Activation of the legacy mode
legacy_mode()
# Loading objects:
# my_data
# Warning message:
# This function replaces datasets with the previous (legacy) version for # compatibility reason
# Legacy version
head(my_data, 3)
# A tibble: 3 x 2
# cat val
# <fct> <int>
# 1 a 9
# 2 c 2
# 3 b 3
不要忘记通过更新 R/my_data.R 中的数据集文档来记录您的更改。您可以在备注中提及 legacy 模式.
注意：我还写了一篇关于这个主题的文章blog post，内容稍多一些。
初稿
1。重命名已弃用的数据
objective是将之前的数据移动到一个名为dep_的文件中。然后新数据将替换它。
# Moving the deprecated data prefixed with dep_
dep_my_data <- my_data
usethis::use_data(dep_my_data)
# Overwriting data with the new version of the dataset
my_data <- new_data
usethis::use_data(my_data, overwrite = TRUE)
2。在文档中声明弃用
#' MyData package
#'
#' Note: this dataset is the new version. If you want to use the old one for compatibility reason,
#' please use instead \code{\link{dep_my_data}}.
#'
#' @docType data
#'
#' @rdname dep_my_data
"mydata"
#' [Deprecated] MyData package
#'
#' Note: this dataset still exist but will be removed (defunct) in the next version.
#' Please use instead \code{\link{my_data}}.
#'
#' @docType data
#'
#' @rdname dep_my_data
"dep_mydata"
3。结果
> data()
# dep_mydata [Deprecated] MyData package
# mydata MyData package
在我的一个 R 包中，我有一些愚蠢的示例数据，我想将其删除。为此，我想按照常见的方式先弃用它，然后再取消它。
为了从 R 包中删除函数，我找到了这样的方法：
oldFunc <- function()
{
.Deprecated("newFunc")
}
其次是（比方说 6 个月）
oldFunc <- function()
{
.Defunct("newFunc")
}
再过 6 个月后，我可以从包中删除该功能。
但是，如何删除包中存储为 /data/myData.rda 并且还有一些 myData.Rd 描述的数据对象？
除了使用 .Deprecated 和 .Defunct 你还应该
- 从
data/中删除数据集。用户可以从 CRAN 获取存档版本
- 在NEWS/CHANGELOG 中添加备注
为了对以后的读者有所帮助，答案是对原问题下评论的总结。
好问题，遗憾的是我没有找到答案。
因此，我将分享我为解决此案而起草的内容。我知道它并不完美，但我希望它会有用和/或改进。
更新
所以在完成初稿（见下文）之后，我应用了一个看起来合理且足够好的解决方案的过程。
1。移动数据文件
第一步是将数据文件从其默认位置./data移动到另一个位置以避免其自动加载——即使它是一个懒惰的加载中。
目标位置是 ./data-raw 它是一个目录，按照惯例用于存储脚本和原始数据，以便能够更新或重现导出数据集的生产——更多信息在Data chapter of the book R packages.
我按照惯例使用 leg_ 前缀将其标记为 遗留数据集 。
$ mv ./data/my_data.rda ./data-raw/leg_my_data.rda
2。编写脚本来转换数据集
用于将数据集从旧格式转换为新格式的代码与旧数据集一起存储在./data-raw/my_data.R中。这将使 整个过程可重现 。
# my_data new version
library(tidyverse)
# Load legacy data -----
load("data-raw/leg_my_data.rda")
leg_my_data <- my_data
# Create the new dataset -----
# Perform here every change that has to be performed
my_data <- leg_my_data %>%
rename(cat = categ) %>%
arrange(categ)
# Write the new dataset ----
usethis::use_data(my_data, overwrite = TRUE, compress = 'xz')
源文件，新版本已上线！
source('./data-raw/my_data.R', echo=TRUE)
# ✓ Saving 'my_data' to 'data/my_data.rda'
# ● Document your data (see 'https://r-pkgs.org/data.html')
my_data
# A tibble: 10 x 2
# categ val
# <fct> <int>
# 1 a 9
# 2 a 6
# 3 a 4
3。秘方
在 ./R/my_package-package.R 文件中，创建一个 legacy_mode 函数 。如果用户出于兼容性原因需要使用数据集。
#' Load legacy version of datasets.
#'
#' Load legacy (previous) version of all the datasets for compatibility reason.
#' The environment where data will be loaded can be chosen.
#'
#' @param envdir the environment where the data should be loaded.
#' @param verbose should item names be printed during loading?
#'
#' @export
legacy_mode <- function(envdir = parent.frame(), verbose = TRUE) {
.Deprecated(msg = "This function replaces datasets with the previous (legacy) version for compatibility reason")
# TODO: To be improved to load a subset of datasets
paths <- sort(Sys.glob(c("data-raw/leg_*.rda", "data-raw/leg_*.RData")))
for (i in 1:length(paths)) {
load(paths[i], envir = envdir, verbose = verbose)
}
}
4。结果
所以现在您可以访问 默认情况下可用的新版本数据集和出于兼容性原因需要的旧版本 。如果使用旧数据，则会显示 正确的弃用消息 。
# The current version
head(my_data, 3)
# A tibble: 3 x 2
categ val
<fct> <int>
1 a 9
2 a 6
3 a 4
# Activation of the legacy mode
legacy_mode()
# Loading objects:
# my_data
# Warning message:
# This function replaces datasets with the previous (legacy) version for # compatibility reason
# Legacy version
head(my_data, 3)
# A tibble: 3 x 2
# cat val
# <fct> <int>
# 1 a 9
# 2 c 2
# 3 b 3
不要忘记通过更新 R/my_data.R 中的数据集文档来记录您的更改。您可以在备注中提及 legacy 模式.
注意：我还写了一篇关于这个主题的文章blog post，内容稍多一些。
初稿
1。重命名已弃用的数据
objective是将之前的数据移动到一个名为dep_的文件中。然后新数据将替换它。
# Moving the deprecated data prefixed with dep_
dep_my_data <- my_data
usethis::use_data(dep_my_data)
# Overwriting data with the new version of the dataset
my_data <- new_data
usethis::use_data(my_data, overwrite = TRUE)
2。在文档中声明弃用
#' MyData package
#'
#' Note: this dataset is the new version. If you want to use the old one for compatibility reason,
#' please use instead \code{\link{dep_my_data}}.
#'
#' @docType data
#'
#' @rdname dep_my_data
"mydata"
#' [Deprecated] MyData package
#'
#' Note: this dataset still exist but will be removed (defunct) in the next version.
#' Please use instead \code{\link{my_data}}.
#'
#' @docType data
#'
#' @rdname dep_my_data
"dep_mydata"
3。结果
> data()
# dep_mydata [Deprecated] MyData package
# mydata MyData package