en fr

(1)

HAL Id: hal-02609367

https://hal.inrae.fr/hal-02609367

Submitted on 16 May 2020

HAL is a multi-disciplinary open access archive for the deposit and dissemination of sci- entific research documents, whether they are pub- lished or not. The documents may come from teaching and research institutions in France or abroad, or from public or private research centers.

L’archive ouverte pluridisciplinaire HAL, est destinée au dépôt et à la diffusion de documents scientifiques de niveau recherche, publiés ou non, émanant des établissements d’enseignement et de recherche français ou étrangers, des laboratoires publics ou privés.

airGR: Suite of GR Hydrological Models for Precipitation-Runoff Modelling (v. 1.2.13.16)

Laurent Coron, Olivier Delaigue, Guillaume Thirel, Charles Perrin, Claude Michel

To cite this version:

Laurent Coron, Olivier Delaigue, Guillaume Thirel, Charles Perrin, Claude Michel. airGR: Suite of GR Hydrological Models for Precipitation-Runoff Modelling (v. 1.2.13.16). 2019, pp.75. �hal-02609367�

(2)

Package ‘airGR’

April 3, 2019

Type Package

Title Suite of GR Hydrological Models for Precipitation-Runoff Modelling

Version 1.2.13.16 Date 2019-04-03 Depends R (>= 3.0.1)

Suggests knitr, rmarkdown, coda, DEoptim, dplyr, FME, ggmcmc, hydroPSO, Rmalschains

Description Hydrological modelling tools developed at Irstea-Antony (HYCAR Re- search Unit, France). The package includes several conceptual rainfall-runoff mod-

els (GR4H, GR4J, GR5J, GR6J, GR2M, GR1A), a snow accumulation and melt model (Ce- maNeige) and the associated functions for their calibration and evalua-

tion. Use help(airGR) for package description and references.

License GPL-2

URL https://hydrogr.github.io/airGR/

NeedsCompilation yes Encoding UTF-8 VignetteBuilder knitr

