airGR (version 1.3.2.23)

CreateRunOptions: 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,
  Outputs_Cal = NULL, Outputs_Sim = "all",
  RunSnowModule, MeanAnSolidPrecip = NULL,
  IsHyst = FALSE,
  warnings = TRUE, verbose = TRUE)

Arguments

FUN_MOD

[function] hydrological model function (e.g. RunModel_GR4J, RunModel_CemaNeigeGR4J)

InputsModel

[object of class InputsModel] see CreateInputsModel for details

IndPeriod_WarmUp

(optional) [numeric] index of period to be used for the model warm-up [-]

IndPeriod_Run

[numeric] index of period to be used for the model run [-]

IniStates

(optional) [numeric] object of class IniStates [mm and <U+00B0>C], see CreateIniStates for details

IniResLevels

(optional) [numeric] vector of initial fillings for the GR stores (2 or 3 values according to the model) [- and/or mm]; see details

Outputs_Cal

(optional) [character] vector giving the outputs needed for the calibration (e.g. c("Qsim")), the fewer outputs the faster the calibration

Outputs_Sim

(optional) [character] vector giving the requested outputs (e.g. c("DatesR", "Qsim", "SnowPack")), default = "all"

RunSnowModule

(deprecated) [boolean] option indicating whether CemaNeige should be activated. Please adapt FUN_MOD instead

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 = TRUE

verbose

(optional) [boolean] boolean indicating if the function is run in verbose mode or not, default = TRUE

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 warm-up [-]
IndPeriod_Run	[numeric] index of period to be used for the model run [-]
IniStates	[numeric] vector of initial model states [mm and <U+00B0>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
MeanAnSolidPrecip	[numeric] vector giving the annual mean of average solid precipitation for each layer [mm/y]

Details

Users wanting to use FUN_MOD functions that are not included in the package must create their own RunOptions object accordingly.

## ---- 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 one-year warm-up using the time steps preceding the IndPeriod_Run. The actual length of this warm-up might be shorter depending on data availability (no missing value of climate inputs being allowed in model input series).

• IniStates and IniResLevels are automatically set to initialise all the model states at 0, except for the production and routing stores which are respectively initialised at 30 % and 50 % of their capacity. In case GR6J is used, the exponential store is initialised by default with 0 mm. This initialisation is made at the very beginning of the model call (i.e. at the beginning of IndPeriod_WarmUp or at the beginning of IndPeriod_Run if the warm-up period is disabled).

(2) Customisation of initialisation options:

• IndPeriod_WarmUp can be used to specify the indices of the warm-up 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 and IndPeriod_Run = 1366:5000). However, it is also possible to perform a long-term initialisation if other indices than the warm-up ones are set in IndPeriod_WarmUp (e.g. IndPeriod_WarmUp = c(1:5000, 1:5000, 1:5000, 1000:1365)).

  • remark 2: it is also possible to completely disable the warm-up period when using IndPeriod_WarmUp = 0L. This is necessary if you want IniStates and/or IniResLevels 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 and IniResLevels can be used to specify the initial model states.

  • remark 1: IniStates and IniResLevels 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 previous RunModel call, as $StateEnd already respects the correct format; - IniStates can be created with the CreateIniStates 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) 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) should be use to obtain initial fillings of 30 % and 50 % for the production, routing stores and 0 mm for the exponential store, respectively. IniResLevels is optional and can only be used if IniStates is also defined (the state values corresponding to these two other stores in IniStates are not used in such case).

## ---- CemaNeige version

If IsHyst = FALSE, the original CemaNeige version from Val<U+00E9>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 rainfall-runoff 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 rainfall-runoff model.

See Also

RunModel, CreateInputsModel, CreateInputsCrit, CreateCalibOptions, CreateIniStates

Examples

# NOT RUN {
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")=="1990-01-01"), 
               which(format(BasinObs$DatesR, format = "%Y-%m-%d")=="1999-12-31"))

## 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: Nash-Sutcliffe Efficiency
InputsCrit  <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
                                RunOptions = RunOptions,
                                Obs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
# }