define_hisafe: Define a Hi-sAFe experiment
In kevinwolz/hisafer: An R Toolbox for the Hi-sAFe Biophysical Agroforestry Model

Description Usage Arguments Details Value See Also Examples

Defines a Hi-sAFe experiment - the input parameters to one or more Hi-sAFe simulations.

define_hisafe(
  path,
  exp.name = "experiment",
  profiles = "all",
  freqs = NULL,
  template = "agroforestry",
  factorial = FALSE,
  force = FALSE,
  bulk.pass = NULL,
  ...
)

`path`	A character string of the path (relative or absolute) to the directory where the simulation/experiment is to be built.
`exp.name`	A character string of the name of the experiment folder. Only used if defining more than one simulation.
`profiles`	A character vector of Hi-sAFe export profiles to be exported by Hi-sAFe. If "all" (the default), then the basic set of profiles for all data levels will be exported.
`freqs`	A numeric vector of export frequencies (days) for the export profiles specified in `profiles`. if `NULL` (the default), then the default export frequences (daily, monthly, annual) are applied to respective profiles. Export frequencies can be any positive integer. Special values include 30, which triggers export on the first day of each month, and 365, which triggers export on the first day of each January.
`template`	A character string of the path to the directory containing the template set of Hi-sAFe simulation folders/files to use. hisafer comes with a variety of "default" templates than can be used by specificying specific character strings: "agroforestry" - a simple alley cropping template, with trees spaced at 9m x 13m and a durum wheat alley crop "forestry" - a simple forestry template, with trees spaced at 5m x 7m and an understory of bare soil "monocrop" - a simple, single-celled monocrop template with durum-wheat "restinclieres_agroforestry_A2" - a template based on the agroforestry calibration simulation of Hi-sAFe in Plot A2 at Restinclieres in Southern France "restinclieres_agroforestry_A3" - a template based on the agroforestry calibration simulation of Hi-sAFe in Plot A3 at Restinclieres in Southern France "restinclieres_forestry_A4" - a template based on the forestry calibration simulation of Hi-sAFe in Plot A4 at Restinclieres in Southern France "restinclieres_monocrop_A2" - a template basd on the monocrop calibration simulation of Hi-sAFe in Plot A2 at Restinclieres in Southern France "restinclieres_monocrop_A3" - a template basd on the monocrop calibration simulation of Hi-sAFe in Plot A3 at Restinclieres in Southern France "castries_agroforestry" - a template basd on the agroforestry validation simulation of Hi-sAFe at Castries in Southern France
`factorial`	If `FALSE`, the default, then supplied input values are recycled (i.e. such as for default behavior of `data.frame`). If `TRUE`, then a factorial experiment is created, in which an experiment is defined for each possible combination of supplied values.
`force`	Logical indicating wether the supplied values should be forced past the constraint checks. Use `TRUE` for development only.
`bulk.pass`	Any Hi-sAFe input parameter in the .SIM, .PLD, .TREE, and .PAR files can be passed here grouped as a list, just as can be passed to `...`. This facilitates sending the same list of arguments to multiple calls of `define_hisafe`.
`...`	Any Hi-sAFe input parameter in the .SIM, .PLD, .TREE, .PLT, .TEC, and .PAR files can be passed. Parameters in .TREE, .PLT, and .TEC files will be applied to all .TREE, .PLT, and .TEC files in each simulation. To display supported parameters, use `hip_params`. See below for further details. There are three methods for passing parameters to `define_hisafe`, one for each of the three types of parameters within the parameter files: individual numeric or character values - For parameters that require a single value (most parameters), a simulation can be defined via `parameterName = value`. To define an experiment, use `parameterName = c(value1, value2)` multiple numeric values - For parameters that require multiple numeric values (e.g. tree planting, tree pruning, tree thinning, and root pruning parameters), a simulation can be defined by wrapping one or more numeric vectors within a list. For a single simulation, use `parameterName = list(c(value1, value2, ...))`. For an experiment, use `parameterName = list(c(value1, value2, ...), c(value3, value4, ...))`. "tables" - There are four parameter tables within the .pld file (layers, layer.initialization, tree.initialization, root.initialization) and one parameter table with the .plt file (varieties) that are supported. To define prameters within these tables, use the helper functions `layer_params`, `layer_init_params`, `tree_init_params`, `root_init_params`, and `variety_params`. These functions create a list of data frames (tibbles). Passing `NA` to any parameter will "deactivate" the parameter by commenting it out in the resulting Hi-sAFe parameter file. This can be useful to deactivate processes such as tree root pruning or branch pruning, but care must be taken to only deactivate parameters that are not mandatory!

It is strongly recommended to name each simulation in your experiment. This can be done via the SimulationName parameter. If no names are provided, then generic names of "Sim_1", "Sim_2", etc. will be generated. The only additional input parameter that is available but not part of the input files is **weatherFile**, which specifies a path to a .WTH file to use.

An object of class "hip". This is a list of 5 elements:

"exp.plan" - A data frame (tibble) of manipulated Hi-sAFe input parameters, with each row a Hi-sAFe simulation and each column a Hi-sAFe input parameter.
"template" - A character string of the path to the directory containing the template set of Hi-sAFe simulation folders/files used.
"profiles" - A character vector of the names of the Hi-sAFe export profiles that will be exported by Hi-sAFe.
"freqs" - A numeric vector of the exportFrequencies at which the Hi-sAFe export profiles will be exported by Hi-sAFe.
"path" - A character string of the absolute path to the directory where the simulation/experiment is to be built. If a relative path is via path, it is converted to an absolute path to maximize "hip" object versaitility.

Other hisafe definition functions: define_hisafe_file(), layer_init_params(), layer_params(), root_init_params(), tree_init_params(), variety_params()

## Not run: 
# To define a Hi-sAFe simulation using all default parameter values:
default.exp <- define_hisafe(path = "./")

# To define a Hi-sAFe experiment analyzing only variation in latitude:
latitude.exp <- define_hisafe(path = "./", SimulationName = c("Lat15", "Lat30", "Lat45", "Lat60"),
                               latitude = seq(15, 60, 15))

# To define a factorial Hi-sAFe experiment analyzing
# simultaneous variation in latitude and tree line orientation:
lat.orient.exp <- define_hisafe(path = "./",
                                 latitude = seq(15, 60, 15),
                                 treeLineOrientation = c(0,90))

## End(Not run)