Author Laurent Coron [aut, trl] (<https://orcid.org/0000-0002-1503-6204>), Olivier Delaigue [aut, cre] (<https://orcid.org/0000-0002-7668-8468>), Guillaume Thirel [aut] (<https://orcid.org/0000-0002-1444-1830>), Charles Perrin [aut, ths] (<https://orcid.org/0000-0001-8552-1881>), Claude Michel [aut, ths],

Vazken Andréassian [ctb, ths] (<https://orcid.org/0000-0001-7124-9303>), François Bourgin [ctb] (<https://orcid.org/0000-0002-2820-7260>, 'Parameter estimation' vignettes),

Pierre Brigode [ctb] (<https://orcid.org/0000-0001-8257-0741>), Nicolas Le Moine [ctb],

Thibaut Mathevet [ctb], Safouane Mouelhi [ctb], Ludovic Oudin [ctb], Raji Pushpalatha [ctb], Audrey Valéry [ctb]

1

(3)

2 Rtopics documented:

Maintainer Olivier Delaigue<[email protected]>

Repository CRAN

Date/Publication 2019-04-03 14:50:03 UTC

R topics documented:

airGR . . . 3

BasinInfo . . . 5

BasinObs . . . 6

Calibration . . . 7

Calibration_Michel . . . 9

CreateCalibOptions . . . 11

CreateIniStates . . . 14

CreateInputsCrit . . . 17

CreateInputsModel . . . 21

CreateRunOptions . . . 23

DataAltiExtrapolation_Valery . . . 26

ErrorCrit . . . 28

ErrorCrit_KGE . . . 30

ErrorCrit_KGE2 . . . 32

ErrorCrit_NSE . . . 35

ErrorCrit_RMSE . . . 37

Param_Sets_GR4J . . . 38

PEdaily_Oudin . . . 40

plot.OutputsModel . . . 42

RunModel . . . 43

RunModel_CemaNeige . . . 44

RunModel_CemaNeigeGR4J . . . 47

RunModel_GR1A . . . 57

RunModel_GR2M . . . 59

RunModel_GR4H . . . 61

RunModel_GR4J . . . 63

SeriesAggreg . . . 72

TransfoParam . . . 73

Index 75

(4)

airGR 3

airGR Suite of GR Hydrological Models for Precipitation-Runoff Modelling

Description

This package brings into R the hydrological modelling tools used at IRSTEA-Antony (HYCAR Research Unit, France), including rainfall-runoff models (GR4H,GR4J,GR5J,GR6J,GR2M, GR1A) and a snow accumulation and melt model (CemaNeige). Each model core is coded in FORTRAN to ensure low computational time. The other package functions (i.e. mainly the calibration algorithm and the computation of the efficiency criteria) are coded in R.

## —- Functions and objects

The airGR package has been designed to fulfil two major requirements: facilitate the use by non- expert users and allow flexibility regarding the addition of external criteria, models or calibration algorithms. The names of the functions and their arguments were chosen to this end.

The package is mostly based on three families of functions:

- the functions belonging to theRunModelfamily require three arguments: InputsModel,RunOp- tionsandParam; please refer to help pagesCreateInputsModelandCreateRunOptionsfor further details and examples;

- the functions belonging to theErrorCrit family require two arguments: InputsCrit andOut- putsModel; please refer to help pages CreateInputsCritandRunModelfor further details and examples;

- the functions belonging to theCalibrationfamily require four arguments:InputsModel,RunOp- tions,InputsCritandCalibOptions; please refer to help pagesCreateInputsModel,CreateRunOptions, CreateInputsCritandCreateCalibOptionsfor further details and examples.

In order to limit the risk of mis-use and increase the flexibility of these main functions, we imposed the structure of their arguments and defined their class. Most users will not need to worry about these imposed structures since functions are provided to prepare these arguments for them:

CreateInputsModel,CreateRunOptions,CreateInputsCrit,CreateCalibOptions. However, advanced users wishing to supplement the package with their own models will need to comply with these imposed structures and refer to the package source codes to get all the specification requirements.

## —- Models

Six hydrological models and one snow melt and accumulation model are implemented in airGR.

The snow model can also be used alone or with the daily hydrological models, and each hydrological model can either be used alone or together with the snow model.

These models can be called within airGR using the following functions:

-RunModel_GR4H: four-parameter hourly lumped hydrological model (Mathevet, 2005) -RunModel_GR4J: four-parameter daily lumped hydrological model (Perrinet al., 2003) -RunModel_GR5J: five-parameter daily lumped hydrological model (Le Moine, 2008) -RunModel_GR6J: six-parameter daily lumped hydrological model (Pushpalathaet al., 2011) -RunModel_GR2M: two-parameter monthly lumped hydrological model (Mouelhi, 2003 ; Mouelhi

(5)

4 airGR et al., 2006a)

-RunModel_GR1A: one-parameter yearly lumped hydrological model (Mouelhi, 2003 ; Mouelhiet al., 2006b)

-RunModel_CemaNeige: two-parameter degree-day snow melt and accumulation daily model (Valéry et al., 2014)

-RunModel_CemaNeigeGR4J: combined use of GR4J and CemaNeige -RunModel_CemaNeigeGR5J: combined use of GR5J and CemaNeige -RunModel_CemaNeigeGR6J: combined use of GR6J and CemaNeige

## —- How to get started

To learn how to use the functions from the airGR package, it is recommended to follow the five steps described below:

1. refer to the help forRunModel_GR4Jthen run the provided example to assess how to make a simulation;

2. refer to the help for CreateInputsModelto understand how the inputs of a model are prepared/organised;

3. refer to the help forCreateRunOptions to understand how the run options of a model are parametrised/organised;

4. refer to the help forErrorCrit_NSEandCreateInputsCritto understand how the computation of an error criterion is prepared/made;

5. refer to the help forCalibration_Michel, run the provided example and then refer to the help forCreateCalibOptionsto understand how a model calibration is prepared/made.

For more information and to get started with the package, you can refer to the vignette (vignette("airGR")) and go on theairGR website.

## —- References

- Le Moine, N. (2008). Le bassin versant de surface vu par le souterrain : une voie d’amélioration des performances et du réalisme des modèles pluie-débit ?, PhD thesis (in French), UPMC - Cema- gref Antony, Paris, France, 324 pp.

- Mathevet, T. (2005). Quels modèles pluie-débit globaux pour le pas de temps horaire ? Développe- ment empirique et comparaison de modèles sur un large échantillon de bassins versants, PhD thesis (in French), ENGREF - Cemagref Antony, Paris, France, 463 pp.

- Mouelhi S. (2003). Vers une chaîne cohérente de modèles pluie-débit conceptuels globaux aux pas de temps pluriannuel, annuel, mensuel et journalier, PhD thesis (in French), ENGREF - Cemagref Antony, Paris, France, 323 pp.

- Mouelhi, S., C. Michel, C. Perrin and V. Andréassian (2006a). Stepwise development of a two-

parameter monthly water balance model, Journal of Hydrology, 318(1-4), 200-214, doi:10.1016/j.jhydrol.2005.06.014.

- Mouelhi, S., C. Michel, C. Perrin. & V. Andreassian (2006b). Linking stream flow to rainfall at the annual time step: the Manabe bucket model revisited, Journal of Hydrology, 328, 283-296, doi:10.1016/j.jhydrol.2005.12.022.

- Perrin, C., C. Michel and V. Andréassian (2003). Improvement of a parsimonious model for streamflow simulation, Journal of Hydrology, 279(1-4), 275-289, doi:10.1016/S0022-1694(03)00225- 7.

- Pushpalatha, R., C. Perrin, N. Le Moine, T. Mathevet and V. Andréassian (2011). A downward

(6)

BasinInfo 5 structural sensitivity analysis of hydrological models to improve low-flow simulation, Journal of Hydrology, 411(1-2), 66-76, doi:10.1016/j.jhydrol.2011.09.034.

- Valéry, A., V. Andréassian and C. Perrin (2014). "As simple as possible but not simpler": What is useful in a temperature-based snow-accounting routine? Part 2 - Sensitivity analysis of the Ce- maneige snow accounting routine on 380 catchments, Journal of Hydrology, 517(0): 1176-1187, doi: 1176-1187, doi:10.1016/j.jhydrol.2014.04.058.

BasinInfo Data sample: characteristics of a different catchments

Description

L0123001, L0123002 and L0123003 are fictional catchments.

X0310010 contains actual data from the Durance River at Embrun [La Clapière] (Hautes-Alpes, France).

R-object containing the code, station’s name, area and hypsometric curve of the catchment.

Format

List named ’BasinInfo’ containing

• two strings: catchment’s code and station’s name

• one float: catchment’s area in km2

• one numeric vector: catchment’s hypsometric curve (min, quantiles 01 to 99 and max) in metres

See Also

Calibration,RunModel_GR4J,TransfoParam,ErrorCrit_RMSE,CreateInputsModel,CreateRunOptions, CreateInputsCrit,CreateCalibOptions.

Examples

library(airGR)

RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel,

(12)

CreateCalibOptions 11 IndPeriod_Run = Ind_Run)

## calibration

OutputsCalib <- Calibration_Michel(InputsModel = InputsModel, RunOptions = RunOptions, InputsCrit = InputsCrit, CalibOptions = CalibOptions, FUN_MOD = RunModel_GR4J)

## simulation

OutputsModel <- RunModel_GR4J(InputsModel = InputsModel,

RunOptions = RunOptions, Param = Param)

## results preview

InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel, RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run]) OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)

