Creation of the InputsCrit object required to the ErrorCrit_* 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.

# S3 method for InputsModel
CreateInputsCrit(InputsModel, FUN_CRIT, ...)

Arguments

InputsModel

[object of class InputsModel] see CreateInputsModel for details

FUN_CRIT

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

...

Further arguments for compatibility with S3 method

Value

[list] object of class InputsCrit containing 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", "boxcox" or a number for power transformation)
$epsilon [numeric] small value to add to all observations and simulations when "log" or "inv" transformations are used [same unit as Obs]
$Weights [numeric] vector (same length as VarObs) giving the weights to use for elements of FUN_CRIT [-]

When Weights = NULL, CreateInputsCrit returns an object of class Single that is a list such as the one described above.
When Weights contains at least one NULL value and Obs contains a list of observations, CreateInputsCrit returns an object of class Multi that is a list of lists such as the one described above. The ErrorCrit function will then compute the different criteria prepared by CreateInputsCrit.
When Weights is a list of at least 2 numerical values, CreateInputsCrit returns an object of class Compo that is a list of lists such as the one described above. This object will be useful to compute composite criterion with the ErrorCrit function.
To calculate composite or multiple criteria, it is necessary to use the ErrorCrit function. The other ErrorCrit_* functions (e.g. ErrorCrit_RMSE, ErrorCrit_NSE) can only use objects of class Single (and not Multi or Compo).

Details

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

## --- Period of calculation

Criteria can be calculated over discontinuous periods (i.e. only over winter periods, or when observed discharge is below a certain threshold). To do so, please indicate in Bool_Crit which indices must be used for calcullation. Discontinuous periods are allowed in the Bool_Crit argument.

## --- Transformations

Transformations are simple functions applied to the observed and simulated variables used in order to change their distribution. Transformations are often used in hydrology for modifying the weight put on errors made for high flows or low flows. The following transformations are available:

  • "": no transformation is used (default case)

  • "sqrt": squared root transformation

  • "log": logarithmic transformation (see below regarding the specific case of KGE or KGE2)

  • "inv": inverse transformation

  • "sort": sort transformation (the simulated and observed variables are sorted from lowest to highest)

  • "boxcox": Box-Cox transformation (see below for details)

  • numeric: power transformation (see below for details)

We do not advise computing KGE or KGE' with log-transformation as it might be wrongly influenced 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).

In order to make sure that KGE and KGE2 remain dimensionless and are not impacted by zero values, the Box-Cox transformation (transfo = "boxcox") uses the formulation given in Equation 10 of Santos et al. (2018). Lambda is set to 0.25 accordingly.

The syntax of the power transformation allows a numeric or a string of characters. For example for a squared transformation, the following can be used: transfo = 2, transfo = "2" or transfo = "^2". Negative values are allowed. Fraction values are not allowed (e.g., "-1/2" must instead be written "-0.5").

## --- The epsilon value

The epsilon value is useful when "log" or "inv" transformations are used (to avoid calculation of the inverse or of the logarithm of zero). If an epsilon value is provided, then it is added to the observed and simulated variable time series at each time step and before the application of a transformation. The epsilon value has no effect when the "boxcox" transformation is used. 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'.

## --- Single, multiple or composite criteria calculation

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 CreateInputsCrit arguments atomics only.
Calculation of multiple criteria (e.g. NSE computed on discharge and RMSE computed on discharge) is prepared by providing to CreateInputsCrit arguments lists except for Weights that must be set as NULL.
Calculation of a composite criterion (e.g. the average between NSE computed on discharge and NSE computed on log of discharge) is prepared by providing to CreateInputsCrit arguments lists including Weights.
ErrorCrit_RMSE cannot be used in a composite criterion since it is not a unitless value.

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

Author

Olivier Delaigue, Laurent Coron, Guillaume Thirel

Examples

