Adds columns to the data slot of a `CompadreDB` object that flag potential problems in the matrix population models. These columns can subsequently be used to subset the database by logical argument.
Optional checks include:
check_NA_A: missing values in `matA`? Missing (`NA`) values in matrices prevent most calculations using those matrices.check_NA_U: missing values in `matU`? Missing (`NA`) values in matrices prevent most calculations using those matrices.check_NA_F: missing values in `matF`? Missing (`NA`) values in matrices prevent most calculations using those matrices.check_NA_C: missing values in `matC`? Missing (`NA`) values in matrices prevent most calculations using those matrices.check_zero_U: `matU` all zeros (including `NA`)? Submatrices composed entirely of zero values can be problematic. There may be good biological reasons for this phenomenon. For example, in the particular focal population in the particular focal year, there was truly zero survival recorded. Nevertheless, zero-value submatrices can cause some calculations to fail and it may be necessary to exclude them.check_zero_F: `matF` all zeros (including `NA`)? Submatrices composed entirely of zero values can be problematic. There may be good biological reasons for this phenomenon. For example, in the particular focal population in the particular focal year, there was truly zero reproduction recorded. Nevertheless, zero-value submatrices can cause some calculations to fail and it may be necessary to exclude them.check_zero_U_colsum: Columns of `matU` that sum to zero imply that there is is no survival from that particular stage. This may be a perfectly valid parameterisation for a particular year/place but is biologically unreasonable in the longer term and users may wish to exclude problematic matrices from their analysis.check_singular_U: `matU` singular? Matrices are said to be singular if they cannot be inverted. Inversion is required for many matrix calculations and, therefore, singularity can cause some calculations to fail.check_component_sum: do `matU`/`matF`/`matC` submatrices sum to `matA` (see Details)? A complete MPM (`matA`) can be split into its component submatrices (i.e., `matU`, `matF` and `matC`). The sum of these submatrices should equal the complete MPM (i.e., `matA` = `matU` + `matF` + `matC`). Sometimes, however, errors occur so that the submatrices do NOT sum to `matA`. Normally, this is caused by rounding errors, but more significant errors are possible.check_ergodic: is `matA` ergodic (seeisErgodic)? Some matrix calculations require that the MPM (`matA`) be ergodic. Ergodic MPMs are those where there is a single asymptotic stable state that does not depend on initial stage structure. Conversely, non-ergodic MPMs are those where there are multiple asymptotic stable states, which depend on initial stage structure. MPMs that are non-ergodic are usually biologically unreasonable, both in terms of their life cycle description and their projected dynamics. They cause some calculations to fail.check_irreducible: is `matA` irreducible (seeisIrreducible)? Some matrix calculations require that the MPM (`matA`) be irreducible. Irreducible MPMs are those where parameterised transition rates facilitate pathways from all stages to all other stages. Conversely, reducible MPMs depict incomplete life cycles where pathways from all stages to every other stage are not possible. MPMs that are reducible are usually biologically unreasonable, both in terms of their life cycle description and their projected dynamics. They cause some calculations to fail. Irreducibility is necessary but not sufficient for ergodicity.check_primitive: is `matA` primitive (seeisPrimitive)? A primitive matrix is non-negative matrix that is irreducible and has only a single eigenvalue of maximum modulus. This check is therefore redundant due to the overlap with `check_irreducible` and `checkErdogic`.check_surv_gte_1: does `matU` contains values that are equal to or greater than 1? Survival is bounded between 0 and 1. Values in excess of 1 are biologically unreasonable.
Usage
cdb_flag(
cdb,
checks = c("check_NA_A", "check_NA_U", "check_NA_F", "check_NA_C", "check_zero_U",
"check_zero_F", "check_zero_C", "check_zero_U_colsum", "check_singular_U",
"check_component_sum", "check_ergodic", "check_irreducible", "check_primitive",
"check_surv_gte_1")
)Value
Returns cdb with extra columns appended to the data slot
(columns have the same names as the corresponding elements of
checks) to indicate (TRUE/FALSE) whether there are potential
problems with the matrices corresponding to a given row of the data.
Details
For the flag check_component_sum, a value of NA will be
returned if the matrix sum of matU, matF, and matC consists only of zeros
and/or NA, indicating that the matrix has not been split.
References
Stott, I., Townley, S., & Carslake, D. 2010. On reducibility and ergodicity of population projection matrix models. Methods in Ecology and Evolution. 1 (3), 242-252
See also
Other data checking:
cdb_check_species(),
cdb_collapse(),
cdb_compare(),
mpm_methods
Author
Owen Jones <jones@biology.sdu.dk>
Julia Jones <juliajones@biology.sdu.dk>
Roberto Salguero-Gomez <rob.salguero@zoo.ox.ac.uk>
Danny Buss <dlb50@cam.ac.uk>
Patrick Barks <patrick.barks@gmail.com>
Examples
CompadreFlag <- cdb_flag(Compadre)
# only check whether matA has missing values, and whether matA is ergodic
CompadreFlag <- cdb_flag(Compadre, checks = c("check_NA_A", "check_ergodic"))