CreateCalibOptions Creation of the CalibOptions object required but the Calibration functions

Description

Creation of theCalibOptionsobject required by theCalibration*functions.

Usage

CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_Michel, FUN_TRANSFO = NULL, IsHyst = FALSE, FixedParam = NULL, SearchRanges = NULL, StartParamList = NULL,

StartParamDistrib = NULL)

(13)

12 CreateCalibOptions Arguments

FUN_MOD [function] hydrological model function (e.g.RunModel_GR4J,RunModel_CemaNeigeGR4J) FUN_CALIB (optional) [function] calibration algorithm function (e.g. Calibration_Michel),

default =Calibration_Michel

FUN_TRANSFO (optional) [function] model parameters transformation function, if theFUN_MOD used is native in the package,FUN_TRANSFOis automatically defined

IsHyst [boolean] boolean indicating if the hysteresis version of CemaNeige is used. See details

FixedParam (optional) [numeric] vector giving the values set for the non-optimised parameter values (NParam columns, 1 line)

Example:

NA NA 3.34 ... NA

SearchRanges (optional) [numeric] matrix giving the ranges of real parameters (NParam columns, 2 lines)

Example:

[X1] [X2] [X3] [...] [Xi]

[1,] 0 -1 0 ... 0.0

[2,] 3000 +1 100 ... 3.0

StartParamList (optional) [numeric] matrix of parameter sets used for grid-screening calibration procedure (values in columns, sets in line)

Example:

[X1] [X2] [X3] [...] [Xi]

[set1] 800 -0.7 25 ... 1.0

[set2] 1000 -0.5 22 ... 1.1

[...] ... ... ... ... ...

[set n] 200 -0.3 17 ... 1.0

StartParamDistrib

(optional) [numeric] matrix of parameter values used for grid-screening calibration procedure (values in columns, percentiles in line)

Example:

[X1] [X2] [X3] [...] [Xi]

[value1] 800 -0.7 25 ... 1.0

[value2] 1000 NA 50 ... 1.2

[value3] 1200 NA NA ... 1.6

(14)

CreateCalibOptions 13 Details

Users wanting to useFUN_MOD,FUN_CALIBorFUN_TRANSFOfunctions that are not included in the package must create their ownCalibOptionsobject accordingly.

## —- CemaNeige version

IfIsHyst = FALSE, the original CemaNeige version from Valéry et al. (2014) is used.

IfIsHyst = 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 repre- sentation 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 CalibOptionscontaining the data required to evaluate the model outputs; it can include the following:

$FixedParam [numeric] vector giving the values to allocate to non-optimised parameter values

$SearchRanges [numeric] matrix giving the ranges of raw parameters

$StartParamList [numeric] matrix of parameter sets used for grid-screening calibration procedure

$StartParamDistrib [numeric] matrix of parameter values used for grid-screening calibration procedure

Author(s)

Laurent Coron, Olivier Delaigue, Guillaume Thirel See Also

Calibration,RunModel Examples

library(airGR)

(15)

14 CreateIniStates 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"))

## calibration

OutputsCalib <- Calibration(InputsModel = InputsModel, RunOptions = RunOptions, InputsCrit = InputsCrit, CalibOptions = CalibOptions, FUN_MOD = RunModel_GR4J,

FUN_CALIB = Calibration_Michel)

## simulation

## results preview

CreateIniStates Creation of the IniStates object possibly required by the CreateRunOp- tions functions

Description

Creation of theIniStatesobject possibly required by theCreateRunOptionsfunction.

Usage

CreateIniStates(FUN_MOD, InputsModel, IsHyst = FALSE, ProdStore = 350, RoutStore = 90, ExpStore = NULL,

(16)

CreateIniStates 15 UH1 = NULL, UH2 = NULL,

GCemaNeigeLayers = NULL, eTGCemaNeigeLayers = NULL,

GthrCemaNeigeLayers = NULL, GlocmaxCemaNeigeLayers = NULL, verbose = TRUE)

Arguments

FUN_MOD [function] hydrological model function (e.g. RunModel_GR4J, RunModel_CemaNeigeGR4J) InputsModel [object of classInputsModel] seeCreateInputsModelfor details

ProdStore [numeric] production store level [mm]

RoutStore [numeric] routing store level [mm]

ExpStore (optional) [numeric] series of exponential store level (negative) [mm] for the GR6J model

UH1 (optional) [numeric] unit hydrograph 1 levels [mm]

UH2 (optional) [numeric] unit hydrograph 2 levels [mm]

GCemaNeigeLayers

(optional) [numeric] snow pack [mm], possibly used to create the CemaNeige model initial state

eTGCemaNeigeLayers

(optional) [numeric] snow pack thermal state [°C], possibly used to create the CemaNeige model initial state

GthrCemaNeigeLayers

(optional) [numeric] melt threshold [mm], possibly used to create the CemaNeige model initial state in case the Linear Hysteresis version is used

GlocmaxCemaNeigeLayers

(optional) [numeric] local melt threshold for hysteresis [mm], possibly used to create the CemaNeige model initial state in case the Linear Hysteresis version is used

Details

20 numeric values are required for UH1 and 40 numeric values are required for UH2 if GR4J, GR5J or GR6J are used (respectively 20*24 and 40*24 for the hourly model GR4H).Please note that depending on the X4 parameter value that will be provided when running the model, not all the values may be used (only the first int(X4)+1 values are used for UH1 and the first 2*int(X4)+1 for UH2).

GCemaNeigeLayersandeTGCemaNeigeLayers require each numeric values as many as given in CreateInputsModelwith theNLayersargument.eTGCemaNeigeLayersvalues can be negatives.

