poems (version 1.3.2)

population_simulator: 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)

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).

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).

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