Determine if a matrix is a Leslie matrix population model

Checks if a given matrix is a Leslie matrix.

is_leslie_matrix(A, includes_mat_F = TRUE)

Arguments

A

Matrix to be tested

includes_mat_F

A logical argument (default `TRUE`) indicating whether A is expected to include fecundity. The idea here is that A may not include fertility, but could still be a valid Leslie matrix if fertility was truly measured to be 0, or if fertility was not measured at all. Thus, this argument relaxes the test for the first row of A summing to a positive value.

Value

A logical value indicating whether the matrix is a Leslie matrix or not

Details

A formal Leslie matrix satisfies the following conditions: * All elements are non-negative. * The subdiagonal elements (survivals), excluding the last column, are all between 0 and 1. * The sum of the elements in the first row (fecundities) is positive (unless `includes_mat_F = FALSE`). * The upper triangle, excluding the first row, contains only 0s. * The diagonal, excluding the top-left corner (`A[1,1]`), contains only 0s. * The lower triangle, excluding the subdiagonal, contains only 0s.

**Plus-group extension.** In some models the oldest age class is an open- ended *plus group* representing individuals that have survived beyond the maximum explicitly modelled age. These individuals remain in the last class with probability `A[n,n] > 0`. This function accepts such matrices by also exempting the bottom-right corner (`A[n,n]`) from the diagonal-zero requirement. When a plus-group matrix is passed to `leslie_collapse`, the `A[n,n]` term is correctly carried through the internal `leslie_expand` step.

See also

Other transformation: leslie_collapse(), mpm_collapse(), mpm_rearrange(), mpm_split(), mpm_standardize(), name_stages(), repro_stages(), scale_mpm_to_lambda1(), standard_stages()

Author

Owen Jones <jones@biology.sdu.dk>

Examples

# Standard Leslie matrix
A <- matrix(c(
  0.1, 1.2, 1.1,
  0.1, 0.0, 0.0,
  0.0, 0.2, 0.0
), nrow = 3, byrow = TRUE)
is_leslie_matrix(A) # true
#> [1] TRUE

# Plus-group Leslie matrix: A[n,n] > 0 is permitted
A_plus <- matrix(c(
  0.1, 1.2, 1.1,
  0.1, 0.0, 0.0,
  0.0, 0.2, 0.3
), nrow = 3, byrow = TRUE)
is_leslie_matrix(A_plus) # true
#> [1] TRUE

# Not a Leslie matrix: non-zero off-diagonal elements
A <- matrix(c(
  0.1, 1.2, 1.1,
  0.1, 0.2, 0.1,
  0.2, 0.3, 0.3
), nrow = 3, byrow = TRUE)
is_leslie_matrix(A) # false
#> [1] FALSE

# leslie_mpm1 is a plus-group Leslie matrix (A[n,n] > 0)
data(leslie_mpm1)
A <- leslie_mpm1$matU + leslie_mpm1$matF
is_leslie_matrix(A) # true
#> [1] TRUE