The structure of the object of classIniStatesreturned is always exactly the same for all models (except for the unit hydrographs levels that contain more values with GR4H), even if some states do nt exist (e.g.$UH$UH1for GR2M).

If CemaNeige is not used,$CemaNeigeLayers$Gand$CemaNeigeLayers$eTGare set toNA.

(17)

16 CreateIniStates Nota: theStateEndobjects from the outputs ofRunModel*functions already respect the format given by theCreateIniStatesfunction.

Value

list object of classIniStatescontaining the initial model internal states; it always includes the following:

$Store [numeric] list of store levels ($Prod,$Routand$Exp)

$UH [numeric] list of unit hydrographs levels ($UH1and$UH2)

$CemaNeigeLayers [numeric] list of CemaNeige variables ($Gand$eTG) Author(s)

Olivier Delaigue See Also

CreateRunOptions

Examples

library(airGR)

## preparation of the InputsModel object

## run period selection

### preparation of the IniStates object with low values of ProdStore and RoutStore IniStates <- CreateIniStates(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel,

ProdStore = 0, RoutStore = 0, ExpStore = NULL, UH1 = c(0.52, 0.54, 0.15, rep(0, 17)),

UH2 = c(0.057, 0.042, 0.015, 0.005, rep(0, 36)), GCemaNeigeLayers = NULL, eTGCemaNeigeLayers = NULL, GthrCemaNeigeLayers = NULL, GlocmaxCemaNeigeLayers = NULL) str(IniStates)

## preparation of the RunOptions object

RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel, IndPeriod_WarmUp = 0L,

IndPeriod_Run = Ind_Run, IniStates = IniStates)

## simulation

Param <- c(X1 = 257.238, X2 = 1.012, X3 = 88.235, X4 = 2.208)

(18)

CreateInputsCrit 17 OutputsModel <- RunModel_GR4J(InputsModel = InputsModel,

## results preview

### preparation of the IniStates object with high values of ProdStore and RoutStore IniStates <- CreateIniStates(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel,

ProdStore = 450, RoutStore = 100, ExpStore = NULL, UH1 = c(0.52, 0.54, 0.15, rep(0, 17)),

UH2 = c(0.057, 0.042, 0.015, 0.005, rep(0, 36)), GCemaNeigeLayers = NULL, eTGCemaNeigeLayers = NULL, GthrCemaNeigeLayers = NULL, GlocmaxCemaNeigeLayers = NULL) str(IniStates)

RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel, IndPeriod_WarmUp = 0L,

IndPeriod_Run = Ind_Run, IniStates = IniStates)

## simulation

Param <- c(X1 = 257.238, X2 = 1.012, X3 = 88.235, X4 = 2.208) OutputsModel <- RunModel_GR4J(InputsModel = InputsModel,

## results preview

CreateInputsCrit Creation of the InputsCrit object required to the ErrorCrit functions

Description

Creation of theInputsCritobject required to theErrorCrit_*functions. This function is used to define whether the user wants to calculate a single criterion, multiple criteria in the same time, or a composite criterion, which averages several criteria.

Usage

CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions, Qobs, Obs, VarObs = "Q", BoolCrit = NULL,

transfo = "", Weights = NULL, Ind_zeroes = NULL, epsilon = NULL, warnings = TRUE, verbose = TRUE)

Arguments

FUN_CRIT [function (atomic or list)] error criterion function (e.g.ErrorCrit_RMSE,ErrorCrit_NSE)

(19)

18 CreateInputsCrit InputsModel [object of classInputsModel] seeCreateInputsModelfor details

RunOptions [object of classRunOptions] seeCreateRunOptionsfor details

Qobs (deprecated) [numeric (atomic or list)] series of observed discharges [mm/time step]

Obs [numeric (atomic or list)] series of observed variable ([mm/time step] for discharge or SWE, [-] for SCA)

VarObs (optional) [character (atomic or list)] names of the observed variable ("Q"by default, or one of"SCA","SWE"])

BoolCrit (optional) [boolean (atomic or list)] boolean (the same length asObs) giving the time steps to consider in the computation (all time steps are considered by default)

transfo (optional) [character (atomic or list)] name of the transformation (e.g."","sqrt",

"log","inv","sort")

Weights (optional) [numeric (atomic or list)] vector of weights necessary to calculate a composite criterion (the same length asFUN_CRIT) giving the weights to use for elements ofFUN_CRIT[-]. See details

Ind_zeroes (deprecated) [numeric] indices of the time steps where zeroes are observed epsilon (optional) [numeric (atomic or list)] small value to add to all observations and

simulations when"log"or"inv"transformations are used [same unit asObs].

See details

warnings (optional) [boolean] boolean indicating if the warning messages are shown, default =TRUE

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

Details

Users wanting to useFUN_CRITfunctions that are not included in the package must create their own InputsCrit object accordingly.

The epsilon value is useful when"log"or "inv"transformations are used (to avoid calculation of the inverse or of the logarithm of zero). The impact of this value and a recommendation about the epsilon value to use (usually one hundredth of average observation) are discussed in Pushpalatha et al. (2012) for NSE and in Santos et al. (2018) for KGE and KGE’.

We do not advise computing KGE or KGE’ with log-transformation as it might be wrongly in- fluenced by discharge values close to 0 or 1 and the criterion value is dependent on the discharge unit. See Santos et al. (2018) for more details and alternative solutions (see the references list below).

Users can set the following arguments as atomic or list:FUN_CRIT,Obs,VarObs,BoolCrit,transfo, Weights. If the list format is chosen, all the lists must have the same length.

Calculation of a single criterion (e.g. NSE computed on discharge) is prepared by providing to CreateInputsCritarguments atomics only.

