vignettes/a05_SuggestedQualityControl.Rmd
a05_SuggestedQualityControl.RmdThe specific requirements and assumptions for each function in
Rage varies. Here we provide notes giving an overview of
these requirements, which are also applicable to other
functions/calculations in packages such as popbio and
popdemo. We make some suggestions of how users should
filter their dataset before analysis. To assist with this, the function
Rcompadre::cdb_flag conducts a series of checks on the
matrices in a compadreDB object and adds “flags” to
facilitate the filtering out of problematic matrices. This function
(cdb_flag) can automatically be run by
Rcompadre::cdb_fetch using the argument
flag = TRUE.
The most obvious requirement for most of the Rage
methods is that missing (NA) values in matrices prevent
calculations using those matrices. Sometimes these NA
values are in one of the submatrices (i.e., U,
F or C) of the matrix model, but other
submatrices are complete. For example, there may be NA
entries in the F submatrix, while the
U matrix remains complete. These issues are flagged
with the columns check_NA_A, check_NA_U,
check_NA_F and check_NA_C.
Submatrices composed entirely of zero values can also be problematic.
There may be good biological reasons for this phenomenon. Species that
do not reproduce clonally will have zero-value C
matrices. Another biologically reasonable explanation could be that in
the particular focal population in the particular focal year, there was
no sexual reproduction recorded, so the F matrix was
composed entirely of zeros. Nevertheless, zero-value submatrices can
cause some calculations to fail and it may be necessary to exclude them.
These issues are flagged with the columns check_zero_F,
check_zero_C, check_zero_U.
In a biologically reasonable matrix population model, the set of
survival and growth transitions (i.e., in the U matrix)
from a particular stage cannot exceed 1. However, in some cases, errors
in the original matrices (including data entry and rounding errors)
cause this situation to occur and may persist in the data set. We can
check for this error using column sums of the U matrix,
and may wish to exclude matrices with any column sum greater than
1.
This issue is examined using the column SurvivalIssue which
gives the maximum value of the column sums for matU . An
additional column check_surv_gte_1 (produced with
cdb_flag) reports whether any single value
is greater than or equal to 1.
At the opposite end of the survival spectrum, there may be some
matrices where some of the column sums of the U matrix
are zero, implying that there 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. This issue
is indicated by the column check_zero_U_colsum.
Several matrix manipulations or calculations require that the MPM
(matA) be irreducible and ergodic (Stott et al. 2018).
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. 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 reducible and/or non-ergodic are
usually biologically unreasonable, both in terms of their life cycle
description and their projected dynamics. They cause some calculations
in Rage (and elsewhere) to fail. Irreducibility is
necessary but not sufficient for ergodicity. These issues are flagged
with check_irreducible and check_ergodic. Even
if Rage functions do not fail due to these issues, the fact
that they can indicate biologically unreasonable life cycles may mean
that users nevertheless wish to exclude reducible, non-ergodic matrices
from their analyses.
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. This issue is flagged
with check_singular_U. Calculations for
longevity, life_expect_mean,
life_expect_var and net_repro_rate fail with
singular matrices, so users may wish to exclude singular matrices when
conducting analyses using these functions.
A complete MPM (A) can be split into its component
submatrices (i.e. U, F and
C). The sum of these submatrices should equal the
complete MPM (i.e. A = U +
F + C). Sometimes, however, errors
occur so that the submatrices do NOT sum to A.
Normally, this is caused by rounding errors, but more significant errors
are possible. This problem is flagged with
check_component_sum (only relevant for divided (split)
matrices). We recommend that users carefully check their matrices for
these errors and correct or exclude them as appropriate.
It is a general requirement for almost all Rage
functions that the matrices used as arguments do not include
NA values. With divided (split) matrices, NA
values may be present in some submatrices but not others. For example,
the U matrix may be complete, but the
F matrix may have NA values. In this case,
functions that require an F matrix will fail, while
those that only require a U matrix will work. Users
should filter the data to exclude entries with NA values in
the matrices required for their analysis. The functions
mpm_split, mpm_rearrange and
mpm_standardise do not require complete
NA-free matrices.
For functions that use the U matrix, we further
suggest filtering the data to exclude the biologically unreasonable
entries where one or more of the matU columns sum to zero,
or to greater than 1 (see Excessive Survival, above).
Alternatively, users could examine the offending matrices and make
sensible corrections (e.g. to correct rounding errors).
For functions that use the F matrix, and where sexual reproduction is known to occur in the species, we suggest that users consider filtering the data to exclude entries where F is entirely zero. This is not always desirable because there are some situations where zero recorded reproduction is biologically reasonable. We suggest a similar approach for the C matrix.
When using age-from-stage methods, users should be aware of the issue
of convergence to quasi-stationary distribution (see ). Briefly, All
age-from-stage calculations produce age-trajectories that inevitably
asymptote as a mathematical consequence of describing the vital rates as
functions of discrete stages (Horvitz & Tuljapurkar, 2008). This
mathematical artefact can introduce bias into measures obtained using
age-from-stage methods. Rage provides a convenient and
principled way of correcting for this artefact by imposing a lower
probability threshold defined by the degree of convergence to the
quasi-stationary distribution (see ). We suggest that users filter out
from their analyses matrices that do not pass this threshold
criterion.
Users should also be aware of the issue of census type. For
populations that reproduce in a pulse once per year. The demographic
census may be carried out before or after the reproduction event. There
are thus two types of census: Pre- and post-reproductive census. This
distinction has potentially important implications for demographic
measures because of its effects on measured population structure. For
example, the fraction of individuals in the first age class will tend to
be larger larger in a post-reproductive census than a pre-reproductive
census. There is a column in the com(p)adre metadata
(CensusType) that is intended to record this information
but, because authors of source publications have rarely clearly stated
this information, it is very incomplete. For serious analyses we
therefore recommend that users carefully collect this information
themselves from the source papers.
Although we highlight here a range of issues that could cause problems for MPM analyses we have likely inadvertently omitted some issues. We therefore urge users to carefully consider issues that may pertain to their particular analyses.
Horvitz, C. C., & Tuljapurkar, S. (2008). Stage dynamics, period survival, and mortality plateaus. The American Naturalist, 172(2), 203–215.
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