diff --git a/DESCRIPTION b/DESCRIPTION index 878886e..a1539ae 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -7,7 +7,7 @@ Authors@R: c( person("Hugo", "Gruson", , "hugo@data.org", role = "rev", comment = c(ORCID = "0000-0002-4094-1476")) ) -Description: Provides tools to help label and validate data according to user-specified rules. The 'safeframe' class adds variable level attributes to 'data.frame' columns. Once labelled, these variables can be seamlessly used in downstream analyses, making data pipelines clearer, more robust, and more reliable. +Description: Provides tools to help label and validate data according to user-specified rules. The 'safeframe' class adds variable level attributes to 'data.frame' columns. Once tagged, these variables can be seamlessly used in downstream analyses, making data pipelines clearer, more robust, and more reliable. License: MIT + file LICENSE URL: https://epiverse-trace.github.io/safeframe/, https://github.com/epiverse-trace/safeframe BugReports: https://github.com/epiverse-trace/safeframe/issues diff --git a/R/labels_df.R b/R/labels_df.R index 2d9aae9..ac12adc 100644 --- a/R/labels_df.R +++ b/R/labels_df.R @@ -1,6 +1,6 @@ -#' Extract a data.frame of all labelled variables +#' Extract a data.frame of all tagged variables #' -#' This function returns a `data.frame`, where labelled variables (as stored in +#' This function returns a `data.frame`, where tagged variables (as stored in #' the `safeframe` object) are renamed. Note that the output is no longer a #' `safeframe`, but a regular `data.frame`. Unlabeled variables are unaffected. #' diff --git a/R/lost_labels.R b/R/lost_labels.R index fa18680..ab8f583 100644 --- a/R/lost_labels.R +++ b/R/lost_labels.R @@ -18,7 +18,7 @@ lost_labels <- function(old, new, lost_action) { lost_msg <- vars_labels(lost_vars, lost_labels) msg <- paste( - "The following labelled variables are lost:\n", + "The following tagged variables are lost:\n", lost_msg ) if (lost_action == "warning") { diff --git a/R/lost_labels_action.R b/R/lost_labels_action.R index fa0b01b..119b464 100644 --- a/R/lost_labels_action.R +++ b/R/lost_labels_action.R @@ -1,10 +1,10 @@ #' Check and set behaviour for lost labels #' -#' This function determines the behaviour to adopt when labelled variables of a +#' This function determines the behaviour to adopt when tagged variables of a #' `safeframe` are lost for example through subsetting. This is achieved using #' `options` defined for the `safeframe` package. #' -#' @param action a `character` indicating the behaviour to adopt when labelled +#' @param action a `character` indicating the behaviour to adopt when tagged #' variables have been lost: "error" (default) will issue an error; "warning" #' will issue a warning; "none" will do nothing #' @@ -13,7 +13,7 @@ #' #' @return returns `NULL`; the option itself is set in `options("safeframe")` #' -#' @details The errors or warnings generated by safeframe in case of labelled +#' @details The errors or warnings generated by safeframe in case of tagged #' variable loss has a custom class of `safeframe_error` and `safeframe_warning` #' respectively. #' diff --git a/R/make_safeframe.R b/R/make_safeframe.R index 23710c5..b6ac4a2 100644 --- a/R/make_safeframe.R +++ b/R/make_safeframe.R @@ -1,9 +1,9 @@ #' Create a safeframe from a data.frame #' #' This function converts a `data.frame` or a `tibble` into a `safeframe` -#' object, where data are labelled and validated. The output will seem to be the +#' object, where data are tagged and validated. The output will seem to be the #' same `data.frame`, but `safeframe`-aware packages will then be able to -#' automatically use labelled fields for further data cleaning and analysis. +#' automatically use tagged fields for further data cleaning and analysis. #' #' @param x a `data.frame` or a `tibble` #' @@ -15,7 +15,7 @@ #' @seealso #' #' * An overview of the [safeframe] package -#' * [labels()]: for a list of labelled variables in a `safeframe` +#' * [labels()]: for a list of tagged variables in a `safeframe` #' * [set_labels()]: for modifying labels #' * [labels_df()]: for selecting variables by labels #' diff --git a/R/names.R b/R/names.R index 0591d5c..1fe896a 100644 --- a/R/names.R +++ b/R/names.R @@ -41,7 +41,7 @@ # variable names. We do this by: # 1. Storing old names and new names to have define replacement rules - # 2. Replace all labelled variables using the replacement rules + # 2. Replace all tagged variables using the replacement rules out <- drop_safeframe(x) names(out) <- value diff --git a/R/print.safeframe.R b/R/print.safeframe.R index b1c8d34..727720b 100644 --- a/R/print.safeframe.R +++ b/R/print.safeframe.R @@ -41,9 +41,9 @@ print.safeframe <- function(x, ...) { labels_txt <- vars_labels(label_names, label_values) if (labels_txt == "") { - cat("\n[no labelled variables]\n") + cat("\n[no tagged variables]\n") } else { - cat("\nlabelled variables:\n", labels_txt, "\n") + cat("\ntagged variables:\n", labels_txt, "\n") } invisible(x) diff --git a/R/restore_labels.R b/R/restore_labels.R index 09022dc..3cd90a9 100644 --- a/R/restore_labels.R +++ b/R/restore_labels.R @@ -2,7 +2,7 @@ #' #' Internal. This function is used to restore labels of a `safeframe` object #' which may have lost its labels after handling for example through `dplyr` -#' verbs. Specific actions can be triggered when some of the labelled variables +#' verbs. Specific actions can be triggered when some of the tagged variables #' have disappeared from the object. #' #' @param x a `data.frame` @@ -12,7 +12,7 @@ #' names with `x` to restore labels. Throws an error if no matches are found. #' #' @param lost_action a `character` indicating the behaviour to adopt when -#' labelled variables have been lost: "error" (default) will issue an error; +#' tagged variables have been lost: "error" (default) will issue an error; #' "warning" will issue a warning; "none" will do nothing #' #' @noRd @@ -40,7 +40,7 @@ restore_labels <- function(x, newLabels, lost_msg <- vars_labels(lost_vars, lost_labels) msg <- paste( - "The following labelled variables are lost:\n", + "The following tagged variables are lost:\n", lost_msg ) if (lost_action == "warning") { diff --git a/R/safeframe-package.R b/R/safeframe-package.R index 6f28309..5d96317 100644 --- a/R/safeframe-package.R +++ b/R/safeframe-package.R @@ -2,7 +2,7 @@ #' #' The \pkg{safeframe} package provides tools to help label and validate data. #' The 'safeframe' class adds column level attributes to a 'data.frame'. -#' Once labelled, variables can be seamlessly used in downstream analyses, +#' Once tagged, variables can be seamlessly used in downstream analyses, #' making data pipelines more robust and reliable. #' #' @aliases safeframe @@ -12,31 +12,31 @@ #' * [make_safeframe()]: to create `safeframe` objects from a `data.frame` or #' a `tibble` #' -#' * [set_labels()]: to change or add labelled variables in a `safeframe` +#' * [set_labels()]: to change or add tagged variables in a `safeframe` #' #' * [labels()]: to get the list of labels of a `safeframe` #' #' * [labels_df()]: to get a `data.frame` of all tagged variables #' -#' * [lost_labels_action()]: to change the behaviour of actions where labelled -#' variables are lost (e.g removing columns storing labelled variables) to +#' * [lost_labels_action()]: to change the behaviour of actions where tagged +#' variables are lost (e.g removing columns storing tagged variables) to #' issue warnings, errors, or do nothing #' #' * [get_lost_labels_action()]: to check the current behaviour of actions -#' where labelled variables are lost +#' where tagged variables are lost #' #' @section Dedicated methods: #' #' Specific methods commonly used to handle `data.frame` are provided for #' `safeframe` objects, typically to help flag or prevent actions which could -#' alter or lose labelled variables (and may thus break downstream data +#' alter or lose tagged variables (and may thus break downstream data #' pipelines). #' #' * `names() <-` (and related functions, such as [dplyr::rename()]) will #' rename labels as needed #' #' * `x[...] <-` and `x[[...]] <-` (see [sub_safeframe]): will adopt the -#' desired behaviour when labelled variables are lost +#' desired behaviour when tagged variables are lost #' #' * `print()`: prints info about the `safeframe` in addition to the #' `data.frame` or `tibble` @@ -54,7 +54,7 @@ #' ) #' x #' -#' ## check labelled variables +#' ## check tagged variables #' labels(x) #' #' ## robust renaming @@ -92,7 +92,7 @@ #' #' head(x) #' -#' ## extract labelled variables +#' ## extract tagged variables #' x %>% #' select(has_label(c("Ticket yes/no"))) #' diff --git a/R/square_bracket.R b/R/square_bracket.R index 446ffb3..3482caf 100644 --- a/R/square_bracket.R +++ b/R/square_bracket.R @@ -1,7 +1,7 @@ #' Subsetting of safeframe objects #' #' The `[]` and `[[]]` operators for `safeframe` objects behaves like for -#' regular `data.frame` or `tibble`, but check that labelled variables are not +#' regular `data.frame` or `tibble`, but check that tagged variables are not #' lost, and takes the appropriate action if this is the case (warning, error, #' or ignore, depending on the general option set via [lost_labels_action()]) . #' @@ -41,7 +41,7 @@ #' set_labels(result = "Ticket") #' x #' -#' ## dangerous removal of a labelled column setting it to NULL issues warning +#' ## dangerous removal of a tagged column setting it to NULL issues warning #' x[, 1] <- NULL #' x #' @@ -60,7 +60,7 @@ # 1. that the subsetted object is still a `data.frame` or a `tibble`; if not, # we automatically drop the `safeframe` class and tags # 2. if the output is going to be a `safeframe` we need to restore previous - # labels with the appropriate behaviour in case of missing labelled variables + # labels with the appropriate behaviour in case of missing tagged variables # # Note that the [ operator's implementation is messy and does not seem to pass # the drop argument well when using NextMethod(); also it does not allow extra diff --git a/R/validate_labels.R b/R/validate_labels.R index 4dbc67c..f56a56f 100644 --- a/R/validate_labels.R +++ b/R/validate_labels.R @@ -10,7 +10,7 @@ #' #' @return If checks pass, a `safeframe` object; otherwise issues an error. #' -#' @seealso [validate_types()] to check if labelled variables have +#' @seealso [validate_types()] to check if tagged variables have #' the right classes #' #' @examples diff --git a/man/labels_df.Rd b/man/labels_df.Rd index be9ea07..f0e69ed 100644 --- a/man/labels_df.Rd +++ b/man/labels_df.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/labels_df.R \name{labels_df} \alias{labels_df} -\title{Extract a data.frame of all labelled variables} +\title{Extract a data.frame of all tagged variables} \usage{ labels_df(x) } @@ -13,7 +13,7 @@ labels_df(x) A \code{data.frame} of with variables renamed according to their labels. } \description{ -This function returns a \code{data.frame}, where labelled variables (as stored in +This function returns a \code{data.frame}, where tagged variables (as stored in the \code{safeframe} object) are renamed. Note that the output is no longer a \code{safeframe}, but a regular \code{data.frame}. Unlabeled variables are unaffected. } diff --git a/man/lost_labels_action.Rd b/man/lost_labels_action.Rd index 8c90f06..a60b70c 100644 --- a/man/lost_labels_action.Rd +++ b/man/lost_labels_action.Rd @@ -10,7 +10,7 @@ lost_labels_action(action = c("warning", "error", "none"), quiet = FALSE) get_lost_labels_action() } \arguments{ -\item{action}{a \code{character} indicating the behaviour to adopt when labelled +\item{action}{a \code{character} indicating the behaviour to adopt when tagged variables have been lost: "error" (default) will issue an error; "warning" will issue a warning; "none" will do nothing} @@ -21,12 +21,12 @@ used outside pipelines} returns \code{NULL}; the option itself is set in \code{options("safeframe")} } \description{ -This function determines the behaviour to adopt when labelled variables of a +This function determines the behaviour to adopt when tagged variables of a \code{safeframe} are lost for example through subsetting. This is achieved using \code{options} defined for the \code{safeframe} package. } \details{ -The errors or warnings generated by safeframe in case of labelled +The errors or warnings generated by safeframe in case of tagged variable loss has a custom class of \code{safeframe_error} and \code{safeframe_warning} respectively. } diff --git a/man/make_safeframe.Rd b/man/make_safeframe.Rd index c157b28..6f3b5f9 100644 --- a/man/make_safeframe.Rd +++ b/man/make_safeframe.Rd @@ -19,9 +19,9 @@ The function returns a \code{safeframe} object. } \description{ This function converts a \code{data.frame} or a \code{tibble} into a \code{safeframe} -object, where data are labelled and validated. The output will seem to be the +object, where data are tagged and validated. The output will seem to be the same \code{data.frame}, but \code{safeframe}-aware packages will then be able to -automatically use labelled fields for further data cleaning and analysis. +automatically use tagged fields for further data cleaning and analysis. } \examples{ @@ -50,7 +50,7 @@ identical(x, new_x) \seealso{ \itemize{ \item An overview of the \link{safeframe} package -\item \code{\link[=labels]{labels()}}: for a list of labelled variables in a \code{safeframe} +\item \code{\link[=labels]{labels()}}: for a list of tagged variables in a \code{safeframe} \item \code{\link[=set_labels]{set_labels()}}: for modifying labels \item \code{\link[=labels_df]{labels_df()}}: for selecting variables by labels } diff --git a/man/safeframe-package.Rd b/man/safeframe-package.Rd index 5cd0e9e..3001b19 100644 --- a/man/safeframe-package.Rd +++ b/man/safeframe-package.Rd @@ -8,7 +8,7 @@ \description{ The \pkg{safeframe} package provides tools to help label and validate data. The 'safeframe' class adds column level attributes to a 'data.frame'. -Once labelled, variables can be seamlessly used in downstream analyses, +Once tagged, variables can be seamlessly used in downstream analyses, making data pipelines more robust and reliable. } \note{ @@ -21,14 +21,14 @@ not preserve labels. We only provide compatibility for \code{\link[dplyr:rename] \itemize{ \item \code{\link[=make_safeframe]{make_safeframe()}}: to create \code{safeframe} objects from a \code{data.frame} or a \code{tibble} -\item \code{\link[=set_labels]{set_labels()}}: to change or add labelled variables in a \code{safeframe} +\item \code{\link[=set_labels]{set_labels()}}: to change or add tagged variables in a \code{safeframe} \item \code{\link[=labels]{labels()}}: to get the list of labels of a \code{safeframe} \item \code{\link[=labels_df]{labels_df()}}: to get a \code{data.frame} of all tagged variables -\item \code{\link[=lost_labels_action]{lost_labels_action()}}: to change the behaviour of actions where labelled -variables are lost (e.g removing columns storing labelled variables) to +\item \code{\link[=lost_labels_action]{lost_labels_action()}}: to change the behaviour of actions where tagged +variables are lost (e.g removing columns storing tagged variables) to issue warnings, errors, or do nothing \item \code{\link[=get_lost_labels_action]{get_lost_labels_action()}}: to check the current behaviour of actions -where labelled variables are lost +where tagged variables are lost } } @@ -37,13 +37,13 @@ where labelled variables are lost Specific methods commonly used to handle \code{data.frame} are provided for \code{safeframe} objects, typically to help flag or prevent actions which could -alter or lose labelled variables (and may thus break downstream data +alter or lose tagged variables (and may thus break downstream data pipelines). \itemize{ \item \verb{names() <-} (and related functions, such as \code{\link[dplyr:rename]{dplyr::rename()}}) will rename labels as needed \item \verb{x[...] <-} and \verb{x[[...]] <-} (see \link{sub_safeframe}): will adopt the -desired behaviour when labelled variables are lost +desired behaviour when tagged variables are lost \item \code{print()}: prints info about the \code{safeframe} in addition to the \code{data.frame} or \code{tibble} } @@ -58,7 +58,7 @@ x <- make_safeframe(cars[1:50, ], ) x -## check labelled variables +## check tagged variables labels(x) ## robust renaming @@ -96,7 +96,7 @@ if (require(dplyr) && require(magrittr)) { head(x) - ## extract labelled variables + ## extract tagged variables x \%>\% select(has_label(c("Ticket yes/no"))) diff --git a/man/sub_safeframe.Rd b/man/sub_safeframe.Rd index ef3103a..f2a6ef1 100644 --- a/man/sub_safeframe.Rd +++ b/man/sub_safeframe.Rd @@ -43,7 +43,7 @@ If no drop is happening, a \code{safeframe}. Otherwise an atomic vector. } \description{ The \verb{[]} and \verb{[[]]} operators for \code{safeframe} objects behaves like for -regular \code{data.frame} or \code{tibble}, but check that labelled variables are not +regular \code{data.frame} or \code{tibble}, but check that tagged variables are not lost, and takes the appropriate action if this is the case (warning, error, or ignore, depending on the general option set via \code{\link[=lost_labels_action]{lost_labels_action()}}) . } @@ -59,7 +59,7 @@ if (require(dplyr) && require(magrittr)) { set_labels(result = "Ticket") x - ## dangerous removal of a labelled column setting it to NULL issues warning + ## dangerous removal of a tagged column setting it to NULL issues warning x[, 1] <- NULL x diff --git a/man/validate_labels.Rd b/man/validate_labels.Rd index 67357f1..5dbe705 100644 --- a/man/validate_labels.Rd +++ b/man/validate_labels.Rd @@ -37,6 +37,6 @@ validate_safeframe(x, ) } \seealso{ -\code{\link[=validate_types]{validate_types()}} to check if labelled variables have +\code{\link[=validate_types]{validate_types()}} to check if tagged variables have the right classes } diff --git a/safeframe.Rproj b/safeframe.Rproj index 21a4da0..8bd744a 100644 --- a/safeframe.Rproj +++ b/safeframe.Rproj @@ -1,4 +1,5 @@ Version: 1.0 +ProjectId: 931e7392-5867-454d-a913-e44cba1a06dd RestoreWorkspace: Default SaveWorkspace: Default diff --git a/tests/testthat/_snaps/compat-dplyr.md b/tests/testthat/_snaps/compat-dplyr.md index b1217f8..5caa827 100644 --- a/tests/testthat/_snaps/compat-dplyr.md +++ b/tests/testthat/_snaps/compat-dplyr.md @@ -1,16 +1,16 @@ # Compatibility with dplyr::transmute() - The following labelled variables are lost: + The following tagged variables are lost: speed - Miles per hour dist - Distance in miles # Compatibility with dplyr::mutate(.keep) - The following labelled variables are lost: + The following tagged variables are lost: speed - Miles per hour # Compatibility with dplyr::select() - The following labelled variables are lost: + The following tagged variables are lost: speed - Miles per hour diff --git a/tests/testthat/_snaps/print.md b/tests/testthat/_snaps/print.md index 62e1460..fe64718 100644 --- a/tests/testthat/_snaps/print.md +++ b/tests/testthat/_snaps/print.md @@ -54,7 +54,7 @@ 49 24 120 50 25 85 - labelled variables: + tagged variables: speed - Miles per hour dist - Distance in miles @@ -114,5 +114,5 @@ 49 24 120 50 25 85 - [no labelled variables] + [no tagged variables] diff --git a/tests/testthat/_snaps/square_bracket.md b/tests/testthat/_snaps/square_bracket.md index c1987fb..670d7b2 100644 --- a/tests/testthat/_snaps/square_bracket.md +++ b/tests/testthat/_snaps/square_bracket.md @@ -1,10 +1,10 @@ # tests for [[<- operator - The following labelled variables are lost: + The following tagged variables are lost: speed - Miles per hour --- - The following labelled variables are lost: + The following tagged variables are lost: speed - Miles per hour diff --git a/tests/testthat/test-square_bracket.R b/tests/testthat/test-square_bracket.R index 0183dcd..a0c4db7 100644 --- a/tests/testthat/test-square_bracket.R +++ b/tests/testthat/test-square_bracket.R @@ -6,15 +6,15 @@ test_that("tests for [ operator", { # errors lost_labels_action("warning", quiet = TRUE) - msg <- "The following labelled variables are lost:\n dist - Distance in miles" + msg <- "The following tagged variables are lost:\n dist - Distance in miles" expect_warning(x[, 1], msg) lost_labels_action("error", quiet = TRUE) - msg <- "The following labelled variables are lost:\n dist - Distance in miles" + msg <- "The following tagged variables are lost:\n dist - Distance in miles" expect_error(x[, 1], msg) lost_labels_action("warning", quiet = TRUE) - msg <- "The following labelled variables are lost:\n speed - Miles per hour\n dist - Distance in miles" + msg <- "The following tagged variables are lost:\n speed - Miles per hour\n dist - Distance in miles" expect_warning(x[, NULL], msg) # functionalities @@ -60,12 +60,12 @@ test_that("tests for [<- operator", { # errors lost_labels_action("warning", quiet = TRUE) x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") - msg <- "The following labelled variables are lost:\n speed - Miles per hour" + msg <- "The following tagged variables are lost:\n speed - Miles per hour" expect_warning(x[, 1] <- NULL, msg) lost_labels_action("error", quiet = TRUE) x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") - msg <- "The following labelled variables are lost:\n speed - Miles per hour" + msg <- "The following tagged variables are lost:\n speed - Miles per hour" expect_error(x[, 1] <- NULL, msg) # functionalities @@ -138,12 +138,12 @@ test_that("$<- operator detects label loss", { # errors lost_labels_action("warning", quiet = TRUE) x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") - msg <- "The following labelled variables are lost:\n speed - Miles per hour" + msg <- "The following tagged variables are lost:\n speed - Miles per hour" expect_warning(x$speed <- NULL, msg) lost_labels_action("error", quiet = TRUE) x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") - msg <- "The following labelled variables are lost:\n speed - Miles per hour" + msg <- "The following tagged variables are lost:\n speed - Miles per hour" expect_error(x$speed <- NULL, msg) lost_labels_action("none", quiet = TRUE) @@ -161,7 +161,7 @@ test_that("$<- allows innocuous label modification", { expect_identical(x$speed, y) }) -test_that("no warnings when unlabelled columns are dropped - #55", { +test_that("no warnings when untagged columns are dropped - #55", { x <- make_safeframe(cars, speed = "Miles per hour" ) diff --git a/vignettes/compat-dplyr.Rmd b/vignettes/compat-dplyr.Rmd index 41a89ff..d5cf64a 100644 --- a/vignettes/compat-dplyr.Rmd +++ b/vignettes/compat-dplyr.Rmd @@ -86,8 +86,8 @@ x %>% During operations on columns, safeframe will: -- stay invisible and conserve labels if no labelled column is affected by the operation -- trigger `lost_labels_action()` if labelled columns are affected by the operation +- stay invisible and conserve labels if no tagged column is affected by the operation +- trigger `lost_labels_action()` if tagged columns are affected by the operation ### `dplyr::mutate()` ✓ (partial)