CreateRunOptions {airGR}  R Documentation 
Creation of the RunOptions object required to the RunModel functions
Description
Creation of the RunOptions object required to the RunModel*
functions.
Usage
CreateRunOptions(FUN_MOD, InputsModel,
IndPeriod_WarmUp = NULL, IndPeriod_Run,
IniStates = NULL, IniResLevels = NULL, Imax = NULL,
Outputs_Cal = NULL, Outputs_Sim = "all",
MeanAnSolidPrecip = NULL, IsHyst = FALSE,
warnings = TRUE, verbose = TRUE)
Arguments
FUN_MOD 
[function] hydrological model function (e.g. 
InputsModel 
[object of class InputsModel] see 
IndPeriod_WarmUp 
(optional) [numeric] index of period to be used for the model warmup []. See details 
IndPeriod_Run 
[numeric] index of period to be used for the model run []. See details 
IniStates 
(optional) [numeric] object of class 
IniResLevels 
(optional) [numeric] vector of initial fillings for the GR stores (4 values; use NA when not relevant for a given model) [ and/or mm]. See details 
Imax 
(optional) [numeric] an atomic vector of the maximum capacity of the GR5H interception store [mm]; see 
Outputs_Cal 
(optional) [character] vector giving the outputs needed for the calibration 
Outputs_Sim 
(optional) [character] vector giving the requested outputs 
MeanAnSolidPrecip 
(optional) [numeric] vector giving the annual mean of average solid precipitation for each layer (computed from InputsModel if not defined) [mm/y] 
IsHyst 
[boolean] boolean indicating if the hysteresis version of CemaNeige is used. See details 
warnings 
(optional) [boolean] boolean indicating if the warning messages are shown, default = 
verbose 
(optional) [boolean] boolean indicating if the function is run in verbose mode or not, default = 
Details
Users wanting to use FUN_MOD
functions that are not included in
the package must create their own RunOptions
object accordingly.
## — IndPeriod_WarmUp and IndPeriod_Run
Since the hydrological models included in airGR are continuous models, meaning that internal states of the models are propagated to the next time step, IndPeriod_WarmUp
and IndPeriod_Run
must be continuous periods, represented by continuous indices values; no gaps are allowed. To calculate criteria or to calibrate a model over discontinuous periods, please see the Bool_Crit
argument of the CreateInputsCrit
function.
## — Initialisation options
The model initialisation options can either be set to a default configuration or be defined by the user.
This is done via three vectors:
IndPeriod_WarmUp
, IniStates
, IniResLevels
.
A default configuration is used for initialisation if these vectors are not defined.
(1) Default initialisation options:

IndPeriod_WarmUp
default setting ensures a oneyear warmup using the time steps preceding theIndPeriod_Run
. The actual length of this warmup might be shorter depending on data availability (no missing value of climate inputs being allowed in model input series). 
IniStates
andIniResLevels
are automatically set to initialise all the model states at 0, except for the production and routing stores levels which are respectively initialised at 30 % and 50 % of their capacity. In case GR5H is used with an interception store, the intercetion store level is initialised by default with 0 mm. In case GR6J is used, the exponential store level is initialised by default with 0 mm. This initialisation is made at the very beginning of the model call (i.e. at the beginning ofIndPeriod_WarmUp
or at the beginning ofIndPeriod_Run
if the warmup period is disabled).
(2) Customisation of initialisation options:

IndPeriod_WarmUp
can be used to specify the indices of the warmup period (within the time series prepared in InputsModel).remark 1: for most common cases, indices corresponding to one or several years preceding
IndPeriod_Run
are used (e.g.IndPeriod_WarmUp = 1000:1365
andIndPeriod_Run = 1366:5000)
.
However, it is also possible to perform a longterm initialisation if other indices than the warmup ones are set inIndPeriod_WarmUp
(e.g.IndPeriod_WarmUp = c(1:5000, 1:5000, 1:5000, 1000:1365)
).
remark 2: it is also possible to completely disable the warmup period when using
IndPeriod_WarmUp = 0L
. This is necessary if you wantIniStates
and/orIniResLevels
to be the actual initial values of the model variables from your simulation (e.g. to perform a forecast form a given initial state).

IniStates
andIniResLevels
can be used to specify the initial model states.remark 1:
IniStates
andIniResLevels
can not be used with GR1A.
remark 2: if
IniStates
is used, two possibilities are offered:
IniStates
can be set to the $StateEnd output of a previousRunModel
call, as $StateEnd already respects the correct format;
IniStates
can be created with theCreateIniStates
function.remark 3: in addition to
IniStates
,IniResLevels
allows to set the filling rate of the production and routing stores for the GR models. For instance for GR4J and GR5J:IniResLevels = c(0.3, 0.5, NA, NA)
should be used to obtain initial fillings of 30 % and 50 % for the production and routing stores, respectively. For GR6J,IniResLevels = c(0.3, 0.5, 0, NA)
should be used to obtain initial fillings of 30 % and 50 % for the production and routing stores levels and 0 mm for the exponential store level, respectively. For GR5H with an interception store,IniResLevels = c(0.3, 0.5, NA, 0.4)
should be used to obtain initial fillings of 30 %, 50 % and 40 % for the production, routing and interception stores levels, respectively.IniResLevels
is optional and can only be used ifIniStates
is also defined (the state values corresponding to these two other stores inIniStates
are not used in such case).
## — CemaNeige version
If IsHyst = FALSE
, the original CemaNeige version from Valéry et al. (2014) is used.
If IsHyst = TRUE
, the CemaNeige version from Riboust et al. (2019) is used. Compared to the original version, this version of CemaNeige needs two more parameters and it includes a representation of the hysteretic relationship between the Snow Cover Area (SCA) and the Snow Water Equivalent (SWE) in the catchment. The hysteresis included in airGR is the Modified Linear hysteresis (LH*); it is represented on panel b) of Fig. 3 in Riboust et al. (2019). Riboust et al. (2019) advise to use the LH* version of CemaNeige with parameters calibrated using an objective function combining 75 % of KGE calculated on discharge simulated from a rainfallrunoff model compared to observed discharge and 5 % of KGE calculated on SCA on 5 CemaNeige elevation bands compared to satellite (e.g. MODIS) SCA (see Eq. (18), Table 3 and Fig. 6). Riboust et al. (2019)'s tests were realized with GR4J as the chosen rainfallrunoff model.
Value
[list] object of class RunOptions containing the data required to evaluate the model outputs; it can include the following:
IndPeriod_WarmUp  [numeric] index of period to be used for the model warmup [] 
IndPeriod_Run  [numeric] index of period to be used for the model run [] 
IniStates  [numeric] vector of initial model states [mm and °C] 
IniResLevels  [numeric] vector of initial filling rates for production and routing stores [] and level for the exponential store for GR6J [mm] 
Outputs_Cal  [character] character vector giving only the outputs needed for the calibration 
Outputs_Sim  [character] character vector giving the requested outputs 
Imax  [numeric] vector giving the maximal capacity of the GR5H interception store 
MeanAnSolidPrecip  [numeric] vector giving the annual mean of average solid precipitation for each layer [mm/y] 
Author(s)
Laurent Coron, Olivier Delaigue, Guillaume Thirel
See Also
RunModel
, CreateInputsModel
, CreateInputsCrit
,
CreateCalibOptions
, CreateIniStates
, Imax
Examples
library(airGR)
## loading catchment data
data(L0123001)
## preparation of the InputsModel object
InputsModel < CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR,
Precip = BasinObs$P, PotEvap = BasinObs$E)
## run period selection
Ind_Run < seq(which(format(BasinObs$DatesR, format = "%Y%m%d")=="19900101"),
which(format(BasinObs$DatesR, format = "%Y%m%d")=="19991231"))
## preparation of the RunOptions object
RunOptions < CreateRunOptions(FUN_MOD = RunModel_GR4J,
InputsModel = InputsModel, IndPeriod_Run = Ind_Run)
## simulation
Param < c(X1 = 734.568, X2 = 0.840, X3 = 109.809, X4 = 1.971)
OutputsModel < RunModel(InputsModel = InputsModel,
RunOptions = RunOptions, Param = Param,
FUN_MOD = RunModel_GR4J)
## results preview
plot(OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])
## efficiency criterion: NashSutcliffe Efficiency
InputsCrit < CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions,
Obs = BasinObs$Qmm[Ind_Run])
OutputsCrit < ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)