Version:	1.2.0
Depends:	R (≥ 3.5.0),GA (≥ 3.0.2)
LinkingTo:	Rcpp
Imports:	ggplot2 (≥ 3.3.0), directlabels, cowplot, stats, graphics, grDevices, utils, moments, jsonlite, progress, rcorpora, scales, viridisLite, fields, rlang, lattice, mvtnorm, Matrix, SoilHyP, cmaes, dfoptim, RGN,
Suggests:	knitr (≥ 1.8), rmarkdown (≥ 1.18),testthat, evd
Title:	Systems Insights from Generation of Hydroclimatic Timeseries
BugReports:	https://github.com/ClimateAnalytics/foreSIGHT/issues
Description:	A tool to create hydroclimate scenarios, stress test systems and visualize system performance in scenario-neutral climate change impact assessments. Scenario-neutral approaches 'stress-test' the performance of a modelled system by applying a wide range of plausible hydroclimate conditions (see Brown & Wilby (2012) <doi:10.1029/2012EO410001> and Prudhomme et al. (2010) <doi:10.1016/j.jhydrol.2010.06.043>). These approaches allow the identification of hydroclimatic variables that affect the vulnerability of a system to hydroclimate variation and change. This tool enables the generation of perturbed time series using a range of approaches including simple scaling of observed time series (e.g. Culley et al. (2016) <doi:10.1002/2015WR018253>) and stochastic simulation of perturbed time series via an inverse approach (see Guo et al. (2018) <doi:10.1016/j.jhydrol.2016.03.025>). It incorporates 'Richardson-type' weather generator model configurations documented in Richardson (1981) <doi:10.1029/WR017i001p00182>, Richardson and Wright (1984), as well as latent variable type model configurations documented in Bennett et al. (2018) <doi:10.1016/j.jhydrol.2016.12.043>, Rasmussen (2013) <doi:10.1002/wrcr.20164>, Bennett et al. (2019) <doi:10.5194/hess-23-4783-2019> to generate hydroclimate variables on a daily basis (e.g. precipitation, temperature, potential evapotranspiration) and allows a variety of different hydroclimate variable properties, herein called attributes, to be perturbed. Options are included for the easy integration of existing system models both internally in R and externally for seamless 'stress-testing'. A suite of visualization options for the results of a scenario-neutral analysis (e.g. plotting performance spaces and overlaying climate projection information) are also included. Version 1.0 of this package is described in Bennett et al. (2021) <doi:10.1016/j.envsoft.2021.104999>. As further developments in scenario-neutral approaches occur the tool will be updated to incorporate these advances.
License:	GPL-3
NeedsCompilation:	yes
VignetteBuilder:	knitr
LazyData:	true
RoxygenNote:	7.2.3
Packaged:	2023-10-17 11:17:03 UTC; a1065639
Author:	Bree Bennett [aut], Sam Culley [aut], Anjana Devanand [aut], David McInerney [aut, cre], Seth Westra [aut], Danlu Guo [ctb], Holger Maier [ths]
Maintainer:	David McInerney <david.mcinerney@adelaide.edu.au>
Repository:	CRAN
Date/Publication:	2023-10-19 07:00:08 UTC

Multi-site rainfall observations in the Barossa Valley used in examples and vignette

Description

Dataset of observed rainfall for multiple sites in the Barossa Valley based on SILO point data

Format

A list of observed rainfall data with elements Year Month Day P. P is a matrix with rows corresponding to dates, and columns corresponding to 13 sites in the Barossa Valley

Source

SILO point rainfall data obtained from https://www.longpaddock.qld.gov.au. Data obtained for stations 23300, 23302, 23305, 23309, 23312, 23313, 23317, 23318, 23321, 23363, 23373, 23752, 23756 for the period 1 Jan 1972 to 31 December 1999.

Calculates the attributes of the hydroclimate time series

Description

calculateAttributes calculates the specified attributes of the input daily hydroclimate time series.

Usage

calculateAttributes(climateData, attSel, startYr = NULL, endYr = NULL)

Arguments

Value

The function returns a vector of attributes with names of the attributes (attSel). For multi-site data, names are combinations of attribute and site names.

Examples

#----------------------------------------------------------------------
# Example 1: Single-site data.frame input
# load 'tank' example climate data available in the package
data("tankDat")
# specify rainfall and temperature attributes to calculate
attSel <- c("P_ann_tot_m", "P_ann_nWet_m", "P_ann_R10_m", "Temp_ann_rng_m", "Temp_ann_avg_m")
tank_obs_atts <- calculateAttributes(tank_obs, attSel = attSel)
#----------------------------------------------------------------------
# Example 2: Multi-site list input
# load 'Barossa' example climate data available in the package
data("barossaDat")
# specify rainfall attributes to calculate
attSel <- c("P_ann_tot_m", "P_ann_nWet_m", "P_ann_P99")
barossa_obs_atts <- calculateAttributes(tank_obs, attSel = attSel)

Example climate projection data

Description

A dataframe of climate projection data for superposition on performance spaces via plotLayers

Format

climdata is a dataframe with 12 rows and 3 columns

climdata

A dataframe of climate attributes and performance in the form P_ann_tot_m Temp_ann_avg_m performance.

Creates exposure space of hydroclimatic targets for generation of scenarios using 'generateScenarios'

Description

createExpSpace returns a list containing the targets (targetMat) and the metadata (input arguments) used to create the exposure space.

Usage

createExpSpace(
  attPerturb,
  attPerturbSamp,
  attPerturbMin,
  attPerturbMax,
  attPerturbType = "regGrid",
  attPerturbBy = NULL,
  attHold = NULL,
  attTargetsFile = NULL
)

Arguments

Details

See "Detailed Tutorial: Climate 'Stress-Testing' using *fore*SIGHT" vignette for specifying attribute names for attPerturb and attHold. The definition of the attribute can be viewed using the function viewAttributeDef.

Value

The exposure space as a list containing the following fields:

• targetMat a dataframe or matrix; each column is a perturb/hold attribute, each row is a point in the exposure space.

