From c92fadaddbd78f139ab151ee570409bcbf6e291b Mon Sep 17 00:00:00 2001 From: Dawid Kaledkowski Date: Wed, 18 Dec 2024 12:12:46 +0100 Subject: [PATCH 1/3] teal_data characteristics --- R/teal_data-constructor.R | 19 ++++++++++++++++++- man/cdisc_data.Rd | 2 +- man/teal_data.Rd | 23 ++++++++++++++++++++++- vignettes/teal-data.Rmd | 18 ++++++++++-------- 4 files changed, 51 insertions(+), 11 deletions(-) diff --git a/R/teal_data-constructor.R b/R/teal_data-constructor.R index f79350126..4e83f80a2 100644 --- a/R/teal_data-constructor.R +++ b/R/teal_data-constructor.R @@ -14,7 +14,24 @@ #' @param code (`character`, `language`) optional code to reproduce the datasets provided in `...`. #' Note this code is not executed and the `teal_data` may not be reproducible #' -#' Use [verify()] to verify code reproducibility . +#' Use [verify()] to verify code reproducibility. +#' +#' @details +#' +#' `teal_data` is an extension of [`teal.code::qenv`] class. Please get familiar with [`teal.code`] +#' characteristics first. +#' +#' @section `teal_data` characteristics: +#' +#' A `teal_data` object inherits from the `environment` class (via `qenv` class), behaves like an +#' environment, and has #' the following characteristics: +#' +#' - The environment is locked, and data modification is only possible through the `eval_code()` +#' and `within()` functions. +#' - It stores metadata about the code used to create the data. +#' - It maintains information about relationships between datasets. +#' - Is immutable which means that each code evaluation does not modify the original `teal_data` object directly. +#' #' #' @return A `teal_data` object. #' diff --git a/man/cdisc_data.Rd b/man/cdisc_data.Rd index fe9f80de8..7ce24d5aa 100644 --- a/man/cdisc_data.Rd +++ b/man/cdisc_data.Rd @@ -21,7 +21,7 @@ For ADAM datasets it would be automatically derived.} \item{code}{(\code{character}, \code{language}) optional code to reproduce the datasets provided in \code{...}. Note this code is not executed and the \code{teal_data} may not be reproducible -Use \code{\link[=verify]{verify()}} to verify code reproducibility .} +Use \code{\link[=verify]{verify()}} to verify code reproducibility.} } \value{ A \code{teal_data} object. diff --git a/man/teal_data.Rd b/man/teal_data.Rd index 98985d108..53e5257b7 100644 --- a/man/teal_data.Rd +++ b/man/teal_data.Rd @@ -19,7 +19,7 @@ If empty then no joins between pairs of objects.} \item{code}{(\code{character}, \code{language}) optional code to reproduce the datasets provided in \code{...}. Note this code is not executed and the \code{teal_data} may not be reproducible -Use \code{\link[=verify]{verify()}} to verify code reproducibility .} +Use \code{\link[=verify]{verify()}} to verify code reproducibility.} \item{x}{(\code{teal_data})} @@ -33,6 +33,24 @@ A \code{teal_data} object. Universal function to pass data to teal application. } +\details{ +\code{teal_data} is an extension of \code{\link[teal.code:qenv]{teal.code::qenv}} class. Please get familiar with \code{\link{teal.code}} +characteristics first. +} +\section{\code{teal_data} characteristics}{ + + +A \code{teal_data} object inherits from the \code{environment} class (via \code{qenv} class), behaves like an +environment, and has #' the following characteristics: +\itemize{ +\item The environment is locked, and data modification is only possible through the \code{eval_code()} +and \code{within()} functions. +\item It stores metadata about the code used to create the data. +\item It maintains information about relationships between datasets. +\item Is immutable which means that each code evaluation does not modify the original \code{teal_data} object directly. +} +} + \section{Subsetting}{ \code{x[names]} subsets objects in \code{teal_data} environment and limit the code to the necessary needed to build limited @@ -56,3 +74,6 @@ join_keys(data)["a"] # should show empty keys join_keys(data)["b"] } +\seealso{ +\link{get_code}, \link{get_var}, \link{names} +} diff --git a/vignettes/teal-data.Rmd b/vignettes/teal-data.Rmd index 1301814b3..1df249d3c 100644 --- a/vignettes/teal-data.Rmd +++ b/vignettes/teal-data.Rmd @@ -16,7 +16,7 @@ The `teal_data` class inherits from [`qenv`](https://insightsengineering.github. ## Quick Start To create an object of class `teal_data`, use the `teal_data` function. -`teal_data` has a number of methods to manage relevant information in private class slots. +`teal_data` has a number of methods to interact with the object. ```{r, results = 'hide', message = FALSE} library(teal.data) @@ -46,6 +46,7 @@ get_code(my_data) # get code just for specific object get_code(my_data, names = "data2") + # get datanames names(my_data) @@ -56,12 +57,12 @@ print(my_data) ## `teal_data` characteristics -A `teal_data` object keeps the following information: +A `teal_data` object inherits from the `environment` class (via `qenv` class), behaves like an environment, and has the following characteristics: -- `env` - an environment containing data. -- `code` - a string containing code to reproduce `env` (details in [reproducibility](teal-data-reproducibility.html)). -- `names` - a character vector listing objects of interest to `teal` modules (details in [this `teal` vignette](https://insightsengineering.github.io/teal/latest-tag/articles/including-data-in-teal-applications.html)). -- `join_keys` - a `join_keys` object defining relationships between datasets (details in [Join Keys](join-keys.html)). +- The environment is locked, and data modification is only possible through the `eval_code()` and `within()` functions. +- It stores metadata about the code used to create the data [reproducibility](#reproducibility). +- It maintains information about relationships between datasets [Join Keys](#relational-data-models). +- Is immutable which means that each code evaluation does not modify the original `teal_data` object directly. ### Reproducibility @@ -104,8 +105,8 @@ join_keys(my_data["child"]) ### Hidden objects -An object is hidden in `teal_data` if its name starts with a dot (`.`). -This can be used to pass auxiliary objects / function in the `teal_data` instance, without being visible in the `teal` summary and filter panel. +An object is hidden in `teal_data` if its name starts with a dot (`.`). This can be used to pass auxiliary objects in +the `teal_data` instance, without being visible in the `teal` summary and filter panel. ```{r} my_data <- teal_data() @@ -114,5 +115,6 @@ my_data <- within(my_data, { .data2 <- data.frame(id = 1:20, data_id = c(1:10, 1:10), y = 21:30) }) +ls(my_data) names(my_data) ``` From 671cd4881b266d6cf4fbec1fabee54ea9cae9c00 Mon Sep 17 00:00:00 2001 From: Dawid Kaledkowski Date: Thu, 19 Dec 2024 10:16:33 +0100 Subject: [PATCH 2/3] adjust teal_data constructor and vignette --- R/teal_data-constructor.R | 29 +++++++++++++++-------------- man/teal_data-class.Rd | 2 +- man/teal_data.Rd | 30 ++++++++++++++---------------- vignettes/teal-data.Rmd | 21 ++++++++++----------- 4 files changed, 40 insertions(+), 42 deletions(-) diff --git a/R/teal_data-constructor.R b/R/teal_data-constructor.R index 4e83f80a2..8168bd457 100644 --- a/R/teal_data-constructor.R +++ b/R/teal_data-constructor.R @@ -3,7 +3,7 @@ #' @description #' `r lifecycle::badge("stable")` #' -#' Universal function to pass data to teal application. +#' Initializes a data for `teal` application. #' #' @param ... any number of objects (presumably data objects) provided as `name = value` pairs. #' @@ -18,23 +18,24 @@ #' #' @details #' -#' `teal_data` is an extension of [`teal.code::qenv`] class. Please get familiar with [`teal.code`] -#' characteristics first. -#' -#' @section `teal_data` characteristics: -#' -#' A `teal_data` object inherits from the `environment` class (via `qenv` class), behaves like an -#' environment, and has #' the following characteristics: -#' -#' - The environment is locked, and data modification is only possible through the `eval_code()` -#' and `within()` functions. -#' - It stores metadata about the code used to create the data. -#' - It maintains information about relationships between datasets. -#' - Is immutable which means that each code evaluation does not modify the original `teal_data` object directly. +#' A `teal_data` is meant to be used for reproducibility purposes. The class inherits from +#' [`teal.data::qenv`] and we encourage to get familiar with \CRANpkg{teal.code} first. +#' `teal_data` has following characteristics: #' +#' - It inherits from the environment and methods such as [`$`], [get()], [ls()], [as.list()], +#' [parent.env()] work out of the box. +#' - `teal_data` is a locked environment, and data modification is only possible through the +#' [teal.code::eval_code()] and [within.qenv()] functions. +#' - It stores metadata about the code used to create the data (see [get_code()]). +#' - It supports slicing (see [`teal.code::subset-qenv`]) +#' - Is immutable which means that each code evaluation does not modify the original `teal_data` +#' environment directly. +#' - It maintains information about relationships between datasets (see [join_keys()]). #' #' @return A `teal_data` object. #' +#' @seealso [`teal.code::eval_code`], [get_code()], [join_keys()], [names.teal_data()] +#' #' @export #' #' @examples diff --git a/man/teal_data-class.Rd b/man/teal_data-class.Rd index 494010499..d046b4bd3 100644 --- a/man/teal_data-class.Rd +++ b/man/teal_data-class.Rd @@ -24,7 +24,7 @@ Access variables with \code{\link[=get]{get()}}, \code{\link{$}}, \code{\link[te No setter provided. Evaluate code to add variables into \verb{@.xData}.} \item{\code{code}}{(\code{list} of \code{character}) representing code necessary to reproduce the contents of \code{qenv}. -Access with \code{\link[teal.code:qenv]{teal.code::get_code()}}. +Access with \code{\link[teal.code:get_code]{teal.code::get_code()}}. No setter provided. Evaluate code to append code to the slot.} \item{\code{join_keys}}{(\code{join_keys}) object specifying joining keys for data sets in diff --git a/man/teal_data.Rd b/man/teal_data.Rd index 53e5257b7..a142c2b1e 100644 --- a/man/teal_data.Rd +++ b/man/teal_data.Rd @@ -31,26 +31,24 @@ A \code{teal_data} object. \description{ \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}} -Universal function to pass data to teal application. +Initializes a data for \code{teal} application. } \details{ -\code{teal_data} is an extension of \code{\link[teal.code:qenv]{teal.code::qenv}} class. Please get familiar with \code{\link{teal.code}} -characteristics first. -} -\section{\code{teal_data} characteristics}{ - - -A \code{teal_data} object inherits from the \code{environment} class (via \code{qenv} class), behaves like an -environment, and has #' the following characteristics: +A \code{teal_data} is meant to be used for reproducibility purposes. The class inherits from +\code{\link{qenv}} and we encourage to get familiar with \CRANpkg{teal.code} first. +\code{teal_data} has following characteristics: \itemize{ -\item The environment is locked, and data modification is only possible through the \code{eval_code()} -and \code{within()} functions. -\item It stores metadata about the code used to create the data. -\item It maintains information about relationships between datasets. -\item Is immutable which means that each code evaluation does not modify the original \code{teal_data} object directly. +\item It inherits from the environment and methods such as \code{\link{$}}, \code{\link[=get]{get()}}, \code{\link[=ls]{ls()}}, \code{\link[=as.list]{as.list()}}, +\code{\link[=parent.env]{parent.env()}} work out of the box. +\item \code{teal_data} is a locked environment, and data modification is only possible through the +\code{\link[teal.code:eval_code]{teal.code::eval_code()}} and \code{\link[=within.qenv]{within.qenv()}} functions. +\item It stores metadata about the code used to create the data (see \code{\link[=get_code]{get_code()}}). +\item It supports slicing (see \code{\link[teal.code:subset-qenv]{teal.code::subset-qenv}}) +\item Is immutable which means that each code evaluation does not modify the original \code{teal_data} +environment directly. +\item It maintains information about relationships between datasets (see \code{\link[=join_keys]{join_keys()}}). } } - \section{Subsetting}{ \code{x[names]} subsets objects in \code{teal_data} environment and limit the code to the necessary needed to build limited @@ -75,5 +73,5 @@ join_keys(data)["b"] } \seealso{ -\link{get_code}, \link{get_var}, \link{names} +\code{\link[teal.code:eval_code]{teal.code::eval_code}}, \code{\link[=get_code]{get_code()}}, \code{\link[=join_keys]{join_keys()}}, \code{\link[=names.teal_data]{names.teal_data()}} } diff --git a/vignettes/teal-data.Rmd b/vignettes/teal-data.Rmd index 1df249d3c..93685f183 100644 --- a/vignettes/teal-data.Rmd +++ b/vignettes/teal-data.Rmd @@ -11,7 +11,16 @@ vignette: > # Introduction The `teal.data` package specifies the data format used in `teal` applications. -The `teal_data` class inherits from [`qenv`](https://insightsengineering.github.io/teal.code/latest-tag/articles/qenv.html) and is meant to be used for reproducibility purposes. + + +A `teal_data` is meant to be used for reproducibility purposes. The class inherits from [`qenv`](https://insightsengineering.github.io/teal.code/latest-tag/articles/qenv.html) and we encourage to get familiar with [`teal.code`](https://insightsengineering.github.io/teal.code/latest-tag/) first. `teal_data` has following characteristics: + +- It inherits from the environment and methods such as `$`, `get()`, `ls()`, `as.list()` work out of the box. +- `teal_data` is a locked environment, and data modification is only possible through the `teal.code::eval_code()` and `within.qenv()` functions. +- It stores metadata about the code used to create the data (see [reproducibility](#reproducibility)). +- It supports slicing by `[`. +- Is immutable which means that each code evaluation does not modify the original `teal_data` environment directly. +- It maintains information about relationships between datasets (see [Join Keys](#relational-data-models)). ## Quick Start @@ -54,16 +63,6 @@ names(my_data) print(my_data) ``` - -## `teal_data` characteristics - -A `teal_data` object inherits from the `environment` class (via `qenv` class), behaves like an environment, and has the following characteristics: - -- The environment is locked, and data modification is only possible through the `eval_code()` and `within()` functions. -- It stores metadata about the code used to create the data [reproducibility](#reproducibility). -- It maintains information about relationships between datasets [Join Keys](#relational-data-models). -- Is immutable which means that each code evaluation does not modify the original `teal_data` object directly. - ### Reproducibility The primary function of `teal_data` is to provide reproducibility of data. From b26fe19ebaf69980774dec912eb99d51dd72a7bd Mon Sep 17 00:00:00 2001 From: Dawid Kaledkowski Date: Fri, 20 Dec 2024 10:45:34 +0100 Subject: [PATCH 3/3] update print --- R/teal_data-show.R | 3 ++- vignettes/teal-data.Rmd | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/R/teal_data-show.R b/R/teal_data-show.R index fca8cf66e..4ce54d8b8 100644 --- a/R/teal_data-show.R +++ b/R/teal_data-show.R @@ -16,5 +16,6 @@ setMethod("show", signature = "teal_data", function(object) { } else { cat("\u2716", "unverified teal_data object\n") } - rlang::env_print(teal.code::get_env(object)) + methods::callNextMethod(object) + invisible(object) }) diff --git a/vignettes/teal-data.Rmd b/vignettes/teal-data.Rmd index 93685f183..174bb2633 100644 --- a/vignettes/teal-data.Rmd +++ b/vignettes/teal-data.Rmd @@ -19,7 +19,7 @@ A `teal_data` is meant to be used for reproducibility purposes. The class inheri - `teal_data` is a locked environment, and data modification is only possible through the `teal.code::eval_code()` and `within.qenv()` functions. - It stores metadata about the code used to create the data (see [reproducibility](#reproducibility)). - It supports slicing by `[`. -- Is immutable which means that each code evaluation does not modify the original `teal_data` environment directly. +- It is immutable which means that each code evaluation does not modify the original `teal_data` environment directly. - It maintains information about relationships between datasets (see [Join Keys](#relational-data-models)). ## Quick Start