Introduce path and deprecate hub_con and config_tasks as args to submission_tmpl

NAMESPACE

@@ -85,5 +85,6 @@ importFrom(hubUtils,get_hub_model_output_dir)
 importFrom(hubUtils,get_hub_timezone)
 importFrom(hubUtils,read_config)
 importFrom(hubUtils,read_config_file)
+importFrom(lifecycle,deprecated)
 importFrom(lubridate,"%within%")
 importFrom(rlang,"!!!")

NEWS.md

@@ -1,5 +1,7 @@
 # hubValidations (development version)
 
+* Introduced `hub_path` as main argument to `submission_tmpl()` and deprecated arguments `hub_con` and `config_tasks` (#165 & #137). This way, all that is required by the user to create a submission template is the path to a hub directory.
+
 # hubValidations 0.10.1
 
 * `check_tbl_value_col_ascending()` will now use the order of the

R/submission_tmpl.R

@@ -1,6 +1,13 @@
 #' Create a model output submission file template
 #'
-#' @param hub_con A `⁠<hub_connection`>⁠ class object.
+#' @param path Character string. Path to a fully configured
+#' hub directory or path to a `tasks.json` file.
+#' @param hub_con `r lifecycle::badge("deprecated")` Use `path` instead. A
+#' `⁠<hub_connection>⁠` class object.
+#' @param config_tasks `r lifecycle::badge("deprecated")` Use `path` instead.
+#'  A list version of the content's of a hub's `tasks.json` config file,
+#'  accessed through the `"config_tasks"` attribute of a `<hub_connection>`
+#'  object or function [read_config()].
 #' @inheritParams expand_model_out_grid
 #' @param derived_task_ids Character vector of derived task ID names (task IDs whose
 #' values depend on other task IDs) to ignore. Columns for such task ids will
@@ -49,107 +56,94 @@
 #' specified in `round_id` property of `config_tasks`) is set to the value of the
 #' `round_id` argument in the returned output.
 #' @export
+#' @importFrom lifecycle deprecated
 #'
 #' @examples
-#' hub_con <- hubData::connect_hub(
-#'   system.file("testhubs/flusight", package = "hubUtils")
-#' )
-#' submission_tmpl(hub_con, round_id = "2023-01-02")
+#' hub_path <- system.file("testhubs/flusight", package = "hubUtils")
+#' submission_tmpl(hub_path, round_id = "2023-01-02")
+#' # Return required values only
 #' submission_tmpl(
-#'   hub_con,
+#'   hub_path,
 #'   round_id = "2023-01-02",
 #'   required_vals_only = TRUE
 #' )
 #' submission_tmpl(
-#'   hub_con,
+#'   hub_path,
 #'   round_id = "2023-01-02",
 #'   required_vals_only = TRUE,
 #'   complete_cases_only = FALSE
 #' )
-#' # Specifying a round in a hub with multiple rounds
-#' hub_con <- hubData::connect_hub(
-#'   system.file("testhubs/simple", package = "hubUtils")
-#' )
-#' submission_tmpl(hub_con, round_id = "2022-10-01")
-#' submission_tmpl(hub_con, round_id = "2022-10-29")
-#' submission_tmpl(hub_con,
-#'   round_id = "2022-10-29",
-#'   required_vals_only = TRUE
-#' )
-#' submission_tmpl(hub_con,
-#'   round_id = "2022-10-29",
-#'   required_vals_only = TRUE,
-#'   complete_cases_only = FALSE
+#' # Specify a round in a hub with multiple rounds
+#' hub_path <- system.file("testhubs/simple", package = "hubUtils")
+#' submission_tmpl(hub_path, round_id = "2022-10-01")
+#' submission_tmpl(hub_path, round_id = "2022-10-29")
+#' # Subset for a specific output type
+#' hub_path <- system.file("testhubs", "samples", package = "hubValidations")
+#' submission_tmpl(
+#'   hub_path,
+#'   round_id = "2022-12-17",
+#'   output_types = "sample"
 #' )
-#' # Hub with sample output type
-#' config_tasks <- read_config_file(system.file("config", "tasks.json",
+#' # Create a template from the path to a tasks config file
+#' config_path <- system.file("config", "tasks.json",
 #'   package = "hubValidations"
-#' ))
+#' )
 #' submission_tmpl(
-#'   config_tasks = config_tasks,
+#'   config_path,
 #'   round_id = "2022-12-26"
 #' )
 #' # Hub with sample output type and compound task ID structure
-#' config_tasks <- read_config_file(system.file("config", "tasks-comp-tid.json",
+#' config_path <- system.file("config", "tasks-comp-tid.json",
 #'   package = "hubValidations"
-#' ))
+#' )
 #' submission_tmpl(
-#'   config_tasks = config_tasks,
-#'   round_id = "2022-12-26"
+#'   config_path,
+#'   round_id = "2022-12-26",
+#'   output_types = "sample"
 #' )
 #' # Override config compound task ID set
 #' # Create coarser compound task ID set for the first modeling task which contains
 #' # samples
 #' submission_tmpl(
-#'   config_tasks = config_tasks,
+#'   config_path,
 #'   round_id = "2022-12-26",
+#'   output_types = "sample",
 #'   compound_taskid_set = list(
 #'     c("forecast_date", "target"),
 #'     NULL
 #'   )
 #' )
-#' # Subsetting for a single output type
-#' submission_tmpl(
-#'   config_tasks = config_tasks,
-#'   round_id = "2022-12-26",
-#'   output_types = "sample"
-#' )
 #' # Derive a template with ignored derived task ID. Useful to avoid creating
 #' # a template with invalid derived task ID value combinations.
-#' config_tasks <- read_config(
-#'   system.file("testhubs", "flusight", package = "hubValidations")
-#' )
+#' hub_path <- system.file("testhubs", "flusight", package = "hubValidations")
 #' submission_tmpl(
-#'   config_tasks = config_tasks,
+#'   hub_path,
 #'   round_id = "2022-12-12",
 #'   output_types = "pmf",
 #'   derived_task_ids = "target_end_date",
 #'   complete_cases_only = FALSE
 #' )
 #' # Force optional output type, in this case "mean".
 #' submission_tmpl(
-#'   config_tasks = config_tasks,
+#'   hub_path,
 #'   round_id = "2022-12-12",
 #'   required_vals_only = TRUE,
 #'   output_types = c("pmf", "quantile", "mean"),
 #'   force_output_types = TRUE,
 #'   derived_task_ids = "target_end_date",
 #'   complete_cases_only = FALSE
 #' )
-submission_tmpl <- function(hub_con, config_tasks, round_id,
+submission_tmpl <- function(path, round_id,
                             required_vals_only = FALSE,
                             force_output_types = FALSE,
                             complete_cases_only = TRUE,
                             compound_taskid_set = NULL,
                             output_types = NULL,
-                            derived_task_ids = NULL) {
-  switch(rlang::check_exclusive(hub_con, config_tasks),
-    hub_con = {
-      checkmate::assert_class(hub_con, classes = "hub_connection")
-      config_tasks <- attr(hub_con, "config_tasks")
-    },
-    config_tasks = checkmate::assert_list(config_tasks)
-  )
+                            derived_task_ids = NULL,
+                            hub_con = deprecated(),
+                            config_tasks = deprecated()) {
+  config_tasks <- switch_get_config(hub_con, config_tasks, path)
+
   if (is.null(derived_task_ids)) {
     derived_task_ids <- get_config_derived_task_ids(
       config_tasks, round_id
@@ -231,13 +225,12 @@ message_opt_tasks <- function(na_cols, n_mt) {
   if (n_mt > 1L) {
     msg <- c(
       msg,
-      "!" = "Round contains more than one modeling task ({.val {n_mt}})"
+      "!" = "Round contains more than one modeling task (n = {.val {n_mt}})"
     )
   }
   msg <- c(
     msg,
-    "i" = "See Hub's {.path tasks.json} file or {.cls hub_connection} attribute
-          {.val config_tasks} for details of optional
+    "i" = "See Hub's {.path tasks.json} file for details of optional
     task ID/output_type/output_type ID value combinations."
   )
   cli::cli_bullets(msg)
@@ -265,3 +258,39 @@ subset_complete_cases <- function(tmpl_df) {
   )
   tmpl_df[compl_cases, ]
 }
+
+# This function
+switch_get_config <- function(hub_con, config_tasks, path) {
+  input_arg <- rlang::check_exclusive(hub_con, config_tasks, path,
+    .frame = parent.frame()
+  )
+  switch(input_arg,
+    hub_con = {
+      # Signal the deprecation to the user
+      lifecycle::deprecate_warn(
+        "0.11.0",
+        "hubValidations::submission_tmpl(hub_con = )",
+        "hubValidations::submission_tmpl(hub_path = )"
+      )
+      checkmate::assert_class(hub_con, classes = "hub_connection")
+      attr(hub_con, "config_tasks")
+    },
+    config_tasks = {
+      lifecycle::deprecate_warn(
+        "0.11.0",
+        "hubValidations::submission_tmpl(config_tasks = )",
+        "hubValidations::submission_tmpl(hub_path = )"
+      )
+      checkmate::assert_list(config_tasks)
+    },
+    path = {
+      if (!fs::file_exists(path)) {
+        cli::cli_abort("{.arg path} {.file {path}} does not exist.")
+      }
+      if (fs::is_dir(path)) {
+        return(read_config(path))
+      }
+      read_config_file(path)
+    }
+  )
+}