• attRot a char vector containing the one-at-a-time ("OAT") attributes associated with targetMat, attRot is NULL for other types of sampling.

• attPerturb, attHold, attPerturbSamp, attPerturbMin, attPerturbMax, attPerturbType in the function input arguments, if not NULL.

See Also

generateScenarios, viewAttributeDef

Examples

# To view the definition of any valid attribute
viewAttributeDef("P_ann_tot_m")

# To create an exposure space of points on a regular grid
attPerturb <- c("P_ann_tot_m", "P_ann_nWet_m", "P_ann_R10_m")
attPerturbType <- "regGrid"
attPerturbSamp <- c(3, 1, 1)
attPerturbMin <- c(0.9, 1, 1)
attPerturbMax <- c(1.1, 1, 1)
attHold <- c("P_Feb_tot_m", "P_SON_dyWet_m", "P_JJA_avgWSD_m", 
"P_MAM_tot_m", "P_DJF_avgDSD_m", "Temp_ann_rng_m", "Temp_ann_avg_m")
expSpace <- createExpSpace(attPerturb = attPerturb, attPerturbSamp = attPerturbSamp, 
attPerturbMin = attPerturbMin, attPerturbMax = attPerturbMax, 
attPerturbType = attPerturbType, attHold = attHold, attTargetsFile = NULL)

# Using attPerturbBy to specify the increment of perturbation (attPerturbSamp set to NULL)

attPerturb <- c("P_ann_tot_m", "P_ann_nWet_m", "P_ann_R10_m")
attPerturbType <- "regGrid"
attPerturbMin <- c(0.9, 1, 1)
attPerturbMax <- c(1.1, 1, 1)
attPerturbBy <- c(0.1, 0, 0)
attHold <- c("P_Feb_tot_m", "P_SON_dyWet_m", "P_JJA_avgWSD_m", "P_MAM_tot_m", 
"P_DJF_avgDSD_m", "Temp_ann_rng_m", "Temp_ann_avg_m")
expSpace <- createExpSpace(attPerturb = attPerturb, attPerturbSamp = NULL, 
attPerturbMin = attPerturbMin, attPerturbMax = attPerturbMax, attPerturbType = attPerturbType, 
attPerturbBy = attPerturbBy, attHold = attHold, attTargetsFile = NULL)

# To create an exposure space of observed attributes without perturbation
# Note that attPerturbMin and attPerturbMax values are set to 1 for variables like precipitation, 
# and 0 for temperature 
attPerturb <- c("P_ann_tot_m", "P_ann_nWet_m", "P_ann_R10_m", "Temp_DJF_avg_m")
attPerturbType <- "regGrid"
attPerturbSamp <- c(1, 1, 1, 1)
attPerturbMin <- c(1, 1, 1, 0)
attPerturbMax <- c(1, 1, 1, 0)
expSpace <- createExpSpace(attPerturb = attPerturb, attPerturbSamp = attPerturbSamp, 
attPerturbMin = attPerturbMin, attPerturbMax = attPerturbMax, attPerturbType = attPerturbType, 
attHold = NULL, attTargetsFile = NULL)

Climate attributes from projections.

Description

A example dataset containing the climate attribute values in fraction/additive change

Usage

egClimData

Format

A data frame with 6 rows and 6 variables:

P_ann_tot_m

change in mean annual total P, fraction

P_ann_seasRatio

change in seasonal ratio of P, fraction

P_ann_nWet_m

change in the number of wet days, fraction

Temp_ann_avg_m

change in average annual Temp, additive

Name

name of the climate model

Avg. Deficit

performance metric values

Output from call to generateScenarios() using multi-site model (see example 5 in generateScenarios).

Description

Output from call to generateScenarios() using multi-site model (see example 5 in generateScenarios).

Usage

egMultiSiteSim

Format

A list with 4 elements

Rep1

List containing majority of simulation output, including output for different calibration stages

simDates

the dates of the simulation

expSpace

the exposure space of the simulation

controlFile

the setting in the control file

Performance metrics of the tank model using simple scaled scenarios.

Description

Performance metrics of the tank model using simple scaled scenarios.

Usage

egScalPerformance

Format

A list with 2 elements

Avg. Deficit

average daily deficit of water, litres

Reliability

reliability of the tank, fraction

Summary of a simple scaled scenario.

Description

Summary generated using the function getSimSummary.

Usage

egScalSummary

Format

A list containing 3 elements

simDates

the dates of the simulation

expSpace

the exposure space of the simulation

controlFile

"scaling"

Performance metrics of the tank model using OAT scenarios.

Description

Performance metrics of the tank model using OAT scenarios.

Usage

egSimOATPerformance

Format

A list with 2 elements

Avg. Deficit

average daily deficit of water, litres

Reliability

reliability of the tank, fraction

Summary of a OAT scenario.

Description

Summary generated using the function getSimSummary for a scenarios generated using stochastic models for an OAT exposure space

Usage

egSimOATSummary

Format

A list containing 13 elements

Performance metrics of the tank model using regGrid scenarios.

Description

Performance metrics of the tank model using regGrid scenarios.

Usage

egSimPerformance

Format

A list with 2 elements

Avg. Deficit

average daily deficit of water, litres

Reliability

reliability of the tank, fraction

Performance metrics of an alternate tank model using regGrid scenarios.

Description

Performance metrics of an alternate tank model using regGrid scenarios.

Usage

egSimPerformance_systemB

Format

A list with 2 elements

Avg. Deficit

average daily deficit of water, litres

Reliability

reliability of the tank, fraction

Summary of a regGrid scenario.

Description

Summary generated using the function getSimSummary for a scenarios generated using stochastic models for a regGrid exposure space

Usage

egSimSummary

Format

A list containing 13 elements

foreSIGHT: A package for Systems Insights from Generation of Hydroclimatic Timeseries

Description

A tool to create hydroclimate scenarios, stress test systems and visualize system performance in scenario-neutral climate change impact assessments.

Calculates the cold season length

Description

Calculates the cold season length

Usage

func_CSL(data)

Arguments

Calculates the number of frost days

Description

