11

In one of my R-packages I have some silly example data that I would like to remove. For that I'd like to follow the common way first to deprecate and then defunct it.

For removing functions from an R-package I found a way like this:

oldFunc <- function()
{
    .Deprecated("newFunc")
}

followed by (lets say 6 months)

oldFunc <- function()
{
    .Defunct("newFunc")
}

And then after another 6 months I could delete the function from the package.

However, how to remove a data object stored as /data/myData.rda in the package and that has also some myData.Rd description?

0

3 Answers 3

2

Good question, unfortunately I did not find an answer.
So I'm sharing what I have drafted to solve this case. I know it's not perfect, however I Hope it will be useful and / or improved.

Update

So after a first draft (see below), I've applied a process that seems to be a reasonable--good enough--solution.

1. Move the data file

The first step is to move the data file from its default location ./data to another location in order to avoid its automatic loading--even if it's a lazy loading.

The target location is ./data-raw it's a directory that is used by convention to store script and raw data in order to be able to update or reproduce the production of the exported dataset--more on that in the Data chapter of the book R packages.

I'm using by convention a leg_ prefix to flag it as a legacy dataset.

$ mv ./data/my_data.rda ./data-raw/leg_my_data.rda

2. Write a script to transform the dataset

The code used to transform the dataset from its legacy to its new format is stored along with the legacy dataset in ./data-raw/my_data.R. This will make the whole process reproducible.

# 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 the file and you're good the new version is live!

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. Secret sauce

In the ./R/my_package-package.R file, create a legacy_mode function. This function will be a way for the users to load the previous (legacy) version of the datasets if they need to use them for compatibility reason.

#' 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. Result

And so now you have access to both the new version of the dataset available by default and the legacy version if needed for compatibility reasons. If the legacy data is used, a proper deprecation message is displayed.

# 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

Do not forget to document your changes by updating the dataset documentation in R/my_data.R. You can mention in a note the legacy mode.

Note: I've also written a blog post on this topic with a little more content.

First draft

1. Rename the deprecated data

The objective is to move the previous data to a file called prefixed with dep_. The new data will then replace it.

# 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. Declare deprecation in the documentation

#' 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. Result

> data()

# dep_mydata   [Deprecated] MyData package
# mydata       MyData package
2
  • I think this answer contains a better guide on how to handle this situation, hence, I changed the accepted answer to this one here. Apr 12, 2020 at 14:49
  • @DanielFischer thank you, appreciate. However I still do not think it's the best way to go. This is not a conservative procedure. There is an alternative that could be to make the contrary, define a new dataset and leave the old unchanged. I will update my answer by mentioning both approach.
    – Romain
    Apr 12, 2020 at 15:41
2

I still think there’s a better solution: using delayedAssign().

This Bioconductor page explains it very well:

25.4.1 Step 1 - Save a promise object

The initial step of deprecating a dataset is to signal to any users on the devel branch of Bioconductor that the dataset will no longer be used. This can be done using a warning message when the devel user loads the dataset. In order to do this, we first create a promise object with the same name as the dataset name using the delayedAssign function:

delayedAssign(
    x = "pkgDataset",
    value = {
        warning("'pkgDataset' dataset is deprecated; see '?newData'")
        pkgDataset
    }
)

You can also include the dataset as an output after the warning. We then replace the original .Rda dataset file in the package with the promise object and dataset using the save function:

save("pkgDataset", eval.promises = FALSE, file = "data/pkgDataset.Rda")

With the eval.promises argument set to FALSE, we can delay the evaluation of the promise object until the user loads the data with data("pkgDataset", package = "yourPkg"). The user will then get a warning along with the dataset. The warning should include instructions that will point the user to a new dataset or functionality that will replace the data, if necessary.

You can read the manual of delayedAssign() here.

1

In addition to using .Deprecated and .Defunct you should also

  • remove the data set from data/. Users can obtain archived versions from CRAN
  • add a note in the NEWS/CHANGELOG

To be helpful for future readers, the answer is a summary of comments under the original question.

2
  • Accepted this answer also to make it easier for future readers to find the answer. Apr 7, 2017 at 7:55
  • 4
    The NEWS suggestion is good, but how could you use .Deprecated or .Defunct for a dataset, which has no function where you could place those calls?
    – pangia
    Jul 28, 2017 at 17:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.