Package 'poems'

Description

R6 class functionality for modeling sea, ice and other frictional barriers to dispersal within a spatially-explicit population model. The dispersal friction model utilizes the gdistance package functionality to calculate distance multipliers to modify distance-based dispersal rates for simulated migrations in a spatio-temporal frictional landscape. The frictional landscape is defined via conductance/permeability values, the inverse of friction, which ranges from zero (barrier) to one (no friction) with values in-between representing some friction. For example, a conductance value of 1/5 = 0.2 represents a landscape in which simulated animals move 5 times slower than a non-friction landscape. In this example the resultant distance multiplier would be 5, thus reducing the effective dispersal range.

Super classes

poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> DispersalFriction

Public fields

Active bindings

Methods

Public methods

• DispersalFriction$calculate_distance_multipliers()

• DispersalFriction$clone()

Method calculate_distance_multipliers()

Calculates and returns spatio-temporal dispersal distance multipliers for each in-range migration.

Usage

DispersalFriction$calculate_distance_multipliers(dispersal_indices, ...)

Arguments

Returns

Temporal list of dispersal distance multiplier arrays with values for each in-range migration.

Method clone()

The objects of this class are cloneable with this method.

Usage

DispersalFriction$clone(deep = FALSE)

Arguments

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)
raster::plot(region$region_raster,
  main = "Example region (indices)",
  xlab = "Longitude (degrees)", ylab = "Latitude (degrees)",
  colNA = "blue"
)

#' Dispersal distances
dispersal_gen <- DispersalGenerator$new(region = region)
dispersal_gen$set_attributes(params = list(p = 0.5, b = 700, r = 3000))
distances <- round(dispersal_gen$calculate_distance_matrix()) #' in m
dispersal_gen$calculate_distance_data()
dispersal_indices <- as.matrix(dispersal_gen$distance_data$base[, 1:2])

#' Distance multipliers with friction in cell 4
dispersal_friction <- DispersalFriction$new(
  region = region,
  conductance = c(1, 1, 1, 0.5, 1, 1, 1)
)
multipliers <- dispersal_friction$calculate_distance_multipliers(dispersal_indices)
cbind(dispersal_indices,
  distance = distances[dispersal_indices],
  multiplier = multipliers[[1]]
)

#' Note that crossing the water is avoided.

Description

R6 class functionality for modeling dispersals within a spatially-explicit population model. The model calculates dispersal rates between population model cells using a distance-based function: p*exp(-distance/b) for distance <= r (otherwise zero), where p (proportion), b (breadth or average distance) and r (range or maximum distance) are configurable model attributes. The dispersal rates are adjusted to limit emigration from each cell to p. The model also generates data for constructing compacted dispersal matrices. It dynamically generates attributes defined as outputs (default: dispersal_data) given sampled inputs (default: dispersal_proportion and dispersal_max_distance). An optional DispersalFriction object may be utilized to modify (equivalent) distances given a (spatio-temporal) frictional landscape. When this landscape includes temporal changes, the generated dispersal_data will be a temporal list of changing dispersal rates.

Super classes

poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> poems::Generator -> DispersalGenerator

Public fields

Active bindings

Methods

Public methods

• DispersalGenerator$new()

• DispersalGenerator$generative_requirements_satisfied()

• DispersalGenerator$set_distance_classes()

• DispersalGenerator$calculate_distance_matrix()

• DispersalGenerator$calculate_distance_data()

• DispersalGenerator$calculate_dispersals()

• DispersalGenerator$clone()

Method new()

Initialization method sets the generative template and requirements, optionally the dispersal friction object, as well as any attributes passed via a params list or individually.

Usage

DispersalGenerator$new(
  generative_template = NULL,
  generative_requirements = NULL,
  dispersal_friction = NULL,
  attribute_aliases = NULL,
  ...
)

Arguments

Method generative_requirements_satisfied()

Returns a boolean to indicate that all the default, file and/or function template settings that are required for attribute generation are present.

Usage

DispersalGenerator$generative_requirements_satisfied()

Returns

Boolean to indicate that the required settings for attribute generation are present.

Method set_distance_classes()

Sets the distance classes to a sequence of values from minimum to maximum in steps of interval size.

Usage

DispersalGenerator$set_distance_classes(
  minimum = 1,
  maximum = 10,
  interval = 1
)

Arguments

Method calculate_distance_matrix()

Returns a matrix with the calculated distance (in meters by default) between each pair of region cells.

Usage

DispersalGenerator$calculate_distance_matrix(use_longlat = NULL)

Arguments

Returns

Matrix with distances between region cells.

Method calculate_distance_data()

Calculates the distance class for within-range populations using the set/provided distance classes. Also calculates indices for constructing compact matrices.

Usage

DispersalGenerator$calculate_distance_data(distance_matrix = NULL, ...)

Arguments

Method calculate_dispersals()

Calculates, using the conditional dispersal limiting function for a simulation sample, a dispersal matrix, or a list of data frames of non-zero dispersal rates and indices for constructing a compact dispersal matrix (default), and optional changing rates over time (via DispersalFriction object).

Usage

DispersalGenerator$calculate_dispersals(type = "data")

Arguments

Returns

Returns character string message when calculation prerequisites are not met (for simulation logging).

Method clone()

The objects of this class are cloneable with this method.

Usage

DispersalGenerator$clone(deep = FALSE)

Arguments

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)
raster::plot(region$region_raster,
  main = "Example region (indices)",
  xlab = "Longitude (degrees)", ylab = "Latitude (degrees)",
  colNA = "blue"
)

# Distance-based dispersal generator
dispersal_gen <- DispersalGenerator$new(
  region = region,
  dispersal_max_distance = 3000, # in m
  inputs = c("dispersal_p", "dispersal_b"),
  decimals = 5
)
dispersal_gen$calculate_distance_data() # pre-calculate
dispersal_gen$generate(input_values = list(
  dispersal_p = 0.5,
  dispersal_b = 700
))

Description

R6 class representing a nested container for DispersalGenerator attributes that are maintained when new model clones are created. The container maintains input and output attribute names, file, function and distribution templates, correlation parameters (for distribution generation), rounding decimals, occupancy mask, and other DispersalGenerator attributes that need to be maintained when cloning.