Calculates the number of frost days

Usage

func_F0(data)

Arguments

Calculates the growing season length

Description

Calculates the growing season length

Usage

func_GSL(data)

Arguments

Calculates a quantile value

Description

Calculates a quantile value

Usage

func_P(data, attArgs)

Arguments

Calculates the number of days above a threshold (often used for temperature)

Description

Calculates the number of days above a threshold (often used for temperature)

Usage

func_R(data, attArgs)

Arguments

Calculates average of time series

Description

Calculates average of time series

Usage

func_avg(data)

Arguments

Calculates average dry spell duration (below threshold)

Description

Calculates average dry spell duration (below threshold)

Usage

func_avgDSD(data, attArgs)

Arguments

Calculates average wet spell duration (below threshold)

Description

Calculates average wet spell duration (below threshold)

Usage

func_avgWSD(data, attArgs)

Arguments

Calculates average rainfall on wet days (above threshold)

Description

Calculates average rainfall on wet days (above threshold)

Usage

func_dyWet(data, attArgs)

Arguments

Calculates maximum dry spell duration (below threshold)

Description

Calculates maximum dry spell duration (below threshold)

Usage

func_maxDSD(data, attArgs)

Arguments

Calculates maximum wet spell duration (above threshold)

Description

Calculates maximum wet spell duration (above threshold)

Usage

func_maxWSD(data, attArgs)

Arguments

Calculates number of wet days (above threshold)

Description

Calculates number of wet days (above threshold)

Usage

func_nWet(data, attArgs)

Arguments

Calculates the inter-quantile range

Description

Calculates the inter-quantile range

Usage

func_rng(data, attArgs)

Arguments

Calculates seasonality ratio

Description

Calculates seasonality ratio

Usage

func_seasRatio(data, attArgs)

Arguments

Calculates total of time series

Description

Calculates total of time series

Usage

func_tot(data)

Arguments

Calculates the day of year corresponding to the wettest 6 months

Description

Calculates the day of year corresponding to the wettest 6 months

Usage

func_wettest6monPeakDay(data, attArgs = NULL)

Arguments

Calculates the ratio of wet season to dry season rainfall, based on wettest6monPeakDay

Description

Calculates the ratio of wet season to dry season rainfall, based on wettest6monPeakDay

Usage

func_wettest6monSeasRatio(data, attArgs = NULL)

Arguments

Produces time series of hydroclimatic variables for an exposure target.

Description

generateScenario is the base function used by generateScenarios. The function produces time series of hydroclimatic variables using requested climate attributes that correspond to a single target in the exposure space. The function argument definitions are detailed in the documentation of generateScenarios; please refer to that documentation using ?generateScenarios.

Usage

generateScenario(
  reference,
  expTarg,
  simLengthNyrs = NULL,
  seedID = NULL,
  controlFile = NULL
)

Arguments

See Also

generateScenarios

Produces time series of hydroclimatic variables for an exposure space.

Description

generateScenarios produces time series of hydroclimatic variables using requested climate attributes that correspond to a target exposure space using a reference daily time series as an input.

Usage

generateScenarios(
  reference,
  expSpace,
  simLengthNyrs = NULL,
  numReplicates = 1,
  seedID = NULL,
  controlFile = NULL
)

Arguments

Value

The function returns a list containing the time series data generated. The list can contain multiple replicates (named as Rep1, Rep2 etc.) equal to the numReplicates function argument. Each replicate can contain multiple targets (named as Target1, Target2 etc.) based on the specified exposure space (expSpace). The expSpace and controlFile are also returned as part of this output list.

See Also

createExpSpace, writeControlFile, viewModels

Examples

# Example 1: Simple scaling
#-----------------------------------------------------------------------
attPerturb<-c("P_ann_tot_m","Temp_ann_avg_m")
attPerturbType = "regGrid"
attPerturbSamp = c(2, 2)
attPerturbMin = c(0.8, -1)
attPerturbMax = c(1.1, 1)
expSpace <- createExpSpace(attPerturb = attPerturb,
                           attPerturbSamp = attPerturbSamp,
                           attPerturbMin = attPerturbMin,
                           attPerturbMax = attPerturbMax,
                           attPerturbType = attPerturbType)
data(tankDat)
simScaling <- generateScenarios(reference = tank_obs,
                                expSpace = expSpace,
                                controlFile = "scaling")

# Example 2: Seasonal scaling
#-----------------------------------------------------------------------
attPerturb<-c("P_ann_tot_m","P_ann_seasRatio")
attPerturbType = "regGrid"
attPerturbSamp = c(2, 2)
attPerturbMin = c(0.8, 0.9)
attPerturbMax = c(1.1, 1.2)
expSpace <- createExpSpace(attPerturb = attPerturb,
                           attPerturbSamp = attPerturbSamp,
                           attPerturbMin = attPerturbMin,
                           attPerturbMax = attPerturbMax,
                           attPerturbType = attPerturbType)
data(tankDat)
seasScaling <- generateScenarios(reference = tank_obs,
                                expSpace = expSpace,
                                controlFile = "scaling")

# Example 3: Stochastic simulation using foreSIGHT default settings
#----------------------------------------------------------------------
## Not run: 
# create an exposure space
attPerturb <- c("P_ann_tot_m", "P_ann_nWet_m", "P_ann_R10_m")
attHold <- c("P_Feb_tot_m", "P_SON_dyWet_m", "P_JJA_avgWSD_m", "P_MAM_tot_m",
"P_DJF_avgDSD_m", "Temp_ann_rng_m", "Temp_ann_avg_m")
attPerturbType = "regGrid"
attPerturbSamp = c(2, 1, 1)
attPerturbMin = c(0.8, 1, 1)
attPerturbMax = c(1.1, 1, 1)
expSpace <- createExpSpace(attPerturb = attPerturb,
                           attPerturbSamp = attPerturbSamp,
                           attPerturbMin = attPerturbMin,
                           attPerturbMax = attPerturbMax,
                           attPerturbType = attPerturbType,
                           attHold = attHold,
                           attTargetsFile = NULL)
