diff --git a/CITATION.cff b/CITATION.cff index c0620d1..cf43b0f 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -2,254 +2,254 @@ # CITATION file created with {cffr} R package # See also: https://docs.ropensci.org/cffr/ # -------------------------------------------- - + cff-version: 1.2.0 -message: 'To cite package "datatagr" in publications use:' +message: 'To cite package "safeframe" in publications use:' type: software license: MIT -title: 'datatagr: Generic Data Labelling and Validating' +title: "safeframe: Generic Data Labelling and Validating" version: 0.0.1 -abstract: Provides tools to help label and validate data according to user-specified - rules. The 'datatagr' class adds variable level attributes to 'data.frame' columns. +abstract: + 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. authors: -- family-names: Hartgerink - given-names: Chris - email: chris@data.org - orcid: https://orcid.org/0000-0003-1050-6809 -repository-code: https://github.com/epiverse-trace/datatagr -url: https://epiverse-trace.github.io/datatagr/ + - family-names: Hartgerink + given-names: Chris + email: chris@data.org + orcid: https://orcid.org/0000-0003-1050-6809 +repository-code: https://github.com/epiverse-trace/safeframe +url: https://epiverse-trace.github.io/safeframe/ contact: -- family-names: Hartgerink - given-names: Chris - email: chris@data.org - orcid: https://orcid.org/0000-0003-1050-6809 + - family-names: Hartgerink + given-names: Chris + email: chris@data.org + orcid: https://orcid.org/0000-0003-1050-6809 references: -- type: software - title: 'R: A Language and Environment for Statistical Computing' - notes: Depends - url: https://www.R-project.org/ - authors: - - name: R Core Team - institution: - name: R Foundation for Statistical Computing - address: Vienna, Austria - year: '2024' - version: '>= 3.1.0' -- type: software - title: checkmate - abstract: 'checkmate: Fast and Versatile Argument Checks' - notes: Imports - url: https://mllg.github.io/checkmate/ - repository: https://CRAN.R-project.org/package=checkmate - authors: - - family-names: Lang - given-names: Michel - email: michellang@gmail.com - orcid: https://orcid.org/0000-0001-9754-0393 - year: '2024' - doi: 10.32614/CRAN.package.checkmate -- type: software - title: lifecycle - abstract: 'lifecycle: Manage the Life Cycle of your Package Functions' - notes: Imports - url: https://lifecycle.r-lib.org/ - repository: https://CRAN.R-project.org/package=lifecycle - authors: - - family-names: Henry - given-names: Lionel - email: lionel@posit.co - - family-names: Wickham - given-names: Hadley - email: hadley@posit.co - orcid: https://orcid.org/0000-0003-4757-117X - year: '2024' - doi: 10.32614/CRAN.package.lifecycle -- type: software - title: rlang - abstract: 'rlang: Functions for Base Types and Core R and ''Tidyverse'' Features' - notes: Imports - url: https://rlang.r-lib.org - repository: https://CRAN.R-project.org/package=rlang - authors: - - family-names: Henry - given-names: Lionel - email: lionel@posit.co - - family-names: Wickham - given-names: Hadley - email: hadley@posit.co - year: '2024' - doi: 10.32614/CRAN.package.rlang -- type: software - title: tidyselect - abstract: 'tidyselect: Select from a Set of Strings' - notes: Imports - url: https://tidyselect.r-lib.org - repository: https://CRAN.R-project.org/package=tidyselect - authors: - - family-names: Henry - given-names: Lionel - email: lionel@posit.co - - family-names: Wickham - given-names: Hadley - email: hadley@posit.co - year: '2024' - doi: 10.32614/CRAN.package.tidyselect -- type: software - title: callr - abstract: 'callr: Call R from R' - notes: Suggests - url: https://callr.r-lib.org - repository: https://CRAN.R-project.org/package=callr - authors: - - family-names: Csárdi - given-names: Gábor - email: csardi.gabor@gmail.com - orcid: https://orcid.org/0000-0001-7098-9676 - - family-names: Chang - given-names: Winston - year: '2024' - doi: 10.32614/CRAN.package.callr -- type: software - title: dplyr - abstract: 'dplyr: A Grammar of Data Manipulation' - notes: Suggests - url: https://dplyr.tidyverse.org - repository: https://CRAN.R-project.org/package=dplyr - authors: - - family-names: Wickham - given-names: Hadley - email: hadley@posit.co - orcid: https://orcid.org/0000-0003-4757-117X - - family-names: François - given-names: Romain - orcid: https://orcid.org/0000-0002-2444-4226 - - family-names: Henry - given-names: Lionel - - family-names: Müller - given-names: Kirill - orcid: https://orcid.org/0000-0002-1416-3412 - - family-names: Vaughan - given-names: Davis - email: davis@posit.co - orcid: https://orcid.org/0000-0003-4777-038X - year: '2024' - doi: 10.32614/CRAN.package.dplyr -- type: software - title: knitr - abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R' - notes: Suggests - url: https://yihui.org/knitr/ - repository: https://CRAN.R-project.org/package=knitr - authors: - - family-names: Xie - given-names: Yihui - email: xie@yihui.name - orcid: https://orcid.org/0000-0003-0645-5666 - year: '2024' - doi: 10.32614/CRAN.package.knitr -- type: software - title: magrittr - abstract: 'magrittr: A Forward-Pipe Operator for R' - notes: Suggests - url: https://magrittr.tidyverse.org - repository: https://CRAN.R-project.org/package=magrittr - authors: - - family-names: Bache - given-names: Stefan Milton - email: stefan@stefanbache.dk - - family-names: Wickham - given-names: Hadley - email: hadley@rstudio.com - year: '2024' - doi: 10.32614/CRAN.package.magrittr -- type: software - title: rmarkdown - abstract: 'rmarkdown: Dynamic Documents for R' - notes: Suggests - url: https://pkgs.rstudio.com/rmarkdown/ - repository: https://CRAN.R-project.org/package=rmarkdown - authors: - - family-names: Allaire - given-names: JJ - email: jj@posit.co - - family-names: Xie - given-names: Yihui - email: xie@yihui.name - orcid: https://orcid.org/0000-0003-0645-5666 - - family-names: Dervieux - given-names: Christophe - email: cderv@posit.co - orcid: https://orcid.org/0000-0003-4474-2498 - - family-names: McPherson - given-names: Jonathan - email: jonathan@posit.co - - family-names: Luraschi - given-names: Javier - - family-names: Ushey - given-names: Kevin - email: kevin@posit.co - - family-names: Atkins - given-names: Aron - email: aron@posit.co - - family-names: Wickham - given-names: Hadley - email: hadley@posit.co - - family-names: Cheng - given-names: Joe - email: joe@posit.co - - family-names: Chang - given-names: Winston - email: winston@posit.co - - family-names: Iannone - given-names: Richard - email: rich@posit.co - orcid: https://orcid.org/0000-0003-3925-190X - year: '2024' - doi: 10.32614/CRAN.package.rmarkdown -- type: software - title: spelling - abstract: 'spelling: Tools for Spell Checking in R' - notes: Suggests - url: https://ropensci.r-universe.dev/spelling - repository: https://CRAN.R-project.org/package=spelling - authors: - - family-names: Ooms - given-names: Jeroen - email: jeroen@berkeley.edu - orcid: https://orcid.org/0000-0002-4035-0289 - - family-names: Hester - given-names: Jim - email: james.hester@rstudio.com - year: '2024' - doi: 10.32614/CRAN.package.spelling -- type: software - title: testthat - abstract: 'testthat: Unit Testing for R' - notes: Suggests - url: https://testthat.r-lib.org - repository: https://CRAN.R-project.org/package=testthat - authors: - - family-names: Wickham - given-names: Hadley - email: hadley@posit.co - year: '2024' - doi: 10.32614/CRAN.package.testthat -- type: software - title: tibble - abstract: 'tibble: Simple Data Frames' - notes: Suggests - url: https://tibble.tidyverse.org/ - repository: https://CRAN.R-project.org/package=tibble - authors: - - family-names: Müller - given-names: Kirill - email: kirill@cynkra.com - orcid: https://orcid.org/0000-0002-1416-3412 - - family-names: Wickham - given-names: Hadley - email: hadley@rstudio.com - year: '2024' - doi: 10.32614/CRAN.package.tibble - + - type: software + title: "R: A Language and Environment for Statistical Computing" + notes: Depends + url: https://www.R-project.org/ + authors: + - name: R Core Team + institution: + name: R Foundation for Statistical Computing + address: Vienna, Austria + year: "2024" + version: ">= 3.1.0" + - type: software + title: checkmate + abstract: "checkmate: Fast and Versatile Argument Checks" + notes: Imports + url: https://mllg.github.io/checkmate/ + repository: https://CRAN.R-project.org/package=checkmate + authors: + - family-names: Lang + given-names: Michel + email: michellang@gmail.com + orcid: https://orcid.org/0000-0001-9754-0393 + year: "2024" + doi: 10.32614/CRAN.package.checkmate + - type: software + title: lifecycle + abstract: "lifecycle: Manage the Life Cycle of your Package Functions" + notes: Imports + url: https://lifecycle.r-lib.org/ + repository: https://CRAN.R-project.org/package=lifecycle + authors: + - family-names: Henry + given-names: Lionel + email: lionel@posit.co + - family-names: Wickham + given-names: Hadley + email: hadley@posit.co + orcid: https://orcid.org/0000-0003-4757-117X + year: "2024" + doi: 10.32614/CRAN.package.lifecycle + - type: software + title: rlang + abstract: "rlang: Functions for Base Types and Core R and 'Tidyverse' Features" + notes: Imports + url: https://rlang.r-lib.org + repository: https://CRAN.R-project.org/package=rlang + authors: + - family-names: Henry + given-names: Lionel + email: lionel@posit.co + - family-names: Wickham + given-names: Hadley + email: hadley@posit.co + year: "2024" + doi: 10.32614/CRAN.package.rlang + - type: software + title: tidyselect + abstract: "tidyselect: Select from a Set of Strings" + notes: Imports + url: https://tidyselect.r-lib.org + repository: https://CRAN.R-project.org/package=tidyselect + authors: + - family-names: Henry + given-names: Lionel + email: lionel@posit.co + - family-names: Wickham + given-names: Hadley + email: hadley@posit.co + year: "2024" + doi: 10.32614/CRAN.package.tidyselect + - type: software + title: callr + abstract: "callr: Call R from R" + notes: Suggests + url: https://callr.r-lib.org + repository: https://CRAN.R-project.org/package=callr + authors: + - family-names: Csárdi + given-names: Gábor + email: csardi.gabor@gmail.com + orcid: https://orcid.org/0000-0001-7098-9676 + - family-names: Chang + given-names: Winston + year: "2024" + doi: 10.32614/CRAN.package.callr + - type: software + title: dplyr + abstract: "dplyr: A Grammar of Data Manipulation" + notes: Suggests + url: https://dplyr.tidyverse.org + repository: https://CRAN.R-project.org/package=dplyr + authors: + - family-names: Wickham + given-names: Hadley + email: hadley@posit.co + orcid: https://orcid.org/0000-0003-4757-117X + - family-names: François + given-names: Romain + orcid: https://orcid.org/0000-0002-2444-4226 + - family-names: Henry + given-names: Lionel + - family-names: Müller + given-names: Kirill + orcid: https://orcid.org/0000-0002-1416-3412 + - family-names: Vaughan + given-names: Davis + email: davis@posit.co + orcid: https://orcid.org/0000-0003-4777-038X + year: "2024" + doi: 10.32614/CRAN.package.dplyr + - type: software + title: knitr + abstract: "knitr: A General-Purpose Package for Dynamic Report Generation in R" + notes: Suggests + url: https://yihui.org/knitr/ + repository: https://CRAN.R-project.org/package=knitr + authors: + - family-names: Xie + given-names: Yihui + email: xie@yihui.name + orcid: https://orcid.org/0000-0003-0645-5666 + year: "2024" + doi: 10.32614/CRAN.package.knitr + - type: software + title: magrittr + abstract: "magrittr: A Forward-Pipe Operator for R" + notes: Suggests + url: https://magrittr.tidyverse.org + repository: https://CRAN.R-project.org/package=magrittr + authors: + - family-names: Bache + given-names: Stefan Milton + email: stefan@stefanbache.dk + - family-names: Wickham + given-names: Hadley + email: hadley@rstudio.com + year: "2024" + doi: 10.32614/CRAN.package.magrittr + - type: software + title: rmarkdown + abstract: "rmarkdown: Dynamic Documents for R" + notes: Suggests + url: https://pkgs.rstudio.com/rmarkdown/ + repository: https://CRAN.R-project.org/package=rmarkdown + authors: + - family-names: Allaire + given-names: JJ + email: jj@posit.co + - family-names: Xie + given-names: Yihui + email: xie@yihui.name + orcid: https://orcid.org/0000-0003-0645-5666 + - family-names: Dervieux + given-names: Christophe + email: cderv@posit.co + orcid: https://orcid.org/0000-0003-4474-2498 + - family-names: McPherson + given-names: Jonathan + email: jonathan@posit.co + - family-names: Luraschi + given-names: Javier + - family-names: Ushey + given-names: Kevin + email: kevin@posit.co + - family-names: Atkins + given-names: Aron + email: aron@posit.co + - family-names: Wickham + given-names: Hadley + email: hadley@posit.co + - family-names: Cheng + given-names: Joe + email: joe@posit.co + - family-names: Chang + given-names: Winston + email: winston@posit.co + - family-names: Iannone + given-names: Richard + email: rich@posit.co + orcid: https://orcid.org/0000-0003-3925-190X + year: "2024" + doi: 10.32614/CRAN.package.rmarkdown + - type: software + title: spelling + abstract: "spelling: Tools for Spell Checking in R" + notes: Suggests + url: https://ropensci.r-universe.dev/spelling + repository: https://CRAN.R-project.org/package=spelling + authors: + - family-names: Ooms + given-names: Jeroen + email: jeroen@berkeley.edu + orcid: https://orcid.org/0000-0002-4035-0289 + - family-names: Hester + given-names: Jim + email: james.hester@rstudio.com + year: "2024" + doi: 10.32614/CRAN.package.spelling + - type: software + title: testthat + abstract: "testthat: Unit Testing for R" + notes: Suggests + url: https://testthat.r-lib.org + repository: https://CRAN.R-project.org/package=testthat + authors: + - family-names: Wickham + given-names: Hadley + email: hadley@posit.co + year: "2024" + doi: 10.32614/CRAN.package.testthat + - type: software + title: tibble + abstract: "tibble: Simple Data Frames" + notes: Suggests + url: https://tibble.tidyverse.org/ + repository: https://CRAN.R-project.org/package=tibble + authors: + - family-names: Müller + given-names: Kirill + email: kirill@cynkra.com + orcid: https://orcid.org/0000-0002-1416-3412 + - family-names: Wickham + given-names: Hadley + email: hadley@rstudio.com + year: "2024" + doi: 10.32614/CRAN.package.tibble diff --git a/DESCRIPTION b/DESCRIPTION index aec951e..878886e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,4 +1,4 @@ -Package: datatagr +Package: safeframe Title: Generic Data Labelling and Validating Version: 0.0.1 Authors@R: c( @@ -7,10 +7,10 @@ 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 'datatagr' 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 labelled, 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/datatagr/, https://github.com/epiverse-trace/datatagr -BugReports: https://github.com/epiverse-trace/datatagr/issues +URL: https://epiverse-trace.github.io/safeframe/, https://github.com/epiverse-trace/safeframe +BugReports: https://github.com/epiverse-trace/safeframe/issues Depends: R (>= 3.1.0) Imports: diff --git a/NAMESPACE b/NAMESPACE index e572844..e862fc1 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,20 +1,20 @@ # Generated by roxygen2: do not edit by hand -S3method("$<-",datatagr) -S3method("[",datatagr) -S3method("[<-",datatagr) -S3method("[[<-",datatagr) -S3method("names<-",datatagr) -S3method(print,datatagr) +S3method("$<-",safeframe) +S3method("[",safeframe) +S3method("[<-",safeframe) +S3method("[[<-",safeframe) +S3method("names<-",safeframe) +S3method(print,safeframe) export(get_lost_labels_action) export(has_label) export(labels) export(labels_df) export(lost_labels_action) -export(make_datatagr) +export(make_safeframe) export(set_labels) export(type) -export(validate_datatagr) export(validate_labels) +export(validate_safeframe) export(validate_types) importFrom(lifecycle,deprecated) diff --git a/R/drop_datatagr.R b/R/drop_safeframe.R similarity index 55% rename from R/drop_datatagr.R rename to R/drop_safeframe.R index 96e22bb..4731a0d 100644 --- a/R/drop_datatagr.R +++ b/R/drop_safeframe.R @@ -1,20 +1,20 @@ -#' Remove the datatagr class from an object +#' Remove the safeframe class from an object #' #' Internal function. Used for dispatching to other methods when `NextMethod` is -#' an issue (typically to pass additional arguments to the `datatagr` method). +#' an issue (typically to pass additional arguments to the `safeframe` method). #' -#' @param x a `datatagr` object +#' @param x a `safeframe` object #' #' @param remove_labels a `logical` indicating if labels should be removed from #' the attributes; defaults to `TRUE` #' #' @noRd #' -#' @return The function returns the object without the `datatagr` class. +#' @return The function returns the object without the `safeframe` class. #' -drop_datatagr <- function(x, remove_labels = TRUE) { +drop_safeframe <- function(x, remove_labels = TRUE) { classes <- class(x) - class(x) <- setdiff(classes, "datatagr") + class(x) <- setdiff(classes, "safeframe") if (remove_labels) { # Set the label attribute to NULL for all variables in x for (var in names(x)) { diff --git a/R/has_label.R b/R/has_label.R index 7b35ba8..86a4c23 100644 --- a/R/has_label.R +++ b/R/has_label.R @@ -5,15 +5,15 @@ #' @returns A numeric vector containing the position of the columns with the #' requested labels #' -#' @note Using this in a pipeline results in a 'datatagr' object, but does not +#' @note Using this in a pipeline results in a 'safeframe' object, but does not #' maintain the variable labels at this time. It is primarily useful to make #' your pipelines human readable. #' #' @export #' #' @examples -#' ## create datatagr -#' x <- make_datatagr(cars, +#' ## create safeframe +#' x <- make_safeframe(cars, #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) diff --git a/R/labels.R b/R/labels.R index 64660cf..5da2a0a 100644 --- a/R/labels.R +++ b/R/labels.R @@ -1,9 +1,9 @@ -#' Get the list of labels in a datatagr +#' Get the list of labels in a safeframe #' #' This function returns the list of labels identifying specific variable types -#' in a `datatagr` object. +#' in a `safeframe` object. #' -#' @param x a `datatagr` object +#' @param x a `safeframe` object #' #' @param show_null a `logical` indicating if the complete list of labels, #' including `NULL` ones, should be returned; if `FALSE`, only labels with a @@ -18,8 +18,8 @@ #' #' @examples #' -#' ## make a datatagr -#' x <- make_datatagr(cars, speed = "Miles per hour") +#' ## make a safeframe +#' x <- make_safeframe(cars, speed = "Miles per hour") #' #' ## check non-null labels #' labels(x) @@ -27,7 +27,7 @@ #' ## get a list of all labels, including NULL ones #' labels(x, TRUE) labels <- function(x, show_null = FALSE) { - checkmate::assertClass(x, "datatagr") + checkmate::assertClass(x, "safeframe") out <- lapply(names(x), FUN = function(var) { attr(x[[var]], "label") }) diff --git a/R/labels_df.R b/R/labels_df.R index 55ed49c..2d9aae9 100644 --- a/R/labels_df.R +++ b/R/labels_df.R @@ -1,10 +1,10 @@ #' Extract a data.frame of all labelled variables #' #' This function returns a `data.frame`, where labelled variables (as stored in -#' the `datatagr` object) are renamed. Note that the output is no longer a -#' `datatagr`, but a regular `data.frame`. Unlabeled variables are unaffected. +#' the `safeframe` object) are renamed. Note that the output is no longer a +#' `safeframe`, but a regular `data.frame`. Unlabeled variables are unaffected. #' -#' @param x a `datatagr` object +#' @param x a `safeframe` object #' #' @export #' @@ -12,7 +12,7 @@ #' #' @examples #' -#' x <- make_datatagr(cars, +#' x <- make_safeframe(cars, #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) @@ -20,10 +20,10 @@ #' ## get a data.frame with variables renamed based on labels #' labels_df(x) labels_df <- function(x) { - checkmate::assertClass(x, "datatagr") + checkmate::assertClass(x, "safeframe") labels <- unlist(labels(x)) - out <- drop_datatagr(x) + out <- drop_safeframe(x) # Replace the names of out that are in intersection with corresponding labels names(out)[match(names(labels), names(out))] <- labels[names(labels)] diff --git a/R/lost_labels.R b/R/lost_labels.R index bfd657a..fa18680 100644 --- a/R/lost_labels.R +++ b/R/lost_labels.R @@ -23,11 +23,11 @@ lost_labels <- function(old, new, lost_action) { ) if (lost_action == "warning") { # nolint next: condition_call_linter. - warning(warningCondition(msg, class = "datatagr_warning")) + warning(warningCondition(msg, class = "safeframe_warning")) } if (lost_action == "error") { # nolint next: condition_call_linter. - stop(errorCondition(msg, class = "datatagr_error")) + stop(errorCondition(msg, class = "safeframe_error")) } } } diff --git a/R/lost_labels_action.R b/R/lost_labels_action.R index abbc5c9..fa0b01b 100644 --- a/R/lost_labels_action.R +++ b/R/lost_labels_action.R @@ -1,8 +1,8 @@ #' Check and set behaviour for lost labels #' #' This function determines the behaviour to adopt when labelled variables of a -#' `datatagr` are lost for example through subsetting. This is achieved using -#' `options` defined for the `datatagr` package. +#' `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 #' variables have been lost: "error" (default) will issue an error; "warning" @@ -11,10 +11,10 @@ #' @param quiet a `logical` indicating if a message should be displayed; only #' used outside pipelines #' -#' @return returns `NULL`; the option itself is set in `options("datatagr")` +#' @return returns `NULL`; the option itself is set in `options("safeframe")` #' -#' @details The errors or warnings generated by datatagr in case of labelled -#' variable loss has a custom class of `datatagr_error` and `datatagr_warning` +#' @details The errors or warnings generated by safeframe in case of labelled +#' variable loss has a custom class of `safeframe_error` and `safeframe_warning` #' respectively. #' #' @export @@ -43,11 +43,11 @@ #' lost_labels_action <- function(action = c("warning", "error", "none"), quiet = FALSE) { - datatagr_options <- options("datatagr")$datatagr + safeframe_options <- options("safeframe")$safeframe action <- match.arg(action) - datatagr_options$lost_labels_action <- action - options(datatagr = datatagr_options) + safeframe_options$lost_labels_action <- action + options(safeframe = safeframe_options) if (!quiet) { if (action == "warning") msg <- "Lost labels will now issue a warning." if (action == "error") msg <- "Lost labels will now issue an error." @@ -64,5 +64,5 @@ lost_labels_action <- function(action = c("warning", "error", "none"), #' @rdname lost_labels_action get_lost_labels_action <- function() { - options("datatagr")$datatagr$lost_labels_action + options("safeframe")$safeframe$lost_labels_action } diff --git a/R/make_datatagr.R b/R/make_safeframe.R similarity index 64% rename from R/make_datatagr.R rename to R/make_safeframe.R index 03dfff7..23710c5 100644 --- a/R/make_datatagr.R +++ b/R/make_safeframe.R @@ -1,8 +1,8 @@ -#' Create a datatagr from a data.frame +#' Create a safeframe from a data.frame #' -#' This function converts a `data.frame` or a `tibble` into a `datatagr` object, -#' where data are labelled and validated. The output will seem to be the same -#' `data.frame`, but `datatagr`-aware packages will then be able to +#' 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 +#' same `data.frame`, but `safeframe`-aware packages will then be able to #' automatically use labelled fields for further data cleaning and analysis. #' #' @param x a `data.frame` or a `tibble` @@ -14,18 +14,18 @@ #' #' @seealso #' -#' * An overview of the [datatagr] package -#' * [labels()]: for a list of labelled variables in a `datatagr` +#' * An overview of the [safeframe] package +#' * [labels()]: for a list of labelled variables in a `safeframe` #' * [set_labels()]: for modifying labels #' * [labels_df()]: for selecting variables by labels #' #' @export #' -#' @return The function returns a `datatagr` object. +#' @return The function returns a `safeframe` object. #' #' @examples #' -#' x <- make_datatagr(cars, +#' x <- make_safeframe(cars, #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) @@ -41,13 +41,13 @@ #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) -#' new_x <- make_datatagr(cars, !!!my_labels) +#' new_x <- make_safeframe(cars, !!!my_labels) #' #' ## The output is strictly equivalent to the previous one #' identical(x, new_x) #' -make_datatagr <- function(x, - ...) { +make_safeframe <- function(x, + ...) { # assert inputs checkmate::assert_data_frame(x, min.cols = 1) assert_not_data_table(x) @@ -56,6 +56,6 @@ make_datatagr <- function(x, x <- label_variables(x, labels) # shape output and return object - class(x) <- c("datatagr", class(x)) + class(x) <- c("safeframe", class(x)) x } diff --git a/R/names.R b/R/names.R index 222367a..0591d5c 100644 --- a/R/names.R +++ b/R/names.R @@ -1,19 +1,20 @@ -#' Rename columns of a datatagr +#' Rename columns of a safeframe #' -#' This function can be used to rename the columns a `datatagr` (that is, adjust +#' This function can be used to rename the columns a `safeframe` (that is, +#' adjust #' variable names). #' -#' @param x a `datatagr` object +#' @param x a `safeframe` object #' #' @param value a `character` vector to set the new names of the columns of `x` #' -#' @return a `datatagr` with new column names +#' @return a `safeframe` with new column names #' #' @export #' #' @examples -#' ## create datatagr -#' x <- make_datatagr(cars, +#' ## create safeframe +#' x <- make_safeframe(cars, #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) @@ -33,7 +34,7 @@ #' head(x) #' labels(x) #' } -`names<-.datatagr` <- function(x, value) { +`names<-.safeframe` <- function(x, value) { # Strategy for renaming # Since renaming cannot drop columns, we can update labels to match new @@ -42,7 +43,7 @@ # 1. Storing old names and new names to have define replacement rules # 2. Replace all labelled variables using the replacement rules - out <- drop_datatagr(x) + out <- drop_safeframe(x) names(out) <- value # Step 1 diff --git a/R/print.datatagr.R b/R/print.safeframe.R similarity index 74% rename from R/print.datatagr.R rename to R/print.safeframe.R index 277f1fb..b1c8d34 100644 --- a/R/print.datatagr.R +++ b/R/print.safeframe.R @@ -1,8 +1,8 @@ -#' Printing method for datatagr objects +#' Printing method for safeframe objects #' -#' This function prints datatagr objects. +#' This function prints safeframe objects. #' -#' @param x a `datatagr` object +#' @param x a `safeframe` object #' #' @param ... further arguments to be passed to 'print' #' @@ -11,8 +11,8 @@ #' @export #' #' @examples -#' ## create datatagr -#' x <- make_datatagr(cars, +#' ## create safeframe +#' x <- make_safeframe(cars, #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) @@ -24,14 +24,14 @@ #' if (require(tibble) && require(magrittr)) { #' cars %>% #' tibble() %>% -#' make_datatagr( +#' make_safeframe( #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) #' } -print.datatagr <- function(x, ...) { - cat("\n// datatagr object\n") - print(drop_datatagr(x)) +print.safeframe <- function(x, ...) { + cat("\n// safeframe object\n") + print(drop_safeframe(x)) # Extract names and values from labels(x) label_values <- unlist(labels(x)) diff --git a/R/restore_labels.R b/R/restore_labels.R index 961a2ef..8692e39 100644 --- a/R/restore_labels.R +++ b/R/restore_labels.R @@ -1,6 +1,6 @@ -#' Restore labels of a datatagr +#' Restore labels of a safeframe #' -#' Internal. This function is used to restore labels of a `datatagr` object +#' 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 #' have disappeared from the object. @@ -17,7 +17,7 @@ #' #' @noRd #' -#' @return The function returns a `datatagr` object with updated labels. +#' @return The function returns a `safeframe` object with updated labels. #' restore_labels <- function(x, newLabels, @@ -45,11 +45,11 @@ restore_labels <- function(x, newLabels, ) if (lost_action == "warning") { # nolint next: condition_call_linter. - warning(warningCondition(msg, class = "datatagr_warning")) + warning(warningCondition(msg, class = "safeframe_warning")) } if (lost_action == "error") { # nolint next: condition_call_linter. - stop(errorCondition(msg, class = "datatagr_error")) + stop(errorCondition(msg, class = "safeframe_error")) } } @@ -58,8 +58,8 @@ restore_labels <- function(x, newLabels, } # Ensure class consistency - if (!inherits(x, "datatagr")) { - class(x) <- c("datatagr", class(x)) + if (!inherits(x, "safeframe")) { + class(x) <- c("safeframe", class(x)) } x diff --git a/R/datatagr-package.R b/R/safeframe-package.R similarity index 78% rename from R/datatagr-package.R rename to R/safeframe-package.R index 132a917..6f28309 100644 --- a/R/datatagr-package.R +++ b/R/safeframe-package.R @@ -1,20 +1,20 @@ #' Base Tools for Labelling and Validating Data #' -#' The \pkg{datatagr} package provides tools to help label and validate data. -#' The 'datatagr' class adds column level attributes to a 'data.frame'. +#' 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, #' making data pipelines more robust and reliable. #' -#' @aliases datatagr +#' @aliases safeframe #' #' @section Main functions: #' -#' * [make_datatagr()]: to create `datatagr` objects from a `data.frame` or a -#' `tibble` +#' * [make_safeframe()]: to create `safeframe` objects from a `data.frame` or +#' a `tibble` #' -#' * [set_labels()]: to change or add labelled variables in a `datatagr` +#' * [set_labels()]: to change or add labelled variables in a `safeframe` #' -#' * [labels()]: to get the list of labels of a `datatagr` +#' * [labels()]: to get the list of labels of a `safeframe` #' #' * [labels_df()]: to get a `data.frame` of all tagged variables #' @@ -28,17 +28,17 @@ #' @section Dedicated methods: #' #' Specific methods commonly used to handle `data.frame` are provided for -#' `datatagr` objects, typically to help flag or prevent actions which could +#' `safeframe` objects, typically to help flag or prevent actions which could #' alter or lose labelled 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_datatagr]): will adopt the +#' * `x[...] <-` and `x[[...]] <-` (see [sub_safeframe]): will adopt the #' desired behaviour when labelled variables are lost #' -#' * `print()`: prints info about the `datatagr` in addition to the +#' * `print()`: prints info about the `safeframe` in addition to the #' `data.frame` or `tibble` #' #' @note The package does not aim to have complete integration with \pkg{dplyr} @@ -48,7 +48,7 @@ #' @examples #' #' # using base R style -#' x <- make_datatagr(cars[1:50, ], +#' x <- make_safeframe(cars[1:50, ], #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) @@ -77,13 +77,13 @@ #' #' # using tidyverse style #' -#' ## example of creating a datatagr, adding a new variable, and adding a label +#' ## example of creating a safeframe, adding a new variable, and adding a label #' ## for it #' #' if (require(dplyr) && require(magrittr)) { #' x <- cars %>% #' tibble() %>% -#' make_datatagr( +#' make_safeframe( #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) %>% diff --git a/R/set_labels.R b/R/set_labels.R index 2cfc2d5..68414f4 100644 --- a/R/set_labels.R +++ b/R/set_labels.R @@ -1,20 +1,20 @@ -#' Change labels of a datatagr object +#' Change labels of a safeframe object #' -#' This function changes the `labels` of a `datatagr` object, using the same -#' syntax as the constructor [make_datatagr()]. +#' This function changes the `labels` of a `safeframe` object, using the same +#' syntax as the constructor [make_safeframe()]. #' -#' @inheritParams make_datatagr +#' @inheritParams make_safeframe #' -#' @seealso [make_datatagr()] to create a `datatagr` object +#' @seealso [make_safeframe()] to create a `safeframe` object #' #' @export #' -#' @return The function returns a `datatagr` object. +#' @return The function returns a `safeframe` object. #' #' @examples #' -#' ## create a datatagr -#' x <- make_datatagr(cars, speed = "Miles per hour") +#' ## create a safeframe +#' x <- make_safeframe(cars, speed = "Miles per hour") #' labels(x) #' #' ## add new labels and fix an existing one @@ -31,7 +31,7 @@ #' labels(x) set_labels <- function(x, ...) { # assert inputs - checkmate::assertClass(x, "datatagr") + checkmate::assertClass(x, "safeframe") labels <- rlang::list2(...) diff --git a/R/square_bracket.R b/R/square_bracket.R index 94360bc..eb6aa21 100644 --- a/R/square_bracket.R +++ b/R/square_bracket.R @@ -1,22 +1,22 @@ -#' Subsetting of datatagr objects +#' Subsetting of safeframe objects #' -#' The `[]` and `[[]]` operators for `datatagr` objects behaves like for regular -#' `data.frame` or `tibble`, but check that labelled 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()]) . +#' The `[]` and `[[]]` operators for `safeframe` objects behaves like for +#' regular `data.frame` or `tibble`, but check that labelled 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()]) . #' #' @inheritParams base::Extract -#' @param x a `datatagr` object +#' @param x a `safeframe` object #' @param i a vector of `integer` or `logical` to subset the rows of the -#' `datatagr` +#' `safeframe` #' @param j a vector of `character`, `integer`, or `logical` to subset the -#' columns of the `datatagr` +#' columns of the `safeframe` #' @param drop a `logical` indicating if, when a single column is selected, the #' `data.frame` class should be dropped to return a simple vector, in which -#' case the `datatagr` class is lost as well; defaults to `FALSE` +#' case the `safeframe` class is lost as well; defaults to `FALSE` #' @param value the replacement to be used for the entries identified in `x` #' -#' @return If no drop is happening, a `datatagr`. Otherwise an atomic vector. +#' @return If no drop is happening, a `safeframe`. Otherwise an atomic vector. #' #' @seealso #' * [lost_labels_action()] to set the behaviour to adopt when labels are @@ -25,15 +25,15 @@ #' #' @export #' -#' @rdname sub_datatagr +#' @rdname sub_safeframe #' -#' @aliases sub_datatagr +#' @aliases sub_safeframe #' #' @examples #' if (require(dplyr) && require(magrittr)) { -#' ## create a datatagr +#' ## create a safeframe #' x <- cars %>% -#' make_datatagr( +#' make_safeframe( #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) %>% @@ -51,21 +51,21 @@ #' x$age <- NULL #' x #' } -`[.datatagr` <- function(x, i, j, drop = FALSE) { +`[.safeframe` <- function(x, i, j, drop = FALSE) { # Strategy for subsetting # # Subsetting is done using the next method in line, and making post-hoc checks # on two things: # # 1. that the subsetted object is still a `data.frame` or a `tibble`; if not, - # we automatically drop the `datatagr` class and tags - # 2. if the output is going to be a `datatagr` we need to restore previous + # 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 # # 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 # args, in case we wanted to use them; so declassing the object instead using - # the drop_datatagr() function + # the drop_safeframe() function lost_action <- get_lost_labels_action() @@ -77,12 +77,12 @@ # default value. When we subset this way, drop is always considered to be # TRUE. We let warnings from user-specified drop values surface. if (missing(drop)) { - out <- drop_datatagr(x)[i] + out <- drop_safeframe(x)[i] } else { - out <- drop_datatagr(x)[i, drop = drop] + out <- drop_safeframe(x)[i, drop = drop] } } else { - out <- drop_datatagr(x)[i, j, drop = drop] + out <- drop_safeframe(x)[i, j, drop = drop] } # Case 1 @@ -99,9 +99,9 @@ #' @export #' -#' @rdname sub_datatagr +#' @rdname sub_safeframe -`[<-.datatagr` <- function(x, i, j, value) { +`[<-.safeframe` <- function(x, i, j, value) { lost_action <- get_lost_labels_action() old_labels <- labels(x, show_null = TRUE) new_labels <- old_labels @@ -119,7 +119,7 @@ } } - class(x) <- setdiff(class(x), "datatagr") + class(x) <- setdiff(class(x), "safeframe") x <- NextMethod() # Call restore_labels to restore the labels @@ -130,9 +130,9 @@ #' @export #' -#' @rdname sub_datatagr +#' @rdname sub_safeframe -`[[<-.datatagr` <- function(x, i, j, value) { +`[[<-.safeframe` <- function(x, i, j, value) { lost_action <- get_lost_labels_action() old_labels <- labels(x, show_null = TRUE) new_labels <- old_labels @@ -144,7 +144,7 @@ lost_labels(old_labels, new_labels, lost_action) - class(x) <- setdiff(class(x), "datatagr") + class(x) <- setdiff(class(x), "safeframe") x <- NextMethod() # Call restore_labels to restore the labels @@ -156,8 +156,8 @@ #' @export #' -#' @rdname sub_datatagr -`$<-.datatagr` <- function(x, name, value) { +#' @rdname sub_safeframe +`$<-.safeframe` <- function(x, name, value) { lost_action <- get_lost_labels_action() old_labels <- labels(x, show_null = TRUE) new_labels <- old_labels @@ -169,7 +169,7 @@ lost_labels(old_labels, new_labels, lost_action) - class(x) <- setdiff(class(x), "datatagr") + class(x) <- setdiff(class(x), "safeframe") x <- NextMethod() # Call restore_labels to restore the labels diff --git a/R/type.R b/R/type.R index 805751d..6220b36 100644 --- a/R/type.R +++ b/R/type.R @@ -2,7 +2,7 @@ #' #' Function to swiftly provide access to generic categories of types within R. #' These can be used to provide comprehensive typesetting when creating a -#' `datatagr` object. +#' `safeframe` object. #' #' @param x Character indicating the desired type. Options include `date`, #' `category`, `numeric`, `binary` at this time. @@ -11,7 +11,7 @@ #' @export #' #' @examples -#' x <- make_datatagr(cars, +#' x <- make_safeframe(cars, #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) diff --git a/R/validate_labels.R b/R/validate_labels.R index bfc4014..4dbc67c 100644 --- a/R/validate_labels.R +++ b/R/validate_labels.R @@ -1,38 +1,38 @@ -#' Checks the labels of a datatagr object +#' Checks the labels of a safeframe object #' -#' This function evaluates the validity of the labels of a `datatagr` object by +#' This function evaluates the validity of the labels of a `safeframe` object by #' checking that: i) labels are present ii) labels is a `list` of `character` or #' `NULL` values. #' #' @export #' -#' @param x a `datatagr` object +#' @param x a `safeframe` object #' -#' @return If checks pass, a `datatagr` object; otherwise issues an error. +#' @return If checks pass, a `safeframe` object; otherwise issues an error. #' #' @seealso [validate_types()] to check if labelled variables have #' the right classes #' #' @examples -#' ## create a valid datatagr +#' ## create a valid safeframe #' x <- cars |> -#' make_datatagr( +#' make_safeframe( #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) #' x #' -#' ## the below issues an error as datatagr doesn't know any defaults +#' ## the below issues an error as safeframe doesn't know any defaults #' ## note: tryCatch is only used to avoid a genuine error in the example -#' tryCatch(validate_datatagr(x), error = paste) +#' tryCatch(validate_safeframe(x), error = paste) #' #' ## validation requires you to specify the types directly -#' validate_datatagr(x, +#' validate_safeframe(x, #' speed = c("integer", "numeric"), #' dist = "numeric" #' ) validate_labels <- function(x) { - checkmate::assert_class(x, "datatagr") + checkmate::assert_class(x, "safeframe") x_labels <- labels(x, show_null = TRUE) if (is.null(unlist(x_labels))) stop("`x` has no labels") diff --git a/R/validate_datatagr.R b/R/validate_safeframe.R similarity index 69% rename from R/validate_datatagr.R rename to R/validate_safeframe.R index e46273d..4c2ad84 100644 --- a/R/validate_datatagr.R +++ b/R/validate_safeframe.R @@ -1,13 +1,13 @@ -#' Checks the content of a datatagr object +#' Checks the content of a safeframe object #' -#' This function evaluates the validity of a `datatagr` object by checking the +#' This function evaluates the validity of a `safeframe` object by checking the #' object class, its labels, and the types of variables. It combines #' validation checks made by [validate_types()] and [validate_labels()]. See #' 'Details' section for more information on the checks performed. #' #' @details The following checks are performed: #' -#' * `x` is a `datatagr` object +#' * `x` is a `safeframe` object #' * variables in `x` have a well-formed `label` attribute #' * variables correspond to the specified types #' @@ -17,7 +17,7 @@ #' #' @inheritParams set_labels #' -#' @return If checks pass, a `datatagr` object; otherwise issues an error. +#' @return If checks pass, a `safeframe` object; otherwise issues an error. #' #' @seealso #' * [validate_types()] to check if variables have the right types @@ -25,29 +25,29 @@ #' #' @examples #' -#' ## create a valid datatagr +#' ## create a valid safeframe #' x <- cars |> -#' make_datatagr( +#' make_safeframe( #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) #' x #' #' ## validation -#' validate_datatagr(x, +#' validate_safeframe(x, #' speed = c("numeric", "factor"), #' dist = "numeric" #' ) #' #' ## the below issues an error #' ## note: tryCatch is only used to avoid a genuine error in the example -#' tryCatch(validate_datatagr(x, +#' tryCatch(validate_safeframe(x, #' speed = c("numeric", "factor"), #' dist = "factor" #' ), error = paste) -validate_datatagr <- function(x, - ...) { - checkmate::assert_class(x, "datatagr") +validate_safeframe <- function(x, + ...) { + checkmate::assert_class(x, "safeframe") validate_labels(x) validate_types(x, ...) diff --git a/R/validate_types.R b/R/validate_types.R index 91a4ac2..2648f84 100644 --- a/R/validate_types.R +++ b/R/validate_types.R @@ -1,12 +1,12 @@ #' Type check variables #' -#' This function checks the type of variables in a `datatagr` against +#' This function checks the type of variables in a `safeframe` against #' accepted classes. Only checks the type of provided variables and ignores #' those not provided. #' #' @export #' -#' @param x a `datatagr` object +#' @param x a `safeframe` object #' #' @param ... <[`dynamic-dots`][rlang::dyn-dots]> A named list with variable #' names in `x` as list names and the related types as list values. @@ -15,10 +15,10 @@ #' #' @seealso #' * [validate_labels()] to perform a series of checks on variables -#' * [validate_datatagr()] to combine `validate_labels` and `validate_types` +#' * [validate_safeframe()] to combine `validate_labels` and `validate_types` #' #' @examples -#' x <- make_datatagr(cars, +#' x <- make_safeframe(cars, #' speed = "Miles per hour", #' dist = "Distance in miles" #' ) @@ -35,7 +35,7 @@ #' )) #' validate_types <- function(x, ...) { - checkmate::assert_class(x, "datatagr") + checkmate::assert_class(x, "safeframe") types <- rlang::list2(...) checkmate::assert_list(types, min.len = 1, types = "character") diff --git a/R/zzz.R b/R/zzz.R index a8d67cb..ff00f66 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -1,5 +1,5 @@ .onLoad <- function(libname, pkgname) { - lost_labels_action(Sys.getenv("DATATAGR_LOST_ACTION", "warning"), + lost_labels_action(Sys.getenv("SAFEFRAME_LOST_ACTION", "warning"), quiet = TRUE ) } diff --git a/README.Rmd b/README.Rmd index abafcde..3b33f0a 100644 --- a/README.Rmd +++ b/README.Rmd @@ -17,39 +17,39 @@ knitr::opts_chunk$set( ) ``` -# *datatagr*: Generic Data Labelling and Validating Logo for datatagr +# *safeframe*: Generic Data Labelling and Validating Logo for safeframe [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit/) -[![R-CMD-check](https://github.com/epiverse-trace/datatagr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/epiverse-trace/datatagr/actions/workflows/R-CMD-check.yaml) -[![Codecov test coverage](https://codecov.io/gh/epiverse-trace/datatagr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/epiverse-trace/datatagr?branch=main) +[![R-CMD-check](https://github.com/epiverse-trace/safeframe/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/epiverse-trace/safeframe/actions/workflows/R-CMD-check.yaml) +[![Codecov test coverage](https://codecov.io/gh/epiverse-trace/safeframe/branch/main/graph/badge.svg)](https://app.codecov.io/gh/epiverse-trace/safeframe?branch=main) [![lifecycle-concept](https://raw.githubusercontent.com/reconverse/reconverse.github.io/master/images/badge-concept.svg)](https://www.reconverse.org/lifecycle.html#experimental) -**datatagr** provides functions to label and validate data of any kind. datatagr is an abstraction from [**linelist**](https://github.com/epiverse-trace/linelist), which applies these principles to epidemiological linelist data. The original proposal for this package can be found on [the Discussion board](https://github.com/orgs/epiverse-trace/discussions/221). +**safeframe** provides functions to label and validate data of any kind. safeframe is an abstraction from [**linelist**](https://github.com/epiverse-trace/linelist), which applies these principles to epidemiological linelist data. The original proposal for this package can be found on [the Discussion board](https://github.com/orgs/epiverse-trace/discussions/221). ## Installation -You can install the development version of datatagr from +You can install the development version of safeframe from [GitHub](https://github.com/) with: ```r # install.packages("pak") -pak::pak("epiverse-trace/datatagr") +pak::pak("epiverse-trace/safeframe") ``` ## Getting started ```r -library(datatagr) +library(safeframe) -# Create a datatagr object -x <- make_datatagr(cars, speed = 'Miles per hour', dist = 'Distance in miles') +# Create a safeframe object +x <- make_safeframe(cars, speed = 'Miles per hour', dist = 'Distance in miles') # Validate the data are of a specific type -validate_datatagr(x, +validate_safeframe(x, speed = 'numeric', # speed should be numeric # type() is a helper function of related classes dist = type('numeric') # dist should be numeric, integer @@ -67,7 +67,7 @@ for use outside of the development team. ### Contributions -Contributions are welcome via [pull requests](https://github.com/epiverse-trace/datatagr/pulls). Anything bigger than a typo fix or a small documentation update should be discussed in an issue first. If you want to report a bug or suggest an enhancement, please open an issue. 😊 See also [the general Epiverse TRACE contribution document](https://github.com/epiverse-trace/.github/blob/main/CONTRIBUTING.md). +Contributions are welcome via [pull requests](https://github.com/epiverse-trace/safeframe/pulls). Anything bigger than a typo fix or a small documentation update should be discussed in an issue first. If you want to report a bug or suggest an enhancement, please open an issue. 😊 See also [the general Epiverse TRACE contribution document](https://github.com/epiverse-trace/.github/blob/main/CONTRIBUTING.md).
Common issues @@ -95,10 +95,10 @@ This will reduce the time it takes for us to review your contribution. Thank you This project is related to other existing projects in R or other languages, but also differs from them in the following aspects: - [labelled](https://github.com/larmarange/labelled/): A package for labelling data in R, but it is more focused on labelling variables than validating them. -- [linelist](https://github.com/epiverse-trace/linelist): A package for managing and validating linelist data - the original inspiration for datatagr. +- [linelist](https://github.com/epiverse-trace/linelist): A package for managing and validating linelist data - the original inspiration for safeframe. ### Code of Conduct -Please note that the datatagr project is released with a +Please note that the safeframe project is released with a [Contributor Code of Conduct](https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms. diff --git a/README.md b/README.md index 830ac2a..2cff7ce 100644 --- a/README.md +++ b/README.md @@ -5,21 +5,21 @@ -# *datatagr*: Generic Data Labelling and Validating Logo for datatagr +# *safeframe*: Generic Data Labelling and Validating Logo for safeframe [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit/) -[![R-CMD-check](https://github.com/epiverse-trace/datatagr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/epiverse-trace/datatagr/actions/workflows/R-CMD-check.yaml) +[![R-CMD-check](https://github.com/epiverse-trace/safeframe/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/epiverse-trace/safeframe/actions/workflows/R-CMD-check.yaml) [![Codecov test -coverage](https://codecov.io/gh/epiverse-trace/datatagr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/epiverse-trace/datatagr?branch=main) +coverage](https://codecov.io/gh/epiverse-trace/safeframe/branch/main/graph/badge.svg)](https://app.codecov.io/gh/epiverse-trace/safeframe?branch=main) [![lifecycle-concept](https://raw.githubusercontent.com/reconverse/reconverse.github.io/master/images/badge-concept.svg)](https://www.reconverse.org/lifecycle.html#experimental) -**datatagr** provides functions to label and validate data of any kind. -datatagr is an abstraction from +**safeframe** provides functions to label and validate data of any kind. +safeframe is an abstraction from [**linelist**](https://github.com/epiverse-trace/linelist), which applies these principles to epidemiological linelist data. The original proposal for this package can be found on [the Discussion @@ -27,24 +27,24 @@ board](https://github.com/orgs/epiverse-trace/discussions/221). ## Installation -You can install the development version of datatagr from +You can install the development version of safeframe from [GitHub](https://github.com/) with: ``` r # install.packages("pak") -pak::pak("epiverse-trace/datatagr") +pak::pak("epiverse-trace/safeframe") ``` ## Getting started ``` r -library(datatagr) +library(safeframe) -# Create a datatagr object -x <- make_datatagr(cars, speed = 'Miles per hour', dist = 'Distance in miles') +# Create a safeframe object +x <- make_safeframe(cars, speed = 'Miles per hour', dist = 'Distance in miles') # Validate the data are of a specific type -validate_datatagr(x, +validate_safeframe(x, speed = 'numeric', # speed should be numeric # type() is a helper function of related classes dist = type('numeric') # dist should be numeric, integer @@ -63,7 +63,7 @@ and the package is not ready for use outside of the development team. ### Contributions Contributions are welcome via [pull -requests](https://github.com/epiverse-trace/datatagr/pulls). Anything +requests](https://github.com/epiverse-trace/safeframe/pulls). Anything bigger than a typo fix or a small documentation update should be discussed in an issue first. If you want to report a bug or suggest an enhancement, please open an issue. 😊 See also [the general Epiverse @@ -105,11 +105,11 @@ languages, but also differs from them in the following aspects: than validating them. - [linelist](https://github.com/epiverse-trace/linelist): A package for managing and validating linelist data - the original inspiration for - datatagr. + safeframe. ### Code of Conduct -Please note that the datatagr project is released with a [Contributor +Please note that the safeframe project is released with a [Contributor Code of Conduct](https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms. diff --git a/_pkgdown.yml b/_pkgdown.yml index 1c7ab9c..fe54742 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,10 +1,9 @@ # FIXME: The url field needs to be updated to contain the URL of the website # where the package documentation is hosted # (e.g., https://epiverse-trace.github.io/pkg). -url: https://epiverse-trace.github.io/datatagr +url: https://epiverse-trace.github.io/safeframe template: package: epiversetheme - # It is recommended to add a pkgdown reference index, grouping the different # function into logical sections (e.g., modules). # It is also recommended to rely on selector such as `starts_with()` or diff --git a/man/has_label.Rd b/man/has_label.Rd index 286624d..ba031a1 100644 --- a/man/has_label.Rd +++ b/man/has_label.Rd @@ -17,13 +17,13 @@ requested labels A selector function to use in \pkg{tidyverse} functions } \note{ -Using this in a pipeline results in a 'datatagr' object, but does not +Using this in a pipeline results in a 'safeframe' object, but does not maintain the variable labels at this time. It is primarily useful to make your pipelines human readable. } \examples{ -## create datatagr -x <- make_datatagr(cars, +## create safeframe +x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles" ) diff --git a/man/labels.Rd b/man/labels.Rd index 6ed36f9..d0f5ba4 100644 --- a/man/labels.Rd +++ b/man/labels.Rd @@ -2,12 +2,12 @@ % Please edit documentation in R/labels.R \name{labels} \alias{labels} -\title{Get the list of labels in a datatagr} +\title{Get the list of labels in a safeframe} \usage{ labels(x, show_null = FALSE) } \arguments{ -\item{x}{a \code{datatagr} object} +\item{x}{a \code{safeframe} object} \item{show_null}{a \code{logical} indicating if the complete list of labels, including \code{NULL} ones, should be returned; if \code{FALSE}, only labels with a @@ -19,15 +19,15 @@ they correspond to, and values indicate the relevant labels. } \description{ This function returns the list of labels identifying specific variable types -in a \code{datatagr} object. +in a \code{safeframe} object. } \details{ Labels are stored as the \code{label} attribute of the column variable. } \examples{ -## make a datatagr -x <- make_datatagr(cars, speed = "Miles per hour") +## make a safeframe +x <- make_safeframe(cars, speed = "Miles per hour") ## check non-null labels labels(x) diff --git a/man/labels_df.Rd b/man/labels_df.Rd index 780ea81..be9ea07 100644 --- a/man/labels_df.Rd +++ b/man/labels_df.Rd @@ -7,19 +7,19 @@ labels_df(x) } \arguments{ -\item{x}{a \code{datatagr} object} +\item{x}{a \code{safeframe} object} } \value{ 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 -the \code{datatagr} object) are renamed. Note that the output is no longer a -\code{datatagr}, but a regular \code{data.frame}. Unlabeled variables are unaffected. +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. } \examples{ -x <- make_datatagr(cars, +x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles" ) diff --git a/man/lost_labels_action.Rd b/man/lost_labels_action.Rd index 5b67d36..8c90f06 100644 --- a/man/lost_labels_action.Rd +++ b/man/lost_labels_action.Rd @@ -18,16 +18,16 @@ will issue a warning; "none" will do nothing} used outside pipelines} } \value{ -returns \code{NULL}; the option itself is set in \code{options("datatagr")} +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 -\code{datatagr} are lost for example through subsetting. This is achieved using -\code{options} defined for the \code{datatagr} package. +\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 datatagr in case of labelled -variable loss has a custom class of \code{datatagr_error} and \code{datatagr_warning} +The errors or warnings generated by safeframe in case of labelled +variable loss has a custom class of \code{safeframe_error} and \code{safeframe_warning} respectively. } \examples{ diff --git a/man/make_datatagr.Rd b/man/make_safeframe.Rd similarity index 67% rename from man/make_datatagr.Rd rename to man/make_safeframe.Rd index 8cb1490..c157b28 100644 --- a/man/make_datatagr.Rd +++ b/man/make_safeframe.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/make_datatagr.R -\name{make_datatagr} -\alias{make_datatagr} -\title{Create a datatagr from a data.frame} +% Please edit documentation in R/make_safeframe.R +\name{make_safeframe} +\alias{make_safeframe} +\title{Create a safeframe from a data.frame} \usage{ -make_datatagr(x, ...) +make_safeframe(x, ...) } \arguments{ \item{x}{a \code{data.frame} or a \code{tibble}} @@ -15,17 +15,17 @@ names in \code{x} as list names and the labels as list values. Values set to \code{default_values}.} } \value{ -The function returns a \code{datatagr} object. +The function returns a \code{safeframe} object. } \description{ -This function converts a \code{data.frame} or a \code{tibble} into a \code{datatagr} object, -where data are labelled and validated. The output will seem to be the same -\code{data.frame}, but \code{datatagr}-aware packages will then be able to +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 +same \code{data.frame}, but \code{safeframe}-aware packages will then be able to automatically use labelled fields for further data cleaning and analysis. } \examples{ -x <- make_datatagr(cars, +x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles" ) @@ -41,7 +41,7 @@ my_labels <- list( speed = "Miles per hour", dist = "Distance in miles" ) -new_x <- make_datatagr(cars, !!!my_labels) +new_x <- make_safeframe(cars, !!!my_labels) ## The output is strictly equivalent to the previous one identical(x, new_x) @@ -49,8 +49,8 @@ identical(x, new_x) } \seealso{ \itemize{ -\item An overview of the \link{datatagr} package -\item \code{\link[=labels]{labels()}}: for a list of labelled variables in a \code{datatagr} +\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[=set_labels]{set_labels()}}: for modifying labels \item \code{\link[=labels_df]{labels_df()}}: for selecting variables by labels } diff --git a/man/names-set-.datatagr.Rd b/man/names-set-.safeframe.Rd similarity index 64% rename from man/names-set-.datatagr.Rd rename to man/names-set-.safeframe.Rd index 7eab9b4..db06123 100644 --- a/man/names-set-.datatagr.Rd +++ b/man/names-set-.safeframe.Rd @@ -1,26 +1,27 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/names.R -\name{names<-.datatagr} -\alias{names<-.datatagr} -\title{Rename columns of a datatagr} +\name{names<-.safeframe} +\alias{names<-.safeframe} +\title{Rename columns of a safeframe} \usage{ -\method{names}{datatagr}(x) <- value +\method{names}{safeframe}(x) <- value } \arguments{ -\item{x}{a \code{datatagr} object} +\item{x}{a \code{safeframe} object} \item{value}{a \code{character} vector to set the new names of the columns of \code{x}} } \value{ -a \code{datatagr} with new column names +a \code{safeframe} with new column names } \description{ -This function can be used to rename the columns a \code{datatagr} (that is, adjust +This function can be used to rename the columns a \code{safeframe} (that is, +adjust variable names). } \examples{ -## create datatagr -x <- make_datatagr(cars, +## create safeframe +x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles" ) diff --git a/man/print.datatagr.Rd b/man/print.safeframe.Rd similarity index 60% rename from man/print.datatagr.Rd rename to man/print.safeframe.Rd index 10baf6d..2505ad0 100644 --- a/man/print.datatagr.Rd +++ b/man/print.safeframe.Rd @@ -1,13 +1,13 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/print.datatagr.R -\name{print.datatagr} -\alias{print.datatagr} -\title{Printing method for datatagr objects} +% Please edit documentation in R/print.safeframe.R +\name{print.safeframe} +\alias{print.safeframe} +\title{Printing method for safeframe objects} \usage{ -\method{print}{datatagr}(x, ...) +\method{print}{safeframe}(x, ...) } \arguments{ -\item{x}{a \code{datatagr} object} +\item{x}{a \code{safeframe} object} \item{...}{further arguments to be passed to 'print'} } @@ -15,11 +15,11 @@ Invisibly returns the object. } \description{ -This function prints datatagr objects. +This function prints safeframe objects. } \examples{ -## create datatagr -x <- make_datatagr(cars, +## create safeframe +x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles" ) @@ -31,7 +31,7 @@ head(x) if (require(tibble) && require(magrittr)) { cars \%>\% tibble() \%>\% - make_datatagr( + make_safeframe( speed = "Miles per hour", dist = "Distance in miles" ) diff --git a/man/datatagr-package.Rd b/man/safeframe-package.Rd similarity index 73% rename from man/datatagr-package.Rd rename to man/safeframe-package.Rd index 6ff3b1a..5cd0e9e 100644 --- a/man/datatagr-package.Rd +++ b/man/safeframe-package.Rd @@ -1,13 +1,13 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/datatagr-package.R +% Please edit documentation in R/safeframe-package.R \docType{package} -\name{datatagr-package} -\alias{datatagr-package} -\alias{datatagr} +\name{safeframe-package} +\alias{safeframe-package} +\alias{safeframe} \title{Base Tools for Labelling and Validating Data} \description{ -The \pkg{datatagr} package provides tools to help label and validate data. -The 'datatagr' class adds column level attributes to a 'data.frame'. +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, making data pipelines more robust and reliable. } @@ -19,10 +19,10 @@ not preserve labels. We only provide compatibility for \code{\link[dplyr:rename] \section{Main functions}{ \itemize{ -\item \code{\link[=make_datatagr]{make_datatagr()}}: to create \code{datatagr} 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{datatagr} -\item \code{\link[=labels]{labels()}}: to get the list of labels of a \code{datatagr} +\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[=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 @@ -36,15 +36,15 @@ where labelled variables are lost Specific methods commonly used to handle \code{data.frame} are provided for -\code{datatagr} objects, typically to help flag or prevent actions which could +\code{safeframe} objects, typically to help flag or prevent actions which could alter or lose labelled 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_datatagr}): will adopt the +\item \verb{x[...] <-} and \verb{x[[...]] <-} (see \link{sub_safeframe}): will adopt the desired behaviour when labelled variables are lost -\item \code{print()}: prints info about the \code{datatagr} in addition to the +\item \code{print()}: prints info about the \code{safeframe} in addition to the \code{data.frame} or \code{tibble} } } @@ -52,7 +52,7 @@ desired behaviour when labelled variables are lost \examples{ # using base R style -x <- make_datatagr(cars[1:50, ], +x <- make_safeframe(cars[1:50, ], speed = "Miles per hour", dist = "Distance in miles" ) @@ -81,13 +81,13 @@ lost_labels_action() # using tidyverse style -## example of creating a datatagr, adding a new variable, and adding a label +## example of creating a safeframe, adding a new variable, and adding a label ## for it if (require(dplyr) && require(magrittr)) { x <- cars \%>\% tibble() \%>\% - make_datatagr( + make_safeframe( speed = "Miles per hour", dist = "Distance in miles" ) \%>\% @@ -113,9 +113,9 @@ if (require(dplyr) && require(magrittr)) { \seealso{ Useful links: \itemize{ - \item \url{https://epiverse-trace.github.io/datatagr/} - \item \url{https://github.com/epiverse-trace/datatagr} - \item Report bugs at \url{https://github.com/epiverse-trace/datatagr/issues} + \item \url{https://epiverse-trace.github.io/safeframe/} + \item \url{https://github.com/epiverse-trace/safeframe} + \item Report bugs at \url{https://github.com/epiverse-trace/safeframe/issues} } } diff --git a/man/set_labels.Rd b/man/set_labels.Rd index aa24792..88e1f14 100644 --- a/man/set_labels.Rd +++ b/man/set_labels.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/set_labels.R \name{set_labels} \alias{set_labels} -\title{Change labels of a datatagr object} +\title{Change labels of a safeframe object} \usage{ set_labels(x, ...) } @@ -15,16 +15,16 @@ names in \code{x} as list names and the labels as list values. Values set to \code{default_values}.} } \value{ -The function returns a \code{datatagr} object. +The function returns a \code{safeframe} object. } \description{ -This function changes the \code{labels} of a \code{datatagr} object, using the same -syntax as the constructor \code{\link[=make_datatagr]{make_datatagr()}}. +This function changes the \code{labels} of a \code{safeframe} object, using the same +syntax as the constructor \code{\link[=make_safeframe]{make_safeframe()}}. } \examples{ -## create a datatagr -x <- make_datatagr(cars, speed = "Miles per hour") +## create a safeframe +x <- make_safeframe(cars, speed = "Miles per hour") labels(x) ## add new labels and fix an existing one @@ -41,5 +41,5 @@ x <- set_labels(x, !!!old_labels) labels(x) } \seealso{ -\code{\link[=make_datatagr]{make_datatagr()}} to create a \code{datatagr} object +\code{\link[=make_safeframe]{make_safeframe()}} to create a \code{safeframe} object } diff --git a/man/sub_datatagr.Rd b/man/sub_safeframe.Rd similarity index 60% rename from man/sub_datatagr.Rd rename to man/sub_safeframe.Rd index 73b6014..ef3103a 100644 --- a/man/sub_datatagr.Rd +++ b/man/sub_safeframe.Rd @@ -1,33 +1,33 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/square_bracket.R -\name{[.datatagr} -\alias{[.datatagr} -\alias{sub_datatagr} -\alias{[<-.datatagr} -\alias{[[<-.datatagr} -\alias{$<-.datatagr} -\title{Subsetting of datatagr objects} +\name{[.safeframe} +\alias{[.safeframe} +\alias{sub_safeframe} +\alias{[<-.safeframe} +\alias{[[<-.safeframe} +\alias{$<-.safeframe} +\title{Subsetting of safeframe objects} \usage{ -\method{[}{datatagr}(x, i, j, drop = FALSE) +\method{[}{safeframe}(x, i, j, drop = FALSE) -\method{[}{datatagr}(x, i, j) <- value +\method{[}{safeframe}(x, i, j) <- value -\method{[[}{datatagr}(x, i, j) <- value +\method{[[}{safeframe}(x, i, j) <- value -\method{$}{datatagr}(x, name) <- value +\method{$}{safeframe}(x, name) <- value } \arguments{ -\item{x}{a \code{datatagr} object} +\item{x}{a \code{safeframe} object} \item{i}{a vector of \code{integer} or \code{logical} to subset the rows of the -\code{datatagr}} +\code{safeframe}} \item{j}{a vector of \code{character}, \code{integer}, or \code{logical} to subset the -columns of the \code{datatagr}} +columns of the \code{safeframe}} \item{drop}{a \code{logical} indicating if, when a single column is selected, the \code{data.frame} class should be dropped to return a simple vector, in which -case the \code{datatagr} class is lost as well; defaults to \code{FALSE}} +case the \code{safeframe} class is lost as well; defaults to \code{FALSE}} \item{value}{the replacement to be used for the entries identified in \code{x}} @@ -39,19 +39,19 @@ case the \code{datatagr} class is lost as well; defaults to \code{FALSE}} } } \value{ -If no drop is happening, a \code{datatagr}. Otherwise an atomic vector. +If no drop is happening, a \code{safeframe}. Otherwise an atomic vector. } \description{ -The \verb{[]} and \verb{[[]]} operators for \code{datatagr} objects behaves like for regular -\code{data.frame} or \code{tibble}, but check that labelled 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()}}) . +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 +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()}}) . } \examples{ if (require(dplyr) && require(magrittr)) { - ## create a datatagr + ## create a safeframe x <- cars \%>\% - make_datatagr( + make_safeframe( speed = "Miles per hour", dist = "Distance in miles" ) \%>\% diff --git a/man/type.Rd b/man/type.Rd index a6d3c13..44acbe7 100644 --- a/man/type.Rd +++ b/man/type.Rd @@ -16,10 +16,10 @@ A vector of classes \description{ Function to swiftly provide access to generic categories of types within R. These can be used to provide comprehensive typesetting when creating a -\code{datatagr} object. +\code{safeframe} object. } \examples{ -x <- make_datatagr(cars, +x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles" ) diff --git a/man/validate_labels.Rd b/man/validate_labels.Rd index f633942..67357f1 100644 --- a/man/validate_labels.Rd +++ b/man/validate_labels.Rd @@ -2,36 +2,36 @@ % Please edit documentation in R/validate_labels.R \name{validate_labels} \alias{validate_labels} -\title{Checks the labels of a datatagr object} +\title{Checks the labels of a safeframe object} \usage{ validate_labels(x) } \arguments{ -\item{x}{a \code{datatagr} object} +\item{x}{a \code{safeframe} object} } \value{ -If checks pass, a \code{datatagr} object; otherwise issues an error. +If checks pass, a \code{safeframe} object; otherwise issues an error. } \description{ -This function evaluates the validity of the labels of a \code{datatagr} object by +This function evaluates the validity of the labels of a \code{safeframe} object by checking that: i) labels are present ii) labels is a \code{list} of \code{character} or \code{NULL} values. } \examples{ -## create a valid datatagr +## create a valid safeframe x <- cars |> - make_datatagr( + make_safeframe( speed = "Miles per hour", dist = "Distance in miles" ) x -## the below issues an error as datatagr doesn't know any defaults +## the below issues an error as safeframe doesn't know any defaults ## note: tryCatch is only used to avoid a genuine error in the example -tryCatch(validate_datatagr(x), error = paste) +tryCatch(validate_safeframe(x), error = paste) ## validation requires you to specify the types directly -validate_datatagr(x, +validate_safeframe(x, speed = c("integer", "numeric"), dist = "numeric" ) diff --git a/man/validate_datatagr.Rd b/man/validate_safeframe.Rd similarity index 70% rename from man/validate_datatagr.Rd rename to man/validate_safeframe.Rd index d42789a..c6cab68 100644 --- a/man/validate_datatagr.Rd +++ b/man/validate_safeframe.Rd @@ -1,22 +1,22 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/validate_datatagr.R -\name{validate_datatagr} -\alias{validate_datatagr} -\title{Checks the content of a datatagr object} +% Please edit documentation in R/validate_safeframe.R +\name{validate_safeframe} +\alias{validate_safeframe} +\title{Checks the content of a safeframe object} \usage{ -validate_datatagr(x, ...) +validate_safeframe(x, ...) } \arguments{ -\item{x}{a \code{datatagr} object} +\item{x}{a \code{safeframe} object} \item{...}{<\code{\link[rlang:dyn-dots]{dynamic-dots}}> A named list with variable names in \code{x} as list names and the related types as list values.} } \value{ -If checks pass, a \code{datatagr} object; otherwise issues an error. +If checks pass, a \code{safeframe} object; otherwise issues an error. } \description{ -This function evaluates the validity of a \code{datatagr} object by checking the +This function evaluates the validity of a \code{safeframe} object by checking the object class, its labels, and the types of variables. It combines validation checks made by \code{\link[=validate_types]{validate_types()}} and \code{\link[=validate_labels]{validate_labels()}}. See 'Details' section for more information on the checks performed. @@ -24,30 +24,30 @@ validation checks made by \code{\link[=validate_types]{validate_types()}} and \c \details{ The following checks are performed: \itemize{ -\item \code{x} is a \code{datatagr} object +\item \code{x} is a \code{safeframe} object \item variables in \code{x} have a well-formed \code{label} attribute \item variables correspond to the specified types } } \examples{ -## create a valid datatagr +## create a valid safeframe x <- cars |> - make_datatagr( + make_safeframe( speed = "Miles per hour", dist = "Distance in miles" ) x ## validation -validate_datatagr(x, +validate_safeframe(x, speed = c("numeric", "factor"), dist = "numeric" ) ## the below issues an error ## note: tryCatch is only used to avoid a genuine error in the example -tryCatch(validate_datatagr(x, +tryCatch(validate_safeframe(x, speed = c("numeric", "factor"), dist = "factor" ), error = paste) diff --git a/man/validate_types.Rd b/man/validate_types.Rd index 8c9ad0d..a613931 100644 --- a/man/validate_types.Rd +++ b/man/validate_types.Rd @@ -7,7 +7,7 @@ validate_types(x, ...) } \arguments{ -\item{x}{a \code{datatagr} object} +\item{x}{a \code{safeframe} object} \item{...}{<\code{\link[rlang:dyn-dots]{dynamic-dots}}> A named list with variable names in \code{x} as list names and the related types as list values.} @@ -16,12 +16,12 @@ names in \code{x} as list names and the related types as list values.} A named \code{list}. } \description{ -This function checks the type of variables in a \code{datatagr} against +This function checks the type of variables in a \code{safeframe} against accepted classes. Only checks the type of provided variables and ignores those not provided. } \examples{ -x <- make_datatagr(cars, +x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles" ) @@ -41,6 +41,6 @@ validate_types(x, speed = "numeric", dist = c( \seealso{ \itemize{ \item \code{\link[=validate_labels]{validate_labels()}} to perform a series of checks on variables -\item \code{\link[=validate_datatagr]{validate_datatagr()}} to combine \code{validate_labels} and \code{validate_types} +\item \code{\link[=validate_safeframe]{validate_safeframe()}} to combine \code{validate_labels} and \code{validate_types} } } diff --git a/datatagr.Rproj b/safeframe.Rproj similarity index 100% rename from datatagr.Rproj rename to safeframe.Rproj diff --git a/tests/testthat.R b/tests/testthat.R index 8dba9a3..3070b4a 100644 --- a/tests/testthat.R +++ b/tests/testthat.R @@ -7,6 +7,6 @@ # * https://testthat.r-lib.org/articles/special-files.html library(testthat) -library(datatagr) +library(safeframe) -test_check("datatagr", stop_on_warning = FALSE) +test_check("safeframe", stop_on_warning = FALSE) diff --git a/tests/testthat/_snaps/print.md b/tests/testthat/_snaps/print.md index 649505f..62e1460 100644 --- a/tests/testthat/_snaps/print.md +++ b/tests/testthat/_snaps/print.md @@ -1,7 +1,7 @@ -# tests for print.datatagr +# tests for print.safeframe - // datatagr object + // safeframe object speed dist 1 4 2 2 4 10 @@ -61,7 +61,7 @@ --- - // datatagr object + // safeframe object speed dist 1 4 2 2 4 10 diff --git a/tests/testthat/_snaps/set_labels.md b/tests/testthat/_snaps/set_labels.md index be1c663..0a561a3 100644 --- a/tests/testthat/_snaps/set_labels.md +++ b/tests/testthat/_snaps/set_labels.md @@ -4,7 +4,7 @@ set_labels(cars) Condition Error in `set_labels()`: - ! Assertion on 'x' failed: Must inherit from class 'datatagr', but has class 'data.frame'. + ! Assertion on 'x' failed: Must inherit from class 'safeframe', but has class 'data.frame'. --- diff --git a/tests/testthat/test-compat-dplyr.R b/tests/testthat/test-compat-dplyr.R index bf1e120..529043b 100644 --- a/tests/testthat/test-compat-dplyr.R +++ b/tests/testthat/test-compat-dplyr.R @@ -1,15 +1,15 @@ skip_if_not_installed("dplyr") -x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") +x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") # Rows ---- test_that("Compatibility with dplyr::arrange()", { ordered_x <- expect_no_warning(dplyr::arrange(x, dist)) - expect_s3_class(ordered_x, "datatagr") + expect_s3_class(ordered_x, "safeframe") expect_identical( - drop_datatagr(ordered_x), + drop_safeframe(ordered_x), dplyr::arrange(cars, dist) ) }) @@ -38,7 +38,7 @@ test_that("Compatibility with dplyr::filter()", { test_that("Compatibility with dplyr::slice()", { x %>% dplyr::slice(5:10) %>% - expect_s3_class("datatagr") %>% + expect_s3_class("safeframe") %>% dim() %>% expect_identical(c(6L, ncol(x))) }) @@ -48,7 +48,7 @@ test_that("Compatibility with dplyr::slice()", { test_that("Compatibility with dplyr::transmute()", { x %>% dplyr::transmute(vitesse = speed) %>% - expect_s3_class("datatagr") %>% + expect_s3_class("safeframe") %>% expect_snapshot_warning() }) @@ -58,7 +58,7 @@ test_that("Compatibility with dplyr::mutate(.keep)", { # labels as it does in the rename() case. x %>% dplyr::mutate(vitesse = speed, .keep = "unused") %>% - expect_s3_class("datatagr") %>% + expect_s3_class("safeframe") %>% expect_snapshot_warning() }) @@ -130,7 +130,7 @@ test_that("Compatibility with dplyr::rename_with()", { test_that("Compatibility with dplyr::select()", { x %>% dplyr::select("dist") %>% - expect_s3_class("datatagr") %>% + expect_s3_class("safeframe") %>% labels() %>% expect_identical(list(dist = "Distance in miles")) %>% expect_snapshot_warning() @@ -138,7 +138,7 @@ test_that("Compatibility with dplyr::select()", { # Even when renames happen x %>% dplyr::select(dist, vitesse = speed) %>% - expect_s3_class("datatagr") %>% + expect_s3_class("safeframe") %>% labels() %>% expect_identical(list( dist = "Distance in miles", @@ -153,6 +153,6 @@ test_that("Compatibility with dplyr::bind_rows()", { expect_s3_class( x, - "datatagr" + "safeframe" ) }) diff --git a/tests/testthat/test-drop_datatagr.R b/tests/testthat/test-drop_datatagr.R deleted file mode 100644 index e379e99..0000000 --- a/tests/testthat/test-drop_datatagr.R +++ /dev/null @@ -1,8 +0,0 @@ -test_that("tests for drop_datatagr", { - x <- make_datatagr(cars, speed = "Miles per hour") - expect_identical(cars, drop_datatagr(x, remove_labels = TRUE)) - - y <- drop_datatagr(x, remove_labels = FALSE) - expect_identical(labels(x, TRUE)$speed, attr(y$speed, "label")) - expect_identical(labels(x, TRUE)$dist, attr(y$dist, "label")) -}) diff --git a/tests/testthat/test-drop_safeframe.R b/tests/testthat/test-drop_safeframe.R new file mode 100644 index 0000000..fdd1eb7 --- /dev/null +++ b/tests/testthat/test-drop_safeframe.R @@ -0,0 +1,8 @@ +test_that("tests for drop_safeframe", { + x <- make_safeframe(cars, speed = "Miles per hour") + expect_identical(cars, drop_safeframe(x, remove_labels = TRUE)) + + y <- drop_safeframe(x, remove_labels = FALSE) + expect_identical(labels(x, TRUE)$speed, attr(y$speed, "label")) + expect_identical(labels(x, TRUE)$dist, attr(y$dist, "label")) +}) diff --git a/tests/testthat/test-labels.R b/tests/testthat/test-labels.R index 24dc21d..358a504 100644 --- a/tests/testthat/test-labels.R +++ b/tests/testthat/test-labels.R @@ -1,6 +1,6 @@ test_that("tests for labels", { # Check error messages - x <- make_datatagr(cars, speed = "Miles per hour") + x <- make_safeframe(cars, speed = "Miles per hour") # Check functionality expect_identical(labels(x), list(speed = "Miles per hour")) @@ -11,8 +11,8 @@ test_that("tests for labels", { # labels() returns an empty named list, which we cannot compare to list() # directly. - expect_identical(length(labels(make_datatagr(cars))), length(list())) - expect_identical(labels(make_datatagr(cars), TRUE), list( + expect_identical(length(labels(make_safeframe(cars))), length(list())) + expect_identical(labels(make_safeframe(cars), TRUE), list( speed = NULL, dist = NULL )) diff --git a/tests/testthat/test-labels_df.R b/tests/testthat/test-labels_df.R index 5781b1a..c35f43f 100644 --- a/tests/testthat/test-labels_df.R +++ b/tests/testthat/test-labels_df.R @@ -1,6 +1,6 @@ test_that("tests for labels_df without unlabeled variables", { # These are now order dependent for the tests - x <- make_datatagr(cars, + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles" ) @@ -8,7 +8,7 @@ test_that("tests for labels_df without unlabeled variables", { names(y) <- c("Miles per hour", "Distance in miles") # errors - msg <- "Must inherit from class 'datatagr', but has class 'data.frame'." + msg <- "Must inherit from class 'safeframe', but has class 'data.frame'." expect_error(labels_df(cars), msg) # functionality @@ -17,7 +17,7 @@ test_that("tests for labels_df without unlabeled variables", { test_that("labels_df with unlabeled variables works as expected", { - x <- make_datatagr(cars, + x <- make_safeframe(cars, dist = "Distance in miles" ) y <- cars[c("speed", "dist")] diff --git a/tests/testthat/test-make_datatagr.R b/tests/testthat/test-make_datatagr.R deleted file mode 100644 index a2cd95c..0000000 --- a/tests/testthat/test-make_datatagr.R +++ /dev/null @@ -1,58 +0,0 @@ -test_that("tests for make_datatagr", { - # test errors - msg <- "Must be of type 'data.frame', not 'NULL'." - expect_error(make_datatagr(NULL), msg) - - msg <- "Must have at least 1 cols, but has 0 cols." - expect_error(make_datatagr(data.frame()), msg) - - msg <- "* Variable 'namedLabel': Must be element of set {'speed','dist'}, but" - expect_error(make_datatagr(cars, outcome = "bar"), msg, fixed = TRUE) - - expect_error( - make_datatagr(cars, outcome = "bar", age = "bla"), - "2 assertions failed" - ) - - # test functionalities - expect_identical( - list(speed = NULL, dist = NULL), - labels(make_datatagr(cars), TRUE) - ) - - x <- make_datatagr(cars, dist = "Date onset", speed = "Date outcome") - expect_identical(labels(x)$dist, "Date onset") - expect_identical(labels(x)$speed, "Date outcome") - expect_null(labels(x)$"Date onset") - expect_null(labels(x)$"Date outcome") - - x <- make_datatagr(cars, speed = "foo", dist = "bar") - expect_identical( - labels(x, TRUE), - c(list(), speed = "foo", dist = "bar") - ) -}) - -test_that("make_datatagr() works with dynamic dots", { - expect_identical( - make_datatagr(cars, dist = "date_onset", speed = "date_outcome"), - make_datatagr(cars, !!!list(dist = "date_onset", speed = "date_outcome")) - ) -}) - -test_that("make_datatagr() errors on data.table input", { - dt_cars <- structure( - cars, - class = c("data.table", "data.frame") - ) - - expect_error( - make_datatagr(dt_cars), - "NOT be a data.table" - ) -}) - -test_that("make_datatagr() works with single & multi-word labels", { - expect_no_condition(make_datatagr(cars, speed = "mph")) - expect_no_condition(make_datatagr(cars, speed = "Miles per hour")) -}) diff --git a/tests/testthat/test-make_safeframe.R b/tests/testthat/test-make_safeframe.R new file mode 100644 index 0000000..4cc2ee7 --- /dev/null +++ b/tests/testthat/test-make_safeframe.R @@ -0,0 +1,58 @@ +test_that("tests for make_safeframe", { + # test errors + msg <- "Must be of type 'data.frame', not 'NULL'." + expect_error(make_safeframe(NULL), msg) + + msg <- "Must have at least 1 cols, but has 0 cols." + expect_error(make_safeframe(data.frame()), msg) + + msg <- "* Variable 'namedLabel': Must be element of set {'speed','dist'}, but" + expect_error(make_safeframe(cars, outcome = "bar"), msg, fixed = TRUE) + + expect_error( + make_safeframe(cars, outcome = "bar", age = "bla"), + "2 assertions failed" + ) + + # test functionalities + expect_identical( + list(speed = NULL, dist = NULL), + labels(make_safeframe(cars), TRUE) + ) + + x <- make_safeframe(cars, dist = "Date onset", speed = "Date outcome") + expect_identical(labels(x)$dist, "Date onset") + expect_identical(labels(x)$speed, "Date outcome") + expect_null(labels(x)$"Date onset") + expect_null(labels(x)$"Date outcome") + + x <- make_safeframe(cars, speed = "foo", dist = "bar") + expect_identical( + labels(x, TRUE), + c(list(), speed = "foo", dist = "bar") + ) +}) + +test_that("make_safeframe() works with dynamic dots", { + expect_identical( + make_safeframe(cars, dist = "date_onset", speed = "date_outcome"), + make_safeframe(cars, !!!list(dist = "date_onset", speed = "date_outcome")) + ) +}) + +test_that("make_safeframe() errors on data.table input", { + dt_cars <- structure( + cars, + class = c("data.table", "data.frame") + ) + + expect_error( + make_safeframe(dt_cars), + "NOT be a data.table" + ) +}) + +test_that("make_safeframe() works with single & multi-word labels", { + expect_no_condition(make_safeframe(cars, speed = "mph")) + expect_no_condition(make_safeframe(cars, speed = "Miles per hour")) +}) diff --git a/tests/testthat/test-names.R b/tests/testthat/test-names.R index c66d434..2722759 100644 --- a/tests/testthat/test-names.R +++ b/tests/testthat/test-names.R @@ -1,5 +1,5 @@ test_that("tests for the names<- operator", { - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") old_x <- x old_class <- class(x) old_names <- names(x) diff --git a/tests/testthat/test-print.R b/tests/testthat/test-print.R index 40d71f8..e7cd69a 100644 --- a/tests/testthat/test-print.R +++ b/tests/testthat/test-print.R @@ -1,7 +1,7 @@ -test_that("tests for print.datatagr", { - x <- make_datatagr(cars, dist = "Distance in miles", speed = "Miles per hour") +test_that("tests for print.safeframe", { + x <- make_safeframe(cars, dist = "Distance in miles", speed = "Miles per hour") expect_snapshot_output(print(x)) - y <- make_datatagr(cars) + y <- make_safeframe(cars) expect_snapshot_output(print(y)) }) diff --git a/tests/testthat/test-restore_labels.R b/tests/testthat/test-restore_labels.R index 1a3052d..b81daba 100644 --- a/tests/testthat/test-restore_labels.R +++ b/tests/testthat/test-restore_labels.R @@ -1,7 +1,7 @@ test_that("tests for restore_labels", { # These are now order dependent for the tests - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") - y <- drop_datatagr(x) + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") + y <- drop_safeframe(x) z <- y names(z) <- c("titi", "toto") @@ -16,13 +16,13 @@ test_that("tests for restore_labels", { expect_identical(x, restore_labels(y, labels(x))) # Classes are correct for different operator use - expect_equal(class(x), c("datatagr", "data.frame")) + expect_equal(class(x), c("safeframe", "data.frame")) y <- restore_labels(y, labels(x)) - expect_equal(class(y), c("datatagr", "data.frame")) + expect_equal(class(y), c("safeframe", "data.frame")) x[[1]] <- "test" - expect_equal(class(x), c("datatagr", "data.frame")) + expect_equal(class(x), c("safeframe", "data.frame")) x[1] <- "test2" - expect_equal(class(x), c("datatagr", "data.frame")) + expect_equal(class(x), c("safeframe", "data.frame")) x$speed <- "test3" - expect_equal(class(x), c("datatagr", "data.frame")) + expect_equal(class(x), c("safeframe", "data.frame")) }) diff --git a/tests/testthat/test-set_labels.R b/tests/testthat/test-set_labels.R index 4410498..4f4c7e5 100644 --- a/tests/testthat/test-set_labels.R +++ b/tests/testthat/test-set_labels.R @@ -1,5 +1,5 @@ test_that("tests for set_labels()", { - x <- make_datatagr(cars, dist = "Distance") + x <- make_safeframe(cars, dist = "Distance") # Check whether error messages are the same as before # Uses snapshot to prevent formatting issues in validating the error message diff --git a/tests/testthat/test-square_bracket.R b/tests/testthat/test-square_bracket.R index 8a953f0..8abacc4 100644 --- a/tests/testthat/test-square_bracket.R +++ b/tests/testthat/test-square_bracket.R @@ -1,7 +1,7 @@ library(dplyr) test_that("tests for [ operator", { - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") on.exit(lost_labels_action()) # errors @@ -24,7 +24,7 @@ test_that("tests for [ operator", { expect_identical(x[, 1, drop = TRUE], cars[, 1]) lost_labels_action("none", quiet = TRUE) - expect_identical(x[, 1], make_datatagr(cars[, 1, drop = FALSE], speed = "Miles per hour")) + expect_identical(x[, 1], make_safeframe(cars[, 1, drop = FALSE], speed = "Miles per hour")) # [ behaves exactly as in the simple data.frame case, including when subset # only cols. https://github.com/epiverse-trace/linelist/issues/51 @@ -59,12 +59,12 @@ test_that("tests for [<- operator", { # errors lost_labels_action("warning", quiet = TRUE) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") msg <- "The following labelled variables are lost:\n speed - Miles per hour" expect_warning(x[, 1] <- NULL, msg) lost_labels_action("error", quiet = TRUE) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") msg <- "The following labelled variables are lost:\n speed - Miles per hour" expect_error(x[, 1] <- NULL, msg) @@ -73,11 +73,11 @@ test_that("tests for [<- operator", { expect_identical(x$speed[1:3], rep(1, 3)) lost_labels_action("none", quiet = TRUE) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") x[, 1:2] <- NULL expect_identical(ncol(x), 0L) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") x[, 1] <- "test1" # should update the values # Should maintain the label @@ -87,7 +87,7 @@ test_that("tests for [<- operator", { expect_identical(attr(x$speed, "label"), "Test label assignment 1") # should not activate the lost_action - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") x[1] <- "test2" # should update the values # Should maintain the label @@ -99,7 +99,7 @@ test_that("tests for [<- operator", { }) test_that("[<- allows innocuous label modification", { - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") expect_no_condition(x[1] <- 1L) y <- rep(1L, nrow(x)) attr(y, "label") <- "Miles per hour" @@ -111,22 +111,22 @@ test_that("tests for [[<- operator", { # errors lost_labels_action("warning", quiet = TRUE) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") expect_snapshot_warning(x[[1]] <- NULL) lost_labels_action("error", quiet = TRUE) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") expect_snapshot_error(x[[1]] <- NULL) # functionalities - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") x[[1]] <- 1L y <- rep(1L, nrow(x)) attr(y, "label") <- "Miles per hour" expect_identical(x$speed, y) lost_labels_action("none", quiet = TRUE) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") x[[2]] <- NULL x[[1]] <- NULL expect_identical(ncol(x), 0L) @@ -137,24 +137,24 @@ test_that("$<- operator detects label loss", { # errors lost_labels_action("warning", quiet = TRUE) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") msg <- "The following labelled variables are lost:\n speed - Miles per hour" expect_warning(x$speed <- NULL, msg) lost_labels_action("error", quiet = TRUE) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") msg <- "The following labelled variables are lost:\n speed - Miles per hour" expect_error(x$speed <- NULL, msg) lost_labels_action("none", quiet = TRUE) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") x$speed <- NULL x$dist <- NULL expect_identical(ncol(x), 0L) }) test_that("$<- allows innocuous label modification", { - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") expect_no_condition(x$speed <- 1L) y <- rep(1L, nrow(x)) attr(y, "label") <- "Miles per hour" diff --git a/tests/testthat/test-type.R b/tests/testthat/test-type.R index 798f2cd..2287372 100644 --- a/tests/testthat/test-type.R +++ b/tests/testthat/test-type.R @@ -20,7 +20,7 @@ test_that("type() returns all options as expected", { }) test_that("type() works nicely when combined with validate_types()", { - x <- make_datatagr(cars, + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles" ) diff --git a/tests/testthat/test-validate_datatagr.R b/tests/testthat/test-validate_datatagr.R index 075b158..05a9fb2 100644 --- a/tests/testthat/test-validate_datatagr.R +++ b/tests/testthat/test-validate_datatagr.R @@ -1,19 +1,19 @@ -test_that("tests for validate_datatagr", { +test_that("tests for validate_safeframe", { # errors - msg <- "Must inherit from class 'datatagr', but has class 'NULL'." - expect_error(validate_datatagr(NULL), msg) + msg <- "Must inherit from class 'safeframe', but has class 'NULL'." + expect_error(validate_safeframe(NULL), msg) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") msg <- "Assertion on 'types' failed: Must have length >= 1, but has length 0." - expect_error(validate_datatagr(x), msg) - expect_identical(x, validate_datatagr(x, + expect_error(validate_safeframe(x), msg) + expect_identical(x, validate_safeframe(x, speed = "numeric", dist = "numeric" )) - x <- make_datatagr(cars, speed = "Miles per hour") + x <- make_safeframe(cars, speed = "Miles per hour") expect_error( - validate_datatagr(x, speed = c( + validate_safeframe(x, speed = c( "character", "factor" )), @@ -21,7 +21,7 @@ test_that("tests for validate_datatagr", { ) # Functionalities - x <- make_datatagr(cars) + x <- make_safeframe(cars) msg <- "`x` has no labels" - expect_error(validate_datatagr(x), msg) + expect_error(validate_safeframe(x), msg) }) diff --git a/tests/testthat/test-validate_labels.R b/tests/testthat/test-validate_labels.R index fdf7f10..87a1a57 100644 --- a/tests/testthat/test-validate_labels.R +++ b/tests/testthat/test-validate_labels.R @@ -1,14 +1,14 @@ test_that("tests for validate_labels", { # test errors - msg <- "Must inherit from class 'datatagr', but has class 'data.frame'." + msg <- "Must inherit from class 'safeframe', but has class 'data.frame'." expect_error(validate_labels(cars), msg) - x <- make_datatagr(cars) + x <- make_safeframe(cars) msg <- "`x` has no labels" expect_error(validate_labels(x), msg) # functionalities - x <- make_datatagr(cars) + x <- make_safeframe(cars) expect_error(validate_labels(x)) x <- set_labels(x, dist = "Distance in miles", speed = "Miles per hour") diff --git a/tests/testthat/test-validate_types.R b/tests/testthat/test-validate_types.R index f79c70e..a0ee664 100644 --- a/tests/testthat/test-validate_types.R +++ b/tests/testthat/test-validate_types.R @@ -1,13 +1,13 @@ test_that("tests for validate_types() basic input checking", { expect_error( validate_types(cars), - "Must inherit from class 'datatagr', but has class 'data.frame'." + "Must inherit from class 'safeframe', but has class 'data.frame'." ) }) test_that("validate_types() validates types", { # Successful validations - x <- make_datatagr(cars, speed = "Miles per hour") + x <- make_safeframe(cars, speed = "Miles per hour") expect_silent( expect_identical( x, @@ -16,20 +16,20 @@ test_that("validate_types() validates types", { ) # Failed validations - x <- make_datatagr(cars, speed = "Miles per hour") + x <- make_safeframe(cars, speed = "Miles per hour") expect_error( validate_types(x, speed = "factor"), "speed: Must inherit from class 'factor', but has class 'numeric'" ) - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") expect_snapshot_error( validate_types(x, speed = "factor", dist = "character") ) }) test_that("ensure validate_types throws error if no types provided", { - x <- make_datatagr(cars, speed = "Miles per hour", dist = "Distance in miles") + x <- make_safeframe(cars, speed = "Miles per hour", dist = "Distance in miles") expect_error( validate_types(x), "Assertion on 'types' failed: Must have length >= 1, but has length 0." diff --git a/tests/testthat/test-zzz.R b/tests/testthat/test-zzz.R index 5448f82..b77636c 100644 --- a/tests/testthat/test-zzz.R +++ b/tests/testthat/test-zzz.R @@ -4,7 +4,7 @@ test_that("tests for zzz", { # We need to use callr to avoid conflicts with other tests res <- callr::r( function() { - library(datatagr) + library(safeframe) get_lost_labels_action() } ) @@ -15,10 +15,10 @@ test_that("Environment variable is used for initial `lost_labels_action`", { # We need to use callr to avoid conflicts with other tests res <- callr::r( function() { - library(datatagr) + library(safeframe) get_lost_labels_action() }, - env = c(DATATAGR_LOST_ACTION = "error") + env = c(SAFEFRAME_LOST_ACTION = "error") ) expect_identical(res, "error") }) diff --git a/vignettes/compat-dplyr.Rmd b/vignettes/compat-dplyr.Rmd index fb93c38..41a89ff 100644 --- a/vignettes/compat-dplyr.Rmd +++ b/vignettes/compat-dplyr.Rmd @@ -14,15 +14,15 @@ knitr::opts_chunk$set( ) ``` -**datatagr** philosophy is to prevent you from accidentally losing valuable data, but to otherwise be totally transparent and not to interfere with your workflow. +**safeframe** philosophy is to prevent you from accidentally losing valuable data, but to otherwise be totally transparent and not to interfere with your workflow. -One popular ecosystem for data science workflow is the **tidyverse**. We try to ensure decent datatagr compatibility with the tidyverse. All dplyr verbs are tested in the `tests/test-compat-dplyr.R` file. +One popular ecosystem for data science workflow is the **tidyverse**. We try to ensure decent safeframe compatibility with the tidyverse. All dplyr verbs are tested in the `tests/test-compat-dplyr.R` file. ```{r} -library(datatagr) +library(safeframe) library(dplyr) -x <- make_datatagr( +x <- make_safeframe( cars, speed = "Miles per hour", dist = "Distance in miles" @@ -33,8 +33,8 @@ head(x) ## Verbs operating on rows -datatagr does not modify anything regarding the behaviour for row-operations. As such, it is fully compatible with dplyr verbs operating on rows out-of-the-box. -You can see in the following examples that datatagr does not produce any errors, warnings or messspeeds and its labels are conserved through dplyr operations on rows. +safeframe does not modify anything regarding the behaviour for row-operations. As such, it is fully compatible with dplyr verbs operating on rows out-of-the-box. +You can see in the following examples that safeframe does not produce any errors, warnings or messspeeds and its labels are conserved through dplyr operations on rows. ### `dplyr::arrange()` ✅ @@ -84,7 +84,7 @@ x %>% ## Verbs operating on columns -During operations on columns, datatagr will: +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 @@ -93,7 +93,7 @@ During operations on columns, datatagr will: There is an incomplete compatibility with `dplyr::mutate()` in that simple renames without any actual modification of the column don't update the labels. In this scenario, users should rather use `dplyr::rename()` -Although `dplyr::mutate()` is not able to leverspeed to full power of datatagr labels, datatagr objects behave as expected the same way a data.frame would: +Although `dplyr::mutate()` is not able to leverspeed to full power of safeframe labels, safeframe objects behave as expected the same way a data.frame would: ```{r} # In place modification doesn't lose labels @@ -114,7 +114,7 @@ x %>% ### `dplyr::pull()` ✅ -`dplyr::pull()` returns a vector, which results, as expected, in the loss of the datatagr class and labels: +`dplyr::pull()` returns a vector, which results, as expected, in the loss of the safeframe class and labels: ```{r} x %>% @@ -132,7 +132,7 @@ x %>% ### `dplyr::rename()` & `dplyr::rename_with()` ✅ -`dplyr::rename()` is fully compatible out-of-the-box with datatagr, meaning that labels will be updated at the same time that columns are renamed. This is possibly because it uses `names<-()` under the hood, which datatagr provides a custom `names<-.datatagr()` method for: +`dplyr::rename()` is fully compatible out-of-the-box with safeframe, meaning that labels will be updated at the same time that columns are renamed. This is possibly because it uses `names<-()` under the hood, which safeframe provides a custom `names<-.safeframe()` method for: ```{r} x %>% @@ -146,7 +146,7 @@ x %>% ### `dplyr::select()` ✅ -`dplyr::select()` is fully compatible with datatagr, including when columns are renamed in a `select()`: +`dplyr::select()` is fully compatible with safeframe, including when columns are renamed in a `select()`: ```{r} # Works fine @@ -162,7 +162,7 @@ x %>% ## Verbs operating on groups ✘ -Groups are not yet supported. Applying any verb operating on group to a datatagr will silently convert it back to a data.frame or tibble. +Groups are not yet supported. Applying any verb operating on group to a safeframe will silently convert it back to a data.frame or tibble. ## Verbs operating on data.frames @@ -176,7 +176,7 @@ dim(bind_rows(x, x)) ### `dplyr::bind_cols()` ✘ -`bind_cols()` is currently incompatible with datatagr: +`bind_cols()` is currently incompatible with safeframe: - labels from the second element are lost - Warnings are produced about lost labels, even for labels that are not actually lost @@ -191,7 +191,7 @@ bind_cols( ### Joins ✘ -Joins are currently not compatible with datatagr as labels from the second element are silently dropped. +Joins are currently not compatible with safeframe as labels from the second element are silently dropped. ```{r} full_join( @@ -213,7 +213,7 @@ x %>% head() ``` -As such, we could expect it to work with datatagr custom tidyselect-like function: `has_label()` but it's not the case since `pick()` currently strips out all attributes, including the `datatagr` class and all labels. +As such, we could expect it to work with safeframe custom tidyselect-like function: `has_label()` but it's not the case since `pick()` currently strips out all attributes, including the `safeframe` class and all labels. This unclassing is documented in `?pick`: > `pick()` returns a data frame containing the selected columns for the current group. diff --git a/vignettes/design-principles.Rmd b/vignettes/design-principles.Rmd index 9ba3684..122c840 100644 --- a/vignettes/design-principles.Rmd +++ b/vignettes/design-principles.Rmd @@ -1,8 +1,8 @@ --- -title: "Design Principles for {datatagr}" +title: "Design Principles for {safeframe}" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{Design Principles for {datatagr}} + %\VignetteIndexEntry{Design Principles for {safeframe}} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -14,7 +14,7 @@ knitr::opts_chunk$set( ) ``` -This vignette outlines the design decisions that have been taken during the development of the `{datatagr}` R package, and provides some of the reasoning, and possible pros and cons of each decision. +This vignette outlines the design decisions that have been taken during the development of the `{safeframe}` R package, and provides some of the reasoning, and possible pros and cons of each decision. This document is primarily intended to be read by those interested in understanding the code within the package and for potential package contributors. @@ -24,7 +24,7 @@ None of the sections are required, feel free to remove any sections not relevant ## Scope -**datatagr** provides generic labelling and validation tools. In contrast to the original versions of **linelist** (`<=v1.1.4`), datatagr functions at the variable level instead of the object level. +**safeframe** provides generic labelling and validation tools. In contrast to the original versions of **linelist** (`<=v1.1.4`), safeframe functions at the variable level instead of the object level. The validation tooling is specific to type checking variables and providing feedback on potential data loss or coercion. It does not aim to do complex validations at this time. @@ -36,9 +36,9 @@ We try to make function names as descriptive as possible, while keeping them sho ## Input/Output/Interoperability -Any data frame object can be passed into **datatagr**. Output from datatagr remains a data frame object, with an additional datatagr class attribute. This means it remains interoperable with all the regular data frame operations one may attempt to do. +Any data frame object can be passed into **safeframe**. Output from safeframe remains a data frame object, with an additional safeframe class attribute. This means it remains interoperable with all the regular data frame operations one may attempt to do. -**datatagr** is interoperable with pipes (that is, `|>` or `%>%`). This allows for easy chaining of functions. Note that there are no guarantees that label attributes are preserved when piping or wrangling in another way. For example, **dplyr** drops variable level attributes when using `dplyr::mutate()`. +**safeframe** is interoperable with pipes (that is, `|>` or `%>%`). This allows for easy chaining of functions. Note that there are no guarantees that label attributes are preserved when piping or wrangling in another way. For example, **dplyr** drops variable level attributes when using `dplyr::mutate()`. ## Design decisions @@ -64,4 +64,4 @@ Any package development has quirks. We outline quirks we are aware of here: ## Development journey -The **datatagr** package is a major refactor of **linelist** `v1.1.4`. The refactor was necessary to make the package more generic and to make the codebase more maintainable. The refactor was completed in a series of steps documented in [#37](https://github.com/epiverse-trace/datatagr/pull/37). +The **safeframe** package is a major refactor of **linelist** `v1.1.4`. The refactor was necessary to make the package more generic and to make the codebase more maintainable. The refactor was completed in a series of steps documented in [#37](https://github.com/epiverse-trace/safeframe/pull/37).