Calculation of multiple criteria (e.g. NSE computed on discharge and RMSE computed on discharge) is prepared by providing toCreateInputsCritarguments lists except forWeights that

(20)

CreateInputsCrit 19 must be set asNULL.

Calculation of a composite criterion (e.g. the average between NSE computed on dscharge and NSE computed on log of discharge) is prepared by providing toCreateInputsCritarguments lists in- cludingWeights.

ErrorCrit_RMSEcannot be used in a composite criterion since it is not a unitless value.

Value

list object of classInputsCritcontaining the data required to evaluate the model outputs; it can include the following:

$FUN_CRIT [function] error criterion function (e.g.ErrorCrit_RMSE,ErrorCrit_NSE)

$Obs [numeric] series of observed variable(s) ([mm/time step] for discharge or SWE, [-] for SCA)

$VarObs [character] names of the observed variable(s)

$BoolCrit [boolean] boolean giving the time steps considered in the computation

$transfo [character] name of the transformation (e.g."","sqrt","log","inv","sort")

$epsilon [numeric] small value to add to all observations and simulations when"log"or"inv"transformations are used [same unit asObs]

$Weights [numeric] vector (same length asVarObs) giving the weights to use for elements ofFUN_CRIT[-]

WhenWeights = NULL,CreateInputsCritreturns an object of classSinglethat is a list such as the one described above.

WhenWeightscontains at least oneNULLvalue andObscontains a list of observations,CreateInputsCrit returns an object of classMultithat is a list of lists such as the one described above. TheErrorCrit function will then compute the different criteria prepared byCreateInputsCrit.

WhenWeightsis a list of at least 2 numerical values,CreateInputsCritreturns an object of class Compothat is a list of lists such as the one described above. This object will be useful to compute composite criterion with theErrorCritfunction.

To calculate composite or multiple criteria, it is necessary to use theErrorCritfunction. The other ErrorCrit_*functions (e.g.ErrorCrit_RMSE,ErrorCrit_NSE) can only use objects of classSin- gle(and notMultiorCompo).

Author(s)

Olivier Delaigue, Laurent Coron, Guillaume Thirel References

Pushpalatha, R., Perrin, C., Le Moine, N. and Andréassian, V. (2012). A review of efficiency criteria suitable for evaluating low-flow simulations. Journal of Hydrology, 420-421: 171-182.

doi:10.1016/j.jhydrol.2011.11.055.

Santos, L., Thirel, G. and Perrin, C. (2018). Technical note: Pitfalls in using log-transformed flows within the KGE criterion. Hydrol. Earth Syst. Sci., 22, 4583-4591. doi:10.5194/hess-22- 4583-2018.

See Also

RunModel,CreateInputsModel,CreateRunOptions,CreateCalibOptions,ErrorCrit

(21)

20 CreateInputsCrit Examples

library(airGR)

RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel, IndPeriod_Run = Ind_Run)

## simulation

Param <- c(X1 = 257.238, X2 = 1.012, X3 = 88.235, X4 = 2.208)

OutputsModel <- RunModel_GR4J(InputsModel = InputsModel, RunOptions = RunOptions, Param = Param)

## single efficiency criterion: Nash-Sutcliffe Efficiency InputsCritSingle <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE,

InputsModel = InputsModel, RunOptions = RunOptions, Obs = list(BasinObs$Qmm[Ind_Run]),

VarObs = "Q", transfo = "", Weights = NULL)

str(InputsCritSingle)

invisible(ErrorCrit(InputsCrit = InputsCritSingle, OutputsModel = OutputsModel))

## 2 efficiency criteria: RMSE and Nash-Sutcliffe Efficiency

InputsCritMulti <- CreateInputsCrit(FUN_CRIT = list(ErrorCrit_RMSE, ErrorCrit_NSE), InputsModel = InputsModel, RunOptions = RunOptions, Obs = list(BasinObs$Qmm[Ind_Run], BasinObs$Qmm[Ind_Run]),

VarObs = list("Q", "Q"), transfo = list("", "sqrt"), Weights = NULL)

str(InputsCritMulti)

invisible(ErrorCrit(InputsCrit = InputsCritMulti, OutputsModel = OutputsModel))

## efficiency composite criterion: Nash-Sutcliffe Efficiency mixing

## both raw and log-transformed flows

InputsCritCompo <- CreateInputsCrit(FUN_CRIT = list(ErrorCrit_NSE, ErrorCrit_NSE), InputsModel = InputsModel, RunOptions = RunOptions, Obs = list(BasinObs$Qmm[Ind_Run], BasinObs$Qmm[Ind_Run]),

VarObs = list("Q", "Q"), transfo = list("", "log"), Weights = list(0.4, 0.6))

str(InputsCritCompo)

invisible(ErrorCrit(InputsCrit = InputsCritCompo, OutputsModel = OutputsModel))

(22)

CreateInputsModel 21

CreateInputsModel Creation of the InputsModel object required to the RunModel functions

Description

Creation of theInputsModelobject required to theRunModel*functions.

Usage

CreateInputsModel(FUN_MOD, DatesR, Precip, PrecipScale = TRUE, PotEvap = NULL, TempMean = NULL, TempMin = NULL, TempMax = NULL, ZInputs = NULL, HypsoData = NULL,

NLayers = 5, verbose = TRUE)

Arguments

FUN_MOD [function] hydrological model function (e.g.RunModel_GR4J,RunModel_CemaNeigeGR4J) DatesR [POSIXt] vector of dates required to create the GR model and CemaNeige mod-

ule inputs

Precip [numeric] time series of total precipitation (catchment average) [mm/time step], required to create the GR model and CemaNeige module inputs

