v1.0.10.7 add a warning message in CreateInputsCrit when the KGE (or KGE') is...

v1.0.10.7 add a warning message in CreateInputsCrit when the KGE (or KGE') is used with a log transfo on Q

DESCRIPTION

 Package: airGR
 Type: Package
 Title: Suite of GR Hydrological Models for Precipitation-Runoff Modelling
-Version: 1.0.10.6
-Date: 2018-05-22
+Version: 1.0.10.7
+Date: 2018-06-15
 Authors@R: c(
   person("Laurent", "Coron", role = c("aut", "trl")),
   person("Charles", "Perrin", role = c("aut", "ths")),

NEWS.rmd

@@ -14,7 +14,7 @@ output:
 
 
 
-### 1.0.10.6 Release Notes (2018-05-22) 
+### 1.0.10.7 Release Notes (2018-06-15) 
 
 
 ____________________________________________________________________________________

R/CreateInputsCrit.R

-CreateInputsCrit <-
-  function(FUN_CRIT,
-           InputsModel,
-           RunOptions,
-           Qobs,
-           BoolCrit = NULL,
-           transfo = "",
-           Ind_zeroes = NULL,
-           epsilon = NULL) {
-    ObjectClass <- NULL
-    
-    
-    ##check_FUN_CRIT
-    BOOL <- FALSE
+CreateInputsCrit <- function(FUN_CRIT,
+                             InputsModel,
+                             RunOptions,
+                             Qobs,
+                             BoolCrit = NULL,
+                             transfo = "",
+                             Ind_zeroes = NULL,
+                             epsilon = NULL,
+                             verbose = TRUE) {
+  
+  
+  ObjectClass <- NULL
+  
+  
+  ##check_FUN_CRIT
+  BOOL <- FALSE
     
     if (identical(FUN_CRIT, ErrorCrit_NSE) | identical(FUN_CRIT, ErrorCrit_KGE) |
         identical(FUN_CRIT, ErrorCrit_KGE2) | identical(FUN_CRIT, ErrorCrit_RMSE)) {
@@ -77,7 +79,7 @@ CreateInputsCrit <-
       stop("transfo must be a chosen among the following: '', 'sqrt', 'log' or 'inv' or 'sort' \n")
       return(NULL)
     }
-    if (transfo %in% c("", "sqrt", "log", "inv", "sort") == FALSE) {
+    if (! transfo %in% c("", "sqrt", "log", "inv", "sort")) {
       stop("transfo must be a chosen among the following: '', 'sqrt', 'log' or 'inv' or 'sort' \n")
       return(NULL)
     }
@@ -102,12 +104,22 @@ CreateInputsCrit <-
       epsilon = as.double(epsilon)
     }
     
+    if (transfo == "log" & verbose) {
+      warn_log_kge <- "we do not advise using the %s with a log transformation on Qobs (see the details part in the 'CreateInputsCrit' help)"
+      if (identical(FUN_CRIT, ErrorCrit_KGE)) {
+          warning(sprintf(warn_log_kge, "KGE"))
+        }
+      if (identical(FUN_CRIT, ErrorCrit_KGE2)) {
+          warning(sprintf(warn_log_kge, "KGE'"))
+      }
+    }
+    
     ##Create_InputsCrit
-    InputsCrit <- list(BoolCrit = BoolCrit,
-                       Qobs     = Qobs,
-                       transfo  = transfo,
+    InputsCrit <- list(BoolCrit   = BoolCrit,
+                       Qobs       = Qobs,
+                       transfo    = transfo,
                        Ind_zeroes = Ind_zeroes,
-                       epsilon = epsilon)
+                       epsilon    = epsilon)
     
     class(InputsCrit) <- c("InputsCrit", ObjectClass)
     

man/CreateInputsCrit.Rd

@@ -10,7 +10,7 @@
 
 \usage{
 CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions, Qobs, BoolCrit = NULL,
-  transfo = "", Ind_zeroes = NULL, epsilon = NULL)
+  transfo = "", Ind_zeroes = NULL, epsilon = NULL, verbose = TRUE)
 }
 
 
@@ -30,6 +30,8 @@ CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions, Qobs, BoolCrit = NULL,
 \item{Ind_zeroes}{(optional) [numeric] indices of the time steps where zeroes are observed}
 
 \item{epsilon}{(optional) [numeric] epsilon to add to all Qobs and Qsim if \emph{$Ind_zeroes} is not empty}
+
+\item{verbose}{(optional) [boolean] boolean indicating if the function is run in verbose mode or not, default = \code{TRUE}}
 }
 
 
@@ -52,7 +54,8 @@ Creation of the \emph{InputsCrit} object required to the \code{ErrorCrit*} funct
 
 \details{
 Users wanting to use \code{FUN_CRIT} functions that are not included in 
-the package must create their own InputsCrit object accordingly.
+the package must create their own InputsCrit object accordingly. \cr
+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 it is dependent on the discharge unit. See Santos et al. (in review) for more details and alternative solutions (see the reference below).
 }
 
 
@@ -119,6 +122,12 @@ OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsMode
 Laurent Coron
 }
 
+\references{
+Santos, L., Thirel, G. and Perrin, C. (in review), 
+      Technical note : Pitfalls in using log-transformed flows within the KGE criterion, 
+      Hydrology and Earth System Sciences Discussions, doi:10.5194/hess-2018-298.
+}
+
 
 \seealso{
 \code{\link{RunModel}}, \code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}}, \code{\link{CreateCalibOptions}}