remove some un-needed function arguments to simplify the workflow (#94)

nicholasjclark · Nov 18, 2024 · 698fe0c · 698fe0c
1 parent f7931f4
commit 698fe0c
Show file tree

Hide file tree

Showing 79 changed files with 1,004 additions and 1,675 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -7,6 +7,9 @@
 * Added `ZMVN()` error models for estimating Zero-Mean Multivariate Normal errors; convenient for working with non time-series data where latent residuals are expected to be correlated (such as when fitting Joint Species Distribution Models); see `?mvgam::ZMVN` for examples
 * Added a `fevd.mvgam()` method to compute forecast error variance decompositions from models fit with Vector Autoregressive dynamics (#21 and #76)
 
+## Deprecations
+* Arguments `use_stan`, `jags_path`, `data_train`, `data_test`, `adapt_delta`, `max_treedepth` and `drift` have been removed from primary functions to streamline documentation and reflect the package's mission to deprecate 'JAGS' as a suitable backend. Both `adapt_delta` and `max_treedepth` should now be supplied in a named `list()` to the new argument `control`
+
 ## Bug fixes
 * Not necessarily a "bug fix", but this update removes several dependencies to lighten installation and improve efficiency of the workflow (#93)
 * Fixed a minor bug in the way `trend_map` recognises levels of the `series` factor

diff --git a/R/get_mvgam_priors.R b/R/get_mvgam_priors.R
@@ -5,6 +5,7 @@
 #'
 #'@inheritParams mvgam
 #'@inheritParams jsdgam
+#'@param ... Not currently used
 #'@param factor_formula Can be supplied instead `trend_formula` to match syntax from
 #'[jsdgam]
 #'@details Users can supply a model formula, prior to fitting the model, so that default priors can be inspected and
@@ -155,23 +156,29 @@
 get_mvgam_priors = function(formula,
                             trend_formula,
                             factor_formula,
-                            data,
-                            data_train,
+                            knots,
+                            trend_knots,
+                            trend_model = 'None',
                             family = poisson(),
+                            data,
                             unit = time,
                             species = series,
-                            knots,
-                            trend_knots,
                             use_lv = FALSE,
                             n_lv,
-                            use_stan = TRUE,
-                            trend_model = 'None',
                             trend_map,
-                            drift = FALSE){
+                            ...){
 
   # Validate the data
-  if(missing("data") & missing("data_train")){
-    stop('Argument "data" is missing with no default')
+  dots <- list(...)
+  if(missing("data")){
+    if('data_train' %in% names(dots)){
+      message('argument "data_train" is deprecated; supply as "data" instead')
+      data <- dots$data_train
+      dots$data_train <- NULL
+    } else {
+      stop('Argument "data" is missing with no default',
+           call. = FALSE)
+    }
   }
   if(!missing("data")){
     data_train <- data
@@ -200,8 +207,10 @@ get_mvgam_priors = function(formula,
   }
 
   # Validate the trend arguments
-  if(drift)
+  if('drift' %in% names(dots)){
     message('The "drift" argument is deprecated; use fixed effects of "time" instead')
+    dots$drift <- NULL
+  }
   drift <- FALSE
   orig_trend_model <- trend_model
   trend_model <- validate_trend_model(orig_trend_model,
@@ -231,6 +240,7 @@ get_mvgam_priors = function(formula,
                                      refit = FALSE)
 
   # Validate the family argument
+  use_stan <- TRUE
   family <- validate_family(family, use_stan = use_stan)
   family_char <- match.arg(arg = family$family,
                            choices = family_char_choices())
@@ -264,17 +274,14 @@ get_mvgam_priors = function(formula,
     validate_trend_formula(trend_formula)
     prior_df <- get_mvgam_priors(formula = orig_formula,
                                  data = data_train,
-                                 #data_train = data_train,
                                  family = family,
                                  use_lv = FALSE,
-                                 use_stan = TRUE,
                                  trend_model = if(trend_model == 'None'){
                                    RW()
                                  } else {
                                    orig_trend_model
                                  },
                                  trend_map = trend_map,
-                                 drift = drift,
                                  knots = knots)
 
     # Replace any terms labelled 'trend' with 'series' for creating the necessary

diff --git a/R/jsdgam.R b/R/jsdgam.R
@@ -9,13 +9,13 @@
 #'
 #'@inheritParams mvgam
 #'@inheritParams ZMVN
-#'@param formula A \code{character} string specifying the GAM observation model formula. These are exactly like the formula
+#'@param formula A \code{formula} object specifying the GAM observation model formula. These are exactly like the formula
 #'for a GLM except that smooth terms, `s()`, `te()`, `ti()`, `t2()`, as well as time-varying
-#'`dynamic()` terms and nonparametric `gp()` terms, can be added to the right hand side
+#'`dynamic()` terms, nonparametric `gp()` terms and offsets using `offset()`, can be added to the right hand side
 #'to specify that the linear predictor depends on smooth functions of predictors
 #'(or linear functionals of these). Details of the formula syntax used by \pkg{mvgam}
 #'can be found in \code{\link{mvgam_formulae}}
-#'@param factor_formula A \code{character} string specifying the linear predictor
+#'@param factor_formula A \code{formula} object specifying the linear predictor
 #'effects for the latent factors. Use `by = trend` within calls to functional terms
 #'(i.e. `s()`, `te()`, `ti()`, `t2()`, `dynamic()`, or `gp()`) to ensure that each factor
 #'captures a different axis of variation. See the example below as an illustration
@@ -322,17 +322,17 @@ jsdgam = function(formula,
                   share_obs_params = FALSE,
                   priors,
                   n_lv = 2,
+                  backend = getOption("brms.backend", "cmdstanr"),
+                  algorithm = getOption("brms.algorithm", "sampling"),
+                  control = list(max_treedepth = 10,
+                                 adapt_delta = 0.8),
                   chains = 4,
                   burnin = 500,
                   samples = 500,
                   thin = 1,
                   parallel = TRUE,
                   threads = 1,
                   silent = 1,
-                  max_treedepth = 10,
-                  adapt_delta = 0.8,
-                  backend = getOption("brms.backend", "cmdstanr"),
-                  algorithm = getOption("brms.algorithm", "sampling"),
                   run_model = TRUE,
                   return_model_data = FALSE,
                   ...){
@@ -545,8 +545,8 @@ jsdgam = function(formula,
                                             chains = chains,
                                             parallel = parallel,
                                             silent = silent,
-                                            max_treedepth = max_treedepth,
-                                            adapt_delta = adapt_delta,
+                                            max_treedepth = control$max_treedepth,
+                                            adapt_delta = control$adapt_delta,
                                             threads = threads,
                                             burnin = burnin,
                                             samples = samples,
@@ -564,8 +564,8 @@ jsdgam = function(formula,
                                          chains = chains,
                                          parallel = parallel,
                                          silent = silent,
-                                         max_treedepth = max_treedepth,
-                                         adapt_delta = adapt_delta,
+                                         max_treedepth = control$max_treedepth,
+                                         adapt_delta = control$adapt_delta,
                                          threads = threads,
                                          burnin = burnin,
                                          samples = samples,
@@ -642,8 +642,8 @@ jsdgam = function(formula,
                           fit_engine = 'stan',
                           backend = backend,
                           algorithm = algorithm,
-                          max_treedepth = max_treedepth,
-                          adapt_delta = adapt_delta),
+                          max_treedepth = control$max_treedepth,
+                          adapt_delta = control$adapt_delta),
                      class = c('mvgam', 'jsdgam'))
   }