Generator: R6 class representing a dynamic attribute generator

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

Arguments

Super classes

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

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).
description: A brief description of what the generator generates.
inputs: An array of input attribute names for the generator.
outputs: An array of output attribute names for the generator.
file_templates: A nested list of file template attributes.
function_templates: A nested list of function template attributes.
distribution_templates: A list of distribution template attributes.
uses_correlations: A boolean to indicate that a SpatialCorrelation (or inherited class) object is used for generating correlated random deviates.
spatial_correlation: A SpatialCorrelation (or inherited class) object for generating correlated random deviates.
temporal_correlation: Absolute correlation coefficient between simulation time steps for all grid cells (0-1; default = 1).
time_steps: Number of simulation time steps.
generate_rasters: Boolean to indicate if rasters should be generated (defaults to TRUE when region uses rasters).
decimals: Number of decimal places applied to generated data outputs (default: NULL = no rounding).
occupancy_mask: Optional binary mask array (matrix), data frame, or raster (stack) for generated (time-series) data outputs.
template_attached: A list of template-nested dynamically attached model attributes that are maintained via shallow or new cloning.
attribute_aliases: A list of alternative alias names for model attributes (form: alias = "attribute") to be used with the set and get attributes methods.
generative_template: A nested GenerativeTemplate (or inherited class) object for model attributes that are maintained via shallow or new cloning.
generative_requirements: A list of attribute names and the template setting ("file", "function", or "default") that is required to generate their values.
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

Inherited methods

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

generative_template: A GenerativeTemplate (or inherited class) object containing the file, function and/or distribution templates utilized (facilitates shallow cloning).

generative_requirements

A list of attribute names and the template setting ("file", "function", or "distribution") that is required to generate their values.

...

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

Generator$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_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

params: Array of attribute names to return, including those to be template-generated (all when NULL).

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

input_values: List of sample input values for generator attributes.

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

param: Name of model attribute to be read from a file.

path_template

Template string for the file path with %s placeholders (see sprintf) for simulation sample parameters.

path_params

Array of the names of the simulation sample parameters to be substituted (in order) into the path template.

file_type

File type raster "GRD" (default), "RData/RDS" or "CSV" to be read.

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

param: Name of model attribute to be generated using a function.

function_def

Function definition (or path to the file containing the function) in form: function(params), where params is a list passed to the function.

call_params

Array of the names of the model parameters/attributes to be passed into the function via a list: params.

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

param: Name of model attribute to be generated via sampling a distribution.

distr_type

Distribution type to sample from (uniform, normal, lognormal, beta or triangular).

distr_params

List of distribution parameters and their values or associated model attributes (uniform: lower, upper; normal: mean, sd; lognormal: meanlog, sdlog (or mean, sd); beta: alpha, beta (or mean, sd); triangular: lower, mode, upper).

sample

Model attribute(s) name(s) or values associated with single sample probabilities (0-1), or bounds as a vector (e.g. sample = c("p_lower", "p_upper")), or as a list (e.g. sample = list(mid = "p", window = 0.2) for bounds p +/- 0.1).

random_seed

Random seed utilized when sample probability is generated internally, via bounds, and/or correlated deviates.

normalize_threshold

Optional normalization threshold is utilized when generated values are to be normalized with a fixed upper limit/threshold.

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

param: Name of model attribute to be read from the file.

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

param: Name of model attribute to be calculated using a function.

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

param: Name of model attribute to be calculated using a sampling distribution.

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

params: Parameters passed via a list (e.g. params = list(attr1 = "file", attr2 = "function", attr3 = "distribution")).

...

Parameters passed individually (e.g. attr3 = "file").

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

deep: Whether to make a deep clone.

Examples

Run this code

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

Run the code above in your browser using DataLab

Description

Arguments

Super classes

Public fields

Active bindings

Methods

Public methods

Method new()

Usage

Arguments

Method new_clone()

Usage

Arguments

Returns

Method get_attributes()

Usage

Arguments

Returns

Method generate()

Usage

Arguments

Returns

Method add_file_template()

Usage

Arguments

Method add_function_template()

Usage

Arguments

Method add_distribution_template()

Usage

Arguments

Method read_file()

Usage

Arguments

Returns

Method run_function()

Usage

Arguments

Returns

Method sample_distribution()

Usage

Arguments

Returns

Method add_generative_requirements()

Usage

Arguments

Method generative_requirements_satisfied()

Usage

Returns

Method clone()

Usage

Arguments

Examples

Method `new()`

Method `new_clone()`

Method `get_attributes()`

Method `generate()`

Method `add_file_template()`

Method `add_function_template()`

Method `add_distribution_template()`

Method `read_file()`

Method `run_function()`

Method `sample_distribution()`

Method `add_generative_requirements()`

Method `generative_requirements_satisfied()`

Method `clone()`