Super class

poems::GenerativeTemplate -> DispersalTemplate

Public fields

Active bindings

Methods

Public methods

• DispersalTemplate$clone()

Method clone()

The objects of this class are cloneable with this method.

Usage

DispersalTemplate$clone(deep = FALSE)

Arguments

Examples

dispersal_template <- DispersalTemplate$new()
dispersal_template$dispersal_breadth <- 130
dispersal_template$dispersal_proportion <- 0.4
coordinates <- data.frame(x = rep(1:4, 4), y = rep(1:4, each = 4))
dispersal_gen <- DispersalGenerator$new(
  coordinates = coordinates, inputs = c("dispersal_r"),
  generative_template = dispersal_template
)
dispersal_gen$dispersal_breadth
dispersal_gen$dispersal_proportion

Description

R6 class representing a nested container for Generator attributes that are maintained when new model clones are created. The container maintains input and output attribute names, file, function and distribution templates, correlation parameters (for distribution generation), rounding decimals, occupancy mask, and any inherited class model attributes that need to be maintained when cloning.

Public fields

Active bindings

Methods

Public methods

• GenerativeTemplate$new()

• GenerativeTemplate$clone()

Method new()

Initialization method initializes the generator templates.

Usage

GenerativeTemplate$new()

Method clone()

The objects of this class are cloneable with this method.

Usage

GenerativeTemplate$clone(deep = FALSE)

Arguments

Examples

gen_template <- GenerativeTemplate$new()
gen_template$occupancy_mask <- array(c(1, 1, 0, 0, 1, 1, 1))
gen_template$decimals <- 4
gen_template$description <- "Test generator"

coordinates <- data.frame(x = c(1:4, 4:2), y = c(1, 1:4, 4:3))

generator <- Generator$new(
  region = Region$new(coordinates = coordinates), attr1 = 1,
  template_attached = gen_template
)
generator$description
generator$occupancy_mask
generator$decimals

Description

R6 class representing a model that dynamically generates attribute values (outputs) via reading data from files, running assigned functions, generating sample distributions, or built-in functions (assigned as default in inherited classes), using simulation sample parameters (inputs).

Super classes

poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> Generator

Public fields

Active bindings

Methods

Public methods

• Generator$new()

• Generator$new_clone()

• Generator$get_attributes()

• Generator$generate()

• Generator$add_file_template()

• Generator$add_function_template()

• Generator$add_distribution_template()

• Generator$read_file()

• Generator$run_function()

• Generator$sample_distribution()

• Generator$add_generative_requirements()

• Generator$generative_requirements_satisfied()

• Generator$clone()

Method new()

Initialization method sets the generative template and requirements as well as any attributes passed via a params list or individually.

Usage

Generator$new(generative_template = NULL, generative_requirements = NULL, ...)

Arguments

Method new_clone()

Creates a new (re-initialized) object of the current (inherited) object class with optionally passed parameters.

Usage

Generator$new_clone(...)

Arguments

Returns

New object of the current (inherited) class.

Method get_attributes()

Returns a list of existing and template-generated values for selected attributes or attribute aliases (when array of parameter names provided), or all existing attributes (when no params).

Usage

Generator$get_attributes(params = NULL)

Arguments

Returns

List of selected or all attributes values.

Method generate()

Returns a list of generated output values (attributes) corresponding to the sample input values (attributes).

Usage

Generator$generate(input_values = list())

Arguments

Returns

List containing generated model output attributes and/or any error/warning messages.

Method add_file_template()

Adds a file template for reading raster/RData(RDS)/CSV files for a given model attribute.

Usage

Generator$add_file_template(
  param,
  path_template,
  path_params = c(),
  file_type = "GRD"
)

Arguments

Method add_function_template()

Adds a function template for running a user-defined function to calculate a given model attribute.

Usage

Generator$add_function_template(param, function_def, call_params = c())

Arguments

Method add_distribution_template()

Adds a distribution template for generating a given model attribute via sampling a distribution.

Usage

Generator$add_distribution_template(
  param,
  distr_type = c("uniform", "normal", "lognormal", "beta", "triangular"),
  distr_params = list(),
  sample = NULL,
  random_seed = NULL,
  normalize_threshold = NULL
)

Arguments

Method read_file()

Reads and returns the value of a model attribute from a file using the corresponding file template and simulation sample parameters.

Usage

Generator$read_file(param)

Arguments

Returns

Model attribute value read from a file.

Method run_function()

Returns the calculated value of a model attribute using the corresponding function template and model simulation sample parameters.

Usage

Generator$run_function(param)

Arguments

Returns

Model attribute value calculated using a function.

Method sample_distribution()

Returns the calculated value of a model attribute using the corresponding distribution template and simulation sample parameters.

Usage

Generator$sample_distribution(param)

Arguments

Returns

Model attribute value calculated via distribution sampling.

Method add_generative_requirements()

Adds attribute names and the template setting ("file", "function" or "distribution") that is required to generate their values (via a params list or individually).

Usage

Generator$add_generative_requirements(params = list(), ...)

Arguments

Method generative_requirements_satisfied()

Returns a boolean to indicate that all the file, function and/or distribution template settings that are required for attribute generation are present.

Usage

Generator$generative_requirements_satisfied()

Returns

Boolean to indicate that the required settings for attribute generation are present.

Method clone()

The objects of this class are cloneable with this method.

Usage

Generator$clone(deep = FALSE)