# load example data available in foreSIGHT
data(tankDat)
# perform stochastic simulation
simStochastic <- generateScenarios(reference = tank_obs,
                                   expSpace = expSpace,
                                   simLengthNyrs = 30)
                                   
## End(Not run)
# Example 4: Simple Scaling with multi-site data
#-----------------------------------------------------------------------
attPerturb <- c("P_ann_tot_m","P_ann_seasRatio")
attPerturbType = "regGrid"
attPerturbSamp = c(3, 3)
attPerturbMin = c(0.8, 1.2)
attPerturbMax = c(0.8, 1.2)
expSpace <- createExpSpace(attPerturb = attPerturb,
                           attPerturbSamp = attPerturbSamp,
                           attPerturbMin = attPerturbMin,
                           attPerturbMax = attPerturbMax,
                           attPerturbType = attPerturbType)
# load multi-site rainfall data
data(barossaDat)
# perform simple scaling
simScaling <- generateScenarios(reference = barossa_obs,
                                expSpace = expSpace,
                                controlFile = "scaling")

# Example 5: Multi-site stochastic simulation
#-----------------------------------------------------------------------
## Not run: 
attPerturb <- c("P_ann_tot_m")
attHold <- c("P_ann_wettest6monSeasRatio","P_ann_wettest6monPeakDay",
"P_ann_P99","P_ann_avgWSD_m", "P_ann_nWetT0.999_m")
attPerturbType = "regGrid"
# consider unperturbed climates in this example
attPerturbSamp = attPerturbMin = attPerturbMax = c(1)
expSpace <- createExpSpace(attPerturb = attPerturb,
                           attPerturbSamp = attPerturbSamp,
                           attPerturbMin = attPerturbMin,
                           attPerturbMax = attPerturbMax,
                           attPerturbType = attPerturbType,
                           attHold = attHold)
# load multi-site rainfall data
data(barossaDat)
# specify the penalty settings in a list
controlFileList <- list()
controlFileList[["penaltyAttributes"]] <- c("P_ann_tot_m",
"P_ann_wettest6monSeasRatio","P_ann_wettest6monPeakDay")
controlFileList[["penaltyWeights"]] <- c(0.5,0.5,0.5)
# specify the alternate model selections
controlFileList[["modelType"]] <- list()
controlFileList[["modelType"]][["P"]] <- "latent"
# specify model parameter selection
controlFileList[["modelParameterVariation"]] <- list()
controlFileList[["modelParameterVariation"]][["P"]] <- "harmonic"
# specify settings for multi-site model
controlFileList[["spatialOptions"]] <- list()
# specify spatial correlation perturbation factor
controlFileList[["spatialOptions"]][["spatCorFac"]] = 0.9
# write control file sttings to file
controlFileJSON <- jsonlite::toJSON(controlFileList, pretty = TRUE, auto_unbox = TRUE)
write(controlFileJSON, file = paste0(tempdir(), "controlFile.json"))
# run multi-site stochastic simulation - this will take a long time (e.g. hours)
sim <- generateScenarios(reference = barossa_obs, expSpace = expSpace,
                         controlFile = paste0(tempdir(), "controlFile.json"),seed=1)
## End(Not run)

Produces a summary object containing the metadata of a full simulation

Description

getSimSummary uses a full simulation generated using the function generateScenarios as input and outputs a summary object containing the metadata of the full simulation. The output summary object may be used as an input to the plotting functions in this package. The output summary object will be much smaller in size than the full simulation for ease of storage and use with the plotting functions.

Usage

getSimSummary(sim)

Arguments

See Also

generateScenarios, plotPerformanceSpace, plotPerformanceOAT

modCalibrator

Description

Calibrates weather generator models specified using modelTag.

Usage

modCalibrator(obs = NULL, modelTag = NULL, window = NULL)

Arguments

Details

modelTag provides the main function with requested models. modelTag is vector of any of the following supported models:

• "P-ann-wgen" a four parameter annual rainfall model

