poems (version 1.3.2)

SimulationResults: R6 class representing simulation results.

Description

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

Super classes

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

Public fields

attached

A list of dynamically attached attributes (name-value pairs).

Active bindings

model_attributes

A vector of model attribute names.

region

A Region (or inherited class) object specifying the study region.

coordinates

Data frame (or matrix) of X-Y population (WGS84) coordinates in longitude (degrees West) and latitude (degrees North) (get and set), or distance-based coordinates dynamically returned by region raster (get only).

time_steps

Number of simulation time steps.

burn_in_steps

Optional number of initial 'burn-in' time steps to be ignored.

occupancy_mask

Optional binary mask array (matrix), data frame, or raster (stack) for each cell at each time-step of the simulation including burn-in.

all

Nested simulation results for all cells.

parent

Parent simulation results for individual cells.

default

Default value/attribute utilized when applying primitive metric functions (e.g. max) to the results.

attribute_aliases

A list of alternative alias names for model attributes (form: alias = "attribute") to be used with the set and get attributes methods.

error_messages

A vector of error messages encountered when setting model attributes.

warning_messages

A vector of warning messages encountered when setting model attributes.

Methods

Public methods

• SimulationResults$new()

• SimulationResults$new_clone()

• SimulationResults$get_attribute_names()

• SimulationResults$get_attributes()

• SimulationResults$set_attributes()

• SimulationResults$clone()

Inherited methods

• poems::GenericModel$get_attribute()
• poems::GenericModel$get_attribute_aliases()

---

Method new()

Initialization method sets attributes from a results list or file, and sets object attributes individually and/or from a list.

Usage

SimulationResults$new(results = NULL, parent = NULL, ...)

Arguments

results

A list containing results or a file path to simulation results.

parent

Parent simulation results for individual cells (used when nesting a simulation results clone for all cells).

...

Parameters passed via a params list or individually.

---

Method new_clone()

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

Usage

SimulationResults$new_clone(...)

Arguments

...

Parameters passed via the inherited class constructor (defined in initialize and run via new).

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

SimulationResults$get_attribute_names(all = FALSE)

Arguments

all

Boolean to indicate if a nested list for all cells (when present) should be also listed (default is FALSE).

Returns

Array of all attribute names with optional inclusion of attribute names of nested results for all cells.

---

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

SimulationResults$get_attributes(params = NULL, remove_burn_in = TRUE)

Arguments

params

Array of attribute names to return (all when NULL).

remove_burn_in

Boolean to indicate whether or not to remove burn-in steps from the attribute values (default = TRUE; mostly for internal use).

Returns

List of selected or all attributes values.

---

Method set_attributes()

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

Usage

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

Arguments

params

List of parameters/attributes.

...

Parameters/attributes passed individually.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

SimulationResults$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

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 3 time steps)
occupancy_raster <- region$raster_from_values(array(1, c(7, 13)))
occupancy_raster[region$region_indices][2, 11:13] <- 0
occupancy_raster[region$region_indices]
# Simulation example results
example_results <- list(abundance = region$raster_from_values(
  t(apply(
    matrix(11:17), 1,
    function(n) c(rep(n, 3), round(n * exp(-(0:9) / log(n))))
  ))
))
example_results$abundance[region$region_indices]
# Simulation results object
sim_results <- SimulationResults$new(
  region = region,
  time_steps = 13,
  burn_in_steps = 3,
  occupancy_mask = occupancy_raster
)
# Clone (for each simulation results)
results_clone <- sim_results$new_clone(results = example_results)
results_clone$get_attribute("abundance")
results_clone$get_attribute("abundance")[region$region_indices]
results_clone$all$get_attribute("abundance")
results_clone$get_attribute("all$abundance")