CreateRunOptions: Creation of the RunOptions object required to the RunModel...

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/CreateRunOptions.R

Description

Creation of the RunOptions object required to the RunModel* functions.

Usage

1
2
3
4
5
6
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. 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 [-]. See details

IndPeriod_Run

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

IniStates

(optional) [numeric] object of class IniStates [mm and °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

Imax

(optional) [numeric] an atomic vector of the maximum capacity of the GR5H interception store [mm]; see RunModel_GR5H

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"

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

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:

(2) Customisation of initialisation options:

## — 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 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.

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 °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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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)

Example output

Warning message:
In CreateRunOptions(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel,  :
  model warm up period not defined: default configuration used
  the year preceding the run period is used 

Crit. NSE[Q] = 0.5698

airGR documentation built on April 27, 2021, 9:07 a.m.