PrecipScale (optional) [boolean] indicating if the mean of the precipitation interpolated on the elevation layers must be kept or not, required to create CemaNeige module inputs, default =TRUE(the mean of the precipitation is kept to the original value) PotEvap [numeric] time series of potential evapotranspiration (catchment average) [mm/time

step], required to create the GR model inputs

TempMean (optional) [numeric] time series of mean air temperature [°C], required to create the CemaNeige module inputs

TempMin (optional) [numeric] time series of min air temperature [°C], possibly used to create the CemaNeige module inputs

TempMax (optional) [numeric] time series of max air temperature [°C], possibly used to create the CemaNeige module inputs

ZInputs (optional) [numeric] real giving the mean elevation of the Precip and Temp series (before extrapolation) [m], possibly used to create the CemaNeige module inputs

HypsoData (optional) [numeric] vector of 101 reals: min, q01 to q99 and max of catchment elevation distribution [m], if not defined a single elevation is used for Ce- maNeige

NLayers (optional) [numeric] integer giving the number of elevation layers requested [-], required to create CemaNeige module inputs, default=5

(23)

22 CreateInputsModel Details

Users wanting to useFUN_MODfunctions that are not included in the package must create their own InputsModel object accordingly.

Please note that if CemaNeige is used, andZInputsis different thanHypsoData, then precipitation and temperature are interpolated with theDataAltiExtrapolation_Valeryfunction.

Value

list object of classInputsModelcontaining the data required to evaluate the model outputs; it can include the following:

$DatesR [POSIXlt] vector of dates

$Precip [numeric] time series of total precipitation (catchment average) [mm/time step]

$PotEvap [numeric] time series of potential evapotranspiration (catchment average) [mm/time step], defined if FUN_MOD includes GR4H, GR4J, GR5J, GR6J, GR2M or GR1A

$LayerPrecip [list] list of time series of precipitation (layer average) [mm/time step], defined ifFUN_MODincludes CemaNeige

$LayerTempMean [list] list of time series of mean air temperature (layer average) [°C], defined ifFUN_MODincludes CemaNeige

$LayerFracSolidPrecip [list] list of time series of solid precipitation fraction (layer average) [-], defined ifFUN_MODincludes CemaNeige

Author(s)

Laurent Coron See Also

RunModel,CreateRunOptions,CreateInputsCrit,CreateCalibOptions,DataAltiExtrapolation_Valery Examples

library(airGR)

(24)

CreateRunOptions 23

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

CreateRunOptions Creation of the RunOptions object required to the RunModel functions

Description

Creation of the RunOptions object required to theRunModel*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 classInputsModel] seeCreateInputsModelfor 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 classIniStates[mm and °C], seeCreateIniStates 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

(25)

24 CreateRunOptions 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 acti- vated. Please adaptFUN_MODinstead

MeanAnSolidPrecip

(optional) [numeric] vector giving the annual mean of average solid precipitation for each layer (computed from InputsModel if not defined) [mm/y]

Details

Users wanting to useFUN_MODfunctions that are not included in the package must create their own RunOptionsobject 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_WarmUpdefault setting ensures a one-year warm-up using the time steps preceding theIndPeriod_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 IniResLevelsare 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_WarmUpor at the beginning ofIndPeriod_Runif the warm-up period is disabled).

(2) Customisation of initialisation options:

• IndPeriod_WarmUpcan 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 preced-

ingIndPeriod_Runare used (e.g.IndPeriod_WarmUp = 1000:1365andIndPeriod_Run = 1366:5000).

However, it is also possible to perform a long-term initialisation if other indices than the

warm-up 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 warm-up period when usingIndPeriod_WarmUp = 0L.

This is necessary if you wantIniStatesand/orIniResLevelsto be the actual initial values of the model variables from your simulation (e.g. to perform a forecast form a given initial state).

(26)

CreateRunOptions 25

• IniStatesandIniResLevelscan be used to specify the initial model states.

– remark 1:IniStatesandIniResLevelscan not be used with GR1A.

– remark 2: ifIniStatesis used, two possibilities are offered:

-IniStatescan be set to the$StateEndoutput of a previousRunModelcall, as$StateEnd already respects the correct format;

-IniStatescan be created with theCreateIniStatesfunction.

– remark 3: in addition toIniStates,IniResLevelsallows 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.IniResLevelsis optional and can only be used ifIniStatesis also defined (the state values corresponding to these two other stores inIniStatesare not used in such case).

## —- CemaNeige version

IfIsHyst = FALSE, the original CemaNeige version from Valéry et al. (2014) is used.

IfIsHyst = 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 repre- sentation 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 classRunOptionscontaining 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

MeanAnSolidPrecip [numeric] vector giving the annual mean of average solid precipitation for each layer [mm/y]

Author(s)

Laurent Coron, Olivier Delaigue, Guillaume Thirel

(27)

26 DataAltiExtrapolation_Valery See Also

RunModel,CreateInputsModel,CreateInputsCrit,CreateCalibOptions,CreateIniStates

Examples

library(airGR)

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

InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, RunOptions = RunOptions,

Obs = BasinObs$Qmm[Ind_Run])

OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)

DataAltiExtrapolation_Valery

Altitudinal extrapolation of precipitation and temperature series described by A. Valery

Description

Function which extrapolates the precipitation and air temperature series for different elevation layers (method from Valéry, 2010).

(28)

DataAltiExtrapolation_Valery 27 Usage

DataAltiExtrapolation_Valery(DatesR, Precip, PrecipScale = TRUE, TempMean, TempMin = NULL, TempMax = NULL,

ZInputs, HypsoData, NLayers, verbose = TRUE)

Arguments

DatesR [POSIXt] vector of dates

Precip [numeric] time series of daily total precipitation (catchment average) [mm/d]

