deterministic projection of spatial matrix population model

Produces deterministic future population sizes of stages s in patches p. Projections can be ordered with demography then movement (dispersal) or vice versa using population vectors arranged by patches or stages as described in Hunter and Caswell (2005) and Lebreton (1996).

Usage

spmm.project(
  n,
  A,
  n_timesteps,
  n_stages,
  n_patches,
  ddf = NULL,
  mod_mort = NA,
  mod_rec = NA,
  mod_move = NA,
  P,
  BB,
  MM
)

Arguments

n: Vector of stage and patch starting values. If structure for `n` is by patches, the vector sould order values for each stage within each patch and "stack" patches. If structure for `n` is by stages, the vector sould order values for each patch within each stage and "stack" stages.
A: The spatial population projection matrix constructed from the vec-permutation matrix P, block diagonal demographic matrix BB, and block diagonal Movement matrix MM (see `spmm.project.matrix` for more details).
n_timesteps: The number of time steps into the future that should be projected.
n_stages: The number of stages (rows) in the metapopulation state matrix N.
n_patches: The number of patches (columns) in the metapopulation state matrix N.
ddf: Density-dependent function parameters (see `?spmm.ddf.params`)
mod_mort: Optional modification to survival rates via additive mortality. Can be used to increase mortality (decrease survival) across one or more demographic matrices. This argument accepts one of the following forms: - **Single numeric value**: A scalar applied uniformly to all non-recruitment elements across all demographic matrices (i.e., same additive mortality everywhere). - **Numeric vector**: A vector of length equal to either `n_patches` or `n_stages`, depending on `group_by`. Each value is applied to the corresponding demographic matrix in the list. - **List of matrices**: A list of the same length as the number of demographic matrices (`n_patches` or `n_stages`), with each matrix matching the dimensions of its corresponding demographic matrix (excluding the recruitment row). This allows specifying element-wise additive mortality for each matrix. Use a single value for uniform mortality, a vector for matrix-wise variation, or a list of matrices for full element-wise control.
mod_rec: Optional modification to recruitment rates via additive effects. This argument can be specified in one of three forms, similar to `mod_mort`: - **Single numeric value**: A scalar applied uniformly to the recruitment row (top row) of all demographic matrices. - **Numeric vector**: A vector of length equal to either `n_patches` or `n_stages` (depending on `group_by`), where each value modifies the recruitment row across the entire corresponding demographic matrix. - **List of numeric vectors**: A list of length equal to the number of demographic matrices (`n_patches` or `n_stages`), where each list element is a vector of length equal to the number of columns (`ncol`) in the demographic matrix. This allows element-wise modification of recruitment rates within each matrix. Use a single value for uniform recruitment modification, a vector for matrix-wise differences, or a list of vectors for full element-wise control across recruitment elements.
mod_move: Optional modification to movement. This is specified as a data.frame that must contain columns: - `stage`: the index of the stage to which the modification applies, - `triangle`: either `"lower"` or `"upper"`, specifying which half of the movement matrix to modify, - `at`: the column index of the movement matrix where modification is applied, - `d_perc`: the proportional change (e.g., `0.5` for 50 for 50 triangle and column. After applying the modification, the corresponding column is re-normalized to ensure they sum to 1. Note: specific patch-to-patch modifications using `from` and `to` columns is being developed for future functionality. Currently modifications are currently applied equally across all stages.
P: (optional) vec-permutation matrix – required if ddf, mod_mort, or mod_move given
BB: (optional) block diagonal demographic matrix – required if ddf, mod_mort, or mod_move given
MM: (optional) block diagonal movement (dispersal) matrix – required if ddf, mod_mort, or mod_move given

Note

Ensure that the structural lh_orders of population vector `n` and projection matrix `A` are the same. Otherwise, projections may produce incorrect values!

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988). The New S Language. Wadsworth & Brooks/Cole.

Wootton, J.T., and Bell, D.A. (1992). A metapopulation model of the peregrine falcon in California: viability and management strategies. Ecological Applications 2:307–321.

Lebreton, J. D. (1996). Demographic models for subdivided populations: the renewal equation approach. Theoretical Population Biology 49:291–313.

Caswell, H. (2001). Matrix Population Models: Construction, analysis, and interpretation (2nd ed.). Sinauer Associates.

Morris, W. F., and Doak, D. F. (2003). Quantitative Conservation Biology: Theory and practice of population viability analysis. Sinauer Associates.

Hunter, C. M. and Caswell, H. (2005). The use of vec-permutation matrix in spatial matrix population models. Ecological Modelling 188:15–21.

Examples

# Peregrine falcon example from Hunter and Caswell (2005), data from Wootton
# and Bell (1992). Continues example from `spmm.project.matrix`.

# Define the number of patches and stages
n_patches <- 2  # northern = 1x; southern = 2x
n_stages <- 2  # juvenile = x1; adult = x2
group_by <- "patches"

# Construct vec-permutation matrix
P <- vec.perm(n_stages, n_patches, group_by)

# Demographic parameter values
# Northern
f11 <- 0.00  # only adults reproduce
f12 <- 0.26
s11 <- 0.72
s12 <- 0.77
# Southern
f21 <- 0.00
f22 <- 0.19
s21 <- 0.72
s22 <- 0.77

# Demography matrices for patches
B1x <-
  matrix(c(f11, f12, s11, s12),
         nrow = 2,
         byrow = TRUE)
B2x <-
  matrix(c(f21, f22, s21, s22),
         nrow = 2,
         byrow = TRUE)
# Demography block matrix construction
BB <- blk.diag(list(B1x, B2x))

# Movement parameter values
dx1 <- 0.27  # only juveniles disperse
dx2 <- 1 - dx1
# Movement matrices for stages
Mx1 <- matrix(c(dx2, dx1, dx1, dx2), nrow = n_patches, byrow = TRUE)
Mx2 <- diag(x = 1, nrow = n_patches, ncol = n_patches)  # no Movement by adults
# Movement block matrix construction
MM <- blk.diag(list(Mx1, Mx2))

# Arrangement by patches
group_by <- "patches"
# Assumed movement before demography
lh_order <- "move"

# Projection matrix construction
A <- spmm.project.matrix(P = P, BB = BB, MM = MM,
group_by = group_by, lh_order = lh_order)  # BB %*% t(P) %*% MM %*% P

# Initial stages within patches (patch group_by)
n <- c(
  50, 22,  # Northern patch juveniles (row 1, column 1) and adults (row 2, column 1)
  40, 17   # Southern patch juveniles (row 1, column 2) and adults (row 2, column 2)
)
comment(n) <- "patches"  # vec comment attr for group_by

# Number of time steps to project into the future
n_timesteps <- 50

# Project spatial matrix population model
projs <- spmm.project(n, A, n_timesteps, n_stages, n_patches)
#> [1] "Deterministic spatial matrix model projections for patches structured population vector and movement then demography A projection matrix. The arg mod_move is currently ignored; please modify manually."