Merged comments branch. Closes #214

Merge branch 'comment'

Conflicts:
	docs/dev/reference/setMetabolicRate.html
	docs/dev/reference/setPredKernel.html
	docs/dev/reference/setSearchVolume.html

R/newMultispeciesParams.R

@@ -207,14 +207,14 @@ newMultispeciesParams <- function(
 #' 
 #' @param params A \linkS4class{MizerParams} object
 #' @inheritParams setInteraction
-#' @inheritDotParams setPredKernel
-#' @inheritDotParams setSearchVolume
-#' @inheritDotParams setMaxIntakeRate
-#' @inheritDotParams setMetabolicRate
-#' @inheritDotParams setExtMort
-#' @inheritDotParams setReproduction
-#' @inheritDotParams setFishing
-#' @inheritDotParams setResource
+#' @inheritDotParams setPredKernel -reset
+#' @inheritDotParams setSearchVolume -reset
+#' @inheritDotParams setMaxIntakeRate -reset
+#' @inheritDotParams setMetabolicRate -reset
+#' @inheritDotParams setExtMort -reset
+#' @inheritDotParams setReproduction -reset
+#' @inheritDotParams setFishing -reset
+#' @inheritDotParams setResource -reset
 #' 
 #' @return A \linkS4class{MizerParams} object
 #' 
@@ -243,26 +243,9 @@ newMultispeciesParams <- function(
 #' Internally that will actually call `setParams()` to recalculate any of the
 #' other parameters that are affected by the change in the species parameter.
 #' 
-#' `setParams()` will use the species parameters in the `params` object to recalculate
-#' the values of all the model functions that you do not specify explicitly when
-#' calling this function, unless you have protected the corresponding slots with
-#' a comment. If you have changed any of the model functions in the
-#' `params` object previously and now want to make changes to a different slot,
-#' you will want to call the appropriate change function individually. So in the
-#' above example you would have used `params <- setSearchVolume(params)`
-#' instead of `params <- setParams(params)`. 
-#' 
-#' If you have added a comment to a slot of the params object, then setParams()
-#' and its subfunctions will not recalculate the value for that slot from the
-#' species parameters. For example
-#' ```
-#' comment(params@search_vol) <- "This should not change"
-#' species_params(params)$gamma <- 10
-#' ```
-#' will just issue a warning "The search volume has been commented and therefore
-#' will not be recalculated from the species parameters". You can remove the
-#' comment, and therefore allow recalculation of the slot, with
-#' `comment(params@search_vol) <- NULL`.
+#' `setParams()` will use the species parameters in the `params` object to
+#' recalculate the values of all the model functions except those for which you have set custom
+#' values.
 #' 
 #' @section Units in mizer:
 #' Mizer uses grams to measure weight, centimetres to measure lengths, and

R/project_methods.R

@@ -173,10 +173,9 @@ mizerEncounter <- function(params, n, n_pp, n_other, t, ...) {
     # params@w_full[idx_sp] = params@w
     idx_sp <- (length(params@w_full) - length(params@w) + 1):length(params@w_full)
 
-    # If the feeding kernel does not have a fixed predator/prey mass ratio
-    # then the integral is not a convolution integral and we can not use fft.
+    # If the the user has set a custom pred_kernel we can not use fft.
     # In this case we use the code from mizer version 0.3
-    if (length(params@ft_pred_kernel_e) == 1) {
+    if (!is.null(comment(params@pred_kernel))) {
         # n_eff_prey is the total prey abundance by size exposed to each
         # predator (prey not broken into species - here we are just working out
         # how much a predator eats - not which species are being eaten - that is
@@ -456,10 +455,9 @@ mizerPredRate <- function(params, n, n_pp, n_other, t, feeding_level, ...) {
     no_w <- length(params@w)
     no_w_full <- length(params@w_full)
 
-    # If the feeding kernel does not have a fixed predator/prey mass ratio
-    # then the integral is not a convolution integral and we can not use fft.
+    # If the the user has set a custom pred_kernel we can not use fft.
     # In this case we use the code from mizer version 0.3
-    if (length(params@ft_pred_kernel_p) == 1) {
+    if (!is.null(comment(params@pred_kernel))) {
         n_total_in_size_bins <- sweep(n, 2, params@dw, '*', check.margin = FALSE)
         # The next line is a bottle neck
         pred_rate <- sweep(params@pred_kernel, c(1,2),

R/setExtMort.R

@@ -22,10 +22,11 @@
 #' @param params MizerParams
 #' @param z0 Optional. An array (species x size) holding the external
 #'   mortality rate.
-#' @param comment_z0 `r lifecycle::badge("experimental")`
-#'   A string describing how the value for 'z0' was obtained. This is
-#'   ignored if 'z0' is not supplied or already has a comment
-#'   attribute.
+#' @param reset If set to TRUE, then the external mortality rate will be reset
+#'   to the value calculated from the species parameters, even if it was
+#'   previously overwritten with a custom value. If set to FALSE (default) then
+#'   a recalculation from the species parameters will take place only if no
+#'   custom value has been set.
 #' @param z0pre If `z0`, the mortality from other sources, is not a column
 #'   in the species data frame, it is calculated as z0pre * w_inf ^ z0exp.
 #'   Default value is 0.6.
@@ -58,11 +59,27 @@
 #' params <- setExtMort(params, z0 = z0)
 #' }
 setExtMort <- function(params, z0 = NULL, z0pre = 0.6, z0exp = -1/4,
-                       comment_z0 = "set manually",  ...) {
-    assert_that(is(params, "MizerParams"))
+                       reset = FALSE,  ...) {
+    assert_that(is(params, "MizerParams"),
+                is.logical(reset))
+
+    if (reset) {
+        if (!is.null(z0)) {
+            warning("Because you set `reset = TRUE`, the value you provided ", 
+                    "for `z0` will be ignored and a value will be ",
+                    "calculated from the species parameters.")
+            z0 <- NULL
+        }
+        comment(params@mu_b) <- NULL
+    }
+
     if (!is.null(z0)) {
         if (is.null(comment(z0))) {
-            comment(z0) <- comment_z0
+            if (is.null(comment(params@mu_b))) {
+                comment(z0) <- "set manually"
+            } else {
+                comment(z0) <- comment(params@mu_b)
+            }
         }
         assert_that(is.array(z0),
                     identical(dim(z0), dim(params@mu_b)))

R/setFishing.R

@@ -92,14 +92,11 @@
 #' @param initial_effort Optional. A number or a named numeric vector specifying
 #'   the fishing effort. If a number, the same effort is used for all gears. If
 #'   a vector, must be named by gear.
-#' @param comment_selectivity `r lifecycle::badge("experimental")`
-#'   A string describing how the value for 'selectivity' was obtained. This is
-#'   ignored if 'selectivity' is not supplied or already has a comment
-#'   attribute.
-#' @param comment_catchability `r lifecycle::badge("experimental")`
-#'   A string describing how the value for 'catchability' was obtained. This is
-#'   ignored if 'catchability' is not supplied or already has a comment
-#'   attribute.
+#' @param reset If set to TRUE, then both `catchability` and `selectivity` will
+#'   be reset to the values calculated from the gear parameters, even if it was
+#'   previously overwritten with a custom value. If set to FALSE (default) then
+#'   a recalculation from the gear parameters will take place only if no custom
+#'   value has been set.
 #' @param ... Unused
 #'   
 #' @return MizerParams object with updated catchability and selectivity. Because
@@ -110,11 +107,11 @@
 #' @export
 #' @seealso [gear_params()]
 #' @family functions for setting parameters
-setFishing <- function(params, selectivity = NULL, catchability = NULL, 
-                       comment_selectivity = "set manually", 
-                       comment_catchability = "set manually", 
+setFishing <- function(params, selectivity = NULL, catchability = NULL,
+                       reset = FALSE,
                        initial_effort = NULL, ...) {
-    assert_that(is(params, "MizerParams"))
+    assert_that(is(params, "MizerParams"),
+                is.logical(reset))
     species_params <- params@species_params
     gear_params <- params@gear_params
     sp_names <- as.character(species_params$species)
@@ -123,6 +120,39 @@ setFishing <- function(params, selectivity = NULL, catchability = NULL,
     no_w <- length(params@w)
     gear_names <- as.character(unique(gear_params$gear))
     no_gears <- length(gear_names)
+
+    if (reset) {
+        if (!is.null(selectivity)) {
+            warning("Because you set `reset = TRUE`, the value you provided ", 
+                    "for `selectivity` will be ignored and a value will be ",
+                    "calculated from the gear parameters.")
+            selectivity <- NULL
+        }
+        comment(params@selectivity) <- NULL
+        if (!is.null(catchability)) {
+            warning("Because you set `reset = TRUE`, the value you provided ", 
+                    "for `catchability` will be ignored and a value will be ",
+                    "calculated from the gear parameters.")
+            catchability <- NULL
+        }
+        comment(params@catchability) <- NULL
+    }
+
+    if (!is.null(selectivity) && is.null(comment(selectivity))) {
+        if (is.null(comment(params@selectivity))) {
+            comment(selectivity) <- "set manually"
+        } else {
+            comment(selectivity) <- comment(params@selectivity)
+        }
+    }
+    if (!is.null(catchability) && is.null(comment(catchability))) {
+        if (is.null(comment(params@catchability))) {
+            comment(catchability) <- "set manually"
+        } else {
+            comment(catchability) <- comment(params@catchability)
+        }
+    }
+
     # The number of gears could be set by the catchability array
     if (!is.null(catchability) && (dim(catchability)[[1]] != no_gears)) {
         if (is.null(selectivity)) {
@@ -143,9 +173,6 @@ setFishing <- function(params, selectivity = NULL, catchability = NULL,
     }
 
     if (!is.null(selectivity)) {
-        if (is.null(comment(selectivity))) {
-            comment(selectivity) <- comment_selectivity
-        }
         assert_that(length(dim(selectivity)) == 3,
                     dim(selectivity)[[1]] == no_gears,
                     dim(selectivity)[[2]] == no_sp,
@@ -202,18 +229,15 @@ setFishing <- function(params, selectivity = NULL, catchability = NULL,
             selectivity[gear, species, ] <- sel
         }
         if (!is.null(comment(params@selectivity)) &&
-            !identical(selectivity, params@selectivity)) {
+            different(selectivity, params@selectivity)) {
             message("The selectivity has been commented and therefore will ",
-                    "not be recalculated from the species parameters.")
+                    "not be recalculated from the gear parameters.")
         } else {
             params@selectivity <- selectivity
         }
     }
 
     if (!is.null(catchability)) {
-        if (is.null(comment(catchability))) {
-            comment(catchability) <- comment_catchability
-        }
         assert_that(length(dim(catchability)) == 2,
                     dim(catchability)[[2]] == no_sp)
         # Check dimnames if they were provided, otherwise set them
@@ -245,9 +269,9 @@ setFishing <- function(params, selectivity = NULL, catchability = NULL,
                 gear_params$catchability[[g]]
         }
         if (!is.null(comment(params@catchability)) &&
-            !identical(catchability, params@catchability)) {
+            different(catchability, params@catchability)) {
             message("The catchability has been commented and therefore will ",
-                    "not be updated from the species parameters.")
+                    "not be updated from the gear parameters.")
         } else {
             params@catchability <- catchability
         }
@@ -280,7 +304,7 @@ setFishing <- function(params, selectivity = NULL, catchability = NULL,
 #' 
 #' If you change a gear parameter, this will be used to recalculate the
 #' `selectivity` and `catchability` arrays by calling [setFishing()],
-#' unless you have protected these with comments.
+#' unless you have previously set these by hand.
 #' @param params A MizerParams object
 #' @export
 #' @family functions for setting parameters

R/setMaxIntakeRate.R

@@ -20,10 +20,11 @@
 #' @param intake_max Optional. An array (species x size) holding the maximum
 #'   intake rate for each species at size. If not supplied, a default is set as
 #'   described in the section "Setting maximum intake rate".
-#' @param comment_intake_max `r lifecycle::badge("experimental")`
-#'   A string describing how the value for 'intake_max' was obtained. This is
-#'   ignored if 'intake_max' is not supplied or already has a comment
-#'   attribute.
+#' @param reset If set to TRUE, then the intake rate will be reset to the value
+#'   calculated from the species parameters, even if it was previously 
+#'   overwritten with a custom value. If set to FALSE (default) then a
+#'   recalculation from the species parameters will take place only if no
+#'   custom value has been set.
 #' @param ... Unused
 #' 
 #' @return A `MizerParams` object with updated maximum intake rate. Because
@@ -33,16 +34,29 @@
 #'   `params <- setMaxIntakeRate(params, ...)`.
 #' @export
 #' @family functions for setting parameters
-setMaxIntakeRate <- function(params, 
-                             intake_max = NULL, 
-                             comment_intake_max = "set manually", ...) {
-    assert_that(is(params, "MizerParams"))
+setMaxIntakeRate <- function(params, intake_max = NULL, reset = FALSE, ...) {
+    assert_that(is(params, "MizerParams"),
+                is.logical(reset))
     species_params <- params@species_params
 
+    if (reset) {
+        if (!is.null(intake_max)) {
+            warning("Because you set `reset = TRUE`, the value you provided ", 
+                    "for `intake_max` will be ignored and a value will be ",
+                    "calculated from the species parameters.")
+            intake_max <- NULL
+        }
+        comment(params@intake_max) <- NULL
+    }
+
     # If intake_max array is supplied, check it, store it and return
     if (!is.null(intake_max)) {
         if (is.null(comment(intake_max))) {
-            comment(intake_max) <- comment_intake_max
+            if (is.null(comment(params@intake_max))) {
+                comment(intake_max) <- "set manually"
+            } else {
+                comment(intake_max) <- comment(params@intake_max)
+            }
         }
         assert_that(is.array(intake_max),
                     identical(dim(intake_max), dim(params@intake_max)))
@@ -58,6 +72,7 @@ setMaxIntakeRate <- function(params,
         return(params)
     }
 
+    # Else recalculate from species params
     params@species_params$h <- get_h_default(params)
 
     intake_max <- sweep(outer(params@species_params[["n"]], 

R/setMetabolicRate.R

@@ -27,10 +27,11 @@
 #' @param p The allometric metabolic exponent. This is only used if `metab`
 #'   is not given explicitly and if the exponent is not specified in a `p`
 #'   column in the `species_params`.
-#' @param comment_metab `r lifecycle::badge("experimental")`
-#'   A string describing how the value for 'metab' was obtained. This is
-#'   ignored if 'metab' is not supplied or already has a comment
-#'   attribute.
+#' @param reset If set to TRUE, then the metabolic rate will be reset to the
+#'   value calculated from the species parameters, even if it was previously
+#'   overwritten with a custom value. If set to FALSE (default) then a
+#'   recalculation from the species parameters will take place only if no
+#'   custom value has been set.
 #' @param ... Unused
 #' 
 #' @return MizerParams object with updated metabolic rate. Because of the way
@@ -40,18 +41,33 @@
 #'   `params <- setMetabolicRate(params, ...)`.
 #' @export
 #' @family functions for setting parameters
-setMetabolicRate <- function(params, 
-                             metab = NULL, p = NULL, 
-                             comment_metab = "set manually", ...) {
-    assert_that(is(params, "MizerParams"))
+setMetabolicRate <- function(params, metab = NULL, p = NULL, 
+                             reset = FALSE, ...) {
+    assert_that(is(params, "MizerParams"),
+                is.logical(reset))
     if (!is.null(p)) {
         assert_that(is.numeric(p))
         params <- set_species_param_default(params, "p", p)
     }
     species_params <- params@species_params
+
+    if (reset) {
+        if (!is.null(metab)) {
+            warning("Because you set `reset = TRUE`, the value you provided ", 
+                    "for `metab` will be ignored and a value will be ",
+                    "calculated from the species parameters.")
+            metab <- NULL
+        }
+        comment(params@metab) <- NULL
+    }
+
     if (!is.null(metab)) {
         if (is.null(comment(metab))) {
-            comment(metab) <- comment_metab
+            if (is.null(comment(params@metab))) {
+                comment(metab) <- "set manually"
+            } else {
+                comment(metab) <- comment(params@metab)
+            }
         }
         assert_that(is.array(metab),
                     identical(dim(metab), dim(params@metab)))