poems (version 1.3.1)

population_transformation: Nested functions for a user-defined population abundance (and capacity) transformation.

Description

Modular functions for the population simulator for performing a transformation of the stage abundance (and optionally carrying capacity) at a specified time step via a user-defined function.

Usage

population_transformation(
  replicates,
  time_steps,
  years_per_step,
  populations,
  demographic_stochasticity,
  density_stages,
  transformation,
  simulator,
  name = "transformation"
)

Value

Abundance (and capacity) transformation function: function(r, tm, carrying_capacity, stage_abundance, occupied_indices), where:

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.

returns

List with transformed stage abundance matrix (and optionally carrying capacity).

Arguments

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.

transformation

A user-defined function (optionally nested in a list with additional attributes) for performing transformation: 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 life cycle 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)

simulator

SimulatorReference object with dynamically accessible attached and results lists.

name

Optional name for the transformation (default is "transformation").

Examples

simulator <- SimulatorReference$new()
# Example transformation: a random population is chosen for a severe disturbance event
# (only life cycle stage 3 individuals survive)
disturbance_function <- function(params) {
  params$simulator$attached$params <- params # attach to reference object
  random_population <- sample(params$occupied_indices, 1)
  new_stage_abundance <- params$stage_abundance
  new_stage_abundance[1:2, random_population] <- 0
  return(new_stage_abundance)
}
transformation_function <- population_transformation(
  replicates = 4, time_steps = 10, years_per_step = 1,
  populations = 7, demographic_stochasticity = TRUE,
  density_stages = c(0, 1, 1), transformation = disturbance_function,
  simulator
)
carrying_capacity <- rep(10, 7)
carrying_capacity <- rep(10, 7)
stage_abundance <- matrix(c(
 7, 13, 0, 26, 0, 39, 47,
 2, 0, 6, 8, 0, 12, 13,
 0, 3, 4, 6, 0, 9, 10
), nrow = 3, ncol = 7, byrow = TRUE)
occupied_indices <- (1:7)[-5]
transformation_function(r = 2, tm = 6, carrying_capacity, stage_abundance,
                        occupied_indices)