introduce teal_data class (#178)

introduce teal_data
deprecate TealData

DESCRIPTION

@@ -33,6 +33,7 @@ Imports:
     shinyjs,
     stats,
     teal.logger (>= 0.1.1),
+    teal.code (>= 0.4.1.9003),
     utils,
     yaml (>= 1.1.0)
 Suggests:
@@ -57,7 +58,7 @@ Config/Needs/verdepcheck: rstudio/shiny, mllg/checkmate,
     yaml=vubiostat/r-yaml, rstudio/bslib, tidyverse/dplyr, yihui/knitr,
     tidyverse/magrittr, bioc::MultiAssayExperiment, tidyverse/readr,
     rstudio/reticulate, rstudio/rmarkdown, bioc::SummarizedExperiment,
-    r-lib/testthat, r-lib/withr
+    insightsengineering/teal.code, r-lib/testthat, r-lib/withr
 Config/Needs/website: insightsengineering/nesttemplate
 Encoding: UTF-8
 Language: en-US

NAMESPACE

@@ -1,5 +1,9 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method("[",JoinKeys)
+S3method("[<-",JoinKeys)
+S3method("get_join_keys<-",JoinKeys)
+S3method("get_join_keys<-",teal_data)
 S3method(as_cdisc,TealDataset)
 S3method(as_cdisc,TealDatasetConnector)
 S3method(dataset,MultiAssayExperiment)
@@ -12,6 +16,7 @@ S3method(get_code,default)
 S3method(get_dataname,TealDataAbstract)
 S3method(get_dataname,TealDataset)
 S3method(get_dataname,TealDatasetConnector)
+S3method(get_dataname,teal_data)
 S3method(get_dataset,TealDataAbstract)
 S3method(get_dataset,TealDataset)
 S3method(get_dataset,TealDatasetConnector)
@@ -20,6 +25,11 @@ S3method(get_dataset_label,TealDatasetConnector)
 S3method(get_datasets,TealDataAbstract)
 S3method(get_datasets,TealDataset)
 S3method(get_datasets,TealDatasetConnector)
+S3method(get_datasets,teal_data)
+S3method(get_join_keys,JoinKeys)
+S3method(get_join_keys,TealData)
+S3method(get_join_keys,default)
+S3method(get_join_keys,teal_data)
 S3method(get_key_duplicates,TealDataset)
 S3method(get_key_duplicates,data.frame)
 S3method(get_keys,TealDataAbstract)
@@ -50,13 +60,14 @@ S3method(set_keys,TealDataAbstract)
 S3method(set_keys,TealDataset)
 S3method(set_keys,TealDatasetConnector)
 S3method(to_relational_data,MultiAssayExperiment)
-S3method(to_relational_data,TealData)
 S3method(to_relational_data,TealDataset)
 S3method(to_relational_data,TealDatasetConnector)
 S3method(to_relational_data,data.frame)
 S3method(to_relational_data,list)
 export("col_labels<-")
 export("data_label<-")
+export("datanames<-")
+export("get_join_keys<-")
 export(as_cdisc)
 export(callable_code)
 export(callable_function)
@@ -67,6 +78,7 @@ export(cdisc_dataset)
 export(cdisc_dataset_connector)
 export(cdisc_dataset_connector_file)
 export(cdisc_dataset_file)
+export(cdisc_join_keys)
 export(code_cdisc_dataset_connector)
 export(code_dataset_connector)
 export(col_labels)
@@ -75,6 +87,7 @@ export(csv_cdisc_dataset_connector)
 export(csv_dataset_connector)
 export(data_connection)
 export(data_label)
+export(datanames)
 export(dataset)
 export(dataset_connector)
 export(dataset_connector_file)
@@ -89,6 +102,7 @@ export(get_dataname)
 export(get_dataset)
 export(get_dataset_label)
 export(get_datasets)
+export(get_join_keys)
 export(get_key_duplicates)
 export(get_keys)
 export(get_labels)
@@ -118,7 +132,8 @@ export(teal_data_file)
 export(to_relational_data)
 export(validate_metadata)
 import(shiny)
+import(teal.code)
 importFrom(digest,digest)
 importFrom(logger,log_trace)
-importFrom(shinyjs,show)
+importFrom(shinyjs,useShinyjs)
 importFrom(stats,setNames)

NEWS.md

@@ -1,5 +1,13 @@
 # teal.data 0.3.0.9007
 
+### Enhancements
+* Simplified `join_key` to better support primary keys.
+* Added subset and subset-assignment to `JoinKeySet` class to manipulate relationship pair keys _(`[` and `[<-`)_.
+
+### Breaking changes
+
+* Introduced new data class (`teal_data`) which replaces deprecated `TealData`. New data class becomes a standard input for whole `teal` framework.
+* Deprecated `teal_data` constructor when `TealDataset`, `TealDatasetConnector` or `TealDataConnector` objects are provided. New delayed data loading functions introduced in `teal` package.
 ### Miscellaneous
 * Specified minimal version of package dependencies.
 

R/CallableFunction.R

@@ -144,7 +144,6 @@ CallableFunction <- R6::R6Class( # nolint
     # @return nothing
     refresh = function() {
       if (!is.null(private$fun_name) || !identical(private$fun_name, character(0))) {
-
         # replaced str2lang found at:
         # https://rlang.r-lib.org/reference/call2.html
         private$call <- as.call(

R/JoinKeys.R

@@ -301,8 +301,10 @@ JoinKeys <- R6::R6Class( # nolint
           return(TRUE)
         }
 
-        if (xor(length(join_key_1$keys) == 0, length(join_key_2$keys) == 0) ||
-          !identical(sort(join_key_1$keys), sort(setNames(names(join_key_2$keys), join_key_2$keys)))) {
+        if (
+          xor(length(join_key_1$keys) == 0, length(join_key_2$keys) == 0) ||
+            !identical(sort(join_key_1$keys), sort(setNames(names(join_key_2$keys), join_key_2$keys)))
+        ) {
           error_message(join_key_1$dataset_1, join_key_1$dataset_2)
         }
       }
@@ -351,17 +353,18 @@ JoinKeys <- R6::R6Class( # nolint
 #' @export
 #'
 #' @examples
-#' join_keys()
+#' # setting join keys
 #' join_keys(
 #'   join_key("dataset_A", "dataset_B", c("col_1" = "col_a")),
 #'   join_key("dataset_A", "dataset_C", c("col_2" = "col_x", "col_3" = "col_y"))
 #' )
-#' join_keys(
-#'   join_key("dataset_A", "dataset_B", c("col_1" = "col_a"))
-#' )
+#' # or
+#' jk <- join_keys()
+#' jk["dataset_A", "dataset_B"] <- c("col_1" = "col_a")
+#' jk["dataset_A", "dataset_C"] <- c("col_2" = "col_x", "col_3" = "col_y")
+#'
 join_keys <- function(...) {
-  x <- list(...)
-
+  x <- rlang::list2(...)
   res <- JoinKeys$new()
   if (length(x) > 0) {
     res$set(x)
@@ -370,6 +373,75 @@ join_keys <- function(...) {
   res
 }
 
+#' @title Getter for JoinKeys that returns the relationship between pairs of datasets
+#' @param x JoinKeys object to extract the join keys
+#' @param dataset_1 (`character`) name of first dataset.
+#' @param dataset_2 (`character`) name of second dataset.
+#' @export
+#' @keywords internal
+`[.JoinKeys` <- function(x, dataset_1, dataset_2 = dataset_1) {
+  checkmate::assert_string(dataset_1)
+  checkmate::assert_string(dataset_2)
+  x$get(dataset_1, dataset_2)
+}
+
+#' @rdname sub-.JoinKeys
+#' @param value value to assign
+#' @export
+#' @keywords internal
+`[<-.JoinKeys` <- function(x, dataset_1, dataset_2 = dataset_1, value) {
+  checkmate::assert_string(dataset_1)
+  checkmate::assert_string(dataset_2)
+  x$mutate(dataset_1, dataset_2, value)
+  x
+}
+
+#' @rdname join_keys
+#' @details
+#' `cdisc_join_keys` is a wrapper around `join_keys` that sets the default
+#' join keys for CDISC datasets. It is used internally by `cdisc_data` to
+#' set the default join keys for CDISC datasets.
+#'
+#' @export
+#' @examples
+#'
+#' # default CDISC join keys
+#' cdisc_join_keys(join_key("dataset_A", "dataset_B", c("col_1" = "col_a")), "ADTTE")
+#'
+cdisc_join_keys <- function(...) {
+  data_objects <- rlang::list2(...)
+
+  join_keys <- join_keys()
+  lapply(seq_along(data_objects), function(ix) {
+    item <- data_objects[[ix]]
+    name <- names(data_objects)[ix]
+
+    if (checkmate::test_class(item, "JoinKeySet")) {
+      join_keys$set(item)
+      return(NULL)
+    } else if (
+      checkmate::test_multi_class(item, c("TealDataConnector", "TealDataset", "TealDatasetConnector"))
+    ) {
+      return(NULL)
+    } else {
+      if ((is.null(name) || identical(trimws(name), "")) && is.character(item)) {
+        name <- item
+      }
+      if (name %in% names(default_cdisc_keys)) {
+        # Set default primary keys
+        keys_list <- default_cdisc_keys[[name]]
+        join_keys[name] <- keys_list$primary
+
+        if (!is.null(keys_list$parent) && !is.null(keys_list$foreign)) {
+          join_keys[name, keys_list$parent] <- keys_list$foreign
+        }
+      }
+    }
+  })
+
+  join_keys
+}
+
 # wrappers ====
 #' Mutate `JoinKeys` with a new values
 #'
@@ -425,12 +497,16 @@ mutate_join_keys.TealData <- function(x, dataset_1, dataset_2, val) { # nolint
   x$mutate_join_keys(dataset_1, dataset_2, val)
 }
 
-
 #' Create a relationship between a pair of datasets
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
+#' @details `join_key()` will create a relationship for the variables on a pair
+#' of datasets.
+#'
 #' @inheritParams mutate_join_keys
+#' @param dataset_2 (optional `character`) other dataset name. In case it is omitted, then it
+#' will create a primary key for `dataset_1`.
 #' @param keys (optionally named `character`) where `names(keys)` are columns in `dataset_1`
 #' with relationship to columns of `dataset_2` given by the elements in `keys`.
 #' If `names(keys)` is `NULL` then the same column names are used for both `dataset_1`
@@ -441,7 +517,7 @@ mutate_join_keys.TealData <- function(x, dataset_1, dataset_2, val) { # nolint
 #' @seealso [join_keys()]
 #'
 #' @export
-join_key <- function(dataset_1, dataset_2, keys) {
+join_key <- function(dataset_1, dataset_2 = dataset_1, keys) {
   checkmate::assert_string(dataset_1)
   checkmate::assert_string(dataset_2)
   checkmate::assert_character(keys, any.missing = FALSE)