R6 Class Representing an `R6Experiment`
R6Experiment.RdManages experimental designs and execution for R6Sim models.
Public fields
modelsis a list containing R6Sim objects.
blocksnumber of population blocks for cases when we want to paralellize individual-level simulations.
exp_designis a data.frame containing one row per experiment to be run.
gridis a data.frame containing one row per point in the grid experimental design.
lhsis a table containing one row per point in the Latin Hypercube experimental design.
paramsis a data.frame containing one row per parameter set defined in the params object of each model included in the experiment.
params_designis a data.frame containing one row per parameter set defined in the params object of each model included in the experiment.
policy_designis a data.frame containing one row per policy experiment.
set_seedis a T if the experiment will be controlling and setting seeds.
experimental_parametersis a list containing details about each experimental parameter. Experimental parameters can be either policy levers or uncertainties. Defining this distinction is up to the user.
Methods
Method new()
This function is used to initialize a `R6Experiment` object. This object represents an experiment that will be run and can encompass multiple models.
Usage
R6Experiment$new(...)Method set_parameter()
Set Experimental Parameter for the Experiment
Arguments
parameter_namecharacter string defining the parameter name.
experimental_designEither "grid" or "lhs" Use lhs if you want to create a Latin Hypercube Sample within the min and max bounds you provided. Use Grid
valuesuse when experimental_design = "grid". This should be a vector including the values to be included in a grid experimental design. Please use parameters and values that can be converted to strings without any issues.
minuse when experimental_design = "lhs". This should be a numeric value indicating the minimum bound in the Latin Hypercube sample.
maxuse when experimental_design = "lhs". This should be a numeric value indicating the minimum bound in the Latin Hypercube sample.
Details
This function constructs the experimental_parameter object, and appends experimental parameters that will be visible inside the model in the future.
Experimental parameters can be either uncertainties or decision levers.
Every parameter defined in this function can be accessed within the model by using experimental_parameters$param_name.
Method set_design()
Set Experimental Design
Usage
R6Experiment$set_design(
n_lhs,
blocks = 1,
grid_design_df,
convert_lhs_to_grid = F,
lhs_to_grid_midpoints = 0,
n_reps = 1,
set_seed = T
)Arguments
n_lhsThe number of points in the Latin Hypercube Sample to be created.
blocksis the number of population blocks to use to parallelize the runs across nodes.
grid_design_dfa data.frame containing a pre-existing experimental design to be used. This function will use this experimental design in lieu of parameters defined in the grid, so this effectively replaces any set of parameters that are part of a grid design.
convert_lhs_to_gridDefault is FALSE. If TRUE, this function convert the LHS parameters to "grid" parameters. This is useful when one needs to test the "corners" of the experimental design before performing a full LHS run.
lhs_to_grid_midpointsOnly relevant when convert_to_lhs = T. Default value is 0. This should be an integer determining how many points within the grid hypercube should be created for the parameters being converted from LHS to a GRID design. For example, if convert_lhs_to_grid = T and lhs_to_grid_midpoints = 0, this function will create a full factorial design of the LHS parameters with 2^n points. If one wants to use one midpoint, then the design will have 3^n points, and so on. This parameter does not affect parameters orignally defined as part of a grid design because their values have already been set.
n_repsNumber of stochastic replications for each experimental design point. Default is 1.
set_seedWhether to set random seeds for reproducibility. If TRUE, generates unique seeds for each replication. Default is TRUE.
Details
Creates two data.frames that represent the experimental design" the `exp_design` for natural history experiments and the `policy_design` for policy experiments. These experimental designs are created based on the parameters defined by the set_parameter functions. The experimental design created by this function is useful to run a typical RDM analysis where each policy is evaluated across a LHS of deep uncertainties. To achieve that, define each policy lever as a grid parameter, and each uncertainty as an "lhs" uncertainty. Natural history uncertainties are often already defined in the model's posterior file and are also considered. The natural history design will have `n_posterior` runs for each model in the experimental design. The policy experimental design will have `blocks` \* `n_lhs` \* `n_grid_points` \* `n_posterior` \* `n_reps` for each model in the experimental design.
Method run()
Run Experiment
Usage
R6Experiment$run(
n_cores = 3,
parallel = F,
cluster_eval_script = NULL,
model_from_cluster_eval = F,
packages = NULL,
...
)Arguments
n_coresnumber of cores to use
parallelwhether to evaluate run in parallel
cluster_eval_scriptOptional path to R script that is sourced once in each parallel process before running experiments. Useful for model setup that should happen once per process, like: - Loading required packages - Compiling models (e.g. odin models) - Setting up simulation parameters/data - Creating model instances for use across runs
model_from_cluster_evalIf TRUE, expects model instances to be created in cluster_eval_script. Set TRUE when model compilation is needed (like with odin).
packagescharacter vector of packages to be loaded before running the model in parallel.
...additional parameters passed to model simulation