From 557d05ff71d6319b548435a93b0506c07606df57 Mon Sep 17 00:00:00 2001 From: go_gonzo Date: Thu, 26 Sep 2024 12:24:36 +0200 Subject: [PATCH] cleanup and docs --- R/teal_data-show.R | 2 +- R/verify.R | 11 +++++++---- man/verify.Rd | 11 +++++++---- vignettes/teal-data-reproducibility.Rmd | 10 ++++++---- 4 files changed, 21 insertions(+), 13 deletions(-) diff --git a/R/teal_data-show.R b/R/teal_data-show.R index b47f29c10..0be4e4cc0 100644 --- a/R/teal_data-show.R +++ b/R/teal_data-show.R @@ -11,7 +11,7 @@ #' verify(teal_data(x = iris, code = "x = iris")) #' @export setMethod("show", signature = "teal_data", function(object) { - if (object@verified) { + if (is_verified(object)) { cat("\u2705\ufe0e", "verified teal_data object\n") } else { cat("\u2716", "unverified teal_data object\n") diff --git a/R/verify.R b/R/verify.R index 42461b5d0..2abea79b6 100644 --- a/R/verify.R +++ b/R/verify.R @@ -1,12 +1,16 @@ #' Verify code reproducibility #' -#' Checks whether code in `teal_data` object reproduces the stored objects. +#' Listed functions verify if code in [`teal_data`] object reproduces the stored objects. +#' Verification status can be checked by [is_verified()], returning respectively `TRUE` or `FALSE`. #' -#' If objects created by code in the `@code` slo|t of `x` are `all_equal` to the contents of the `@env` slot, -#' the function updates the `@verified` slot to `TRUE` in the returned `teal_data` object. +#' [verify()] checks if objects created by code in the `@code` slot of `x` are `all_equal` to the +#' contents of the `@env` slot, +#' [verify()] updates the `@verified` slot to `TRUE` in the returned `teal_data` object. #' Once verified, the slot will always be set to `TRUE`. #' If the `@code` fails to recreate objects in `teal_data@env`, an error is raised. #' +#' See vignette `vignette("teal-data-reproducibility", package = "teal.data")` for more details. +#' #' @return Input `teal_data` object or error. #' #' @param x `teal_data` object @@ -21,7 +25,6 @@ #' #' tdata2 <- teal_data(x1 = iris, code = "x1 <- iris") #' is_verified(tdata1) -#' verify(tdata2) #' is_verified(verify(tdata2)) #' #' tdata3 <- teal_data() diff --git a/man/verify.Rd b/man/verify.Rd index d86a912cf..c9f80ca66 100644 --- a/man/verify.Rd +++ b/man/verify.Rd @@ -20,13 +20,17 @@ is_verified(x) Input \code{teal_data} object or error. } \description{ -Checks whether code in \code{teal_data} object reproduces the stored objects. +Listed functions verify if code in \code{\link{teal_data}} object reproduces the stored objects. +Verification status can be checked by \code{\link[=is_verified]{is_verified()}}, returning respectively \code{TRUE} or \code{FALSE}. } \details{ -If objects created by code in the \verb{@code} slo|t of \code{x} are \code{all_equal} to the contents of the \verb{@env} slot, -the function updates the \verb{@verified} slot to \code{TRUE} in the returned \code{teal_data} object. +\code{\link[=verify]{verify()}} checks if objects created by code in the \verb{@code} slot of \code{x} are \code{all_equal} to the +contents of the \verb{@env} slot, +\code{\link[=verify]{verify()}} updates the \verb{@verified} slot to \code{TRUE} in the returned \code{teal_data} object. Once verified, the slot will always be set to \code{TRUE}. If the \verb{@code} fails to recreate objects in \code{teal_data@env}, an error is raised. + +See vignette \code{vignette("teal-data-reproducibility", package = "teal.data")} for more details. } \examples{ tdata1 <- teal_data() @@ -39,7 +43,6 @@ verify(tdata1) tdata2 <- teal_data(x1 = iris, code = "x1 <- iris") is_verified(tdata1) -verify(tdata2) is_verified(verify(tdata2)) tdata3 <- teal_data() diff --git a/vignettes/teal-data-reproducibility.Rmd b/vignettes/teal-data-reproducibility.Rmd index c37a9ed66..f3b3ea293 100644 --- a/vignettes/teal-data-reproducibility.Rmd +++ b/vignettes/teal-data-reproducibility.Rmd @@ -26,6 +26,7 @@ It is advisable to always begin analysis in a new session and run all code that Every `teal_data` object has a _verification status_, which is a statement of whether the contents of the `env` can be reproduced by `code`. From this perspective, `teal_data` objects that are instantiated empty are _verified_ but ones instantiated with data and code are _unverified_ because the code need not be reproducible. Obviously, `teal_data` objects instantiated with data only are _unverified_ as well. +Verification status can be checked by using `is_verified()` function. When evaluating code in a `teal_data` object, the code that is stored is the same as the code that is executed, so it is reproducible by definition. Therefore, evaluating code in a `teal_data` object _does not_ change its verification status. @@ -42,10 +43,9 @@ data_empty <- within(data_empty, i <- head(iris)) data_empty # remains verified data_with_data <- teal_data(i = head(iris), code = "i <- head(iris)") -data_with_data # is unverified +is_verified(data_with_data) # is unverified data_with_data <- within(data_with_data, i$rand <- sample(nrow(i))) -data_with_data # remains unverified -cat(get_code(data_with_data)) # warning is prepended +is_verified(data_with_data) # remains unverified ``` ### Verification process @@ -70,7 +70,9 @@ data_right <- teal_data( data$id <- seq_len(nrow(data)) }) ) -(data_right_verified <- verify(data_right)) # returns verified object +is_verified(data_right) # FALSE +data_right_verified <- verify(data_right) # returns verified object +is_verified(data_right_verified) # TRUE ``` #### unverified