Arguments

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)
)
coordinates <- coordinates[c(7, 9, 12, 14, 17:19), ]
region <- Region$new(coordinates = coordinates, use_raster = FALSE)
# Spatial correlation
spatial_correlation <- SpatialCorrelation$new(
  region = region, correlation_amplitude = 0.6,
  correlation_breadth = 300
)
spatial_correlation$calculate_compact_decomposition(decimals = 4)
# Example habitat suitability in file
saveRDS(
  array(c(0.5, 0.3, 0.7, 0.9, 0.6, 0.7, 0.8), c(7, 5)),
  file.path(tempdir(), "hs_mean_1.RData")
)
# Generator
capacity_gen <- Generator$new(
  description = "capacity",
  region = region,
  time_steps = 5,
  spatial_correlation = spatial_correlation,
  temporal_correlation = 0.9,
  hs_sd = 0.1, # template attached
  inputs = c("hs_file", "density_max", "initial_n"),
  outputs = c("initial_abundance", "carrying_capacity")
)
capacity_gen$add_generative_requirements(list(
  hs_mean = "file",
  hs_sample = "distribution",
  carrying_capacity = "function",
  initial_abundance = "function"
))
# File template for mean habitat suitability
capacity_gen$add_file_template("hs_mean",
  path_template = file.path(tempdir(), "hs_mean_%s.RData"),
  path_params = c("hs_file"), file_type = "RDS"
)
# Distribution template for sampling habitat suitability
capacity_gen$add_distribution_template("hs_sample",
  distr_type = "beta",
  distr_params = list(
    mean = "hs_mean",
    sd = "hs_sd"
  )
)
# Function templates for initial abundance and carrying capacity
capacity_gen$add_function_template("initial_abundance",
  function_def = function(params) {
    stats::rmultinom(1,
      size = params$initial_n,
      prob = params$hs_sample[, 1]
    )
  },
  call_params = c("initial_n", "hs_sample")
)
capacity_gen$add_function_template("carrying_capacity",
  function_def = function(params) {
    round(params$density_max * params$hs_sample)
  },
  call_params = c("density_max", "hs_sample")
)
# Generation
capacity_gen$generate(input_values = list(
  hs_file = 1,
  initial_n = 400,
  density_max = 100
))

Description

R6 class with generic (abstract) new cloning functionality.

Public fields

Methods

Public methods

• GenericClass$new()

• GenericClass$new_clone()

• GenericClass$clone()

Method new()

Initialization method saves an object generator for new cloning.

Usage

GenericClass$new(object_generator = NULL, ...)

Arguments

Method new_clone()

Creates a new (re-initialized) object of the current (inherited) object class with optionally passed parameters.

Usage

GenericClass$new_clone(...)

Arguments

Returns

New object of the current (inherited) class.

Method clone()

The objects of this class are cloneable with this method.

Usage

GenericClass$clone(deep = FALSE)

Arguments

Examples

object1 <- GenericClass$new()
class(object1)
# Referencing
object_ref <- object1
object_ref$attached$a <- 1
object1$attached
# Cloning
object2 <- object1$clone()
object2$attached$b <- 2
object1$attached
object2$attached
# New cloning
object3 <- object1$new_clone()
object3$attached$c <- 3
object1$attached
object3$attached

Description

R6 class to represent a generic (abstract) manager for generating or processing simulation results, as well as optionally generating values via generators.

Super class

poems::GenericClass -> GenericManager

Public fields

Active bindings

Methods

Public methods

• GenericManager$new()

• GenericManager$get_attribute()

• GenericManager$get_message_sample()

• GenericManager$get_results_filename()

• GenericManager$clone()

Method new()

Initialization method sets any included attributes (sample_data, generators, parallel_cores, results_dir, results_filename_attributes) and attaches other attributes individually listed.

Usage

GenericManager$new(...)

Arguments

Method get_attribute()

Returns a named manager or attached attribute.

Usage

GenericManager$get_attribute(param)

Arguments

Returns

Selected attribute value.

Method get_message_sample()

Substitutes the specified sample details into a status message (using sprintf) and returns the result.

Usage

GenericManager$get_message_sample(status_message, sample_index)

Arguments

Returns

Status message with substituted sample details.

Method get_results_filename()

Constructs and returns the results filename based on the sample data frame index and results filename attributes.

Usage

GenericManager$get_results_filename(sample_index)

Arguments

Returns

Results filename with substituted sample details.

Method clone()

The objects of this class are cloneable with this method.

Usage

GenericManager$clone(deep = FALSE)

Arguments

Examples

generic_manager <- GenericManager$new(
 attr1 = 22:23,
 results_filename_attributes = c("attr1", "example")
)
generic_manager$get_results_filename(1)
generic_manager$get_results_filename(2)

Description

R6 class with generic (abstract) functionality for toolset models, including model attribute get and set methods that resolve attribute scope (public, active, attached), attribute aliases, attribute attachment, and error and warning message attributes.

Super class

poems::GenericClass -> GenericModel

Public fields

Active bindings

Methods

Public methods

• GenericModel$new()

• GenericModel$new_clone()

• GenericModel$get_attribute_names()

• GenericModel$get_attributes()

• GenericModel$get_attribute()

• GenericModel$get_attribute_aliases()

• GenericModel$set_attributes()

• GenericModel$clone()

Method new()

Initialization method sets given attributes individually and/or from a list.

Usage

GenericModel$new(
  model_attributes = NULL,
  attribute_aliases = NULL,
  params = list(),
  ...
)

Arguments

Method new_clone()

Creates a new (re-initialized) object of the current (inherited) object class with optionally passed parameters.

Usage

GenericModel$new_clone(...)

Arguments

Returns

New object of the current (inherited) class.

Method get_attribute_names()

Returns an array of all attribute names including public and private model attributes, as well as attached attributes, error and warning messages.

Usage

GenericModel$get_attribute_names()

Returns

Array of all attribute names.

Method get_attributes()

Returns a list of values for selected attributes or attribute aliases (when array of parameter names provided) or all attributes (when no params).

Usage

GenericModel$get_attributes(params = NULL)

Arguments

Returns

List of selected or all attributes values.

Method get_attribute()

Returns the value of an attribute via character name or attribute alias.

Usage

GenericModel$get_attribute(param)

Arguments

Returns

Attribute value.

Method get_attribute_aliases()

Returns an array of attribute names and aliases for specified or all attributes.

Usage

GenericModel$get_attribute_aliases(params = NULL)

Arguments

Returns

Array of selected or all attribute names and aliases.

Method set_attributes()

Sets given attributes (optionally via alias names) individually and/or from a list.

Usage

