Improving documentation

Author: gustavdelius

R/MizerSim-class.R

@@ -252,11 +252,7 @@ MizerSim <- function(params, t_dimnames = NA, t_max = 100, t_save = 1) {
 #' \linkS4class{MizerSim} class or the \linkS4class{MizerParams} class gains
 #' extra slots. MizerSim objects created in older versions of mizer are then no
 #' longer valid in the new version because of the missing slots. You need to
-#' upgrade them with
-#' ```
-#' sim <- validSim(sim)
-#' ```
-#' where `sim` should be replaced by the name of your MizerSim object.
+#' upgrade them with this function.
 #' 
 #' This function adds the missing slots and fills them with default values. It
 #' also calls [validParams()] to upgrade the MizerParams object inside the
@@ -347,7 +343,6 @@ NResource <- function(sim) {
 #' @param sim A MizerSim object
 #' @return For `finalN()`: An array (species x size) holding the consumer
 #'   number densities at the end of the simulation
-#' @seealso [idxFinalT()]
 #' @export
 #' @examples
 #' str(finalN(NS_sim))
@@ -372,10 +367,8 @@ finalNResource <- function(sim) {
     sim@n_pp[dim(sim@n_pp)[[1]], ]
 }
 
-#' Time index at end of simulation
-#' 
-#' @param sim A MizerSim object
-#' @return An integer giving the index for extracting the
+#' @rdname finalN
+#' @return For `idxFinalT()`: An integer giving the index for extracting the
 #'   results for the final time step
 #' @export
 #' @examples

R/plotBiomassObservedVsModel.R

@@ -55,13 +55,13 @@
 #' params <- calibrateBiomass(params)
 #'
 #' # Plot with default options
-#' plotBiomassObservedVsModel(params)
+#' plotBiomassObservedVsModel(params, ratio = FALSE)
 #' 
 #' # Plot including also species without observations
-#' plotBiomassObservedVsModel(params, show_unobserved = TRUE)
+#' plotBiomassObservedVsModel(params, show_unobserved = TRUE, ratio = FALSE)
 #'
 #' # Show the ratio instead
-#' plotBiomassObservedVsModel(params, ratio = TRUE)
+#' plotBiomassObservedVsModel(params)
 plotBiomassObservedVsModel <- function(object, species = NULL, ratio = TRUE,
                                       log_scale = TRUE, return_data = FALSE, 
                                       labels = TRUE, show_unobserved = FALSE) {

R/plots.R

@@ -1372,8 +1372,6 @@ plotDiet <- function(object, species = NULL, return_data = FALSE) {
 #' params <-  NS_params
 #' sim <- project(params, effort=1, t_max=20, t_save = 2, progress_bar = FALSE)
 #' plot(sim)
-#' plot(sim, time_range = 10:20) # change time period for size-based plots
-#' plot(sim, min_w = 10, max_w = 1000) # change size range for biomass plot
 #' }
 setMethod("plot", signature(x = "MizerSim", y = "missing"),
           function(x, ...) {
@@ -1409,12 +1407,10 @@ setMethod("plot", signature(x = "MizerSim", y = "missing"),
 #' @export
 #' @family plotting functions
 #' @seealso [plotting_functions]
-#' @rdname plotMizerSim
 #' @examples
 #' \donttest{
 #' params <-  NS_params
 #' plot(params)
-#' plot(params, min_w = 10, max_w = 1000) # change size range for biomass plot
 #' }
 setMethod("plot", signature(x = "MizerParams", y = "missing"),
           function(x, ...) {

R/pred_kernel_funcs.R

@@ -24,6 +24,14 @@
 #'   predator/prey mass ratios in the \code{ppmr} argument.
 #' @export
 #' @family predation kernel
+#' @seealso [setPredKernel()]
+#' @examples
+#' params <- NS_params
+#' plot(w_full(params), getPredKernel(params)["Cod", 10, ], type="l", log="x")
+#' # The restriction that the kernel is zero for w/w_p < 1 is more
+#' # noticeable for larger sigma
+#' species_params(params)$sigma <- 4
+#' plot(w_full(params), getPredKernel(params)["Cod", 10, ], type="l", log="x")
 lognormal_pred_kernel <- function(ppmr, beta, sigma) {
     Beta <- log(beta)
     phi <- exp(-(log(ppmr) - Beta)^2 / (2 * sigma^2))
@@ -58,6 +66,11 @@ lognormal_pred_kernel <- function(ppmr, beta, sigma) {
 #'   predator/prey mass ratios in the `ppmr` argument.
 #' @export
 #' @family predation kernel
+#' @seealso [setPredKernel()]
+#' @examples
+#' params <- NS_params
+#' species_params(params)$pred_kernel_type <- "truncated_lognormal"
+#' plot(w_full(params), getPredKernel(params)["Cod", 10, ], type="l", log="x")
 truncated_lognormal_pred_kernel <- function(ppmr, beta, sigma) {
     Beta <- log(beta)
     phi <- exp(-(log(ppmr) - Beta)^2 / (2 * sigma^2))
@@ -86,6 +99,14 @@ truncated_lognormal_pred_kernel <- function(ppmr, beta, sigma) {
 #'   predator/prey mass ratios in the `ppmr` argument.
 #' @export
 #' @family predation kernel
+#' @seealso [setPredKernel()]
+#' @examples
+#' params <- NS_params
+#' # Set all required paramters before changing kernel type
+#' species_params(params)$ppmr_max <- 4000
+#' species_params(params)$ppmr_min <- 200
+#' species_params(params)$pred_kernel_type <- "box"
+#' plot(w_full(params), getPredKernel(params)["Cod", 10, ], type="l", log="x")
 box_pred_kernel <- function(ppmr, ppmr_min, ppmr_max) {
     assert_that(ppmr_min < ppmr_max)
     phi <- rep(1, length(ppmr))
@@ -122,6 +143,17 @@ box_pred_kernel <- function(ppmr, ppmr_min, ppmr_max) {
 #'   predator/prey mass ratios in the `ppmr` argument.
 #' @export
 #' @family predation kernel
+#' @seealso [setPredKernel()]
+#' @examples
+#' params <- NS_params
+#' # Set all required paramters before changing kernel type
+#' species_params(params)["Cod", "kernel_exp"] <- -0.8
+#' species_params(params)["Cod", "kernel_l_l"] <- 4.6
+#' species_params(params)["Cod", "kernel_u_l"] <- 3
+#' species_params(params)["Cod", "kernel_l_r"] <- 12.5
+#' species_params(params)["Cod", "kernel_u_r"] <- 4.3
+#' species_params(params)["Cod", "kernel_type"] <- "power_law"
+#' plot(w_full(params), getPredKernel(params)["Cod", 10, ], type="l", log="x")
 power_law_pred_kernel <- function(ppmr, kernel_exp,
                                   kernel_l_l, kernel_u_l,
                                   kernel_l_r, kernel_u_r) {

R/rate_functions.R

@@ -168,6 +168,10 @@ getFeedingLevel <- function(object, n, n_pp, n_other,
 #' @param params A MizerParams object
 #' @return A matrix (species x size) with the critical feeding level
 #' @export
+#' @examples
+#' \donttest{
+#' str(getFeedingLevel(NS_params))
+#' }
 getCriticalFeedingLevel <- function(params) {
     params <- validParams(params)
     params@metab / params@intake_max / params@species_params$alpha
@@ -195,8 +199,10 @@ getCriticalFeedingLevel <- function(params) {
 #' # Project with constant fishing effort for all gears for 20 time steps
 #' sim <- project(params, t_max = 20, effort = 0.5)
 #' # Get the energy at a particular time step
-#' getEReproAndGrowth(params, n = N(sim)[15, , ], 
-#'                    n_pp = NResource(sim)[15, ], t = 15)
+#' e <- getEReproAndGrowth(params, n = N(sim)[15, , ], 
+#'                         n_pp = NResource(sim)[15, ], t = 15)
+#' # Rate at this time for Sprat of size 2g
+#' e["Sprat", "2"]
 #' }
 getEReproAndGrowth <- function(params, n = initialN(params), 
                                n_pp = initialNResource(params),
@@ -233,10 +239,14 @@ getEReproAndGrowth <- function(params, n = initialN(params),
 #' @examples
 #' \donttest{
 #' params <- NS_params
+#' # Predation rate in initial state
+#' pred_rate <- getPredRate(params)
+#' str(pred_rate)
 #' # With constant fishing effort for all gears for 20 time steps
 #' sim <- project(params, t_max = 20, effort = 0.5)
 #' # Get the feeding level at one time step
-#' getPredRate(params, n = N(sim)[15, , ], n_pp = NResource(sim)[15, ])
+#' pred_rate <- getPredRate(params, n = N(sim)[15, , ], 
+#'                          n_pp = NResource(sim)[15, ], t = 15)
 #' }
 getPredRate <- function(params, n = initialN(params), 
                         n_pp = initialNResource(params),
@@ -276,14 +286,18 @@ getPredRate <- function(params, n = initialN(params),
 #' @examples
 #' \donttest{
 #' params <- NS_params
+#' # Predation mortality in initial state
+#' M2 <- getPredMort(params)
+#' str(M2)
 #' # With constant fishing effort for all gears for 20 time steps
 #' sim <- project(params, t_max = 20, effort = 0.5)
 #' # Get predation mortality at one time step
-#' getPredMort(params, n = N(sim)[15, , ], n_pp = NResource(sim)[15, ])
+#' M2 <- getPredMort(params, n = N(sim)[15, , ], n_pp = NResource(sim)[15, ])
 #' # Get predation mortality at all saved time steps
-#' getPredMort(sim)
+#' M2 <- getPredMort(sim)
+#' str(M2)
 #' # Get predation mortality over the years 15 - 20
-#' getPredMort(sim, time_range = c(15, 20))
+#' M2 <- getPredMort(sim, time_range = c(15, 20))
 #' }
 getPredMort <- function(object, n, n_pp, n_other,
                         time_range, drop = TRUE, ...) {
@@ -416,24 +430,25 @@ getM2Background <- getResourceMort
 #' @examples
 #' \donttest{
 #' params <-NS_params
-#' # Get the fishing mortality when effort is constant
-#' # for all gears and time:
-#' getFMortGear(params, effort = 1)
-#' # Get the fishing mortality when effort is different
-#' # between the four gears but constant in time:
-#' getFMortGear(params, effort = c(0.5, 1, 1.5, 0.75))
+#' # Get the fishing mortality in initial state
+#' F <- getFMortGear(params, effort = 1)
+#' str(F)
+#' # Get the initial fishing mortality when effort is different
+#' # between the four gears:
+#' F <- getFMortGear(params, effort = c(0.5, 1, 1.5, 0.75))
 #' # Get the fishing mortality when effort is different
 #' # between the four gears and changes with time:
 #' effort <- array(NA, dim = c(20, 4))
 #' effort[, 1] <- seq(from=0, to = 1, length = 20)
 #' effort[, 2] <- seq(from=1, to = 0.5, length = 20)
 #' effort[, 3] <- seq(from=1, to = 2, length = 20)
 #' effort[, 4] <- seq(from=2, to = 1, length = 20)
-#' getFMortGear(params, effort = effort)
+#' F <- getFMortGear(params, effort = effort)
+#' str(F)
 #' # Get the fishing mortality using the effort already held in a MizerSim object.
 #' sim <- project(params, t_max = 20, effort = 0.5)
-#' getFMortGear(sim)
-#' getFMortGear(sim, time_range = c(10, 20))
+#' F <- getFMortGear(sim)
+#' F <- getFMortGear(sim, time_range = c(10, 20))
 #' }
 #' 
 getFMortGear <- function(object, effort, time_range) {
@@ -532,25 +547,26 @@ getFMortGear <- function(object, effort, time_range) {
 #' @examples
 #' \donttest{
 #' params <- NS_params
-#' # Get the total fishing mortality when effort is constant for all 
-#' # gears and time:
-#' getFMort(params, effort = 1)
-#' # Get the total fishing mortality when effort is different
-#' # between the four gears but constant in time:
-#' getFMort(params, effort = c(0.5,1,1.5,0.75))
+#' # Get the total fishing mortality in the initial state
+#' F <- getFMort(params, effort = 1)
+#' str(F)
+#' # Get the initial total fishing mortality when effort is different
+#' # between the four gears:
+#' F <- getFMort(params, effort = c(0.5,1,1.5,0.75))
 #' # Get the total fishing mortality when effort is different
 #' # between the four gears and changes with time:
 #' effort <- array(NA, dim = c(20,4))
 #' effort[, 1] <- seq(from = 0, to = 1, length = 20)
 #' effort[, 2] <- seq(from = 1, to = 0.5, length = 20)
 #' effort[, 3] <- seq(from = 1, to = 2, length = 20)
 #' effort[, 4] <- seq(from = 2, to = 1, length = 20)
-#' getFMort(params, effort = effort)
+#' F <- getFMort(params, effort = effort)
+#' str(F)
 #' # Get the total fishing mortality using the effort already held in a 
 #' # MizerSim object.
 #' sim <- project(params, t_max = 20, effort = 0.5)
-#' getFMort(sim)
-#' getFMort(sim, time_range = c(10, 20))
+#' F <- getFMort(sim)
+#' F <- getFMort(sim, time_range = c(10, 20))
 #' }
 getFMort <- function(object, effort, time_range, drop = TRUE) {
     if (is(object, "MizerParams")) {
@@ -665,8 +681,10 @@ getFMort <- function(object, effort, time_range, drop = TRUE) {
 #' # Project with constant fishing effort for all gears for 20 time steps
 #' sim <- project(params, t_max = 20, effort = 0.5)
 #' # Get the total mortality at a particular time step
-#' getMort(params, n = N(sim)[15, , ], n_pp = NResource(sim)[15, ], 
-#'         t = 15, effort = 0.5)
+#' mort <- getMort(params, n = N(sim)[15, , ], n_pp = NResource(sim)[15, ], 
+#'                 t = 15, effort = 0.5)
+#' # Mortality rate at this time for Sprat of size 2g
+#' mort["Sprat", "2"]
 #' }
 getMort <- function(params, 
                     n = initialN(params), 
@@ -718,8 +736,10 @@ getZ <- getMort
 #' params <- NS_params
 #' # Project with constant fishing effort for all gears for 20 time steps
 #' sim <- project(params, t_max = 20, effort = 0.5)
-#' # Get the energy at a particular time step
-#' getERepro(params, n = N(sim)[15, , ], n_pp = NResource(sim)[15, ], t = 15)
+#' # Get the rate at a particular time step
+#' erepro <- getERepro(params, n = N(sim)[15, , ], n_pp = NResource(sim)[15, ], t = 15)
+#' # Rate at this time for Sprat of size 2g
+#' erepro["Sprat", "2"]
 #' }
 getERepro <- function(params, n = initialN(params), 
                       n_pp = initialNResource(params),
@@ -763,7 +783,9 @@ getESpawning <- getERepro
 #' # Project with constant fishing effort for all gears for 20 time steps
 #' sim <- project(params, t_max = 20, effort = 0.5)
 #' # Get the energy at a particular time step
-#' getEGrowth(params, n = N(sim)[15, , ], n_pp = NResource(sim)[15, ], t = 15)
+#' growth <- getEGrowth(params, n = N(sim)[15, , ], n_pp = NResource(sim)[15, ], t = 15)
+#' # Growth rate at this time for Sprat of size 2g
+#' growth["Sprat", "2"]
 #' }
 getEGrowth <- function(params, n = initialN(params), 
                        n_pp = initialNResource(params),

R/setFishing.R

@@ -402,11 +402,28 @@ getInitialEffort <- function(params) {
 #' effort invested into fishing with that gear. The effort value for each gear
 #' is multiplied by the catchability and the selectivity to determine the
 #' fishing mortality imposed by that gear, see [setFishing()] for more details.
-#' 
 #' The initial effort you have set can be overruled when running a simulation
 #' by providing an `effort` argument to [project()] which allows you to
 #' specify a time-varying effort.
 #' 
+#' A valid effort vector is a named vector with one effort value for each gear.
+#' However you can also supply the effort value in different ways:
+#' 
+#' * a scalar, which is then replicated for each gear
+#' * an unnamed vector, which is then assumed to be in the same order as the
+#'   gears in the params object
+#' * a named vector in which the gear names have a different order than in the
+#'   params object. This is then sorted correctly.
+#' * a named vector which only supplies values for some of the gears.
+#'   The effort for the other gears is then set to zero.
+#' 
+#' These conversions are done by the function `validEffortVector()`.
+#'   
+#' An `effort` argument will lead to an error if it is either
+#' * unnamed and of the wrong length
+#' * named but where some names do not match any of the gears
+#' * not numeric
+#' 
 #' @param params A MizerParams object
 #' @return Effort vector
 #' @export
@@ -415,7 +432,8 @@ initial_effort <- function(params) {
 }
 
 #' @rdname initial_effort
-#' @param value The initial fishing effort
+#' @param value A vector or scalar with the initial fishing effort, see Details
+#'   below.
 #' @export
 `initial_effort<-` <- function(params, value) {
     setFishing(params, initial_effort = value)
@@ -602,29 +620,12 @@ validGearParams <- function(gear_params, species_params) {
     gear_params
 }
 
-#' Return valid effort vector
+#' Make a valid effort vector
 #' 
-#' A valid effort vector is a named vector with one effort value for each gear.
-#' 
-#' The function also accepts an `effort` that is not yet valid:
-#' 
-#' * a scalar, which is then replicated for each gear
-#' * an unnamed vector, which is then assumed to be in the same order as the
-#'   gears in the params object
-#' * a named vector in which the gear names have a different order than in the
-#'   params object. This is then sorted correctly.
-#' * a named vector which only supplies values for some of the gears.
-#'   The effort for the other gears is then set to zero.
-#'   
-#' An `effort` argument will lead to an error if it is either
-#' * unnamed and of the wrong length
-#' * named but where some names do not match any of the gears
-#' * not numeric
-#' 
-#' @param effort A vector or scalar.
+#' @param effort A vector or scalar with the initial fishing effort, see Details
+#'   below.
 #' 
 #' @export
-#' @concept helper
 #' @rdname initial_effort
 validEffortVector <- function(effort, params) {
     assert_that(is(params, "MizerParams"),
@@ -679,6 +680,7 @@ validEffortVector <- function(effort, params) {
 #' @export
 #' @examples
 #' params <- NS_params
+#' str(calc_selectivity(params))
 #' calc_selectivity(params)["Pelagic", "Herring", ]
 calc_selectivity <- function(params) {