population_simulator: Runs a stage-based demographic population model simulation.

In poems: Pattern-Oriented Ensemble Modeling System

Runs a stage-based demographic population model simulation.

Description

Simulates a stage-based demographic population model and returns simulation results across multiple replicate runs. Processes run at each simulation time-step include:

1. Density dependence calculations (ceiling, logistic, or user-defined)

2. Environmental stochasticity calculations

3. Stage transition (stochastic) calculations

4. Translocation calculations (user-defined)

5. Harvest calculations (user-defined)

6. Mortality calculations (user-defined)

7. Dispersal calculations (default or user-defined)

8. Results collection

Usage

population_simulator(inputs)

Arguments

inputs

Nested list/object with named elements: random_seed Number to seed the random number generation for stochasticity. replicates Number of replicate simulation runs (default is 1). time_steps Number of simulation time steps. Required input. years_per_step Number of years per time step (default is 1). populations Number of populations. Required input. coordinates Data frame (or matrix) of X-Y population coordinates. stages Number of life cycle stages. region A Region object defining the study region. initial_abundance Array (or matrix) of initial abundances (at each stage in rows) for each population (in columns). If there is only one stage and a region object is attached, then initial abundance may be provided in the form of a raster with the same specs as the region raster. A vector can be provided that will be forced to a matrix. Required input. stage_matrix Matrix of transition (fecundity & survival) rates between stages at each time step (Leslie/Lefkovitch matrix). Required input. fecundity_mask Matrix of 0-1 to indicate which (proportions) of transition rates refer to fecundity. fecundity_max Maximum transition fecundity rate (in Leslie/Lefkovitch matrix). demographic_stochasticity Boolean for choosing demographic stochasticity for transition, dispersal, harvest and/or other processes (default is TRUE). standard_deviation Standard deviation matrix (or single value) for applying environmental stochasticity to transition rates. correlation List containing either an environmental correlation matrix (correlation_matrix), a pre-calculated transposed (Cholesky) decomposition matrix (t_decomposition_matrix), or a compact transposed (Cholesky) decomposition matrix (t_decomposition_compact_matrix) and a corresponding map of population indices (t_decomposition_compact_map), as per SpatialCorrelation class attributes. carrying_capacity Array (matrix) of carrying capacity values at each population cell (populations rows by time_steps columns when across time). Required input. density_dependence Density dependence can be "ceiling" (default), "logistic" (Ricker), or a user-defined function (optionally nested in a list with additional attributes) for adjusting transition rates: function(params), where params is a list passed to the function containing: transition_array 3D array of transition rates: stages by stages by populations. fecundity_mask Matrix of 0-1 to indicate which (proportions) of transition rates refer to fecundity. fecundity_max Maximum transition fecundity rate (in Leslie/Lefkovitch matrix). carrying_capacity Array of carrying capacity values for each population. stage_abundance Matrix of abundances for each stage (rows) and population (columns). population_abundance Array of summed population abundances for all stages. density_abundance Array of summed population abundances for stages affected by density. growth_rate_max Maximum growth rate value or array for populations. occupied_indices Array of indices for populations occupied at (current) time step. calculate_multipliers Function (function(growth_rates)) for finding multipliers (when stages > 1) to apply to affected transitions that result in target growth rates (dominant eigenvalues). apply_multipliers Function (function(transition_array, multipliers) for applying multipliers (when stages > 1) to the affected transition rates within a transition array (returns multiplied array). simulator SimulatorReference object with dynamically accessible attached and results lists. optional attributes Additional numeric attributes when density dependence is optionally nested in a list. returns a transformed transition 3D array growth_rate_max Maximum growth rate (utilized by density dependence processes). density_affects Matrix of booleans or numeric (0-1) indicating the transition vital rates affected by density (default is all). density_stages Array of booleans or numeric (0,1) for each stage to indicate which stages are affected by density (default is all). density_precision Numeric precision of the calculated multipliers (used when stages > 1) applied to affected transition rates (default is 3 decimal places). translocation An optional user-defined function (optionally nested in a list with additional attributes) for applying translocation or spatio-temporal management (to abundances): function(params), where params is a list passed to the function containing: replicates Number of replicate simulation runs. time_steps Number of simulation time steps. years_per_step Number of years per time step. populations Number of populations. stages Number of lifecycle stages. demographic_stochasticity Boolean for optionally choosing demographic stochasticity for the transformation. density_stages Array of booleans or numeric (0,1) for each stage to indicate which stages are affected by density. r Simulation replicate. tm Simulation time step. carrying_capacity Array of carrying capacity values for each population at time step. stage_abundance Matrix of (current) abundance for each stage (rows) and population (columns) at time step. occupied_indices Array of indices for populations occupied at (current) time step. simulator SimulatorReference object with dynamically accessible attached and results lists. additional attributes Additional attributes when the transformation is optionally nested in a list. returns a transformed stage abundance matrix (or a list with stage abundance and carrying capacity) harvest An optional user-defined function (optionally nested in a list with additional attributes) for applying harvesting (to abundances): function(params) as per translocation. mortality An optional user-defined function (optionally nested in a list with additional attributes) for applying mortality (to abundances): function(params) as per translocation. dispersal Either a matrix of dispersal rates between populations (source columns to target rows) or a list of data frames of non-zero dispersal rates and indices for constructing a compact dispersal matrix, and optional changing rates over time (as per class DispersalGenerator dispersal_data attribute). Alternatively a user-defined function (optionally nested in a list with additional attributes) may be used: function(params), where params is a list passed to the function containing: replicates Number of replicate simulation runs. time_steps Number of simulation time steps. years_per_step Number of years per time step. populations Number of populations. demographic_stochasticity Boolean for optionally choosing demographic stochasticity for the transformation. density_stages Array of booleans or numeric (0,1) for each stage to indicate which stages are affected by density. dispersal_stages Array of relative dispersal (0-1) for each stage to indicate the degree to which each stage participates in dispersal. r Simulation replicate. tm Simulation time step. carrying_capacity Array of carrying capacity values for each population at time step. stage_abundance Matrix of abundance for each stage (rows) and population (columns) at time step. occupied_indices Array of indices for populations occupied at time step. simulator SimulatorReference object with dynamically accessible attached and results lists. additional attributes Additional attributes when the transformation is optionally nested in a list. returns the post-dispersal abundance matrix dispersal_stages Array of relative dispersal (0-1) for each stage to indicate the degree to which each stage participates in dispersal (default is 1 for all stages). dispersal_source_n_k Dispersal proportion (p) density dependence via source population abundance divided by carrying capacity (n/k), where p is reduced via a linear slope (defined by two list items) from n/k <= cutoff (p = 0) to n/k >= threshold (aliases: dispersal_n_k_cutoff & dispersal_n_k_threshold). dispersal_target_k Dispersal rate (r) density dependence via target population carrying capacity (k), where r is reduced via a linear slope (through the origin) when k <= threshold (alias: dispersal_k_threshold). dispersal_target_n Dispersal rate (r) density dependence via target population abundance (n), where r is reduced via a linear slope (defined by two list items) from n >= threshold to n <= cutoff (r = 0) or vice versa (aliases: dispersal_n_threshold & dispersal_n_cutoff). dispersal_target_n_k Dispersal rate (r) density dependence via target population abundance divided by carrying capacity (n/k), where r is reduced via a linear slope (defined by two list items) from n/k >= threshold to n/k <= cutoff (r = 0) or vica versa. abundance_threshold Abundance threshold (that needs to be exceeded) for each population to persist. simulation_order A vector of simulation process names in configured order of execution (default is "transition", "translocation", "harvest" (plus harvested results), "mortality", "dispersal", "results" (except harvested). additional transformation functions Additional user-defined abundance transformation functions (optionally nested in lists with additional attributes) are utilised when listed in simulation_order (function as per translocation). results_selection List of results selection from: "abundance" (default), "ema", "extirpation", "extinction_location", "harvested", "occupancy"; "summarize" (default) or "replicate". result_stages Array of booleans or numeric (0, 1, 2, ...) for each stage to indicate which stages are included/combined (each unique digit > 0; optionally named) in the results (default is 1 for all stages).

Value

Selected simulation results as a nested list summarized (mean, sd, min, max) across multiple replicates (default), or 2-3D arrays including results for each replicate:

abundance

Matrix or 3D array of simulation abundance: populations rows by time_steps columns (by replicates deep).

abundance_stages

List of matrices or 3D arrays of simulation abundance for unique stage combinations when present: each populations rows by time_steps columns (by replicates deep).

all$abundance

Array or matrix of total abundance across populations: time_steps (rows by replicates columns).

all$abundance_stages

List of arrays or matrices of total abundance across populations for unique stage combinations when present: each time_steps (rows by replicates columns).

all$ema

Array of expected minimum abundance at each time step (averaged across replicates).

extirpation

Array or matrix of extirpation times: populations (rows by replicates columns).

all$extirpation

Array of extirpation time across populations for each replicate.

all$extinction_location

The weighted centroid of cells occupied in the time-step prior to the extirpation of all populations (if it occurred) for each replicate.

harvested

Matrix or 3D array of individuals harvested: populations rows by time_steps columns (by replicates deep).

harvested_stages

List of matrices or 3D arrays of individuals harvested for unique stage combinations when present: each populations rows by time_steps columns (by replicates deep).

all$harvested

Array or matrix of individuals harvested across populations: time_steps (rows by replicates columns).

all$harvested_stages

List of arrays or matrices of individuals harvested across populations for unique stage combinations when present: each time_steps (rows by replicates columns).

all$occupancy

Array or matrix of the number of populations occupied at each time-step: time_steps (rows by replicates columns).

additional results

Additional results may be attached via user-defined functions (using params$simulator$results).

Examples

# U Island example region
coordinates <- data.frame(
  x = rep(seq(177.01, 177.05, 0.01), 5),
  y = rep(seq(-18.01, -18.05, -0.01), each = 5)
)
template_raster <- Region$new(coordinates = coordinates)$region_raster # full extent
template_raster[][-c(7, 9, 12, 14, 17:19)] <- NA # make U Island
region <- Region$new(template_raster = template_raster)
# Harvest function
harvest <- list(
  rate = 0.3,
  function(params) round(params$stage_abundance * (1 - params$rate))
)
# Population model
stage_matrix <- matrix(c(
  0, 2.5, # Leslie/Lefkovitch matrix
  0.8, 0.5
), nrow = 2, ncol = 2, byrow = TRUE)
pop_model <- PopulationModel$new(
  region = region,
  time_steps = 10, # years
  populations = region$region_cells, # 7
  stage_matrix = stage_matrix,
  initial_abundance = rep(10, 7),
  carrying_capacity = array(70:1, c(7, 10)),
  harvest = harvest,
  results_selection = c("abundance", "harvested")
)
# Simulations
population_simulator(pop_model) # model
inputs <- pop_model$get_attributes()
population_simulator(inputs) # list

poems documentation built on April 4, 2025, 5:07 a.m.