GenericModel$set_attributes(params = list(), ...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

GenericModel$clone(deep = FALSE)

Arguments

Examples

model1 <- GenericModel$new(
  model_attributes = c("a", "b", "c"),
  attribute_aliases = list(A = "a"),
  params = list(a = 1, b = 2), c = 3
)
# Get/set attributes
model1$get_attribute_names()
model1$set_attributes(d = 4)
model1$get_attributes()
model1$get_attribute("A")
model1$get_attribute("B")
model1$get_attribute_aliases() # all attribute names
# New cloning
model2 <- model1$new_clone(e = 5)
model2$get_attributes()
model2$modelattributes
model2$attribute_aliases

Description

R6 class that generates Latin hypercube samples (using randomLHS) for parameters drawn from configured distributions: uniform, Poisson, normal, lognormal, beta, truncated normal or triangular. It generates a data frame of sample values.

Super class

poems::GenericClass -> LatinHypercubeSampler

Public fields

Active bindings

Methods

Public methods

• LatinHypercubeSampler$new()

• LatinHypercubeSampler$set_class_parameter()

• LatinHypercubeSampler$set_uniform_parameter()

• LatinHypercubeSampler$set_normal_parameter()

• LatinHypercubeSampler$set_poisson_parameter()

• LatinHypercubeSampler$set_lognormal_parameter()

• LatinHypercubeSampler$set_beta_parameter()

• LatinHypercubeSampler$set_truncnorm_parameter()

• LatinHypercubeSampler$set_triangular_parameter()

• LatinHypercubeSampler$generate_samples()

• LatinHypercubeSampler$clone()

Method new()

Initialization method sets parameter names when provided.

Usage

LatinHypercubeSampler$new(parameter_names = NULL, ...)

Arguments

Method set_class_parameter()

Sets a parameter to sampled from a vector of classes.

Usage

LatinHypercubeSampler$set_class_parameter(parameter_name, classes)

Arguments

Method set_uniform_parameter()

Sets a parameter to be sampled from a uniform distribution with lower and upper bounds, optionally rounded to a specified number of decimal places.

Usage

LatinHypercubeSampler$set_uniform_parameter(
  parameter_name,
  lower = 0,
  upper = 1,
  decimals = NULL
)

Arguments

Method set_normal_parameter()

Sets a parameter to be sampled from a normal distribution with mean and standard deviation, optionally rounded to a specified number of decimal places.

Usage

LatinHypercubeSampler$set_normal_parameter(
  parameter_name,
  mean = 0,
  sd = 1,
  decimals = NULL
)

Arguments

Method set_poisson_parameter()

Sets a parameter to be sampled from a Poisson distribution with lambda parameter. Produces integers.

Usage

LatinHypercubeSampler$set_poisson_parameter(parameter_name, lambda = 1)

Arguments

Method set_lognormal_parameter()

Sets a parameter to be sampled from a lognormal distribution with log mean and log standard deviation, optionally expressed as regular mean and SD (overriding log mean/sd), and optionally rounded to a specified number of decimal places.

Usage

LatinHypercubeSampler$set_lognormal_parameter(
  parameter_name,
  meanlog = 0,
  sdlog = 1,
  mean = NULL,
  sd = NULL,
  decimals = NULL
)

Arguments

Method set_beta_parameter()

Sets a parameter to be sampled from a beta distribution configured with alpha and beta parameters, or optionally with mean and standard deviation (overriding alpha and beta), and optionally rounded to a specified number of decimal places.

Usage

LatinHypercubeSampler$set_beta_parameter(
  parameter_name,
  alpha = 1,
  beta = 1,
  mean = NULL,
  sd = NULL,
  decimals = NULL
)

Arguments

Method set_truncnorm_parameter()

Sets a parameter to be sampled from a truncated normal distribution with mean, standard deviation, and lower and upper bounds, optionally rounded to a specified number of decimal places.

Usage

LatinHypercubeSampler$set_truncnorm_parameter(
  parameter_name,
  mean = 0,
  sd = 1,
  lower = -Inf,
  upper = Inf,
  decimals = NULL
)

Arguments

Method set_triangular_parameter()

Sets a parameter to be sampled from a triangular distribution with lower and upper bounds and mode (peak), optionally rounded to a specified number of decimal places.

Usage

LatinHypercubeSampler$set_triangular_parameter(
  parameter_name,
  lower = 0,
  upper = 1,
  mode = (lower + upper)/2,
  decimals = NULL
)

Arguments

Method generate_samples()

Generates Latin hypercube sample data (via randomLHS) for the set parameters using corresponding distributions.

Usage

LatinHypercubeSampler$generate_samples(number = 10, random_seed = NULL)

Arguments

Returns

A data frame of generated sample values.

Method clone()

The objects of this class are cloneable with this method.

Usage

LatinHypercubeSampler$clone(deep = FALSE)

Arguments

Examples

lhs_gen <- LatinHypercubeSampler$new(parameter_names = c("size", "age", "km", "price"))
lhs_gen$set_class_parameter("size", c("small", "medium", "large"))
lhs_gen$set_uniform_parameter("age", lower = 18, upper = 70, decimals = 0)
lhs_gen$set_poisson_parameter("offspring", lambda = 2)
lhs_gen$set_normal_parameter("km", mean = 50000, sd = 20000, decimals = 0)
lhs_gen$set_truncnorm_parameter("kg", mean = 75, sd = 20, lower = 0, upper = Inf, decimals = 2)
lhs_gen$set_lognormal_parameter("price", mean = 30000, sd = 10000, decimals = 0)
lhs_gen$set_beta_parameter("tread", mean = 0.7, sd = 0.1, decimals = 2)
lhs_gen$set_triangular_parameter("rating",
  lower = 0, upper = 10, mode = 5,
  decimals = 1
)
lhs_gen$generate_samples(number = 10, random_seed = 123)

Description

R6 class for running individual model simulations via a simulation function, storing results, and generating success/error statuses.

Super class

poems::GenericClass -> ModelSimulator

Public fields

Active bindings

Methods

Public methods

• ModelSimulator$new()

• ModelSimulator$new_clone()

• ModelSimulator$get_attribute()

• ModelSimulator$run()

• ModelSimulator$clone()

Method new()

Initialization method sets the population model, and optionally the simulation function, the sample ID, and any attached attributes listed individually.

Usage

ModelSimulator$new(
  simulation_model = NULL,
  simulation_function = NULL,
  sample_id = NULL,
  ...
)

Arguments

Method new_clone()

Creates a new (re-initialized) object of the current (inherited) object class with optionally passed parameters.

Usage

ModelSimulator$new_clone(...)

Arguments

Returns

New object of the current (inherited) class.

Method get_attribute()

Returns selected named simulator or attached attribute.

Usage

ModelSimulator$get_attribute(param)

Arguments

Returns

Selected parameter/attribute value.

Method run()

Runs a model simulator (function), stores the results, and creates a status log entry as a list.

Usage

ModelSimulator$run()

Returns

A list representing a simulation log entry with a successful boolean and a status message template (with a placeholder for the sample identifier).

Method clone()

The objects of this class are cloneable with this method.

Usage

ModelSimulator$clone(deep = FALSE)

Arguments

Examples

# Simulation model
model1 <- SimulationModel$new(
  time_steps = 10,
  model_attributes = c("time_steps", "a", "b"),
  params = list(a = 1:7)
)
model1$required_attributes <- model1$model_attributes
# Simulation function
test_simulator <- function(model) {
  sum(unlist(model$get_attributes(model$required_attributes)))
}
# Model simulator
simulator1 <- ModelSimulator$new(
  simulation_model = model1,
  simulation_function = test_simulator
)
simulator1$run()
model1$set_attributes(a = 1:10, b = 15)
model1$get_attributes(model1$required_attributes)
simulator1$run()
simulator1$results

Description

The poems package provides a framework of interoperable R6 classes for building ensembles of viable models via the pattern-oriented modeling (POM) approach (Grimm et al., 2005). The package includes classes for encapsulating and generating model parameters, and managing the POM workflow. The workflow includes: model setup; generating model parameters via Latin hypercube sampling; running multiple sampled model simulations; collating summary results; and validating and selecting an ensemble of models that best match known patterns. By default, model validation and selection utilizes an approximate Bayesian computation (ABC) approach (Beaumont, Zhang, & Balding, 2002), although alternative user-defined functionality could be employed. The package also includes a spatially explicit demographic population model simulation engine, which includes default functionality for density dependence, correlated environmental stochasticity, stage-based transitions, and distance-based dispersal. The user may customize the simulator by defining functionality for translocations, harvesting, mortality, and other processes, as well as defining the sequence order for the simulator processes. The framework could also be adapted for use with other model simulators by utilizing its extendable (inheritable) base classes.

Framework and workflow

The poems framework utilizes a hierarchy of extendable (inheritable) R6 class objects that work together to manage a POM workflow for building an ensemble of simulation models.

The workflow is summarized in the following steps:

1. Create a simulation model template (a SimulationModel or inherited class object) with appropriate fixed parameters for the study domain. Also define a study region via the Region class if the simulations are to be spatially explicit.

2. Create generators (Generator or inherited class objects) for dynamically generating (non-singular) model parameters represented by data structures, such as arrays or lists.

3. Generate a data frame of sampled variable model parameters using the LatinHypercubeSampler. This will include singular model parameter values as well as input parameters for the generators.

4. Create a SimulationManager object configured with the simulation model (template), the generators, and the sample parameter data frame. Running this manager sets and runs the models via the simulator function for each set (row) of sampled parameters, utilising the generators when required. The results of each model simulation run are written to a file. A simulation log file is also created.

5. Create a ResultsManager object configured with the sample parameter data and result file details. Running this manager constructs a data frame of configured summary metrics, one row for each simulation result file. The manager utilizes the SimulationResults (or inherited) class to encapsulate, and dynamically generate additional derived, results. The metrics are generated via user-defined specifications and functions for calculating each metric from the results (objects).

6. Create a Validator object configured with the sample parameter data, summary metrics, and target (observed) pattern values for each metric. By default, the validator utilizes an approximate Bayesian computation (ABC) validation method via the abc library, although the validator (call) function can be configured to utilize other library or user-defined functions. Running the validator (with appropriate call function configuration) produces an ensemble of models (indices to sampled parameters) that were found to best match the targets. Diagnostic outputs may also be produced (depending on the call function and its configuration).

7. The selected models may then be utilized for further studies, such as alternative model scenarios or counterfactuals. This can be achieved by utilizing the selected subset of parameter samples to form inputs for further model simulations (by repeating the steps above).

Population modeling components

The spatially explicit demographic population model simulation engine and its associated classes are summarized by the following:

• population_simulator function: The simulation engine's main function processes the model input parameters, controls the flow, calling other function modules as required, and returns the results of each simulation.

• population_density function: Module for configuring and performing density dependence calculations at each simulation time step. A user-defined function may be utilized.

• population_env_stoch function: Module for configuring and stochastically applying environmental variability to stage-based population transition rates at each simulation time step.

• population_transitions function: Module for configuring and performing stage-based demographic transitions of population abundances at each simulation time step.

• population_transformation function: Module for configuring and performing user-defined transformations to staged population abundances. This functionality is utilized when defining functions for translocation, harvest, mortality, or other custom transformative functions.

• population_dispersal function: Module for configuring and performing dispersal calculations at each simulation time step. A user-defined function may be utilized.

• population_results function: Module for configuring, initializing, and collating simulation results.

• PopulationModel class: Inherited from SimulationModel, this class encapsulates the input parameters utilized by the population_simulator.

• SimulatorReference class: This simple R6 class enables user-defined functionality to maintain persistent (attached) attributes and to write to the simulator results.

• SpatialCorrelation class: Provides functionality for generating parameters that can be utilized when optionally applying a spatial correlation within the simulator's environmental variability calculations.

• DispersalGenerator class: Inherited from Generator, this class provides functionality for generating distance-based dispersal parameters that can be utilized when performing dispersal calculations.

• DispersalFriction class: Provides functionality for adjusting the (equivalent) distance between population cells given a spatio-temporal frictional landscape. These adjustments may be utilized by the DispersalGenerator.

• PopulationResults class: Inherited from SimulationResults, this class encapsulates the results generated by the population_simulator, as well as dynamically generating additional derived results.

References

Beaumont, M. A., Zhang, W., & Balding, D. J. (2002). 'Approximate Bayesian computation in population genetics'. Genetics, vol. 162, no. 4, pp, 2025–2035.

Grimm, V., Revilla, E., Berger, U., Jeltsch, F., Mooij, W. M., Railsback, S. F., Thulke, H. H., Weiner, J., Wiegand, T., DeAngelis, D. L., (2005). 'Pattern-Oriented Modeling of Agent-Based Complex Systems: Lessons from Ecology'. Science vol. 310, no. 5750, pp. 987–991.

Examples

# Here we demonstrate building and running a simple population model. For a
# demonstration of the POM workflow with the model, see vignette("simple_example").

# Demonstration example region (U Island) and initial abundance
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)
initial_abundance <- seq(0, 300, 50)
raster::plot(region$raster_from_values(initial_abundance),
  main = "Initial abundance", xlab = "Longitude (degrees)",
  ylab = "Latitude (degrees)", zlim = c(0, 300), colNA = "blue"
)