PrecipScale (optional) [boolean] indicating if the mean of the precipitation interpolated on the elevation layers must be kept or not, required to create CemaNeige module inputs, default =TRUE(the mean of the precipitation is kept to the original value) TempMean [numeric] time series of daily mean air temperature [°C]

TempMin (optional) [numeric] time series of daily min air temperature [°C]

TempMax (optional) [numeric] time series of daily max air temperature [°C]

ZInputs [numeric] real giving the mean elevation of the Precip and Temp series (before extrapolation) [m]

HypsoData [numeric] vector of 101 reals: min, q01 to q99 and max of catchment elevation distribution [m]

NLayers [numeric] integer giving the number of elevation layers requested [-]

Details

Elevation layers of equal surface are created the 101 elevation quantiles (HypsoData) and the number requested elevation layers (NLayers).

Forcing data (precipitation and air temperature) are extrapolated using gradients from Valery (2010).

(e.g. gradP = 0.0004 [m-1] for France and gradT = 0.434 [°C/100m] for January, 1st).

This function is used by theCreateInputsModelfunction.

Value

list containing the extrapolated series of precip. and air temp. on each elevation layer

$LayerPrecip [list] list of time series of daily precipitation (layer average) [mm/d]

$LayerTempMean [list] list of time series of daily mean air temperature (layer average) [°C]

$LayerTempMin [list] list of time series of daily min air temperature (layer average) [°C]

$LayerTempMax [list] list of time series of daily max air temperature (layer average) [°C]

$LayerFracSolidPrecip [list] list of time series of daily solid precip. fract. (layer average) [-]

$ZLayers [numeric] vector of median elevation for each layer

Author(s)

Laurent Coron, Audrey Valéry, Olivier Delaigue, Pierre Brigode, Guillaume Thirel

(29)

28 ErrorCrit References

Turcotte, R., L.-G. Fortin, V. Fortin, J.-P. Fortin and J.-P. Villeneuve (2007). Operational analysis of the spatial distribution and the temporal evolution of the snowpack water equivalent in southern Quebec, Canada, Nordic Hydrology, 38(3), 211. doi:10.2166/nh.2007.009.

Valéry, A. (2010), Modélisation précipitations-débit sous influence nivale ? : Elaboration d’un module neige et évaluation sur 380 bassins versants. PhD thesis (in french), AgroParisTech, Paris, France.

USACE (1956), Snow Hydrology, pp. 437. U.S. Army Coprs of Engineers (USACE) North Pa- cific Division, Portland, Oregon, USA.

See Also

CreateInputsModel,RunModel_CemaNeigeGR4J

ErrorCrit Error criterion using the provided function

Description

Function which computes an error criterion with the provided function.

Usage

ErrorCrit(InputsCrit, OutputsModel, FUN_CRIT, warnings = TRUE, verbose = TRUE)

Arguments

InputsCrit [object of classInputsCrit] seeCreateInputsCritfor details

OutputsModel [object of classOutputsModel] seeRunModel_GR4JorRunModel_CemaNeigeGR4J for details

FUN_CRIT (deprecated) [function] error criterion function (e.g.ErrorCrit_RMSE,ErrorCrit_NSE) warnings (optional) [boolean] boolean indicating if the warning messages are shown, de-

fault =TRUE

Value

IfInputsCritis of classSingle:

[list] containing theErrorCrit_*functions outputs, seeErrorCrit_RMSEorErrorCrit_NSEfor details

(30)

ErrorCrit 29 IfInputsCritis of classMulti:

[list] of list containing theErrorCrit_*functions outputs, seeErrorCrit_RMSEorErrorCrit_NSEfor details

IfInputsCritis of classCompo:

$CritValue [numeric] value of the composite criterion

$CritName [character] name of the composite criterion

$Multiplier [numeric] integer indicating whether the criterion is indeed an error (+1) or an efficiency (-1)

$CritCompo$MultiCritValues [numeric] values of the sub-criteria

$CritCompo$MultiCritNames [numeric] names of the sub-criteria

$CritCompo$MultiCritWeights [character] weighted values of the sub-criteria

$MultiCrit [list] of list containing theErrorCrit_*functions outputs, seeErrorCrit_NSEorErrorCrit_KGEfor details

Author(s)

Olivier Delaigue See Also

CreateInputsCrit,ErrorCrit_RMSE,ErrorCrit_NSE,ErrorCrit_KGE,ErrorCrit_KGE2 Examples

library(airGR)

RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel, IndPeriod_Run = Ind_Run)

## simulation

Param <- c(X1 = 257.238, X2 = 1.012, X3 = 88.235, X4 = 2.208) OutputsModel <- RunModel_GR4J(InputsModel = InputsModel,

## single efficiency criterion: Nash-Sutcliffe Efficiency InputsCritSingle <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE,

(31)

30 ErrorCrit_KGE InputsModel = InputsModel, RunOptions = RunOptions, Obs = list(BasinObs$Qmm[Ind_Run]),

VarObs = "Q", transfo = "", Weights = NULL)

str(ErrorCrit(InputsCrit = InputsCritSingle, OutputsModel = OutputsModel))

## 2 efficiency critera: RMSE and the Nash-Sutcliffe Efficiency

InputsCritMulti <- CreateInputsCrit(FUN_CRIT = list(ErrorCrit_RMSE, ErrorCrit_NSE), InputsModel = InputsModel, RunOptions = RunOptions, Obs = list(BasinObs$Qmm[Ind_Run], BasinObs$Qmm[Ind_Run]),

VarObs = list("Q", "Q"), transfo = list("", "sqrt"), Weights = NULL)

str(ErrorCrit(InputsCrit = InputsCritMulti, OutputsModel = OutputsModel))

