CreateRunOptions.Rd 9.1 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{CreateRunOptions}
\alias{CreateRunOptions}
6
7


Delaigue Olivier's avatar
Delaigue Olivier committed
8
\title{Creation of the RunOptions object required to the RunModel functions}
9
10


Delaigue Olivier's avatar
Delaigue Olivier committed
11
\usage{
12
13
14
15
16
CreateRunOptions(FUN_MOD, InputsModel,
  IndPeriod_WarmUp = NULL, IndPeriod_Run,
  IniStates = NULL, IniResLevels = NULL,
  Outputs_Cal = NULL, Outputs_Sim = "all",
  RunSnowModule, MeanAnSolidPrecip = NULL,
17
  IsHyst = FALSE,
18
  warnings = TRUE, verbose = TRUE)
Delaigue Olivier's avatar
Delaigue Olivier committed
19
}
20
21


Delaigue Olivier's avatar
Delaigue Olivier committed
22
\arguments{
23
\item{FUN_MOD}{[function] hydrological model function (e.g. \code{\link{RunModel_GR4J}}, \code{\link{RunModel_CemaNeigeGR4J}})}
Delaigue Olivier's avatar
Delaigue Olivier committed
24
25
26
27
28
29
30

\item{InputsModel}{[object of class \emph{InputsModel}] see \code{\link{CreateInputsModel}} for details}

\item{IndPeriod_WarmUp}{(optional) [numeric] index of period to be used for the model warm-up [-]}

\item{IndPeriod_Run}{[numeric] index of period to be used for the model run [-]}

31
\item{IniStates}{(optional) [numeric] object of class \code{IniStates} [mm and °C], see \code{\link{CreateIniStates}} for details}
Delaigue Olivier's avatar
Delaigue Olivier committed
32

33
\item{IniResLevels}{(optional) [numeric] vector of initial fillings for the GR stores (2 or 3 values according to the model) [- and/or mm]; see details}
Delaigue Olivier's avatar
Delaigue Olivier committed
34

35
\item{Outputs_Cal}{(optional) [character] vector giving the outputs needed for the calibration \cr (e.g. c("Qsim")), the fewer outputs
36
 the faster the calibration}
Delaigue Olivier's avatar
Delaigue Olivier committed
37

38
\item{Outputs_Sim}{(optional) [character] vector giving the requested outputs \cr (e.g. c(\code{"DatesR"}, \code{"Qsim"}, \code{"SnowPack"})), default = \code{"all"}}
Delaigue Olivier's avatar
Delaigue Olivier committed
39

40
\item{RunSnowModule}{(deprecated) [boolean] option indicating whether CemaNeige should be activated. Please adapt \code{FUN_MOD} instead}
Delaigue Olivier's avatar
Delaigue Olivier committed
41

42
	
Delaigue Olivier's avatar
Delaigue Olivier committed
43
44
\item{MeanAnSolidPrecip}{(optional) [numeric] vector giving the annual mean of average solid precipitation for each layer (computed from InputsModel if not defined) [mm/y]}

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

47
48
\item{warnings}{(optional) [boolean]  boolean indicating if the warning messages are shown, default = \code{TRUE}}

49
\item{verbose}{(optional) [boolean] boolean indicating if the function is run in verbose mode or not, default = \code{TRUE}}
Delaigue Olivier's avatar
Delaigue Olivier committed
50
}
51
52


Delaigue Olivier's avatar
Delaigue Olivier committed
53
54
\value{
[list] object of class \emph{RunOptions} containing the data required to evaluate the model outputs; it can include the following:
55
56
57
58
59
60
61
62
63
  \tabular{ll}{
    \emph{IndPeriod_WarmUp } \tab [numeric] index of period to be used for the model warm-up [-] \cr
    \emph{IndPeriod_Run    } \tab [numeric] index of period to be used for the model run [-] \cr
    \emph{IniStates        } \tab [numeric] vector of initial model states [mm and °C] \cr
    \emph{IniResLevels     } \tab [numeric] vector of initial filling rates for production and routing stores [-] and level for the exponential store for GR6J [mm]\cr
    \emph{Outputs_Cal      } \tab [character] character vector giving only the outputs needed for the calibration \cr
    \emph{Outputs_Sim      } \tab [character] character vector giving the requested outputs \cr
    \emph{MeanAnSolidPrecip} \tab [numeric] vector giving the annual mean of average solid precipitation for each layer [mm/y] \cr
  }
Delaigue Olivier's avatar
Delaigue Olivier committed
64
}
65
66


Delaigue Olivier's avatar
Delaigue Olivier committed
67
\description{
68
Creation of the RunOptions object required to the \code{RunModel*} functions.
Delaigue Olivier's avatar
Delaigue Olivier committed
69
}
70
71


