From 7ceb9af20304ffddc5cb257772ed61209c10004c Mon Sep 17 00:00:00 2001 From: Gustav Delius Date: Thu, 7 Dec 2023 21:04:35 +0000 Subject: [PATCH] Now issue warnings if user gives irrelevant species parameters. Also improve documentation. --- R/setFishing.R | 4 ++ R/species_params.R | 83 +++++++++++++++++++--------- man/completeSpeciesParams.Rd | 2 +- man/gear_params.Rd | 4 ++ man/species_params.Rd | 42 ++++++-------- tests/testthat/test-species_params.R | 37 +++++++++++++ 6 files changed, 120 insertions(+), 52 deletions(-) diff --git a/R/setFishing.R b/R/setFishing.R index 565bea34..21a1ce98 100644 --- a/R/setFishing.R +++ b/R/setFishing.R @@ -309,6 +309,10 @@ setFishing <- function(params, selectivity = NULL, catchability = NULL, #' #' For the details see [setFishing()]. #' +#' There can optionally also be a column `yield_observed` that allows you to +#' specify for each gear and species the total annual fisheries yield. This is +#' used by [plotYieldVsSpecies()], [calibrateYield()] and [matchYields()]. +#' #' The fishing effort, which is also needed to determine the fishing mortality #' exerted by a gear is not set via the `gear_params` data frame but is set #' with `initial_effort()` or is specified when calling `project()`. diff --git a/R/species_params.R b/R/species_params.R index d91e235d..0eaa347e 100644 --- a/R/species_params.R +++ b/R/species_params.R @@ -3,28 +3,6 @@ #' These functions allow you to get or set the species-specific parameters #' stored in a MizerParams object. #' -#' Not all species parameters have to be specified by the user. If they are -#' missing, mizer will give them default values, sometimes by using other -#' species parameters. So mizer distinguishes between the species parameters -#' that you have given explicitly while setting up the mizer model and the -#' species parameters that have been calculated by mizer or set to default -#' values. You can retrieve the given species parameters with -#' `given_species_params()` and the calculated ones with -#' `calculated_species_params()`. You get all species_params with -#' `species_params()`. -#' -#' Mizer stores the given parameters in a data frame `given_species_params` and -#' both the calculated and the given parameters together in a data frame -#' `species_params`. Both these data frames have one row for each species. -#' `given_species_params` only has columns for the explicitly given species -#' parameters while `species_params` has columns for all species parameters. -#' -#' If you change given species parameters with `given_species_params<-()` this -#' may trigger a re-calculation of some of the calculated species parameters. -#' However if you change species parameters with `species_params<-()` your new -#' values will be stored in both species parameter data frames and no -#' recalculation will take place. So in most use cases you will only want to use -#' `given_species_params<-()`. #' #' There are a lot of species parameters and we will list them all below, but #' most of them have sensible default values. The only required columns are @@ -32,6 +10,21 @@ #' if you have information about the values of other parameters then you should #' provide them. #' +#' Mizer distinguishes between the species parameters that you have given +#' explicitly and the species parameters that have been calculated by mizer or +#' set to default values. You can retrieve the given species parameters with +#' `given_species_params()` and the calculated ones with +#' `calculated_species_params()`. You get all species_params with +#' `species_params()`. +#' +#' If you change given species parameters with `given_species_params<-()` this +#' will trigger a re-calculation of the calculated species parameters, where +#' necessary. However if you change species parameters with `species_params<-()` +#' no recalculation will take place and furthermore your values could be +#' overwritten by a future recalculation triggered by a call to +#' `given_species_params<-()` . So in most use cases you will only want to use +#' `given_species_params<-()`. +#' #' There are some species parameters that are used to set up the #' size-dependent parameters that are used in the mizer model: #' @@ -78,9 +71,9 @@ #' * `a` and `b` are the parameters in the allometric weight-length #' relationship \eqn{w = a l ^ b}. #' -#' If you have supplied these, then you can replace weight parameters -#' like `w_max`, `w_mat`, `w_mat25` and `w_min` by their corresponding length -#' parameters `l_max`, `l_mat`, `l_mat25` and `l_min`. +#' If you have supplied the `a` and `b` parameters, then you can replace weight +#' parameters like `w_max`, `w_mat`, `w_mat25` and `w_min` by their +#' corresponding length parameters `l_max`, `l_mat`, `l_mat25` and `l_min`. #' #' The parameters that are only used to calculate default values for other #' parameters are: @@ -163,6 +156,44 @@ given_species_params <- function(params) { `given_species_params<-` <- function(params, value) { assert_that(is(params, "MizerParams")) value <- validSpeciesParams(value) + old_value <- params@given_species_params + + # Create data frame which contains only the values that have changed + common_columns <- intersect(names(value), names(params@given_species_params)) + new_columns <- setdiff(names(value), names(params@given_species_params)) + changes <- value[common_columns] + changes[changes == params@given_species_params[common_columns]] <- NA + # Remove columns that only contain NAs + changes <- changes %>% select(where(~ !all(is.na(.)))) + # Add new columns + changes <- cbind(changes, value[new_columns]) + + # Give warnings when values are changed that will have no impact + if ("gamma" %in% names(params@given_species_params) & + "f0" %in% names(changes) & + any(!is.na(params@given_species_params$gamma[!is.na(changes$f0)]))) { + warning("You have specified some values for `f0` that are going to be ignored because values for `gamma` have already been given.") + } + if ("ks" %in% names(params@given_species_params) & + "fc" %in% names(changes) & + any(!is.na(params@given_species_params$ks[!is.na(changes$fc)]))) { + warning("You have specified some values for `fc` that are going to be ignored because values for `ks` have already been given.") + } + if ("h" %in% names(params@given_species_params) & + "age_mat" %in% names(changes) & + any(!is.na(params@given_species_params$h[!is.na(changes$age_mat)]))) { + warning("You have specified some values for `age_mat` that are going to be ignored because values for `h` have already been given.") + } + + # Warn when user tries to change gear parameters + if (any(c("catchability", "selectivity", "l50", "l25", "sel_func") %in% + names(changes))) { + warning("To make changes to gears you should use `gear_params()<-`, not `species_params()`.") + } + if ("yield_observed" %in% names(changes)) { + warning("To change the observed yield you should use `gear_params()<-`, not `species_params()`.") + } + params@given_species_params <- value params@species_params <- completeSpeciesParams(value) suppressMessages(setParams(params)) @@ -619,7 +650,7 @@ validSpeciesParams <- function(species_params) { #' * `interaction_resource` is set to `1` #' * `n` is set to `3/4` #' -#' It calls `validSpeciesParams()` to check the validity of the species +#' It calls [validSpeciesParams()] to check the validity of the species #' parameters. Nevertheless the species parameters returned by this function are not guaranteed #' to produce a viable model. More checks of the parameters are performed by the #' individual rate-setting functions (see [setParams()] for the list of these diff --git a/man/completeSpeciesParams.Rd b/man/completeSpeciesParams.Rd index 946a3327..af357f83 100644 --- a/man/completeSpeciesParams.Rd +++ b/man/completeSpeciesParams.Rd @@ -22,7 +22,7 @@ are missing or NA: \item \code{n} is set to \code{3/4} } -It calls \code{validSpeciesParams()} to check the validity of the species +It calls \code{\link[=validSpeciesParams]{validSpeciesParams()}} to check the validity of the species parameters. Nevertheless the species parameters returned by this function are not guaranteed to produce a viable model. More checks of the parameters are performed by the individual rate-setting functions (see \code{\link[=setParams]{setParams()}} for the list of these diff --git a/man/gear_params.Rd b/man/gear_params.Rd index d427e36a..5f9173ab 100644 --- a/man/gear_params.Rd +++ b/man/gear_params.Rd @@ -39,6 +39,10 @@ functions. For the details see \code{\link[=setFishing]{setFishing()}}. +There can optionally also be a column \code{yield_observed} that allows you to +specify for each gear and species the total annual fisheries yield. This is +used by \code{\link[=plotYieldVsSpecies]{plotYieldVsSpecies()}}, \code{\link[=calibrateYield]{calibrateYield()}} and \code{\link[=matchYields]{matchYields()}}. + The fishing effort, which is also needed to determine the fishing mortality exerted by a gear is not set via the \code{gear_params} data frame but is set with \code{initial_effort()} or is specified when calling \code{project()}. diff --git a/man/species_params.Rd b/man/species_params.Rd index 14597319..d48c2466 100644 --- a/man/species_params.Rd +++ b/man/species_params.Rd @@ -31,35 +31,27 @@ These functions allow you to get or set the species-specific parameters stored in a MizerParams object. } \details{ -Not all species parameters have to be specified by the user. If they are -missing, mizer will give them default values, sometimes by using other -species parameters. So mizer distinguishes between the species parameters -that you have given explicitly while setting up the mizer model and the -species parameters that have been calculated by mizer or set to default -values. You can retrieve the given species parameters with +There are a lot of species parameters and we will list them all below, but +most of them have sensible default values. The only required columns are +\code{species} for the species name and \code{w_max} for its maximum size. However +if you have information about the values of other parameters then you should +provide them. + +Mizer distinguishes between the species parameters that you have given +explicitly and the species parameters that have been calculated by mizer or +set to default values. You can retrieve the given species parameters with \code{given_species_params()} and the calculated ones with \code{calculated_species_params()}. You get all species_params with \code{species_params()}. -Mizer stores the given parameters in a data frame \code{given_species_params} and -both the calculated and the given parameters together in a data frame -\code{species_params}. Both these data frames have one row for each species. -\code{given_species_params} only has columns for the explicitly given species -parameters while \code{species_params} has columns for all species parameters. - If you change given species parameters with \verb{given_species_params<-()} this -may trigger a re-calculation of some of the calculated species parameters. -However if you change species parameters with \verb{species_params<-()} your new -values will be stored in both species parameter data frames and no -recalculation will take place. So in most use cases you will only want to use +will trigger a re-calculation of the calculated species parameters, where +necessary. However if you change species parameters with \verb{species_params<-()} +no recalculation will take place and furthermore your values could be +overwritten by a future recalculation triggered by a call to +\verb{given_species_params<-()} . So in most use cases you will only want to use \verb{given_species_params<-()}. -There are a lot of species parameters and we will list them all below, but -most of them have sensible default values. The only required columns are -\code{species} for the species name and \code{w_max} for its maximum size. However -if you have information about the values of other parameters then you should -provide them. - There are some species parameters that are used to set up the size-dependent parameters that are used in the mizer model: \itemize{ @@ -109,9 +101,9 @@ weight and length: relationship \eqn{w = a l ^ b}. } -If you have supplied these, then you can replace weight parameters -like \code{w_max}, \code{w_mat}, \code{w_mat25} and \code{w_min} by their corresponding length -parameters \code{l_max}, \code{l_mat}, \code{l_mat25} and \code{l_min}. +If you have supplied the \code{a} and \code{b} parameters, then you can replace weight +parameters like \code{w_max}, \code{w_mat}, \code{w_mat25} and \code{w_min} by their +corresponding length parameters \code{l_max}, \code{l_mat}, \code{l_mat25} and \code{l_min}. The parameters that are only used to calculate default values for other parameters are: diff --git a/tests/testthat/test-species_params.R b/tests/testthat/test-species_params.R index 1c7df9da..b22d8bd0 100644 --- a/tests/testthat/test-species_params.R +++ b/tests/testthat/test-species_params.R @@ -154,6 +154,10 @@ test_that("Setting species params works", { species_params(params)$w_min[[1]] <- 1 expect_identical(params@w_min_idx[[1]], 40) + # given species params are not affected + beta <- params@given_species_params$beta + species_params(params)$beta <- 1 + expect_identical(params@given_species_params$beta, beta) }) @@ -175,3 +179,36 @@ test_that("set_species_params_from_length works", { expect_error(set_species_param_from_length(sp2, "w_mat", "l_mat"), "All lengths should be positive and non-zero.") }) + +test_that("`given_species_params<-()` gives correct warnings", { + params <- NS_params + + no_sp <- nrow(params@species_params) + expect_warning(given_species_params(params)$f0 <- 1) + expect_warning(given_species_params(params)$fc <- 1) + expect_warning(given_species_params(params)$age_mat <- 1) + expect_warning(given_species_params(params)$catchability <- 2) + expect_warning(given_species_params(params)$yield_observed <- 1) + + # No warning if NA + params@given_species_params$gamma[-1] <- NA + expect_warning(given_species_params(params)$f0 <- c(NA, rep(2, no_sp - 1)), + NA) + +}) + +test_that("`given_species_params<-()` triggers recalculation", { + params <- NS_params + params@given_species_params$gamma <- NULL + gamma <- params@species_params$gamma + given_species_params(params)$f0 <- 0.1 + expect_gt(sum(gamma - params@species_params$gamma), 0) +}) + +test_that("`given_species_params<-()` can remove columns", { + params <- NS_params + given_species_params(params)$gamma <- NULL + expect_false("gamma" %in% names(params@given_species_params)) + expect_true("gamma" %in% names(params@species_params)) + expect_error(given_species_params(params)$species <- NULL) +}) \ No newline at end of file