# Set population model
pop_model <- PopulationModel$new(
  region = region,
  time_steps = 5,
  populations = 7,
  initial_abundance = initial_abundance,
  stage_matrix = matrix(c(
    0, 2.5, # Leslie/Lefkovitch matrix
    0.8, 0.5
  ), nrow = 2, ncol = 2, byrow = TRUE),
  carrying_capacity = rep(200, 7),
  density_dependence = "logistic",
  dispersal = (!diag(nrow = 7, ncol = 7)) * 0.05,
  result_stages = c(1, 2)
)

# Run single simulation
results <- population_simulator(pop_model)
results # examine
raster::plot(region$raster_from_values(results$abundance[, 5]),
  main = "Final abundance", xlab = "Longitude (degrees)",
  ylab = "Latitude (degrees)", zlim = c(0, 300), colNA = "blue"
)

Description

Modular functions for the population simulator for performing density dependent adjustments to transition rates.

Usage

population_density(
  populations,
  stage_matrix,
  fecundity_mask,
  fecundity_max,
  density_dependence,
  growth_rate_max,
  density_affects,
  density_stages,
  density_precision,
  simulator
)

Arguments

Value

Density dependent calculation function, either:

function(carrying_capacity, stage_abundance)

For ceiling density dependence function, OR

function(transition_array, carrying_capacity, stage_abundance, occupied_indices)

