Skip to contents

R6 Class Representing a `crcexperiment`

crcexperiment.Rd

This class implements a `crcexperiment`.

Public fields

models

is a list containing crcmodel objects.

nh_design

is a data.frame containing one row per natural history experiment to be run.

screening_design

is a data.frame containing one row per screening experiment to be run.

grid

is a data.frame containing one row per point in the grid experimental design.

lhs

is a table containing one row per point in the Latin Hypercube experimental design.

blocks

is the number of population blocks used in the experimental design. This number of population blocks allows us to divide the experimental design into experimental blocks.

posteriors

is a data.frame containing one row per parameter set defined in the posterior of each model included in the experiment.

experimental_parameters

is 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

Public methods

Method new()

This function is used to initialize a `crcexperiment` object. This object represents an experiment that will be run and can encompass multiple models.

Usage

crcexperiment$new(...)

Arguments

...

set of crcmodels to be included in the experiment. One `crcexperiment` can contain multiple models of the `crcmodel` class.

Returns

a new `crcexperiment` object.

Method set_parameter()

Set Experimental Parameter for the Experiment

Usage

crcexperiment$set_parameter(
  parameter_name,
  experimental_design,
  values,
  min,
  max
)

Arguments

parameter_name

character string defining the parameter name.

experimental_design

Either "grid" or "lhs" Use lhs if you want to create a Latin Hypercube Sample within the min and max bounds you provided. Use Grid

values

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

min

use when experimental_design = "lhs". This should bea numeric value indicating the minimum bound in the Latin Hypercube sample.

max

use when experimental_design = "lhs". This should bea 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

crcexperiment$set_design(
  n_lhs,
  blocks = 1,
  grid_design_df,
  convert_lhs_to_grid = F,
  lhs_to_grid_midpoints = 0
)

Arguments

n_lhs

The number of points in the Latin Hypercube Sample to be created.

blocks

is the number of population blocks to use to parallelize the runs across nodes.

grid_design_df

a 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_grid

Default 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_midpoints

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

Details

Creates two data.frames that represent the experimental design" the `nh_design` for natural history experiments and the `screening_design` for screening 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 screening experimental design will have `blocks` \* `n_lhs` \* `n_grid_points` \* `n_posterior` for each model in the experimental design.

Method write_design()

Write Experimental design to disk

Usage

crcexperiment$write_design(
  path,
  design = c("both", "natural_history", "screening"),
  write_inputs = T,
  block_ids,
  format = c("json", "csv")
)

Arguments

path

folder where json experimental designs should be saved. Do not specify a file name. If missing, the function will return the design specified below.

design

"natural_history", "screening" or "both". If missing, "both" is assumed.

write_inputs

if TRUE (default), writes model inputs to json. Might be unnecessary when inputs are set in the model run script.

block_ids

integer vector of block ids to write to json. can be used to only run specific blocks in the screening experimental design.

format

"json" or "csv". the natural history design must be written to json, whereas the screening design can be written to json or csv.

Details

Creates a data.frame in which each row represents a single experiment. The json object included in each row contains all information that the models need to re-create themselves in the server-side in a HPC workflow.

Method clone()

The objects of this class are cloneable with this method.

Usage

crcexperiment$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.