Delaigue Olivier's avatar
Delaigue Olivier committed
72
\details{
73
74
Users wanting to use \code{FUN_MOD} functions that are not included in 
the package must create their own \code{RunOptions} object accordingly.
Delaigue Olivier's avatar
Delaigue Olivier committed
75

76
## ---- Initialisation options
Delaigue Olivier's avatar
Delaigue Olivier committed
77
78
79

The model initialisation options can either be set to a default configuration or be defined by the user.

80
This is done via three vectors: \cr \code{IndPeriod_WarmUp}, \code{IniStates}, \code{IniResLevels}. \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
81
82
83
84
85
A default configuration is used for initialisation if these vectors are not defined.

(1) Default initialisation options:

\itemize{
86
\item \code{IndPeriod_WarmUp} default setting ensures a one-year warm-up using the time steps preceding the \code{IndPeriod_Run}. 
87
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).
Delaigue Olivier's avatar
Delaigue Olivier committed
88

89
\item \code{IniStates} and \code{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 \code{IndPeriod_WarmUp} or at the beginning of \code{IndPeriod_Run} if the warm-up period is disabled).
Delaigue Olivier's avatar
Delaigue Olivier committed
90
91
92
93
94
}

(2) Customisation of initialisation options:

\itemize{
95
96
97
\item \code{IndPeriod_WarmUp} can be used to specify the indices of the warm-up period (within the time series prepared in InputsModel).
\itemize{
\item remark 1:	for most common cases, indices corresponding to one or several years preceding \code{IndPeriod_Run} are used (e.g. \code{IndPeriod_WarmUp = 1000:1365} and \code{IndPeriod_Run = 1366:5000)}. \cr
98
However, it is also possible to perform a long-term initialisation if other indices than the warm-up ones are set in \code{IndPeriod_WarmUp} (e.g. \code{IndPeriod_WarmUp = c(1:5000, 1:5000, 1:5000, 1000:1365)}). \cr
99
100
101
102
103
104
105
106
\item remark 2:	it is also possible to completely disable the warm-up period when using \code{IndPeriod_WarmUp = 0L}. This is necessary if you want \code{IniStates} and/or \code{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). 
}
\item \code{IniStates} and \code{IniResLevels} can be used to specify the initial model states.
\itemize{
\item remark 1: \code{IniStates} and \code{IniResLevels} can not be used with GR1A. \cr
\item remark 2:	if \code{IniStates} is used, two possibilities are offered:\cr
- \code{IniStates} can be set to the \emph{$StateEnd} output of a previous \code{RunModel} call, as \emph{$StateEnd} already respects the correct format; \cr
- \code{IniStates} can be created with the \code{\link{CreateIniStates}} function.
107
\item remark 3:	in addition to \code{IniStates}, \code{IniResLevels} allows to set the filling rate of the production and routing stores for the GR models. For instance for GR4J and GR5J: \code{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, \code{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. \code{IniResLevels} is optional and can only be used if \code{IniStates} is also defined (the state values corresponding to these two other stores in \code{IniStates} are not used in such case).
108
}
Delaigue Olivier's avatar
Delaigue Olivier committed
109
}
110

111
## ---- CemaNeige version
112
113

If \code{IsHyst = FALSE}, the original CemaNeige version from Valéry et al. (2014) is used.  \cr
114
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
115
}
116
117


Delaigue Olivier's avatar
Delaigue Olivier committed
118
\examples{
119
library(airGR)
unknown's avatar
unknown committed
120
121

## loading catchment data
Delaigue Olivier's avatar
Delaigue Olivier committed
122
123
124
data(L0123001)

## preparation of the InputsModel object
125
126
InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR, 
                                 Precip = BasinObs$P, PotEvap = BasinObs$E)
Delaigue Olivier's avatar
Delaigue Olivier committed
127
128

## run period selection
129
130
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
131
132

## preparation of the RunOptions object
133
134
RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J,
                               InputsModel = InputsModel, IndPeriod_Run = Ind_Run)
Delaigue Olivier's avatar
Delaigue Olivier committed
135
136

## simulation
137
138
139
Param <- c(X1 = 734.568, X2 = -0.840, X3 = 109.809, X4 = 1.971)
OutputsModel <- RunModel(InputsModel = InputsModel,
                         RunOptions = RunOptions, Param = Param, 
140
                         FUN_MOD = RunModel_GR4J)
Delaigue Olivier's avatar
Delaigue Olivier committed
141
142

## results preview
143
plot(OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])
Delaigue Olivier's avatar
Delaigue Olivier committed
144
145

## efficiency criterion: Nash-Sutcliffe Efficiency
146
InputsCrit  <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
147
                                RunOptions = RunOptions,
148
                                Obs = BasinObs$Qmm[Ind_Run])
149
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
Delaigue Olivier's avatar
Delaigue Olivier committed
150
}
151
152


Delaigue Olivier's avatar
Delaigue Olivier committed
153
\author{
154
Laurent Coron, Olivier Delaigue, Guillaume Thirel
Delaigue Olivier's avatar
Delaigue Olivier committed
155
}
156
157


Delaigue Olivier's avatar
Delaigue Olivier committed
158
\seealso{
159
160
\code{\link{RunModel}}, \code{\link{CreateInputsModel}}, \code{\link{CreateInputsCrit}},
\code{\link{CreateCalibOptions}}, \code{\link{CreateIniStates}}
Delaigue Olivier's avatar
Delaigue Olivier committed
161
}