For user-defined density dependence function, where:

transition_array

3D array of transition rates: stages by stages by populations.

carrying_capacity

Array of carrying capacity values for each population.

stage_abundance

Matrix of abundance for each stage (rows) and population (columns).

occupied_indices

Array of indices for populations occupied.

Examples

# Ceiling density dependence
stage_matrix <- array(c(0, 0.5, 0, 3, 0, 0.7, 4, 0, 0.8), c(3, 3))
fecundity_mask <- array(c(0, 0, 0, 1, 0, 0, 1, 0, 0), c(3, 3))
simulator <- SimulatorReference$new()
density_function <- population_density(
 populations = 7, stage_matrix = stage_matrix, fecundity_mask = fecundity_mask,
 fecundity_max = NULL, density_dependence = "ceiling",
 growth_rate_max = NULL, density_affects = NULL, density_stages = c(0, 1, 1),
 density_precision = NULL, simulator = simulator
)
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)

# Life cycle stages 2 and 3 (rows 2 and 3) all add up to 10 or less
density_function(carrying_capacity, stage_abundance)

Description

Modular functions for the population simulator for performing dispersal of stage abundance at a specified time step via dispersal rates provided.

Usage

population_dispersal(
  replicates,
  time_steps,
  years_per_step,
  populations,
  demographic_stochasticity,
  density_stages,
  dispersal,
  dispersal_stages,
  dispersal_source_n_k = NULL,
  dispersal_target_k = NULL,
  dispersal_target_n = NULL,
  dispersal_target_n_k = NULL,
  simulator
)

Arguments

Value

Dispersal 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

New stage abundance matrix with dispersal applied.

Examples

# User-defined dispersal: one-quarter of dispersing stages move one population over
simulator <- SimulatorReference$new()
example_function <- function(params) {
  params$simulator$attached$params <- params # attach to reference object
  emigrants <- round(params$stage_abundance * params$dispersal_stages * 0.25)
  return(params$stage_abundance - emigrants + emigrants[, c(7, 1:6)])
}
dispersal_function <- population_dispersal(
 replicates = 4,
 time_steps = 10,
 years_per_step = 1,
 populations = 7,
 demographic_stochasticity = TRUE,
 density_stages = c(0, 1, 1),
 dispersal = example_function,
 dispersal_stages = c(0, 1, 0.5),
 dispersal_source_n_k = list(cutoff = -0.5, threshold = 1.5),
 dispersal_target_k = 5,
 dispersal_target_n = list(threshold = 10, cutoff = 15),
 simulator = simulator
)
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]
dispersal_function(r = 2, tm = 6, carrying_capacity, stage_abundance,
                   occupied_indices)

Description

Modular functions for the population simulator for performing correlated environmentally stochastic adjustments to transition rates.

Usage

population_env_stoch(
  populations,
  fecundity_matrix,
  fecundity_max,
  survival_matrix,
  standard_deviation,
  correlation
)

Arguments

Value

Environmental stochasticity calculation function: function(fecundity_array, survival_array, occupied_indices), where:

fecundity_array

3D array of fecundity rates (stages rows by stages columns by populations deep).

survival_array

3D array of survival rates (stages rows by stages columns by populations deep).

occupied_indices

Array of indices for those populations occupied.

returns

List containing stochastically varied fecundity and survival arrays.

Examples

fecundity_matrix <- array(c(0, 0, 0, 3, 0, 0, 4, 0, 0), c(3, 3))
survival_matrix <- array(c(0, 0.5, 0, 0, 0, 0.7, 0, 0, 0.8), c(3, 3))
standard_deviation <- (fecundity_matrix + survival_matrix) * 0.3
variation_array <- array(rep(seq(0.85, 1.15, 0.05), each = 9), c(3, 3, 7))
fecundity_array <- array(fecundity_matrix, c(3, 3, 7)) * variation_array
survival_array <- array(survival_matrix, c(3, 3, 7)) * variation_array
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]
env_stoch_function <- population_env_stoch(
  populations = 7, fecundity_matrix, fecundity_max = NULL, survival_matrix,
  standard_deviation, correlation = NULL
)
env_stoch_function(fecundity_array, survival_array, occupied_indices)

