Improved defaults can now be implemented while keeping backwards compatibility via defaults_edition().

Author: gustavdelius

DESCRIPTION

@@ -97,6 +97,7 @@ Collate:
     'manipulate_species.R'
     'calibrate.R'
     'match.R'
+    'defaults_edition.R'
 RoxygenNote: 7.2.0
 Roxygen: list(markdown = TRUE)
 Encoding: UTF-8

NAMESPACE

@@ -40,6 +40,7 @@ export(constantRDD)
 export(constant_other)
 export(customFunction)
 export(default_pred_kernel_params)
+export(defaults_edition)
 export(distanceMaxRelRDI)
 export(distanceSSLogN)
 export(double_sigmoid_length)

NEWS.md

@@ -1,5 +1,7 @@
 # mizer (development version)
 
+* Improved defaults can now be implemented while keeping backwards compatibility
+  via `defaults_edition()`.
 * The entries of the interaction matrix and of interaction_resource are not
   longer restricted to be less or equal to 1. #232
 * If user supplies no row names in the interaction matrix but give column names

R/defaults_edition.R

@@ -0,0 +1,41 @@
+#' Default editions
+#' 
+#' Function to set and get which edition of default choices is being used.
+#'
+#' The mizer functions for creating new models make a lot of choices for default
+#' values for parameters that are not provided by the user. Sometimes we find
+#' better ways to choose the defaults and update mizer accordingly. When we do
+#' this, we will increase the edition number. 
+#' 
+#' If you call `defaults_edition()` without an argument it returns the 
+#' currently active edition. Otherwise it sets the active edition to the 
+#' given value.
+#' 
+#' Users who want their existing code for creating models not to change 
+#' behaviour when run with future versions of mizer should explicitly set the
+#' desired defaults edition at the top of their code.
+#' 
+#' The most recent edition is edition 2. It will become the default in the
+#' next release. The current default is edition 1. The following defaults
+#' are changed in edition 2:
+#' 
+#' * catchability = 0.3 instead of 1
+#' * initial effort = 1 instead of 0
+#' 
+#' @param edition NULL or a numerical value.
+#' @return The current edition number.
+#' @export
+defaults_edition <- function(edition = NULL) {
+    current_edition <- 1
+    # if called without argument or with NULL, return the current edition
+    if (is.null(edition)) {
+        edition <- getOption("mizer_defaults_edition")
+        return(ifelse(is.null(edition), current_edition, edition))
+    }
+    # else check validity and set option
+    assert_that(is.numeric(edition),
+                edition >= 1)
+    options(mizer_defaults_edition = edition)
+    message("Mizer parameter defaults are now at edition ", edition, ".")
+    return(invisible(edition))
+}

man/defaults_edition.Rd

@@ -90,6 +90,7 @@ reference:
   - newTraitParams
   - newMultispeciesParams
   - mizer-package
+  - defaults_edition
 - title: Changing model parameters
   description: Even after you have created a model, you can still make changes
     with the following functions. This is useful while tuning the model and for