CreateRunOptions.Rd 9.1 KB
 Delaigue Olivier committed Oct 28, 2015 1 \encoding{UTF-8}  unknown committed Aug 18, 2017 2 3   Delaigue Olivier committed Oct 28, 2015 4 5 \name{CreateRunOptions} \alias{CreateRunOptions}  unknown committed Aug 18, 2017 6 7   Delaigue Olivier committed Oct 28, 2015 8 \title{Creation of the RunOptions object required to the RunModel functions}  unknown committed Aug 18, 2017 9 10   Delaigue Olivier committed Oct 28, 2015 11 \usage{  Delaigue Olivier committed Oct 17, 2018 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,  Delaigue Olivier committed Oct 17, 2018 18  warnings = TRUE, verbose = TRUE)  Delaigue Olivier committed Oct 28, 2015 19 }  unknown committed Aug 18, 2017 20 21   Delaigue Olivier committed Oct 28, 2015 22 \arguments{  unknown committed Aug 18, 2017 23 \item{FUN_MOD}{[function] hydrological model function (e.g. \code{\link{RunModel_GR4J}}, \code{\link{RunModel_CemaNeigeGR4J}})}  Delaigue Olivier committed Oct 28, 2015 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 [-]}  unknown committed Jun 26, 2017 31 \item{IniStates}{(optional) [numeric] object of class \code{IniStates} [mm and °C], see \code{\link{CreateIniStates}} for details}  Delaigue Olivier committed Oct 28, 2015 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 committed Oct 28, 2015 34   Delaigue Olivier committed Apr 14, 2016 35 \item{Outputs_Cal}{(optional) [character] vector giving the outputs needed for the calibration \cr (e.g. c("Qsim")), the fewer outputs  Delaigue Olivier committed Apr 21, 2016 36  the faster the calibration}  Delaigue Olivier committed Oct 28, 2015 37   unknown committed Aug 18, 2017 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 committed Oct 28, 2015 39   unknown committed Jul 11, 2017 40 \item{RunSnowModule}{(deprecated) [boolean] option indicating whether CemaNeige should be activated. Please adapt \code{FUN_MOD} instead}  Delaigue Olivier committed Oct 28, 2015 41   unknown committed Jul 11, 2017 42   Delaigue Olivier committed Oct 28, 2015 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}  Delaigue Olivier committed Oct 17, 2018 47 48 \item{warnings}{(optional) [boolean] boolean indicating if the warning messages are shown, default = \code{TRUE}}  unknown committed Aug 18, 2017 49 \item{verbose}{(optional) [boolean] boolean indicating if the function is run in verbose mode or not, default = \code{TRUE}}  Delaigue Olivier committed Oct 28, 2015 50 }  unknown committed Aug 18, 2017 51 52   Delaigue Olivier committed Oct 28, 2015 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 committed Oct 28, 2015 64 }  unknown committed Aug 18, 2017 65 66   Delaigue Olivier committed Oct 28, 2015 67 \description{  unknown committed Aug 18, 2017 68 Creation of the RunOptions object required to the \code{RunModel*} functions.  Delaigue Olivier committed Oct 28, 2015 69 }  unknown committed Aug 18, 2017 70 71   Delaigue Olivier committed Oct 28, 2015 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 committed Oct 28, 2015 75   Delaigue Olivier committed Apr 01, 2019 76 ## ---- Initialisation options  Delaigue Olivier committed Oct 28, 2015 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 committed Oct 28, 2015 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}.  Delaigue Olivier committed Apr 14, 2016 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 committed Oct 28, 2015 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 committed Oct 28, 2015 90 91 92 93 94 } (2) Customisation of initialisation options: \itemize{  unknown committed Aug 18, 2017 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  unknown committed Aug 18, 2017 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  unknown committed Aug 18, 2017 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.  unknown committed Dec 05, 2017 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).  unknown committed Aug 18, 2017 108 }  Delaigue Olivier committed Oct 28, 2015 109 }  110   Delaigue Olivier committed Apr 01, 2019 111 ## ---- CemaNeige version  112 113  If \code{IsHyst = FALSE}, the original CemaNeige version from Valéry et al. (2014) is used. \cr  Delaigue Olivier committed Apr 01, 2019 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 committed Oct 28, 2015 115 }  unknown committed Aug 18, 2017 116 117   Delaigue Olivier committed Oct 28, 2015 118 \examples{  Delaigue Olivier committed Apr 14, 2016 119 library(airGR)  unknown committed Oct 25, 2016 120 121  ## loading catchment data  Delaigue Olivier committed Oct 28, 2015 122 123 124 data(L0123001) ## preparation of the InputsModel object  Delaigue Olivier committed Apr 14, 2016 125 126 InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR, Precip = BasinObs$P, PotEvap = BasinObs$E)  Delaigue Olivier committed Oct 28, 2015 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 committed Oct 28, 2015 131 132  ## preparation of the RunOptions object  Delaigue Olivier committed Apr 14, 2016 133 134 RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel, IndPeriod_Run = Ind_Run)  Delaigue Olivier committed Oct 28, 2015 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,  Delaigue Olivier committed Apr 14, 2016 140  FUN_MOD = RunModel_GR4J)  Delaigue Olivier committed Oct 28, 2015 141 142  ## results preview  unknown committed Jan 17, 2017 143 plot(OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])  Delaigue Olivier committed Oct 28, 2015 144 145  ## efficiency criterion: Nash-Sutcliffe Efficiency  Delaigue Olivier committed Apr 14, 2016 146 InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,  Delaigue Olivier committed Mar 28, 2019 147  RunOptions = RunOptions,  Delaigue Olivier committed Apr 01, 2019 148  Obs = BasinObs\$Qmm[Ind_Run])  Delaigue Olivier committed Apr 14, 2016 149 OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)  Delaigue Olivier committed Oct 28, 2015 150 }  unknown committed Aug 18, 2017 151 152   Delaigue Olivier committed Oct 28, 2015 153 \author{  154 Laurent Coron, Olivier Delaigue, Guillaume Thirel  Delaigue Olivier committed Oct 28, 2015 155 }  unknown committed Aug 18, 2017 156 157   Delaigue Olivier committed Oct 28, 2015 158 \seealso{  Delaigue Olivier committed Apr 01, 2019 159 160 \code{\link{RunModel}}, \code{\link{CreateInputsModel}}, \code{\link{CreateInputsCrit}}, \code{\link{CreateCalibOptions}}, \code{\link{CreateIniStates}}  Delaigue Olivier committed Oct 28, 2015 161 }