writeControlFile: Writes a sample `controlFile.json` file

Description

writeControlFile() writes a sample controlFile.json file. The controlFile.json file is used to specify alternate model and optimisation options and used as an input to the function generateScenarios. The user may use the sample file created by this function as a guide to create an "controlFile.json" file for their application.

Usage

writeControlFile(
  jsonfile = "sample_controlFile.json",
  basic = TRUE,
  nml = NULL
)

Value

A json file. The file may be used as an example to create an "controlFile.json" file for input to generateScenarios. An "controlFile.json" file may contain any subset of the fields listed below. The user may delete the unused fields from the file. The exception cases where it is mandatory to specify two fields together in controlFile are detailed as part of the list below.

modelType : a list by variable. Each element of the list is a string specifying the type of stochastic model. if modelType is specified for a variable in controlFile, modelParameterVariation should also be specified. This is because these two fields together define the stochastic model. Use viewModels() to view the valid options for modelType by variable.
modelParameterVariation : a list by variable. Each element of the list is a string specifying the type of the parameter variation (annual, seasonal, harmonic etc.) of the stochastic model. if modelParameterVariation is specified for a variable in controlFile, modelType should also be specified. This is because these two fields together define the stochastic model. Use viewModels() to view valid options for modelParameterVariation by variable.
modelParameterBounds a nested list by variable. Each element is a list containing the bounds of the parameters of the chosen stochastic model. This field exists to provide an option to overwrite the default bounds of the parameters of the stochastic model. Careful consideration is recommended prior to setting modelParameterBounds in the controlFile to overwrite the defaults provided in the package.
optimisationArguments : a list. Contains the optimisation options used by function ga from the ga package. Brief definitions are given below.
- pcrossover a value of probability of crossover. Defaults to 0.8.
- pmutation a value of probability of mutation. Defaults to 0.1.
- maxiter a value of the maximum number of generations. Defaults to 50.
- maxFitness a value of the stopping criteria. Defaults to -0.001.
- popSize a value of the population size. Defaults to 500.
- run a value of an alternative stopping criteria, consecutive runs without improvement in fitness. Defaults to 20.
- seed a value of the random seed. Defaults to NULL.
- parallel specifies if parallel computing should be used. Defaults to False. Can be set to the number of desired cores, or TRUE, where it will detect the number of available cores and run.
- keepBest specifies if the optimisation should keep the best solution in each generation. Defaults to TRUE.
- suggestions suggestions for starting values of parameters for optimisation.
penaltyAttributes : a character vector of climate attributes to place specific focus on during targeting via the use of a penalty function during the optimisation process. The penaltyAttributes should belong to attPerturb or attHold that are specified in the exposure space used as input to generateScenarios. If penaltyAttributes are specified in the controlFile, penaltyWeights should also be specified.
penaltyWeights : a numeric vector; the length of the vector should be equal to the length of penaltyAttributes. penaltyWeights are the multipliers of the corresponding penaltyAttributes used during the optimisation.

Arguments

jsonfile: string; to specify the name of the json file to be written. The default name of the sample file is "sample_controlFile.json". The file will be written to the working directory of the user.
basic: logical (TRUE/FALSE); used to specify whether a "basic" or "advanced" sample file is to be written. The default is TRUE. A "basic" controlFile does not contain modelParameterBounds, and is sufficient for most applications.
nml: list; the namelist to be written to the json file, as an R list. This argument may be used to create a JSON file using an controlFile from an existing simulation. If this argument is set to NULL, the function writes the default model/optimisation options defined in the package to the json file.

Details

The function may be used without any input arguments to write a "basic" sample controlFile.

Examples

Run this code

if (FALSE) {
# To write a sample controlFile
writeControlFile()

# To write an advanced sample controlFile
writeControlFile(jsonfile = "sample_controlFile_advanced.json", basic = FALSE)
}