Generator: R6 class representing a dynamic attribute generator
In poems: Pattern-Oriented Ensemble Modeling System
Generator R Documentation
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).
Super classes
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> Generator
Public fields
attachedA list of dynamically attached attributes (name-value pairs).
Active bindings
model_attributesA vector of model attribute names.
regionA Region (or inherited class) object specifying the study region.
coordinatesData 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).
descriptionA brief description of what the generator generates.
inputsAn array of input attribute names for the generator.
outputsAn array of output attribute names for the generator.
file_templatesA nested list of file template attributes.
function_templatesA nested list of function template attributes.
distribution_templatesA list of distribution template attributes.
uses_correlationsA boolean to indicate that a SpatialCorrelation (or inherited class) object is used for generating correlated random deviates.
spatial_correlationA SpatialCorrelation (or inherited class) object for generating correlated random deviates.
temporal_correlationAbsolute correlation coefficient between simulation time steps for all grid cells (0-1; default = 1).
time_stepsNumber of simulation time steps.
generate_rastersBoolean to indicate if rasters should be generated (defaults to TRUE when region uses rasters).
decimalsNumber of decimal places applied to generated data outputs (default: NULL = no rounding).
occupancy_maskOptional binary mask array (matrix), data frame, or raster (stack) for generated (time-series) data outputs.
template_attachedA list of template-nested dynamically attached model attributes that are maintained via shallow or new cloning.
attribute_aliasesA list of alternative alias names for model attributes (form: alias = "attribute") to be used with the set and get attributes methods.
generative_templateA nested GenerativeTemplate (or inherited class) object for model attributes that are maintained via shallow or new cloning.
generative_requirementsA list of attribute names and the template setting ("file", "function", or "default") that is required to generate their values.
error_messagesA vector of error messages encountered when setting model attributes.
warning_messagesA 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_templateA GenerativeTemplate (or inherited class) object containing the file, function and/or distribution templates utilized (facilitates shallow cloning).
generative_requirementsA 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
paramsArray 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_valuesList 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
paramName of model attribute to be read from a file.
path_templateTemplate string for the file path with %s placeholders (see sprintf) for simulation sample parameters.
path_paramsArray of the names of the simulation sample parameters to be substituted (in order) into the path template.
file_typeFile 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
paramName of model attribute to be generated using a function.
function_defFunction definition (or path to the file containing the function) in form: function(params), where params is a list passed to the function.
call_paramsArray 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
paramName of model attribute to be generated via sampling a distribution.
distr_typeDistribution type to sample from (uniform, normal, lognormal, beta or triangular).
distr_paramsList 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).
sampleModel 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_seedRandom seed utilized when sample probability is generated internally, via bounds, and/or correlated deviates.
normalize_thresholdOptional 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
paramName 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
paramName 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
paramName 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
paramsParameters 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
deepWhether 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))
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))
poems documentation built on Oct. 7, 2023, 9:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Generator | R Documentation |
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).
Super classes
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> Generator
Public fields
attachedA list of dynamically attached attributes (name-value pairs).
Active bindings
model_attributesA vector of model attribute names.
regionA
Region(or inherited class) object specifying the study region.coordinatesData 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).
descriptionA brief description of what the generator generates.
inputsAn array of input attribute names for the generator.
outputsAn array of output attribute names for the generator.
file_templatesA nested list of file template attributes.
function_templatesA nested list of function template attributes.
distribution_templatesA list of distribution template attributes.
uses_correlationsA boolean to indicate that a
SpatialCorrelation(or inherited class) object is used for generating correlated random deviates.spatial_correlationA
SpatialCorrelation(or inherited class) object for generating correlated random deviates.temporal_correlationAbsolute correlation coefficient between simulation time steps for all grid cells (0-1; default = 1).
time_stepsNumber of simulation time steps.
generate_rastersBoolean to indicate if rasters should be generated (defaults to TRUE when region uses rasters).
decimalsNumber of decimal places applied to generated data outputs (default: NULL = no rounding).
occupancy_maskOptional binary mask array (matrix), data frame, or raster (stack) for generated (time-series) data outputs.
template_attachedA list of template-nested dynamically attached model attributes that are maintained via shallow or new cloning.
attribute_aliasesA list of alternative alias names for model attributes (form:
alias = "attribute") to be used with the set and get attributes methods.generative_templateA nested
GenerativeTemplate(or inherited class) object for model attributes that are maintained via shallow or new cloning.generative_requirementsA list of attribute names and the template setting ("file", "function", or "default") that is required to generate their values.
error_messagesA vector of error messages encountered when setting model attributes.
warning_messagesA 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_templateA
GenerativeTemplate(or inherited class) object containing the file, function and/or distribution templates utilized (facilitates shallow cloning).generative_requirementsA 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
paramsArray 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_valuesList 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
paramName of model attribute to be read from a file.
path_templateTemplate string for the file path with %s placeholders (see
sprintf) for simulation sample parameters.path_paramsArray of the names of the simulation sample parameters to be substituted (in order) into the path template.
file_typeFile 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
paramName of model attribute to be generated using a function.
function_defFunction definition (or path to the file containing the function) in form:
function(params), where params is a list passed to the function.call_paramsArray 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
paramName of model attribute to be generated via sampling a distribution.
distr_typeDistribution type to sample from (uniform, normal, lognormal, beta or triangular).
distr_paramsList 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).
sampleModel 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_seedRandom seed utilized when sample probability is generated internally, via bounds, and/or correlated deviates.
normalize_thresholdOptional 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
paramName 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
paramName 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
paramName 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
paramsParameters 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
deepWhether 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))
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))
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.