LHS.scenarios: Generate LHS scenarios
In carlopacioni/HexSimR: An R Package For Post HexSim Simulation Analysis

Description Usage Arguments Details Value Examples

This function is used to generate scenarios whose parameter combinations follow a Latin Hypercupe Sampling design. Parameter values can be drawn from normal, lognormal, binomial, beta or uniform distributions or have a set of fixed values.

LHS.scenarios(
  path.scenarios = NULL,
  xml.template = NULL,
  samples,
  csv.in,
  generate = TRUE
)

`path.scenarios`	The path to the 'Scenarios' folder
`xml.template`	The name of the xml file to use as template for the new nodes
`samples`	The number of LHS samples (i.e. parameter combinations)
`csv.in`	The name of the .csv file in the "Scenarios" folder with the information on the nodes that need to be modified (or checked in case of xml.cond.replacement)
`generate`	Whether generate (TRUE) the xml files or stop after having created the hypercube matrix (FALSE)

An xml file is passed (with xml.template) to build the LHS scenarios, which are saved in the same path.scenarios where the template is.

If generate is FALSE, then the function quits after generating the hypercube matrix.

An .csv file needs to be created, must be located in the scenario folder and the name should be passed with csv.in as a character vector (see system.file("extdata", "test_csv_LHS.csv", package="HexSimR") for an example).

The .csv must have the following headings: nodes, identifier, attribute, param_node, param_node_identifier, param_node_attribute, param_identifier, param_name, type, value, distribution. See documentation for scenarios.batch.modifier on the meaning of nodes, identifier, attribute. When generate=FALSE only the last four are mandatory.

There might be situation where the parameter values to be changed are in an internal node respect to the node identifier. In order to identify uniquely this parameter, the identifier of the parameter node needs to be indicated. This is best explained with an example. An accumulateTrait is identified by the name attribute (i.e. <accumulateTrait name="XXX">), however the parameter values are contained in the <value> node within the accumulateTrait. The node <value> is itself identified by a name attribute, but the parameters are stored under a "threshold" attribute. To avoid multiple hit nodes, identifier and attribute are used to identify uniquely the parent node where the parameter is contained. param_node, param_node_identifier, and param_node_attribute are used to identify the node where the parameter values are contained (if necessary, use NA for param_node and FALSE for the others columns if not relevant), and param_identifier is used to identify the actual parameter values that need to be changed, when this is stored as an attribute. Use FALSE when the latter is not relevant (e.g. if the node identifier is the parameter that needs to be changed).

type refers to the type of parameter. It can take exactly one of the following: "integer", "numeric" or "character". value refers to the parameters of the distribution from which values are drawn (separated by a comma) if one is used: mean and sd for normal, meanlog and sdlog for lognormal, shape1 and shape2 for beta, prob for binomial and min and max for uniform, otherwise a collection of values if distribution="fixed". When distribution="fixed" or type="character" the elements in value have equal probability.

param_name is the name of the parameter that is being changed. These are used as labels (headers) in the hypercube matrix that it is saved to disk and returned as an object.

When generate=TRUE, the second element of the list returned contains the nodes found in the template. It is probably a good idea to scan through these to check whether these were the expected ones and most importantly that none are empty!

A list where the first element is the hyercube matrix and the second are the nodes found in the template (if generate = TRUE). A csv file with the hypercube matrix is saved to disk and, when generate = TRUE, the LHS xml files are also saved to disk.

# Locate the template file
template <- system.file("extdata", "MRVC_4BaitYr_ThreeCells.xml", package="HexSimR")

# Locate the .csv file
csv.LHS.in <- system.file("extdata", "test_csv_LHS.csv", package="HexSimR")

# Create a temp dir
testFolder <- tempdir(check = TRUE)

# copy example files
file.copy(c(template, csv.LHS.in), testFolder)

# Exexute the function
LHS <- LHS.scenarios(
path.scenarios=testFolder,
xml.template="MRVC_4BaitYr_ThreeCells.xml",
samples=9, 
csv.in ="test_csv_LHS.csv",
generate=TRUE)