• "P-seas-wgen" a 16 parameter seasonal rainfall model (phase angles must be specified via modelInfoMod=list("P-har12-wgen-FS"=fixedPars=c(x,x,x,x))

• "P-har-wgen" a harmonic rainfall model

• "Temp-har-wgen" a harmonic temperature model not conditional on rainfall

• "Temp-har-wgen-wd" a harmonic temperature model dependent on wet or dry day

• "Temp-har-wgen-wdsd" a harmonic temperature model where standard deviation parameters are dependent on wet or dry day

• "PET-har-wgen"a harmonic potential evapotranspiration model

• "PET-har-wgen-wd" a harmonic potential evapotranspiration model dependent on wet or dry day

• "Radn-har-wgen" a harmonic solar radiation model (MJ/m2)

Examples

data(tankDat)                               #Load tank data (tank_obs)
modelTag=c("P-ann-wgen","Temp-har-wgen")  #Select a rainfall and a temperature generator
out<- modCalibrator(obs = tank_obs,         #Calibrate models
                    modelTag = modelTag)

modSimulator

Description

Simulates using weather generator models specified using modelTag.

Usage

modSimulator(
  datStart = NULL,
  datFinish = NULL,
  modelTag = NULL,
  parS = NULL,
  seed = NULL,
  file = NULL,
  IOmode = "suppress"
)

Arguments

Details

modelTag provides the main function with requested models. modelTag is vector of any of the following supported models:

• "P-ann-wgen" a four parameter annual rainfall model

• "P-seas-wgen" a 16 parameter seasonal rainfall model (phase angles must be specified via modelInfoMod=list("P-har12-wgen-FS"=fixedPars=c(x,x,x,x))

• "P-har-wgen" a harmonic rainfall model

• "Temp-har-wgen" a harmonic temperature model not conditional on rainfall

• "Temp-har-wgen-wd" a harmonic temperature model dependent on wet or dry day

• "Temp-har-wgen-wdsd" a harmonic temperature model where standard deviation parameters are dependent on wet or dry day

• "PET-har-wgen"a harmonic potential evapotranspiration model

• "PET-har-wgen-wd" a harmonic potential evapotranspiration model dependent on wet or dry day

• "Radn-har-wgen" a harmonic solar radiation model (MJ/m2)

Examples

## Not run: 
data(tankDat); obs=tank_obs                     #Get observed data
modelTag=c("P-har-wgen","Temp-har-wgen")    #Select models
pars=modCalibrator(obs=obs,modelTag=modelTag)   #Calibrate models
sim=modSimulator(datStart="1970-01-01",         #Simulate!
                 datFinish="1999-12-31",
                 modelTag=modelTag,
                 parS=pars,
                 seed=123,
                 file=paste0("tester.csv"),
                 IOmode="verbose")
plot(sim$P[1:365])                             #Plot first year of rainfall

## End(Not run)

Plots the location of points in a two-dimensional exposure space

Description

The function uses an exposure space created using the function createExpSpace as input and creates a plot of the two dimensional (2D) exposure space. plotExpSpace plots only 2D spaces consisting of samples of 2 attributes.

Usage

plotExpSpace(
  expSpace,
  y = expSpace[["attPerturb"]][1],
  x = expSpace[["attPerturb"]][2]
)

Arguments

Details

The number of dimensions of an exposure space is equal to the number of perturbed attributes in that space. If the exposure space has more than 2 dimensions (perturbed attributes), this function can be used to plot 2D slices of the space. Note that the default arguments of this function is defined to plot a slice showing the first two dimensions of the space, arguments x and y may be specified to plot alternate dimensions.

See Also

createExpSpace

Examples

# create an exposure space that has more than 2 dimensions
attPerturb <- c("P_ann_tot_m", "P_ann_nWet_m", "P_Feb_tot_m")
attHold <- c("P_SON_dyWet_m", "P_JJA_avgWSD_m", "P_MAM_tot_m", "P_DJF_avgDSD_m", 
"Temp_ann_rng_m", "Temp_ann_avg_m")
attPerturbType = "regGrid"
attPerturbSamp = c(5, 5, 5)
attPerturbMin = c(0.8, 0.9, 0.85)
attPerturbMax = c(1, 1.1, 1.05)
expSpace <- createExpSpace(attPerturb = attPerturb, 
                           attPerturbSamp = attPerturbSamp, 
                           attPerturbMin = attPerturbMin,
                           attPerturbMax = attPerturbMax,
                           attPerturbType = attPerturbType,
                           attHold = attHold,
                           attTargetsFile = NULL)
# plot the first two dimensions
plotExpSpace(expSpace)
# plot another slice
plotExpSpace(expSpace, y = "P_ann_tot_m", x = "P_Feb_tot_m")

Creates summary plots of the biases in the multi-site scenarios

Description

plotMultiSiteScenarios uses a multi-site simulation performed using the function generateScenarios as input, and creates heatmaps that show biases in simulated attributes and spatial correlation. The function creates heatmaps (for each replicate and target) that show:

• magnitude of biases in single site attributes

• magnitude of biases in catchment total attributes

• biases in spatial correlation

Usage

plotMultiSiteScenarios(
  reference,
  sim,
  attSel = NULL,
  targets = 1,
  reps = 1,
  stages = c("Stage1", "Stage2", "Stage3")
)

Arguments

Value

The function returns three R plots for each target and replicate showing the biases in single site attributes, catchment average attributes, and spatial correlations.

See Also

generateScenarios

Examples

# load data from multi-site simulation
data(egMultiSiteSim)
# plot performance of simulated time series in terms of single site 
# and catchment attributes, and correlation between sites
## Not run: 
plotMultiSiteScenarios(reference=barossa_obs,sim=egMultiSiteSim)

## End(Not run)

Plots the differences in performance metrics from two system options

Description

plotOptions uses the system model performances calculated using the function runSystemModel for two alternate system model options, and the summary of the simulation generated using the functions generateScenarios & getSimSummary as input. The function plots the differences in the performance metrics between the two options, and the changes in performance thresholds in the space. The user may specify the attributes to be used as the axes of the plot. The function contains arguments to control the finer details of the plot.

Usage

plotOptions(
  performanceOpt1,
  performanceOpt2,
  sim,
  metric = NULL,
  attX = NULL,
  attY = NULL,
  topReps = NULL,
  opt1Label = "Option 1",
  opt2Label = "Option 2",
  titleText = paste0(opt2Label, " - ", opt1Label),
  perfThresh = NULL,
  perfThreshLabel = "Threshold",
  attSlices = NULL,
  climData = NULL,
  colMap = NULL,
  colLim = NULL
)

Arguments

Value

The plot of the differences in the performance metrics (option 2 - option 1) in a ggplot object.

See Also

runSystemModel, plotPerformanceSpace, generateScenarios, getSimSummary

Examples

# load example datasets
data("egSimSummary")
data("egSimPerformance")       # performance of option1
data("egSimPerformance_systemB")  # performance of option2
data("egClimData")
plotOptions(egSimPerformance[1], egSimPerformance_systemB [1], egSimSummary, 
attX = "P_ann_seasRatio", attY = "P_ann_tot_m", topReps = 7, perfThreshLabel = "Threshold (28L)",
perfThresh = 28,  opt1Label = "System A", opt2Label = "System B", climData = egClimData)

Plots performance for one-at-a-time (OAT) perturbations in attributes

Description

plotPerformanceOAT uses the system model performance calculated using the function runSystemModel and the summary of the simulation generated using the function generateScenarios & getSimSummary as input. The function creates line plots, each panel shows the variations in performance with perturbations in a single attribute. The function is intended for use with simulations with attributes perturbed on a one-at-a-time (OAT) grid.

Usage

plotPerformanceOAT(
  performance,
  sim,
  metric = NULL,
  topReps = NULL,
  col = NULL,
  ylim = NULL
)

Arguments

Details

The plots show the mean value of performance across replicates. The ranges between the minimum and maximum values of performance across replicates are shaded. The function is intended for use with simulations containing attributes perturbed on an "OAT" grid. If the perturbations are on a "regGrid", this function will subset OAT perturbations, if available, to create the plots. The function creates separate plots for perturbations in attributes of temperature and other variables. The function may be called with performance argument specifying the metric to be plotted to plot other metrics.

Value

The plot of the performance space and the ggplot object.

See Also

runSystemModel, generateScenarios, plotPerformanceSpace, getSimSummary

Examples

# load example datasets
data("egSimSummary")
data("egSimPerformance")
plotPerformanceOAT(egSimPerformance[2], egSimSummary)
plotPerformanceOAT(egSimPerformance[1], egSimSummary)
# using the metric argument
plotPerformanceOAT(egSimPerformance, egSimSummary, metric = "Reliability (-)")

Plots a performance space using the system performance and scenarios as input

Description

plotPerformanceSpace uses the system model performance calculated using the function runSystemModel and the summary of the simulation generated using the functions generateScenarios & getSimSummary as input to plot the performance space of the system. The user may specify the attributes to be used as the axes of the performance space.

Usage

plotPerformanceSpace(
  performance,
  sim,
  metric = NULL,
  attX = NULL,
  attY = NULL,
  topReps = NULL,
  perfThresh = NULL,
  perfThreshLabel = "Threshold",
  attSlices = NULL,
  climData = NULL,
  colMap = NULL,
  colLim = NULL,
  contourBreaks = NULL,
  axesPercentLabel = FALSE,
  type = "heat.plot",
  noPlot = F
)

Arguments

Details

If the space contains more than two perturbed attributes, the performance values are averaged across the perturbations in the attributes other than attX and attY. The user may specify argument attSlices to slice the performance space at specific values of the other perturbed attributes. If attSlices are used to specify minimum-maximum values to subset other perturbed attributes, the performance values are averaged across the subsetted perturbations in these attributes. If the input performance list contains multiple performance metrics, the function plots the first metric. The function may be called with performance argument specifying the metric to be plotted plotPerformanceSpace(performance[2], sim) to plot other metrics.

Value

The plot of the performance space and the ggplot object.

See Also

runSystemModel, generateScenarios, getSimSummary, plotPerformanceOAT

Examples

# load example datasets
data("egSimSummary")       # summary of stochastic simulation
data("egSimPerformance")   # system performance calculated using the stochastic simulation
data("egClimData")         # alternate climate data and system performance

plotPerformanceSpace(performance=egSimPerformance[2], sim=egSimSummary)

## Not run: 
# change plot style to "filled.contour" and specify contours - show contours from
# 0.76 to 0.9 in increments of 0.02
plotPerformanceSpace(type="filled.contour",performance=egSimPerformance[2],
                     sim=egSimSummary,contourBreaks=seq(0.76,0.9,0.02))


# adding climate data, using top 10 replicates
plotPerformanceSpace(performance=egSimPerformance[1], sim=egSimSummary,
                     topReps = 10, climData = egClimData)

# adding a threshold
plotPerformanceSpace(performance=egSimPerformance, sim=egSimSummary, metric = "Avg. Deficit (L)",
                     climData = egClimData, perfThresh = 27.5, perfThreshLabel = "Max Avg. Deficit")

# user specified colMap
plotPerformanceSpace(performance=egSimPerformance[1], sim=egSimSummary,
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",
                     colMap = viridisLite::inferno(100))

#modify theme to change axes positioning to stacked vertically and left aligned
plotPerformanceSpace(performance=egSimPerformance[1], sim=egSimSummary,
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",
                     colMap = viridisLite::inferno(100))+
ggplot2::theme(legend.box="vertical",
               legend.position="bottom",
               legend.box.just = "left",
               legend.margin = ggplot2::margin(t=0.01, r=0.1, b=0.01, l=0.1, "cm"),
               legend.justification=c(0.01,0.01))

# display fractional changes axes as percentage change
plotPerformanceSpace(performance=egSimPerformance, sim=egSimSummary,
                     metric = "Avg. Deficit (L)",
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",
                     axesPercentLabel=TRUE)

# change displayed contours on performance space - show contours from 18 to 34 in increments of 2 L
plotPerformanceSpace(performance=egSimPerformance, sim=egSimSummary,
                     metric = "Avg. Deficit (L)",
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",axesPercentLabel=TRUE,
                     contourBreaks=seq(18,34,2))

# change plot type to filled.contour style
plotPerformanceSpace(type="filled.contour",performance=egSimPerformance,
                     sim=egSimSummary, metric = "Avg. Deficit (L)",
                     climData = egClimData, perfThresh = 27.5,
                     perfThreshLabel = "Max Avg. Deficit",axesPercentLabel=TRUE,
                     contourBreaks=seq(18,34,2))

#example overlay points manually from a dataset in a similar style to egClimData
ptStyle= c(21,22, 24)  #select set of pt styles (e.g. hollow circle, square, triangle)
plotPerformanceSpace(performance=egSimPerformance[1], sim=egSimSummary,axesPercentLabel=TRUE)+
ggplot2::geom_point(data = egClimData,
                    mapping = ggplot2::aes(x = .data[["P_ann_tot_m"]],
                    y = .data[["P_ann_seasRatio"]],
                    shape = .data[["Name"]]),
                    show.legend = TRUE, size = 5, colour = "black", fill = "lightgray") +
ggplot2::scale_shape_manual(name = NULL, values = ptStyle,
                            guide = ggplot2::guide_legend(order = 2, nrow = 1))+
                   #one row of legend for specified ptStyle types
ggplot2::theme(legend.box="vertical", # vertical arrangement of items in legends
               legend.position="bottom", # position legends base of figure
               legend.justification=c(0,0)) # justification according to the plot area

# example of performance generated using simple scaled simulation
data("egScalPerformance")
data("egScalSummary")
data("egClimData")
plotPerformanceSpace(performance=egScalPerformance[1], sim=egScalSummary, climData = egClimData,
                     perfThresh = 28.25, perfThreshLabel = "Max Avg. Deficit")
                     
## End(Not run)

Plots contours of the number of performance thresholds exceeded in the perturbation space

Description

plotPerformanceSpaceMulti uses multiple system model performances calculated using the function runSystemModel and the summary of the simulation generated using the functions generateScenarios & getSimSummary as input to plot filled contours showing the number of performance thresholds exceeded in the perturbation space. The user may specify the attributes to be used as the axes of the perturbation space.

Usage

plotPerformanceSpaceMulti(
  performance,
  sim,
  perfThreshMin,
  perfThreshMax,
  attX = NULL,
  attY = NULL,
  attSlices = NULL,
  topReps = NULL,
  climData = NULL,
  col = NULL,
  axesPercentLabel = FALSE
)

Arguments

Details

If the space contains more than two perturbed attributes, the performance values are averaged across the perturbations in the attributes other than attX and attY. The user may specify argument attSlices to slice the performance space at specific values of the other perturbed attributes. If attSlices are used to specify minimum-maximum values to subset other perturbed attributes, the performance values are averaged across the subsetted perturbations in these attributes. This function cannot be used with sim perturbed on an "OAT" grid since contours of the number of performance thresholds exceeded cannot be calculated for an irregular perturbation space.

Value

The plot showing the number of thresholds exceeded and the ggplot object.

See Also

runSystemModel, generateScenarios, getSimSummary, plotPerformanceSpace

Examples

# load example datasets
data("egSimPerformance")
data("egSimSummary")
data("egClimData")

plotPerformanceSpaceMulti(performance=egSimPerformance, sim=egSimSummary, 
perfThreshMin = c(NA, 0.80), perfThreshMax = c(30, NA))

#replot with axes as percentage changes
plotPerformanceSpaceMulti(performance=egSimPerformance, sim=egSimSummary, 
perfThreshMin = c(NA, 0.80), perfThreshMax = c(30, NA),axesPercentLabel=TRUE)

# add alternate climate data and specify different colours for the plot
plotPerformanceSpaceMulti(performance=egSimPerformance, sim=egSimSummary, 
                          perfThreshMin = c(NA, 0.80),perfThreshMax = c(30, NA), 
                          climData = egClimData, col = viridisLite::magma(3))

# example using simple scaled simulations
data("egScalPerformance")
data("egScalSummary")
data("egClimData")
plotPerformanceSpaceMulti(performance=egScalPerformance, sim=egScalSummary, 
                          perfThreshMin = c(NA, 0.80),perfThreshMax = c(30, NA), 
                          climData = egClimData)

# replot with axes as percentage changes (Note: modifies fractional change attributes only)
plotPerformanceSpaceMulti(performance=egScalPerformance, sim=egScalSummary, 
                          perfThreshMin = c(NA, 0.80),perfThreshMax = c(30, NA), 
                          climData = egClimData,axesPercentLabel=TRUE)

Creates summary plots of the biases in the scenarios

Description

plotScenarios uses a simulation performed using the function generateScenarios as input and creates heatmaps that show the biases in the simulated attributes with respect to the specified target values of the attributes. The plots show the magnitude (absolute value) of the mean biases, and the standard deviation of biases across replicates. The heatmaps can be used to evaluate how well the simulated attributes match the specified targets. The biases are in units of percentage for attributes of variables like precipitation, and in units of degrees K for attributes of temperature. The function creates two heatmaps that show:

• magnitude of the mean biases across all the replicates

• standard deviation of biases across all the replicates

Usage

plotScenarios(
  sim,
  simName = NULL,
  writeToFile = FALSE,
  fileName = "plotScenarios.pdf",
  colMapRange = "default",
  plotAbs = T
)

Arguments

Details

The argument sim may be a full stochastic simulation generated using the function generateScenarrios or the summary of the stochastic simulation generated using getSimSummary

Value

The function returns two R plots showing the biases in the targets of the scenarios generated using the function generateScenarios. The figures may be saved to a pdf file by setting the writeToFile argument to TRUE.

See Also

createExpSpace, generateScenarions, getSimSummary

Examples

## Not run: 
# the examples are nnot run since the run times are too long for CRAN
# create an exposure space
attPerturb <- c("P_ann_tot_m", "P_ann_nWet_m", "P_ann_R10_m")
attHold <- c("P_Feb_tot_m", "P_SON_dyWet_m", "P_JJA_avgWSD_m", "P_MAM_tot_m",
"P_DJF_avgDSD_m", "Temp_ann_rng_m", "Temp_ann_avg_m")
attPerturbType = "regGrid"
attPerturbSamp = c(2, 1, 1)
attPerturbMin = c(0.9, 1, 1)
attPerturbMax = c(1.1, 1, 1)
expSpace <- createExpSpace(attPerturb = attPerturb,
                           attPerturbSamp = attPerturbSamp,
                           attPerturbMin = attPerturbMin,
                           attPerturbMax = attPerturbMax,
                           attPerturbType = attPerturbType,
                           attHold = attHold,
                           attTargetsFile = NULL)
# load example data available in foreSIGHT
data(tankDat)
# perform stochastic simulation
sim <- generateScenarios(reference = tank_obs,
                         expSpace = expSpace,
                         simLengthNyrs = 30,
                         numReplicates = 2)
# plots heatmaps showing biases in simulated targets
plotScenarios(sim)
# to save the figures to a pdf file set writeToFile = TRUE
# using an example stochastic simulation summary provided with the package
data("egSimSummary")
plotScenarios(egSimSummary)

## End(Not run)

Runs a system model and outputs the system performance

Description

runSystemModel uses time series of hydroclimatic variables generated using the function generateScenarios as input to a systemModel and collates the system performance for all the targets and replicates in the scenarios.

Usage

runSystemModel(sim, systemModel, systemArgs, metrics)

Arguments

Details

The runSystemModel function code is structured to be simple and may be used as an example to create scripts that use scenarios generated using generateScenarios to run system models in other programming languages. Type runSystemModel to view the function code. The function tankWrapper in this package may be used as an example to create user defined functions for the systemModel argument. Refer to tankWrapper to understand how the systemModel is expected to use systemArgs and return the calculated performance metrics. The systemModel function is expected to return a named list of performance metrics. The elements of the vector should correspond to metrics.

Value

The function returns a list containing the performance metrics calculated by the systemModel. Each element of the list corresponds to a performance metric and is named using the metrics argument. Each element contains performance values calculated at all the target points in the exposure space in a matrix with nrow corresponding to the targets and ncol corresponding to the replicates.

See Also

tankWrapper, generateScenarios

Examples

# Example using tankWrapper as the systemModel
#=====================================================
## Not run: 
# create an exposure space
attPerturb <- c("P_ann_tot_m", "P_ann_nWet_m")
attHold <- c("P_Feb_tot_m", "P_SON_dyWet_m", "P_JJA_avgWSD_m", "P_MAM_tot_m",
"P_DJF_avgDSD_m", "Temp_ann_rng_m", "Temp_ann_avg_m")
attPerturbType = "regGrid"
attPerturbSamp = c(2, 2)
attPerturbMin = c(0.9, 0.9)
attPerturbMax = c(1.1, 1.1)
expSpace <- createExpSpace(attPerturb = attPerturb,
                           attPerturbSamp = attPerturbSamp,
                           attPerturbMin = attPerturbMin,
                           attPerturbMax = attPerturbMax,
                           attPerturbType = attPerturbType,
                           attHold = attHold,
                           attTargetsFile = NULL)
# load example observed data available in foreSIGHT
data(tankDat)
# perform stochastic simulation
sim <- generateScenarios(reference = tank_obs,
                                  expSpace = expSpace,
                                  simLengthNyrs = 30)
# use the simulation to run a system model
systemArgs <- list(roofArea = 205, nPeople = 1, tankVol = 2400,
firstFlush = 2.0, write.file = FALSE)
tankMetrics <- viewTankMetrics()
systemPerf = runSystemModel(sim = sim,
                            systemModel = tankWrapper,
                            systemArgs = systemArgs,
                            metrics = tankMetrics[1:2])
                            
## End(Not run)

A function to calculate difference performance from simulated tank behaviour

Description

A function to calculate difference performance from simulated tank behaviour

Usage

tankPerformance(data=NULL,
                      roofArea=50,   
                      nPeople=1,
                      tankVol=3000,
		      firstFlush=1,
                      write.file=TRUE,
                      fnam="tankperformance.csv")

Arguments

Wrapper function for a rain water tank system model

Description

tankWrapper is a wrapper function for a rainwater tank system model in foreSIGHT. This function is used in examples in function help files and vignettes. This function may also be used as an example to create wrapper functions for other system models with scenarios generated using foreSIGHT in R or other programming languages.

Usage

tankWrapper(data, systemArgs, metrics)

Arguments

Value

The function returns a list containing the calculated values of the performance metrics specified in metrics after running the system model.

See Also

runSystemModel, viewTankMetrics

Examples

# view available performance metrics
viewTankMetrics()
# load example climate data to run the system model
data(tankDat)
systemArgs <- list(roofArea = 205, nPeople = 1, tankVol = 2400, 
firstFlush = 2.0, write.file = FALSE)
tankWrapper(tank_obs, systemArgs, 
metrics = c("average daily deficit (L)", "reliability (fraction)"))

Observations for demo tank model examples and vignette

Description

Dataset of observations for tank model examples

Format

A dataframe of observed climate data in the form Year Month Day P Temp.

Prints the definition of an attribute

Description

viewAttributeDef prints the short definition of a valid attribute

Usage

viewAttributeDef(attribute)

Arguments

See Also

createExpSpace

Examples

# To view the definition of any valid attribute
viewAttributeDef("P_ann_tot_m")

Prints the list of built-in attribute functions

Description

viewAttributeFuncs prints the list of built-in attribute functions

Usage

viewAttributeFuncs()

See Also

viewAttributeDef, createExpSpace

Examples

# To view the list of built-in functions used to calculate attributes
viewAttributeFuncs()

Prints the default optimisation arguments

Description

viewDefautOptimArgs() prints the default values of optimisation arguments (optimisationArguments) used by generateScenarios

Usage

viewDefaultOptimArgs(optimizer = "RGN")

Arguments

Details

This a helper function that prints the default values of the optimisation arguments. The user may specify alternate values of these arguments in fields named according to the corresponding argument name nested under optimisationArguments in a JSON file to use as the controlFile input to the generateScenarios function.

See Also

writeControlFile

Examples

# To view the default optimisation arguments
viewDefaultOptimArgs()

Prints the names and bounds of the parameters of the stochastic models

Description

viewModelParameters prints the names of the parameters of the stochastic model and its default minimum and maximum bounds. The stochastic model is specified using the function arguments.

Usage

viewModelParameters(variable, modelType, modelParameterVariation)

Arguments

Details

The available stochastic models can be viewed using the function viewModels(). This function prints the default ranges of the parameters of the stochastic model specified the stochastic model of interest.

See Also

viewModels, writeControlFile

Examples

viewModelParameters("P", "wgen", "annual")
viewModelParameters("P", "wgen", "harmonic")

Prints the available stochastic model options

Description

viewModels prints the stochastic model options available for the different hydroclimatic variables in foreSIGHT. These options may be used to create an controlFile for input to function generateScenarios.

Usage

viewModels(variable = NULL)

Arguments

See Also

writeControlFile, generateScenarios

Examples

# To view the valid variable names use the function without arguments
viewModels()

# Examples to view the model options available for different variables
viewModels("P")
viewModels("Temp")
viewModels("Radn")
viewModels("PET")

Prints the names of the performance metrics of the rain water tank system model

Description

viewTankMetrics prints the names of the performance metrics available in the example rain water tank system model. T

Usage

viewTankMetrics()

Details

This is a helper function that does not take any input arguments. The user may specify one or more of the metric names as the metric argument of tankWrapper to select the performance metrics from the tank system model. to select the performance metrics.

See Also

tankWrapper

Examples

viewTankMetrics()

Prints the names of and units of valid variables

Description

viewVariables() prints the names of valid variables and their units in the package. The user should input these variable in the same units.

Usage

viewVariables()

Details

The function does not take any input arguments.

See Also

generateScenarios

Examples

# To view the valid variables
viewVariables()

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

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)