Description

Modular functions for the population simulator for initializing, calculating and collecting simulator results.

Usage

population_results(
  replicates,
  time_steps,
  coordinates,
  initial_abundance,
  results_selection = NULL,
  result_stages = NULL
)

Arguments

Value

List of result functions:

initialize_attributes = function())

Constructs and returns an initialized nested list for the selected result attributes.

initialize_replicate = function(results)

Initializes and returns nested result attributes at the start of each replicate.

calculate_at_timestep = function(r, tm, stage_abundance, harvested, results)

Appends and calculates (non-NULL) results and returns nested result attributes at the end of each time step (tm) within replicate (r).

finalize_attributes = function(results)

Finalizes result calculations at the end of the simulation.

Examples

coordinates <- array(c(1:4, 4:1), c(7, 2))
initial_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)
results_selection <- c("abundance", "ema", "extirpation", 
                        "extinction_location", "harvested", "occupancy")
result_functions <- population_results(
  replicates = 1, time_steps = 10, coordinates, initial_abundance,
  results_selection = results_selection, result_stages = c(0, 1, 1)
)
result_functions$initialize_attributes()

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

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

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

Arguments

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

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)

Description

Modular functions for the population simulator for performing staged-based (Leslie/Lefkovitch matrix) transitions via 3D survival and fecundity arrays.

Usage

population_transitions(
  populations,
  demographic_stochasticity,
  fecundity_matrix,
  fecundity_max,
  survival_matrix
)

Arguments

Value

Transition calculation function: function(fecundity_array, survival_array, stage_abundance, occupied_indices), where:

fecundity_array

3D array of fecundity rates (stages rows by stages columns by populations deep).

survival_array

3D array of survival rates (stages rows by stages columns by populations deep).

stage_abundance

Matrix of stage abundances for each population at time step (stages rows by populations columns).

occupied_indices

Array of indices for those populations occupied.

returns

Transitioned stage abundances.

Examples

# Deterministic transition (no stochasticity)
fecundity_matrix <- array(c(0, 0, 0, 3, 0, 0, 4, 0, 0), c(3, 3))
survival_matrix <- array(c(0, 0.5, 0, 0, 0, 0.7, 0, 0, 0.8), c(3, 3))
variation_array <- array(rep(seq(0.85, 1.15, 0.05), each = 9), c(3, 3, 7))
fecundity_array <- array(fecundity_matrix, c(3, 3, 7)) * variation_array
survival_array <- array(survival_matrix, c(3, 3, 7)) * variation_array
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]
transition_function <- population_transitions(
  populations = 7, demographic_stochasticity = FALSE,
  fecundity_matrix = fecundity_matrix, fecundity_max = NULL,
  survival_matrix = survival_matrix
)
transition_function(fecundity_array, survival_array, stage_abundance, 
                    occupied_indices)

Description

R6 class representing a spatially-explicit demographic-based population model. It extends the SimulationModel class with parameters for the population_simulator function. It inherits functionality for creating a nested model, whereby a nested template model with fixed parameters is maintained when a model is cloned for various sampled parameters. Also provided are extensions to the methods for checking the consistency and completeness of model parameters.

Super classes

poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> poems::SimulationModel -> PopulationModel

Public fields

Active bindings

Methods

Public methods

• PopulationModel$new()

• PopulationModel$list_consistency()

• PopulationModel$clone()

Method new()

Initialization method sets default aliases and given attributes individually and/or from a list.

Usage

PopulationModel$new(attribute_aliases = NULL, ...)

Arguments

Method list_consistency()

Returns a boolean to indicate if (optionally selected or all) model attributes (such as dimensions) are consistent.

Usage

PopulationModel$list_consistency(params = NULL)

Arguments

Returns

List of booleans (or NAs) to indicate consistency of selected/all attributes.

Method clone()

The objects of this class are cloneable with this method.

Usage

PopulationModel$clone(deep = FALSE)

Arguments

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 = NA, # set later
  function(params) round(params$stage_abundance * (1 - params$rate))
)
harvest_rate_alias <- list(harvest_rate = "harvest$rate")
# Template model
stage_matrix <- matrix(c(
  0, 2.5, # Leslie/Lefkovitch matrix
  0.8, 0.5
), nrow = 2, ncol = 2, byrow = TRUE)
template_model <- PopulationModel$new(
  region = region,
  time_steps = 10, # years
  populations = region$region_cells, # 7
  stage_matrix = stage_matrix,
  harvest = harvest,
  results_selection = c("abundance", "harvested"),
  attribute_aliases = harvest_rate_alias
)
template_model$model_attributes
template_model$required_attributes
# Nested model
nested_model <- PopulationModel$new(template_model = template_model)
nested_model$incomplete_attributes()
nested_model$set_sample_attributes(
  initial_abundance = rep(10, 7),
  carrying_capacity = array(70:1, c(10, 7)),
  harvest_rate = 0.3
)
nested_model$inconsistent_attributes()
nested_model$carrying_capacity <- array(70:1, c(7, 10))
nested_model$is_consistent()
nested_model$is_complete()
nested_model$harvest$rate

Description

R6 class encapsulating and dynamically generating spatially-explicit population_simulator results, as well as optional re-generated Generator outputs.

Super classes

poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> poems::SimulationResults -> PopulationResults

Public fields

Active bindings

Methods

Public methods

• PopulationResults$clone()

Method clone()

The objects of this class are cloneable with this method.

Usage

PopulationResults$clone(deep = FALSE)

