Update function prepare_response_variables()

- #116 add checks for param table argument
- update default behaviour description #102
- line linting / indentation #97
- #88 change default behaviour to `process_response()`, not `standardise_response()` when `is.null(dataset_standardise)`, otherwise function did not allow for case when all datasets should not be Z-standardised

R/prepare_response_variables.R

@@ -3,7 +3,7 @@
 #' @param ManyEcoEvo Complete ManyEcoEvo dataset containing nested datasets for each different analysis and exclusion set dataset
 #' @param estimate_type A character string of length 1, equal to either "Zr", "yi", "y25", "y50", "y75", indicating what type of estimates are being prepared.
 #' @param param_table A table of parameters \(mean, sd\) for *most* response variables used by analysts. This tibble is pulled from the named object exported by `ManyEcoEvo::`. but can be overwritten with the users's own `param_table` dataset.
-#' @param dataset_standardise A character string of length 1, equal to the name of the dataset to standardise the response variables to. If `NULL`, all datasets are standardised.
+#' @param dataset_standardise A character string of length 1, equal to the name of the dataset to standardise the response variables to. If `NULL` (default), no datasets are standardised.
 #' @return A tibble of nested list-columns
 #' @details Operates on nested list-columns of dataframes, where each dataframe contains the response variable data for a single analysis. The function standardises the response variable data for each analysis, and returns the modified dataset to the `data` list-column.
 #' @family targets-pipeline functions.
@@ -17,22 +17,43 @@ prepare_response_variables <- function(ManyEcoEvo,
                                        estimate_type = character(1L),
                                        param_table = NULL,
                                        dataset_standardise = NULL) {
-  match.arg(estimate_type, choices = c("Zr", "yi", "y25", "y50", "y75"), several.ok = FALSE)
+  match.arg(estimate_type, 
+            choices = c("Zr", "yi", "y25", "y50", "y75"), 
+            several.ok = FALSE)
   stopifnot(is.data.frame(ManyEcoEvo))
-  pointblank::expect_col_exists(object = ManyEcoEvo, columns = c(dataset, data))
+  pointblank::expect_col_exists(object = ManyEcoEvo, 
+                                columns = c(dataset, data))
   if (!is.null(dataset_standardise)) {
     stopifnot(is.character(dataset_standardise))
     stopifnot(length(dataset_standardise) >= 1)
     stopifnot(length(dataset_standardise) <= length(unique(ManyEcoEvo$dataset)))
-    match.arg(dataset_standardise, choices = ManyEcoEvo$dataset, several.ok = TRUE)
+    match.arg(dataset_standardise, 
+              choices = ManyEcoEvo$dataset,
+              several.ok = TRUE)
   }
+  if (!is.null(param_table)) {
+    stopifnot(is.data.frame(param_table))
+    pointblank::expect_col_exists(object = param_table, 
+                                  columns = c("variable", 
+                                              "parameter", 
+                                              "value"))
+    pointblank::expect_col_is_numeric(object = param_table, 
+                                      columns = "value")
+    pointblank::expect_col_is_character(object = param_table, 
+                                        columns = c("variable", 
+                                                    "parameter"))
+    pointblank::expect_col_vals_in_set(object = param_table, 
+                                       columns = "parameter", 
+                                       set = c("mean", "sd"))
+  }
+
+  # ------ Function Body ------
 
   out <- ManyEcoEvo
 
   if (estimate_type != "Zr") {
-    if (is.null(param_table)) {
-
-      cli::cli_abort("{.arg param_table} must be supplied for {.val {estimate_type}} data")
+    if (all(is.null(param_table), !is.null(dataset_standardise))) {
+      cli::cli_abort("{.arg param_table} must be supplied for {.val {estimate_type}} data when {.arg dataset_standardise} is not {.val NULL}.")
     }
 
     # ------ Back transform if estimate_type is yi only ------
@@ -70,17 +91,9 @@ prepare_response_variables <- function(ManyEcoEvo,
   if (is.null(dataset_standardise)) {
     out <- out %>%
       ungroup() %>%
-      dplyr::mutate(data = purrr::map2(
-        .x = data, 
-        .y = dataset,
-        .f = ~ standardise_response(
-          dat = .x,
-          estimate_type = !!{
-            estimate_type
-          },
-          param_table,
-          dataset = .y
-        )
+      dplyr::mutate(data = purrr::map(
+        data,
+        process_response
       ))
   } else {
 
@@ -89,7 +102,14 @@ prepare_response_variables <- function(ManyEcoEvo,
       fns = list(standardise_response)
     )
 
-    pmap_prepare_response <- function(data, estimate_type, param_table, dataset, fns, ...){
+    pmap_prepare_response <- function(data, 
+                                      estimate_type = character(1L), 
+                                      param_table, 
+                                      dataset = character(1L), 
+                                      fns, 
+                                      ...){ #TODO move into own function as internal
+      stopifnot(is.data.frame(data))
+      stopifnot(class(fns) == "function")
       fns(data, estimate_type, param_table, dataset)
     }