## efficiency composite criterion: Nash-Sutcliffe Efficiency mixing

## both raw and log-transformed flows

InputsCritCompo <- CreateInputsCrit(FUN_CRIT = list(ErrorCrit_NSE, ErrorCrit_NSE), InputsModel = InputsModel, RunOptions = RunOptions, Obs = list(BasinObs$Qmm[Ind_Run], BasinObs$Qmm[Ind_Run]),

VarObs = list("Q", "Q"), transfo = list("", "log"), Weights = list(0.4, 0.6))

str(ErrorCrit(InputsCrit = InputsCritCompo, OutputsModel = OutputsModel))

ErrorCrit_KGE Error criterion based on the KGE formula

Description

Function which computes an error criterion based on the KGE formula proposed by Gupta et al.

(2009).

Usage

ErrorCrit_KGE(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)

Arguments

(32)

ErrorCrit_KGE 31 Details

In addition to the criterion value, the function outputs include a multiplier (-1 or +1) which allows the use of the function for model calibration: the product CritValue * Multiplier is the criterion to be minimised (Multiplier = -1 for KGE).

The KGE formula is

KGE= 1−p

(r−1)²+ (α−1)²+ (β−1)²

with the following sub-criteria:

r= the linear correlation coefficient betweensimandobs α= σ_sim

σobs

β =µsim

µobs

Value

$CritValue [numeric] value of the criterion

$CritName [character] name of the criterion

$SubCritValues [numeric] values of the sub-criteria

$SubCritNames [character] names of the components of the criterion

$Ind_notcomputed [numeric] indices of the time steps whereInputsCrit$BoolCrit=FALSEor no data is available

Author(s)

Laurent Coron, Olivier Delaigue References

Gupta, H. V., Kling, H., Yilmaz, K. K. and Martinez, G. F. (2009). Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling.

Journal of Hydrology, 377(1-2), 80-91. doi:10.1016/j.jhydrol.2009.08.003.

See Also

ErrorCrit,ErrorCrit_RMSE,ErrorCrit_NSE,ErrorCrit_KGE2 Examples

library(airGR)

## loading catchment data

(33)

32 ErrorCrit_KGE2 data(L0123001)

## simulation

Param <- c(X1 = 734.568, X2 = -0.840, X3 = 109.809, X4 = 1.971)

## efficiency criterion: Kling-Gupta Efficiency on square-root-transformed flows transfo <- "sqrt"

InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel, RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run], transfo = transfo)

OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)

## efficiency criterion: Kling-Gupta Efficiency above a threshold (quant. 75 %)

BoolCrit <- BasinObs$Qmm[Ind_Run] >= quantile(BasinObs$Qmm[Ind_Run], 0.75, na.rm = TRUE) InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel,

RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run], BoolCrit = BoolCrit)

OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)

ErrorCrit_KGE2 Error criterion based on the KGE’ formula

Description

Function which computes an error criterion based on the KGE’ formula proposed by Kling et al.

(2012).

Usage

ErrorCrit_KGE2(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)

(34)

ErrorCrit_KGE2 33 Arguments

Details

In addition to the criterion value, the function outputs include a multiplier (-1 or +1) which allows the use of the function for model calibration: the product CritValue * Multiplier is the criterion to be minimised (Multiplier = -1 for KGE2).

The KGE’ formula is

KGE⁰ = 1−p

(r−1)²+ (γ−1)²+ (β−1)²

with the following sub-criteria:

r= the linear correlation coefficient betweensimandobs γ=CV_sim

CVobs

β =µsim

µ_obs Value

$CritValue [numeric] value of the criterion

$CritName [character] name of the criterion

$SubCritValues [numeric] values of the sub-criteria

$SubCritNames [character] names of the components of the criterion

$Ind_notcomputed [numeric] indices of the time steps whereInputsCrit$BoolCrit=FALSEor no data is available

Author(s)

Laurent Coron, Olivier Delaigue References

Gupta, H. V., Kling, H., Yilmaz, K. K. and Martinez, G. F. (2009). Decomposition of the mean squared error and NSE performance criteria: Implications for improving hydrological modelling.

(35)

34 ErrorCrit_KGE2 Journal of Hydrology, 377(1-2), 80-91. doi:10.1016/j.jhydrol.2009.08.003.

Kling, H., Fuchs, M. and Paulin, M. (2012). Runoff conditions in the upper Danube basin under an

ensemble of climate change scenarios. Journal of Hydrology, 424-425, 264-277. doi:10.1016/j.jhydrol.2012.01.011.

See Also

ErrorCrit,ErrorCrit_RMSE,ErrorCrit_NSE,ErrorCrit_KGE Examples

library(airGR)

## simulation

Param <- c(X1 = 734.568, X2 = -0.840, X3 = 109.809, X4 = 1.971)

InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE2, InputsModel = InputsModel, RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run]) OutputsCrit <- ErrorCrit_KGE2(InputsCrit = InputsCrit, OutputsModel = OutputsModel)

## efficiency criterion: Kling-Gupta Efficiency on square-root-transformed flows transfo <- "sqrt"

InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE2, InputsModel = InputsModel, RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run], transfo = transfo)

OutputsCrit <- ErrorCrit_KGE2(InputsCrit = InputsCrit, OutputsModel = OutputsModel)

## efficiency criterion: Kling-Gupta Efficiency above a threshold (quant. 75 %)

BoolCrit <- BasinObs$Qmm[Ind_Run] >= quantile(BasinObs$Qmm[Ind_Run], 0.75, na.rm = TRUE) InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE2, InputsModel = InputsModel,

RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run], BoolCrit = BoolCrit)

OutputsCrit <- ErrorCrit_KGE2(InputsCrit = InputsCrit, OutputsModel = OutputsModel)