SimulationModel: R6 class representing a simulation model
In poems: Pattern-Oriented Ensemble Modeling System
SimulationModel R Documentation
R6 class representing a simulation model
Description
R6 class representing a spatially-explicit simulation
model. It extends the SpatialModel class with a range of common
simulation parameters and 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 methods for checking the consistency and
completeness of model parameters.
Super classes
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> SimulationModel
Public fields
attachedA list of dynamically attached attributes (name-value pairs).
Active bindings
simulation_functionName (character string) or source path of the default simulation function, which takes a model as an input and returns the simulation results.
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).
random_seedNumber to seed the random number generation for stochasticity.
replicatesNumber of replicate simulation runs.
time_stepsNumber of simulation time steps.
years_per_stepNumber of years per time step.
results_selectionList of simulator-dependent attributes to be included in the returned results of each simulation run.
attribute_aliasesA list of alternative alias names for model attributes (form: alias = "attribute") to be used with the set and get attributes methods.
template_modelNested template model for fixed (non-sampled) attributes for shallow cloning.
sample_attributesVector of sample attribute names (only).
required_attributesVector of required attribute names (only), i.e. those needed to run a simulation.
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
-
-
-
-
-
-
-
-
-
-
-
-
-
Method new()
Initialization method sets template model and sets given attributes individually and/or from a list.
Usage
SimulationModel$new(template = NULL, required_attributes = NULL, ...)
Arguments
templateTemplate simulation model (nested) containing fixed (non-sampled) attributes.
required_attributesVector of required attribute names (only), i.e. those needed to run a simulation.
...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
SimulationModel$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 a list of all attribute names including public and private model attributes, as well as attached attributes (including those from the template model).
Usage
SimulationModel$get_attribute_names()
Returns
List 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
SimulationModel$get_attributes(params = NULL)
Arguments
paramsArray of attribute names to return (all when NULL).
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
SimulationModel$set_attributes(params = list(), ...)
Arguments
paramsList of parameters/attributes.
...Parameters/attributes passed individually.
Method set_sample_attributes()
Sets the names (only - when params is a vector) and values (when params is a list and/or when name-value pairs are provided) of the sample attributes for the model.
Usage
SimulationModel$set_sample_attributes(params = list(), ...)
Arguments
paramsList of parameters/attributes (names and values) or array of names only.
...Parameters/attributes passed individually.
Method is_consistent()
Returns a boolean to indicate if (optionally selected or all) model attributes (such as dimensions) are consistent/valid.
Usage
SimulationModel$is_consistent(params = NULL)
Arguments
paramsOptional array of parameter/attribute names.
Returns
Boolean to indicate consistency of selected/all attributes.
Method list_consistency()
Returns a boolean to indicate if (optionally selected or all) model attributes (such as dimensions) are consistent/valid.
Usage
SimulationModel$list_consistency(params = NULL)
Arguments
paramsOptional array of parameter/attribute names.
Returns
List of booleans (or NAs) to indicate consistency of selected/all attributes.
Method inconsistent_attributes()
Returns a list of attributes necessary to simulate the model that are inconsistent/invalid.
Usage
SimulationModel$inconsistent_attributes(include_nas = FALSE)
Arguments
include_nasOptional boolean indicating whether of not to include attributes with unknown consistency (NA).
Returns
List of inconsistent attributes which prevent the model simulation (and optionally those where consistency is not available).
Method is_complete()
Returns a boolean to indicate if all attributes necessary to simulate the model have been set and are consistent/valid.
Usage
SimulationModel$is_complete()
Returns
Boolean to indicate model completeness (and consistency).
Method list_completeness()
Returns a list of booleans (or NAs) for each parameter to indicate attributes that are necessary to simulate the model have been set and are consistent/valid.
Usage
SimulationModel$list_completeness()
Returns
List of booleans (or NAs) for each parameter to indicate to indicate completeness (and consistency).
Method incomplete_attributes()
Returns a list of attributes necessary to simulate the model that are incomplete/inconsistent/invalid.
Usage
SimulationModel$incomplete_attributes(include_nas = FALSE)
Arguments
include_nasOptional boolean indicating whether of not to include attributes with unknown completeness (NA).
Returns
List of incomplete attributes which prevent the model simulation (and optionally those where completeness is not available).
Method clone()
The objects of this class are cloneable with this method.
Usage
SimulationModel$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)
)
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)
# Model template
template_model <- SimulationModel$new(
simulation_function = "test_simulator",
region = region, time_steps = 10
)
template_model$model_attributes <- c(
template_model$model_attributes,
"a", "b", "c", "d"
)
template_model$model_attributes
template_model$required_attributes <- c(
template_model$required_attributes[1:2],
"a", "b", "c", "d"
)
template_model$required_attributes
template_model$get_attributes(template_model$required_attributes)
template_model$simulation_function
# Nested model
nested_model <- SimulationModel$new(template_model = template_model)
nested_model$region$region_cells
nested_model$set_sample_attributes(a = 1:7, b = 1:10, c = 1:15)
nested_model$sample_attributes
nested_model$get_attributes(c("a", "b", "c", "d"))
# Completeness and consistency
nested_model$is_complete()
nested_model$incomplete_attributes()
nested_model$is_consistent()
nested_model$inconsistent_attributes()
nested_model$set_attributes(c = array(1:70, c(7, 10)), d = 15)
nested_model$is_complete()
nested_model$is_consistent()
# Attached attributes
nested_model$attached
template_model$attached
poems documentation built on Nov. 12, 2025, 5:06 p.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.
| SimulationModel | R Documentation |
R6 class representing a simulation model
Description
R6 class representing a spatially-explicit simulation
model. It extends the SpatialModel class with a range of common
simulation parameters and 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 methods for checking the consistency and
completeness of model parameters.
Super classes
poems::GenericClass -> poems::GenericModel -> poems::SpatialModel -> SimulationModel
Public fields
attachedA list of dynamically attached attributes (name-value pairs).
Active bindings
simulation_functionName (character string) or source path of the default simulation function, which takes a model as an input and returns the simulation results.
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).
random_seedNumber to seed the random number generation for stochasticity.
replicatesNumber of replicate simulation runs.
time_stepsNumber of simulation time steps.
years_per_stepNumber of years per time step.
results_selectionList of simulator-dependent attributes to be included in the returned results of each simulation run.
attribute_aliasesA list of alternative alias names for model attributes (form:
alias = "attribute") to be used with the set and get attributes methods.template_modelNested template model for fixed (non-sampled) attributes for shallow cloning.
sample_attributesVector of sample attribute names (only).
required_attributesVector of required attribute names (only), i.e. those needed to run a simulation.
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
Method new()
Initialization method sets template model and sets given attributes individually and/or from a list.
Usage
SimulationModel$new(template = NULL, required_attributes = NULL, ...)
Arguments
templateTemplate simulation model (nested) containing fixed (non-sampled) attributes.
required_attributesVector of required attribute names (only), i.e. those needed to run a simulation.
...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
SimulationModel$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 a list of all attribute names including public and private model attributes, as well as attached attributes (including those from the template model).
Usage
SimulationModel$get_attribute_names()
Returns
List 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
SimulationModel$get_attributes(params = NULL)
Arguments
paramsArray of attribute names to return (all when NULL).
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
SimulationModel$set_attributes(params = list(), ...)
Arguments
paramsList of parameters/attributes.
...Parameters/attributes passed individually.
Method set_sample_attributes()
Sets the names (only - when params is a vector) and values (when params is a list and/or when name-value pairs are provided) of the sample attributes for the model.
Usage
SimulationModel$set_sample_attributes(params = list(), ...)
Arguments
paramsList of parameters/attributes (names and values) or array of names only.
...Parameters/attributes passed individually.
Method is_consistent()
Returns a boolean to indicate if (optionally selected or all) model attributes (such as dimensions) are consistent/valid.
Usage
SimulationModel$is_consistent(params = NULL)
Arguments
paramsOptional array of parameter/attribute names.
Returns
Boolean to indicate consistency of selected/all attributes.
Method list_consistency()
Returns a boolean to indicate if (optionally selected or all) model attributes (such as dimensions) are consistent/valid.
Usage
SimulationModel$list_consistency(params = NULL)
Arguments
paramsOptional array of parameter/attribute names.
Returns
List of booleans (or NAs) to indicate consistency of selected/all attributes.
Method inconsistent_attributes()
Returns a list of attributes necessary to simulate the model that are inconsistent/invalid.
Usage
SimulationModel$inconsistent_attributes(include_nas = FALSE)
Arguments
include_nasOptional boolean indicating whether of not to include attributes with unknown consistency (NA).
Returns
List of inconsistent attributes which prevent the model simulation (and optionally those where consistency is not available).
Method is_complete()
Returns a boolean to indicate if all attributes necessary to simulate the model have been set and are consistent/valid.
Usage
SimulationModel$is_complete()
Returns
Boolean to indicate model completeness (and consistency).
Method list_completeness()
Returns a list of booleans (or NAs) for each parameter to indicate attributes that are necessary to simulate the model have been set and are consistent/valid.
Usage
SimulationModel$list_completeness()
Returns
List of booleans (or NAs) for each parameter to indicate to indicate completeness (and consistency).
Method incomplete_attributes()
Returns a list of attributes necessary to simulate the model that are incomplete/inconsistent/invalid.
Usage
SimulationModel$incomplete_attributes(include_nas = FALSE)
Arguments
include_nasOptional boolean indicating whether of not to include attributes with unknown completeness (NA).
Returns
List of incomplete attributes which prevent the model simulation (and optionally those where completeness is not available).
Method clone()
The objects of this class are cloneable with this method.
Usage
SimulationModel$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)
)
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)
# Model template
template_model <- SimulationModel$new(
simulation_function = "test_simulator",
region = region, time_steps = 10
)
template_model$model_attributes <- c(
template_model$model_attributes,
"a", "b", "c", "d"
)
template_model$model_attributes
template_model$required_attributes <- c(
template_model$required_attributes[1:2],
"a", "b", "c", "d"
)
template_model$required_attributes
template_model$get_attributes(template_model$required_attributes)
template_model$simulation_function
# Nested model
nested_model <- SimulationModel$new(template_model = template_model)
nested_model$region$region_cells
nested_model$set_sample_attributes(a = 1:7, b = 1:10, c = 1:15)
nested_model$sample_attributes
nested_model$get_attributes(c("a", "b", "c", "d"))
# Completeness and consistency
nested_model$is_complete()
nested_model$incomplete_attributes()
nested_model$is_consistent()
nested_model$inconsistent_attributes()
nested_model$set_attributes(c = array(1:70, c(7, 10)), d = 15)
nested_model$is_complete()
nested_model$is_consistent()
# Attached attributes
nested_model$attached
template_model$attached
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.