remove redundant historical/future year/period specification

close #12

DESCRIPTION

@@ -3,8 +3,8 @@ Title: Utilities For Working With North American Climate Data
 Description: Utilities for working with North American climate data from
     'ClimateNA' <https://climatena.ca/>.
 URL: https://github.com/PredictiveEcology/climateData
-Date: 2024-05-22
-Version: 2.2.1
+Date: 2024-07-04
+Version: 2.2.2
 Authors@R: c(
     person("Alex M", "Chubaty", email = "[email protected]",
            role = c("aut", "cre"), comment = c(ORCID = "0000-0001-7146-8135")),

NAMESPACE

@@ -16,6 +16,7 @@ export(checkCalcStackLayers)
 export(checksums_sql)
 export(climateStacksByPeriod)
 export(climateStacksByYear)
+export(extractTimes)
 export(getClimateTable)
 export(getClimateTiles)
 export(getClimateURLs)

NEWS.md

@@ -1,3 +1,7 @@
+# climateData 2.2.2
+
+- remove redundant arguments `historical_years`, `future_years`, `historical_period`, and `future_period` from `prepClimateLayers()` (#12).
+
 # climateData 2.2.1
 
 - add support for multiple parallel backends (#11) via option `climateData.parallel.backend` (default "parallel"; also supports "future");

R/prepClimateLayers.R

@@ -31,28 +31,34 @@ whichTypes <- function(climVars) {
   }, character(1))
 }
 
-#' Prepare rasters for derived and 'as-is' climate variables
+#' Extract historical or future years (or periods) from a climate variables list
+#'
+#' @template climVarsList
 #'
-#' @param climateVarsList Named list of lists, specifying the climate variables to extract and/or
-#' calculate.
-#' The name of each outer list element must be prefixed by either `future_` or `historical_`,
-#' and each inner list should consist of the following named elements:
+#' @param type character string specifying one of:
+#'        `r paste0("'", paste0(.allowedClimDotsNames, collapse = "', '"), "'")`.
 #'
-#' - `vars`: the raw variables used to derive the target variable;
-#' - `fun`: a quoted function used to derive the target variable,
-#'          where `quote(calcAsIs)` denotes target variables that ARE the raw variable:
-#'  - `.dots`: additional arguments passed to `fun`.
+#' @export
+extractTimes <- function(climateVarsList, type) {
+  stopifnot(type %in% .allowedClimDotsNames)
+
+  lapply(climateVarsList, function(v) {
+    v[[".dots"]][[type]]
+  }) |>
+    unlist() |>
+    unname() |>
+    unique() |>
+    sort()
+}
+
+#' Prepare rasters for derived and 'as-is' climate variables
 #'
-#' See examples.
+#' @template climVarsList
 #'
 #' @template ClimateNA_srcdstdir
 #'
 #' @template ClimateNA_tile
 #'
-#' @template ClimateNA_typeyears
-#'
-#' @template ClimateNA_typeperiod
-#'
 #' @template ClimateNA_gcmssp
 #'
 #' @template cl
@@ -144,10 +150,6 @@ whichTypes <- function(climVars) {
 #'     climateVarsList = climateVariables,
 #'     srcdir = climatePath,    ## raw inputs, downloaded from Google Drive
 #'     dstdir = climatePathOut, ## intermediate + final outputs
-#'     historical_years = historical_yrs,
-#'     future_years = future_yrs,
-#'     historical_period = historical_prd,
-#'     future_period = NULL,
 #'     gcm = GCM,
 #'     ssp = SSP,
 #'     cl = NULL,
@@ -158,14 +160,11 @@ whichTypes <- function(climVars) {
 #' }
 prepClimateLayers <- function(climateVarsList, srcdir, dstdir,
                               tile = NULL,
-                              future_years = NULL, future_period = NULL,
-                              historical_years = NULL, historical_period = NULL,
                               gcm = NULL, ssp = NULL, cl = NULL,
                               studyArea = NULL, studyAreaName = NULL, rasterToMatch = NULL,
                               currentModuleName = "NoModule", ...) {
   stopifnot(
     !missing(srcdir), !missing(dstdir),
-    !all(is.null(future_years), is.null(future_period), is.null(historical_years), is.null(historical_period)),
     (!is.null(tile) && is.null(studyArea) && is.null(rasterToMatch)) || ## pass tile but not sA/RTM
       (is.null(tile) && !is.null(studyArea) && !is.null(rasterToMatch)) ## pass sA/RTM but not tile
   )
@@ -187,10 +186,10 @@ prepClimateLayers <- function(climateVarsList, srcdir, dstdir,
   }
 
   ## determine which climate vars are needed from climateVarsList$newVar$var
-  # annual vars: XXX
-  # monthly vars: XXX00
-  # seasonal vars: XXX_zz
-  # normal vars: will need to be prefixed with 'normal_'
+  ## annual vars: XXX
+  ## monthly vars: XXX00
+  ## seasonal vars: XXX_zz
+  ## normal vars: will need to be prefixed with 'normal_'
   needVars <- purrr::transpose(climateVarsList)[["vars"]] |>
     unlist() |>
     unname() |>
@@ -210,6 +209,12 @@ prepClimateLayers <- function(climateVarsList, srcdir, dstdir,
     unique_types_msy <- gsub("^future_(M|S|Y)$", "future_MSY", unique_types_msy) |> unique()
   }
 
+  ## determine which years / periods we need to get
+  historical_years <- extractTimes(climateVarsList, "historical_years")
+  historical_period <- extractTimes(climateVarsList, "historical_period")
+  future_years <- extractTimes(climateVarsList, "future_years")
+  future_period <- extractTimes(climateVarsList, "future_period")
+
   ## 2. download and extract multiple archives per tile (by decade)
   climPreProcessOut <- lapply(unique_types_msy, function(type_msyn) {
     if (type_msyn %in% c("historical_M", "historical_S", "historical_Y", "historical_MSY")) {

man-roxygen/climVarsList.R

@@ -0,0 +1,11 @@
+#' @param climateVarsList Named list of lists, specifying the climate variables to extract and/or
+#' calculate.
+#' The name of each outer list element must be prefixed by either `future_` or `historical_`,
+#' and each inner list should consist of the following named elements:
+#'
+#' - `vars`: the raw variables used to derive the target variable;
+#' - `fun`: a quoted function used to derive the target variable,
+#'          where `quote(calcAsIs)` denotes target variables that ARE the raw variable:
+#'  - `.dots`: additional arguments passed to `fun`.
+#'
+#' See examples.

tests/testthat/test-prepClimateLayers.R

@@ -73,10 +73,6 @@ test_that("prepClimateLayers works for multiple variable types", {
         srcdir = climatePath,    ## 'src' is the place for raw inputs, downloaded from Google Drive
         dstdir = climatePathOut, ## 'dst' is the place for intermediate + final outputs
         tile = tileIDs,
-        historical_years = historical_yrs,
-        future_years = future_yrs,
-        historical_period = historical_prd,
-        future_period = NULL,
         gcm = GCM,
         ssp = SSP,
         cl = NULL,
@@ -111,10 +107,6 @@ test_that("prepClimateLayers works for multiple variable types", {
           srcdir = climatePath,    ## 'src' is the place for raw inputs, downloaded from Google Drive
           dstdir = climatePathOut, ## 'dst' is the place for intermediate + final outputs
           # tile = tileIDs, ## when passing `studyArea`/`rasterToMatch` then `tile` isn't needed
-          historical_years = historical_yrs,
-          future_years = future_yrs,
-          historical_period = historical_prd,
-          future_period = NULL,
           gcm = GCM,
           ssp = SSP,
           cl = NULL,
@@ -164,10 +156,6 @@ test_that("prepClimateLayers properly handles unordered tileIDs", {
     srcdir = climatePath,    ## 'src' is the place for raw inputs, downloaded from Google Drive
     dstdir = climatePathOut, ## 'dst' is the place for intermediate + final outputs
     tile = tileIDs,
-    historical_years = historical_yrs,
-    future_years = NULL,
-    historical_period = NULL,
-    future_period = NULL,
     gcm = NULL,
     ssp = NULL,
     cl = NULL,