#> #> Attaching package: 'airGR'
#> The following objects are masked from 'package:airGRiwrm': #> #> Calibration, CreateCalibOptions, CreateInputsCrit, #> CreateInputsModel, CreateRunOptions, RunModel
## 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) ## calibration 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 RunOptions object RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel, IndPeriod_Run = Ind_Run)
#> Warning: model warm up period not defined: default configuration used #> the year preceding the run period is used
## 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)
#> List of 8 #> $ FUN_CRIT: chr "ErrorCrit_NSE" #> $ Obs : num [1:3652] 1.99 1.8 2.86 2.4 3.31 ... #> $ VarObs : chr "Q" #> $ BoolCrit: logi [1:3652] TRUE TRUE TRUE TRUE TRUE TRUE ... #> $ idLayer : logi NA #> $ transfo : chr "" #> $ epsilon : NULL #> $ Weights : NULL #> - attr(*, "class")= chr [1:2] "Single" "InputsCrit"
invisible(ErrorCrit(InputsCrit = InputsCritSingle, OutputsModel = OutputsModel))
#> Crit. NSE[Q] = 0.7988
## 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)
#> List of 2 #> $ IC1:List of 8 #> ..$ FUN_CRIT: chr "ErrorCrit_RMSE" #> ..$ Obs : num [1:3652] 1.99 1.8 2.86 2.4 3.31 ... #> ..$ VarObs : chr "Q" #> ..$ BoolCrit: logi [1:3652] TRUE TRUE TRUE TRUE TRUE TRUE ... #> ..$ idLayer : logi NA #> ..$ transfo : chr "" #> ..$ epsilon : NULL #> ..$ Weights : NULL #> ..- attr(*, "class")= chr [1:2] "Single" "InputsCrit" #> $ IC2:List of 8 #> ..$ FUN_CRIT: chr "ErrorCrit_NSE" #> ..$ Obs : num [1:3652] 1.99 1.8 2.86 2.4 3.31 ... #> ..$ VarObs : chr "Q" #> ..$ BoolCrit: logi [1:3652] TRUE TRUE TRUE TRUE TRUE TRUE ... #> ..$ idLayer : logi NA #> ..$ transfo : chr "sqrt" #> ..$ epsilon : NULL #> ..$ Weights : NULL #> ..- attr(*, "class")= chr [1:2] "Single" "InputsCrit" #> - attr(*, "class")= chr [1:2] "Multi" "InputsCrit"
invisible(ErrorCrit(InputsCrit = InputsCritMulti, OutputsModel = OutputsModel))
#> Crit. RMSE[Q] = 0.7864
#> Crit. NSE[sqrt(Q)] = 0.8478
## 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)
#> List of 2 #> $ IC1:List of 8 #> ..$ FUN_CRIT: chr "ErrorCrit_NSE" #> ..$ Obs : num [1:3652] 1.99 1.8 2.86 2.4 3.31 ... #> ..$ VarObs : chr "Q" #> ..$ BoolCrit: logi [1:3652] TRUE TRUE TRUE TRUE TRUE TRUE ... #> ..$ idLayer : logi NA #> ..$ transfo : chr "" #> ..$ epsilon : NULL #> ..$ Weights : num 0.4 #> ..- attr(*, "class")= chr [1:2] "Single" "InputsCrit" #> $ IC2:List of 8 #> ..$ FUN_CRIT: chr "ErrorCrit_NSE" #> ..$ Obs : num [1:3652] 1.99 1.8 2.86 2.4 3.31 ... #> ..$ VarObs : chr "Q" #> ..$ BoolCrit: logi [1:3652] TRUE TRUE TRUE TRUE TRUE TRUE ... #> ..$ idLayer : logi NA #> ..$ transfo : chr "log" #> ..$ epsilon : NULL #> ..$ Weights : num 0.6 #> ..- attr(*, "class")= chr [1:2] "Single" "InputsCrit" #> - attr(*, "class")= chr [1:2] "Compo" "InputsCrit"
invisible(ErrorCrit(InputsCrit = InputsCritCompo, OutputsModel = OutputsModel))
#> Crit. NSE[Q] = 0.7988
#> Crit. NSE[log(Q)] = 0.8159
#> ------------------------------------
#> Crit. Composite = 0.8091
#> Formula: sum(0.40 * NSE[Q], 0.60 * NSE[log(Q)])