Skip to contents

Validate species parameter data frame

Source: R/validSpeciesParams.R
validSpeciesParams.Rd

These functions check the validity of a species parameter frame and, where necessary, make corrections. validGivenSpeciesParams() only checks and corrects the given species parameters but does not add default values for species parameters that were not provided. validSpeciesParams() first calls validGivenSpeciesParams() but then goes further by adding default values for species parameters that were not provided.

Usage

validSpeciesParams(species_params, check_misspellings = TRUE)

validGivenSpeciesParams(species_params, check_misspellings = TRUE)

Arguments

species_params

The user-supplied species parameter data frame

check_misspellings

Whether to report column names that look like misspellings of standard species parameter names. TRUE by default.

validSpeciesParams() first calls validGivenSpeciesParams() but then goes further by adding default values for species parameters that were not provided. It only sets defaults for those species parameters that are not owned by a single rate-setting function, namely those that are read by several of them (n), that are used only when projecting (alpha), that determine the size grid (w_min, w_max), that are needed for the length-weight conversion (a, b) or that are used only for reporting (is_background). The function sets default values if any of the following species parameters are missing or NA:

  • w_max is set to 1.5 * w_inf (it is only a computational boundary)

  • w_repro_max is set to w_inf

  • w_mat is set to w_inf/4

  • w_min is set to 0.001

  • alpha is set to 0.6

  • n is set to 3/4

  • a is set to 0.01

  • b is set to 3

  • is_background is set to FALSE

All other species parameters are given their default values by the rate-setting function that uses them, so that each default has a single home. For example p and k are set by setMetabolicRate(), z_ext, d and z0 by setExtMort(), E_ext by setExtEncounter(), D_ext by setExtDiffusion(), interaction_resource by setInteraction(), beta and sigma by setPredKernel(), q and gamma by setSearchVolume(), and erepro, m, w_mat25 and R_max by setReproduction(). These columns are therefore absent from the data frame returned by validSpeciesParams() but present in the species parameters of a MizerParams object, because setParams() calls all the rate-setting functions.

Note that the species parameters returned by these functions 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 functions).

Value

For validSpeciesParams(): A valid species parameter data frame with additional parameters with default values.

For validGivenSpeciesParams(): A valid species parameter data frame without additional parameters.

Details

validGivenSpeciesParams() checks the validity of the given species parameters. It throws an error if

  • the species column does not exist or contains duplicates

  • the asymptotic size w_inf is not specified for all species (but see the backwards-compatibility note below)

If a weight-based parameter is missing but the corresponding length-based parameter is given, as well as the a and b parameters for length-weight conversion, then the weight-based parameters are added. If both length and weight are given, then weight is used and an info_about_default condition is signalled if the two are inconsistent.

The required maximum-size parameter is w_inf, the von Bertalanffy asymptotic size of an average individual. For backwards compatibility, if no w_inf column is given, its values are taken from the w_repro_max column if that is present, or otherwise from the w_max column, and an informational message is issued. (w_repro_max is preferred over w_max because in earlier versions of mizer it was the size at which growth stopped and is therefore the closest analogue to the asymptotic size.)

Some inconsistencies in the size parameters are resolved as follows:

  • Any w_mat that is not smaller than w_inf is set to w_inf / 4.

  • Any w_mat25 that is not smaller than w_mat is marked as missing, as is the corresponding l_mat25, so that the default is used instead.

  • Any w_min that is not smaller than w_mat is set to 0.001 or w_mat /10, whichever is smaller.

  • Any w_repro_max that is not larger than w_mat is set to 4 * w_mat.

The row names of the returned data frame will be the species names. If species_params was provided as a tibble it is converted back to an ordinary data frame.

The function tests for some typical misspellings of parameter names, like wrong capitalisation or missing underscores and issues a warning if it detects such a name. Pass check_misspellings = FALSE to skip that test, as mizer does when it re-validates a table it has already checked, so that the report is made once, when the column is introduced.

See also

species_params(), validGearParams(), validParams(), validSim()