Arguments

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)
raster::plot(region$region_raster,
  main = "Example region (indices)",
  xlab = "Longitude (degrees)", ylab = "Latitude (degrees)",
  colNA = "blue"
)
# Sample results occupancy (ignore cell 2 in last 5 time steps)
occupancy_raster <- region$raster_from_values(array(1, c(7, 13)))
occupancy_raster[region$region_indices][2, 9:13] <- 0
occupancy_raster[region$region_indices]
# Population simulation example results
example_results <- list(abundance = t(apply(matrix(11:17), 1, function(n) {
  c(rep(n, 3), round(n * exp(-(0:9) / 2)))
})))
example_results$harvested <- round(example_results$abundance * 0.3)
example_results
# Population results object
pop_results <- PopulationResults$new(
  region = region,
  time_steps = 13,
  burn_in_steps = 3,
  occupancy_mask = occupancy_raster,
  trend_interval = 1:5
)
pop_results$get_attribute_names(all = TRUE)
# Clone (for each population simulation results)
results_clone <- pop_results$new_clone(results = example_results)
results_clone$all$get_attribute("abundance")
results_clone$get_attributes(c(
  "abundance", "all$abundance",
  "abundance_trend", "all$abundance_trend",
  "all$ema", # only defined for all
  "extirpation", "all$extirpation",
  "all$extinction_location", # only defined for all
  "harvested", "all$harvested",
  "occupancy", "all$occupancy"
))

Description

R6 class representing a study region of spatial grid cells defined via a list of longitude/latitude cell coordinates (WGS84), or a RasterLayer object (see raster).

Super class

poems::GenericClass -> Region

Public fields

Active bindings

Methods

Public methods

• Region$new()

• Region$raster_is_consistent()

• Region$raster_from_values()

• Region$clone()

Method new()

Initialization method sets coordinates or raster for region.

Usage

Region$new(
  coordinates = NULL,
  template_raster = NULL,
  region_raster = NULL,
  use_raster = TRUE,
  ...
)

Arguments

Method raster_is_consistent()

Returns a boolean to indicate if a raster is consistent with the region raster (matching extent, resolution, and finite/NA cells).

Usage

Region$raster_is_consistent(check_raster)

Arguments

Returns

Boolean to indicate if the raster is consistent with the region raster.

Method raster_from_values()

Converts an array (or matrix) of values into a raster (or stack) consistent with the region raster (matching extent, resolution, and finite/NA cells).

Usage

Region$raster_from_values(values)

Arguments

Returns

A RasterLayer (or RasterStack/Brick) object consistent with the region raster.

Method clone()

The objects of this class are cloneable with this method.

Usage

Region$clone(deep = FALSE)

Arguments

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)
raster::plot(region$region_raster,
  main = "Example region (cell indices)",
  xlab = "Longitude (degrees)", ylab = "Latitude (degrees)",
  colNA = "blue"
)
region$region_cells
region$coordinates
# Generate value layers
value_brick <- region$raster_from_values(array(8:28, c(7, 3)))
raster::plot(value_brick,
  main = "Example value layers",
  xlab = "Longitude (degrees)", ylab = "Latitude (degrees)",
  colNA = "blue"
)
value_brick[region$region_indices]

Description

R6 class to represent a manager for generating summary metrics and/or matrices from simulation results, as well as optionally regenerating values via generators.

Super classes

poems::GenericClass -> poems::GenericManager -> ResultsManager

Public fields

Active bindings

Methods

Public methods

• ResultsManager$new()

• ResultsManager$generate()

• ResultsManager$calculate_result_attachments()

• ResultsManager$calculate_summaries()

• ResultsManager$log_generation()

• ResultsManager$calculate_summary_weighted_averages()

• ResultsManager$clone()

Method new()

Initialization method optionally copies attributes from a simulation (results) manager, sets any included attributes (sample_data, simulation_results, generators, result_attachment_functions, summary_metrics, summary_functions, parallel_cores, results_dir, results_ext, results_filename_attributes), and attaches other attributes individually listed.

Usage

ResultsManager$new(simulation_manager = NULL, ...)

Arguments

Method generate()

Generates the summary metric data and/or matrix list via the summary functions for each simulation sample, and creates/writes a generation log.

Usage

ResultsManager$generate(results_dir = NULL)

Arguments

Returns

Generation log as a list.

Method calculate_result_attachments()

Calculates and attaches intermediate values to the sample result model (via the result attachment functions).

Usage

ResultsManager$calculate_result_attachments(simulation_results)

Arguments

Method calculate_summaries()

Calculates the summary metrics and/or matrices for the results of a sample simulation (via the summary functions).

Usage

ResultsManager$calculate_summaries(simulation_results, sample_index)

Arguments

Returns

Generation log entry as a (nested) list, including generated summary metric data and (optionally) matrices.

Method log_generation()

Summarizes the log generated within the generate method and writes it to a text file in the results directory.

Usage

ResultsManager$log_generation(generation_log)

Arguments

Returns

Extended generation log as a nested with added summary and failure/warning indices.

Method calculate_summary_weighted_averages()

Calculates the weighted averages for each of the summary matrices (providing the sample data has a weight column).

Usage

ResultsManager$calculate_summary_weighted_averages(na_replacements = NULL)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

ResultsManager$clone(deep = FALSE)

Arguments

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)
raster::plot(region$region_raster,
  main = "Example region (indices)",
  xlab = "Longitude (degrees)", ylab = "Latitude (degrees)",
  colNA = "blue"
)
# Results manager
results_manager <- ResultsManager$new(
  sample_data = data.frame(index = 1:3),
  simulation_results = PopulationResults$new(region = region),
  summary_metrics = c("trend_n", "total_h"),
  summary_matrices = c("n", "h"),
  summary_functions = list(
    trend_n = function(results) {
      round(results$all$abundance_trend, 2)
    },
    total_h = function(results) {
      sum(results$harvested)
    },
    n = "all$abundance", # string
    h = "all$harvested"
  ),
  parallel_cores = 2,
  results_dir = tempdir()
)
# Write example result files
results <- list()
for (i in 1:3) {
  results[[i]] <- list(abundance = t(apply(
    matrix(11:17), 1,
    function(n) round(n * exp(-(0:9) / i))
  )))
  results[[i]]$harvested <- round(results[[i]]$abundance * i / 7)
  file_name <- paste0(results_manager$get_results_filename(i), ".RData")
  saveRDS(results[[i]], file.path(tempdir(), file_name))
}
# Generate result metrics and matrices
gen_output <- results_manager$generate()
gen_output$summary
dir(tempdir(), "*.txt") # plus generation log
results_manager$summary_metric_data
results_manager$summary_matrix_list