writeControlFile: Writes a sample 'controlFile.json' file

In foreSIGHT: Systems Insights from Generation of Hydroclimatic Timeseries

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
)

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.

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.

  • optimizer: the numerical optimization routine. Options include 'RGN' for Robust Gauss Newton (using RGN::rgn), 'NM' for Nelder-Mead (using dfoptim::nmkb), 'SCE' for Shuffled Complex Evolution (using SoilHyP::SCEoptim). 'GA' for Genetic Algorithm (using GA::ga), Defaults to 'RGN'.

  • seed: random seed used (for first multistart) in numerical optimization (often for determining random initial parameter values). Default is 1.

  • obj.func: the type of objective function used (important only when penalty weights are not equal.

  • suggestions: suggestions for starting values of parameters for optimisation. Options include 'WSS' (weighted sum of squares) and SS_absPenalty (sum of squares plus absolute penalty)

  • nMultiStart: the number of multistarts used in optimization. Default is 5.

  • RGN.control: RGN optional arguments specified by control list in RGN::rgn.

  • NM.control: NM optional arguments specified by control list in dfoptim::nmkb.

  • SCE.control: SCE optional arguments specified by control list in SoilHyP::SCEoptim.

  • GA.args: GA optional arguments specified in GA::ga.

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

See Also

generateScenarios, viewModels, viewDefaultOptimArgs

Examples

## Not run: 
# To write a sample controlFile
writeControlFile()

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

## End(Not run)

foreSIGHT documentation built on Oct. 19, 2023, 9:08 a.m.