CreateCalibOptions.Rd 6.78 KB
Newer Older
Delaigue Olivier's avatar
Delaigue Olivier committed
1
\encoding{UTF-8}
2
3


Delaigue Olivier's avatar
Delaigue Olivier committed
4
5
\name{CreateCalibOptions}
\alias{CreateCalibOptions}
6
7


8
\title{Creation of the CalibOptions object required but the Calibration functions}
9
10


Delaigue Olivier's avatar
Delaigue Olivier committed
11
\usage{
12
CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_Michel,
13
  FUN_TRANSFO = NULL, IsHyst = FALSE, FixedParam = NULL,
14
  SearchRanges = NULL, StartParamList = NULL,
Delaigue Olivier's avatar
Delaigue Olivier committed
15
16
  StartParamDistrib = NULL)
}
17
18


Delaigue Olivier's avatar
Delaigue Olivier committed
19
\arguments{
20
\item{FUN_MOD}{[function] hydrological model function (e.g. \code{\link{RunModel_GR4J}}, \code{\link{RunModel_CemaNeigeGR4J}})}
Delaigue Olivier's avatar
Delaigue Olivier committed
21

22
\item{FUN_CALIB}{(optional) [function] calibration algorithm function (e.g. Calibration_Michel), default = \code{Calibration_Michel}}
Delaigue Olivier's avatar
Delaigue Olivier committed
23

24
\item{FUN_TRANSFO}{(optional) [function] model parameters transformation function, if the \code{FUN_MOD} used is native in the package, \code{FUN_TRANSFO} is automatically defined}
Delaigue Olivier's avatar
Delaigue Olivier committed
25

26
27
\item{IsHyst}{[boolean] boolean indicating if the hysteresis version of CemaNeige is used. See details}

28
29
30
\item{FixedParam}{(optional) [numeric] vector giving the values set for the non-optimised parameter values (NParam columns, 1 line)
\cr Example:
\tabular{llllll}{
31
              \tab   NA   \tab   NA   \tab 3.34   \tab  ...    \tab   NA \cr
32
}}
Delaigue Olivier's avatar
Delaigue Olivier committed
33
34

\item{SearchRanges}{(optional) [numeric] matrix giving the ranges of real parameters (NParam columns, 2 lines)
35
\cr Example:
Delaigue Olivier's avatar
Delaigue Olivier committed
36
37
38
39
40
41
42
\tabular{llllll}{
              \tab [X1]   \tab [X2]   \tab [X3]   \tab [...]   \tab [Xi] \cr
     [1,]     \tab    0   \tab   -1   \tab    0   \tab  ...    \tab  0.0 \cr
     [2,]     \tab 3000   \tab   +1   \tab  100   \tab  ...    \tab  3.0 \cr
}}

\item{StartParamList}{(optional) [numeric] matrix of parameter sets used for grid-screening calibration procedure (values in columns, sets in line)
43
\cr Example:
Delaigue Olivier's avatar
Delaigue Olivier committed
44
45
46
47
48
49
50
51
\tabular{llllll}{
              \tab [X1]   \tab [X2]   \tab [X3]   \tab [...]   \tab [Xi] \cr
     [set1]   \tab  800   \tab -0.7   \tab   25   \tab  ...    \tab  1.0 \cr
     [set2]   \tab 1000   \tab -0.5   \tab   22   \tab  ...    \tab  1.1 \cr
     [...]    \tab  ...   \tab  ...   \tab  ...   \tab  ...    \tab  ... \cr
     [set n]  \tab  200   \tab -0.3   \tab   17   \tab  ...    \tab  1.0 \cr
}}

52
53
\item{StartParamDistrib}{(optional) [numeric] matrix of parameter values used for grid-screening calibration procedure (values in columns, percentiles in line)
\cr Example:
Delaigue Olivier's avatar
Delaigue Olivier committed
54
55
56
57
58
59
60
61
62
\tabular{llllll}{
              \tab [X1]   \tab [X2]   \tab [X3]   \tab [...]   \tab [Xi] \cr
     [value1] \tab  800   \tab -0.7   \tab   25   \tab  ...    \tab  1.0 \cr
     [value2] \tab 1000   \tab   NA   \tab   50   \tab  ...    \tab  1.2 \cr
     [value3] \tab 1200   \tab   NA   \tab   NA   \tab  ...    \tab  1.6 \cr
}}
}
\value{
[list] object of class \emph{CalibOptions} containing the data required to evaluate the model outputs; it can include the following:
63
64
65
66
67
68
  \tabular{ll}{
    \emph{$FixedParam       } \tab [numeric] vector giving the values to allocate to non-optimised parameter values   \cr
    \emph{$SearchRanges     } \tab [numeric] matrix giving the ranges of raw parameters                               \cr
    \emph{$StartParamList   } \tab [numeric] matrix of parameter sets used for grid-screening calibration procedure   \cr
    \emph{$StartParamDistrib} \tab [numeric] matrix of parameter values used for grid-screening calibration procedure \cr
  }
Delaigue Olivier's avatar
Delaigue Olivier committed
69
}
70
71


