v1.2.10.0 NEW: add an IsHyst argument in CreatRunOptions to use hysteresis #5252

DESCRIPTION

 Package: airGR
 Type: Package
 Title: Suite of GR Hydrological Models for Precipitation-Runoff Modelling
-Version: 1.2.9.34
-Date: 2019-03-21
+Version: 1.2.10.0
+Date: 2019-03-22
 Authors@R: c(
   person("Laurent", "Coron", role = c("aut", "trl"), comment = c(ORCID = "0000-0002-1503-6204")),
   person("Charles", "Perrin", role = c("aut", "ths"), comment = c(ORCID = "0000-0001-8552-1881")),

NEWS.rmd

@@ -13,7 +13,7 @@ output:
 
 
 
-### 1.2.9.34 Release Notes (2019-03-21) 
+### 1.2.10.0 Release Notes (2019-03-22) 
 
 
 
@@ -45,6 +45,8 @@ output:
 
 - <code>CreateInputsCrit()</code> now returns a <code>idLayer</code> element to indicate which layer to use for SCA or SWE aggregation.
 
+- <code>CreateRunOptions()</code> now presents a <code>IsHyst</code> argument to give the possibility to use the hysteresis with CemaNeige. 
+
 - <code>CreateRunOptions()</code> now presents a <code>warnings</code> argument to replace the verbose action (the <code>verbose</code> argument is kept to print messages).
 
 

R/CreateRunOptions.R

 CreateRunOptions <- function(FUN_MOD, InputsModel, IndPeriod_WarmUp = NULL, IndPeriod_Run,
                              IniStates = NULL, IniResLevels = NULL, 
                              Outputs_Cal = NULL, Outputs_Sim = "all",
-                             RunSnowModule, MeanAnSolidPrecip = NULL,
+                             RunSnowModule, MeanAnSolidPrecip = NULL, IsHyst = FALSE, 
                              warnings = TRUE, verbose = TRUE) {
   
   if (!missing(RunSnowModule)) {
     warning("argument 'RunSnowModule' is deprecated; please adapt 'FUN_MOD' instead.", call. = FALSE)
   }
-  
+  if (!is.logical(IsHyst) | length(IsHyst) != 1L) {
+    stop("'IsHyst' must be a 'logical' of length 1")
+  }
   ObjectClass <- NULL
   
   FUN_MOD <- match.fun(FUN_MOD)
@@ -38,6 +40,9 @@ CreateRunOptions <- function(FUN_MOD, InputsModel, IndPeriod_WarmUp = NULL, IndP
     ObjectClass <- c(ObjectClass, "GR", "CemaNeige", "daily")
     BOOL <- TRUE
   }
+  if (IsHyst) {
+    ObjectClass <- c(ObjectClass, "hysteresis")
+  }
   if (!BOOL) {
     stop("incorrect 'FUN_MOD' for use in 'CreateRunOptions'")
   }

man/CreateRunOptions.Rd

@@ -14,6 +14,7 @@ CreateRunOptions(FUN_MOD, InputsModel,
   IniStates = NULL, IniResLevels = NULL,
   Outputs_Cal = NULL, Outputs_Sim = "all",
   RunSnowModule, MeanAnSolidPrecip = NULL,
+  IsHyst = FALSE,
   warnings = TRUE, verbose = TRUE)
 }
 
@@ -41,6 +42,8 @@ CreateRunOptions(FUN_MOD, InputsModel,
 	
 \item{MeanAnSolidPrecip}{(optional) [numeric] vector giving the annual mean of average solid precipitation for each layer (computed from InputsModel if not defined) [mm/y]}
 
+\item{IsHyst}{[boolean] boolean indicating if the hysteresis version of CemaNeige is used. See details}
+
 \item{warnings}{(optional) [boolean]  boolean indicating if the warning messages are shown, default = \code{TRUE}}
 
 \item{verbose}{(optional) [boolean] boolean indicating if the function is run in verbose mode or not, default = \code{TRUE}}
@@ -104,6 +107,12 @@ However, it is also possible to perform a long-term initialisation if other indi
 \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).
 }
 }
+
+##### CemaNeige version #####
+
+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 \cr
+
 }