Delaigue Olivier's avatar
Delaigue Olivier committed
72
\description{
73
Creation of the \emph{CalibOptions} object required by the \code{Calibration*} functions.
Delaigue Olivier's avatar
Delaigue Olivier committed
74
}
75
76


Delaigue Olivier's avatar
Delaigue Olivier committed
77
\details{
78
Users wanting to use \code{FUN_MOD}, \code{FUN_CALIB} or \code{FUN_TRANSFO} functions that are not included in 
79
the package must create their own \code{CalibOptions} object accordingly. \cr
80

81
## ---- CemaNeige version
82

83
84
If \code{IsHyst = FALSE}, the original CemaNeige version from Valéry et al. (2014) is used. \cr
If \code{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. \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
85
}
86
87


Delaigue Olivier's avatar
Delaigue Olivier committed
88
\examples{
89
library(airGR)
unknown's avatar
unknown committed
90
91

## loading catchment data
Delaigue Olivier's avatar
Delaigue Olivier committed
92
93
94
data(L0123001)

## preparation of InputsModel object
95
96
InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR, 
                                 Precip = BasinObs$P, PotEvap = BasinObs$E)
Delaigue Olivier's avatar
Delaigue Olivier committed
97
98

## calibration period selection
99
100
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"))
Delaigue Olivier's avatar
Delaigue Olivier committed
101
102

## preparation of RunOptions object
103
104
RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J,
                               InputsModel = InputsModel, IndPeriod_Run = Ind_Run)
Delaigue Olivier's avatar
Delaigue Olivier committed
105
106

## calibration criterion: preparation of the InputsCrit object
107
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
108
                               RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run])
Delaigue Olivier's avatar
Delaigue Olivier committed
109
110

## preparation of CalibOptions object
111
CalibOptions <- CreateCalibOptions(FUN_MOD = RunModel_GR4J, FUN_CALIB = Calibration_Michel)
Delaigue Olivier's avatar
Delaigue Olivier committed
112
113

## calibration
114
115
OutputsCalib <- Calibration(InputsModel = InputsModel, RunOptions = RunOptions,
                            InputsCrit = InputsCrit, CalibOptions = CalibOptions,
116
                            FUN_MOD = RunModel_GR4J, 
117
                            FUN_CALIB = Calibration_Michel)
Delaigue Olivier's avatar
Delaigue Olivier committed
118
119
120

## simulation
Param <- OutputsCalib$ParamFinalR
121
122
OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions, 
                         Param = Param, FUN = RunModel_GR4J)
Delaigue Olivier's avatar
Delaigue Olivier committed
123
124

## results preview
125
plot(OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])
Delaigue Olivier's avatar
Delaigue Olivier committed
126
127

## efficiency criterion: Nash-Sutcliffe Efficiency
128
InputsCrit  <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
129
                                RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run])
130
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
Delaigue Olivier's avatar
Delaigue Olivier committed
131
132

## efficiency criterion: Kling-Gupta Efficiency
133
InputsCrit  <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel, 
134
                                RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run])
135
OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
Delaigue Olivier's avatar
Delaigue Olivier committed
136
}
137
138


Delaigue Olivier's avatar
Delaigue Olivier committed
139
\author{
140
Laurent Coron, Olivier Delaigue, Guillaume Thirel
Delaigue Olivier's avatar
Delaigue Olivier committed
141
}
142
143


Delaigue Olivier's avatar
Delaigue Olivier committed
144
145
146
\seealso{
\code{\link{Calibration}}, \code{\link{RunModel}}
}