v1.0.6.5 ErrorCrit_KGE and ErrorCrit_KGE2 now return clean subcriteria names #4538

DESCRIPTION

 Package: airGR
 Type: Package
 Title: Suite of GR Hydrological Models for Precipitation-Runoff Modelling
-Version: 1.0.6.4
+Version: 1.0.6.6
 Date: 2017-04-05
 Authors@R: c(
   person("Laurent", "Coron", role = c("aut", "trl")),

R/ErrorCrit_KGE.R

@@ -48,16 +48,18 @@ ErrorCrit_KGE <- function(InputsCrit,OutputsModel, warnings = TRUE, verbose = TR
   ##Other_variables_preparation
   meanVarObs <- mean(VarObs[!TS_ignore]);
   meanVarSim <- mean(VarSim[!TS_ignore]);
-  iCrit           <- 0;
-  SubCritNames    <- NULL;
-  SubCritValues   <- NULL;
+  iCrit           <- 0
+  SubCritPrint    <- NULL
+  SubCritNames    <- NULL
+  SubCritValues   <- NULL
 
 
 
 ##SubErrorCrit_____KGE_rPearson__________________
   iCrit <- iCrit+1;
-  SubCritNames[iCrit]  <- paste(CritName," cor(sim, obs, \"pearson\") =", sep = "")
+  SubCritPrint[iCrit]  <- paste(CritName," cor(sim, obs, \"pearson\") =", sep = "")
   SubCritValues[iCrit] <- NA;
+  SubCritNames[iCrit]  <- "r"
   Numer <- sum( (VarObs[!TS_ignore]-meanVarObs)*(VarSim[!TS_ignore]-meanVarSim) );
   Deno1 <- sqrt( sum((VarObs[!TS_ignore]-meanVarObs)^2) );
   Deno2 <- sqrt( sum((VarSim[!TS_ignore]-meanVarSim)^2) );
@@ -68,8 +70,9 @@ ErrorCrit_KGE <- function(InputsCrit,OutputsModel, warnings = TRUE, verbose = TR
 
 ##SubErrorCrit_____KGE_alpha_____________________
   iCrit <- iCrit+1;
-  SubCritNames[iCrit]  <-  paste(CritName," sd(sim)/sd(obs)          =", sep = "")
+  SubCritPrint[iCrit]  <-  paste(CritName," sd(sim)/sd(obs)          =", sep = "")
   SubCritValues[iCrit] <- NA;
+  SubCritNames[iCrit]  <- "alpha"
   Numer <- sd(VarSim[!TS_ignore]); 
   Denom <- sd(VarObs[!TS_ignore]); 
   if(Numer==0 & Denom==0){ Crit <- 1; } else { Crit <- Numer/Denom ; }
@@ -78,8 +81,9 @@ ErrorCrit_KGE <- function(InputsCrit,OutputsModel, warnings = TRUE, verbose = TR
 
 ##SubErrorCrit_____KGE_beta______________________  
   iCrit <- iCrit+1;
-  SubCritNames[iCrit]  <-  paste(CritName," mean(sim)/mean(obs)      =", sep = "")
+  SubCritPrint[iCrit]  <-  paste(CritName," mean(sim)/mean(obs)      =", sep = "")
   SubCritValues[iCrit] <- NA;
+  SubCritNames[iCrit]  <- "beta"
   if(meanVarSim==0 & meanVarObs==0){ Crit <- 1; } else { Crit <- meanVarSim/meanVarObs ; }
   if(is.numeric(Crit) & is.finite(Crit)){ SubCritValues[iCrit] <- Crit; }
   
@@ -93,7 +97,7 @@ ErrorCrit_KGE <- function(InputsCrit,OutputsModel, warnings = TRUE, verbose = TR
 ##Verbose______________________________________
   if(verbose) {
     message("Crit. ", CritName, " = ", sprintf("%.4f", CritValue))
-    message(paste("\tSubCrit.", SubCritNames, sprintf("%.4f", SubCritValues), "\n", sep = " "))
+    message(paste("\tSubCrit.", SubCritPrint, sprintf("%.4f", SubCritValues), "\n", sep = " "))
   }
   
 

R/ErrorCrit_KGE2.R

@@ -48,14 +48,16 @@ ErrorCrit_KGE2 <- function(InputsCrit,OutputsModel, warnings = TRUE, verbose = T
   ##Other_variables_preparation
   meanVarObs <- mean(VarObs[!TS_ignore]);
   meanVarSim <- mean(VarSim[!TS_ignore]);
-  iCrit           <- 0;
-  SubCritNames    <- NULL;
-  SubCritValues   <- NULL;
+  iCrit           <- 0
+  SubCritPrint    <- NULL
+  SubCritNames    <- NULL
+  SubCritValues   <- NULL
 
 
 ##SubErrorCrit_____KGE_rPearson__________________
   iCrit <- iCrit+1;
-  SubCritNames[iCrit]  <- paste(CritName," cor(sim, obs, \"pearson\") =", sep = "")
+  SubCritPrint[iCrit]  <- paste(CritName," cor(sim, obs, \"pearson\") =", sep = "")
+  SubCritNames[iCrit]  <- "r"
   SubCritValues[iCrit] <- NA;
   Numer <- sum( (VarObs[!TS_ignore]-meanVarObs)*(VarSim[!TS_ignore]-meanVarSim) );
   Deno1 <- sqrt( sum((VarObs[!TS_ignore]-meanVarObs)^2) );
@@ -67,7 +69,8 @@ ErrorCrit_KGE2 <- function(InputsCrit,OutputsModel, warnings = TRUE, verbose = T
 
 ##SubErrorCrit_____KGE_gamma______________________
   iCrit <- iCrit+1;
-  SubCritNames[iCrit]  <-  paste(CritName," cv(sim)/cv(obs)          =", sep = "")
+  SubCritPrint[iCrit]  <-  paste(CritName," cv(sim)/cv(obs)          =", sep = "")
+  SubCritNames[iCrit]  <- "gamma"
   SubCritValues[iCrit] <- NA;
   if(meanVarSim==0){ if(sd(VarSim[!TS_ignore])==0){ CVsim <- 1; } else { CVsim <- 99999; } } else { CVsim <- sd(VarSim[!TS_ignore])/meanVarSim; }
   if(meanVarObs==0){ if(sd(VarObs[!TS_ignore])==0){ CVobs <- 1; } else { CVobs <- 99999; } } else { CVobs <- sd(VarObs[!TS_ignore])/meanVarObs; }
@@ -77,7 +80,8 @@ ErrorCrit_KGE2 <- function(InputsCrit,OutputsModel, warnings = TRUE, verbose = T
 
 ##SubErrorCrit_____KGE_beta______________________
   iCrit <- iCrit+1;
-  SubCritNames[iCrit]  <-  paste(CritName," mean(sim)/mean(obs)      =", sep = "")
+  SubCritPrint[iCrit]  <-  paste(CritName," mean(sim)/mean(obs)      =", sep = "")
+  SubCritNames[iCrit]  <- "beta"
   SubCritValues[iCrit] <- NA;
   if(meanVarSim==0 & meanVarObs==0){ Crit <- 1; } else { Crit <- meanVarSim/meanVarObs ; }
   if(is.numeric(Crit) & is.finite(Crit)){ SubCritValues[iCrit] <- Crit; }
@@ -92,7 +96,7 @@ ErrorCrit_KGE2 <- function(InputsCrit,OutputsModel, warnings = TRUE, verbose = T
 ##Verbose______________________________________
   if(verbose) {
     message("Crit. ", CritName, " = ", sprintf("%.4f", CritValue))
-    message(paste("\tSubCrit.", SubCritNames, sprintf("%.4f", SubCritValues), "\n", sep = " "))
+    message(paste("\tSubCrit.", SubCritPrint, sprintf("%.4f", SubCritValues), "\n", sep = " "))
   }
   
 

man/ErrorCrit_KGE.Rd

 \encoding{UTF-8}
+
 \name{ErrorCrit_KGE}
 \alias{ErrorCrit_KGE}
+
 \title{Error criterion based on the KGE formula}
+
 \usage{
 ErrorCrit_KGE(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
 }
+
 \arguments{
 \item{InputsCrit}{[object of class \emph{InputsCrit}] see \code{\link{CreateInputsCrit}} for details}
 
@@ -26,25 +30,37 @@ ErrorCrit_KGE(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
          \emph{$Ind_notcomputed}   \tab   [numeric] indices of the time steps where InputsCrit$BoolCrit=FALSE or no data is available \cr
          }
 }
+
 \description{
 Function which computes an error criterion based on the KGE formula proposed by Gupta et al. (2009).
 }
+
 \details{
 In addition to the criterion value, the function outputs include a multiplier (-1 or +1) which allows 
-the use of the function for model calibration: the product CritValue*Multiplier is the criterion to be minimised (Multiplier=-1 for KGE).
+the use of the function for model calibration: the product CritValue*Multiplier is the criterion to be minimised (Multiplier=-1 for KGE).\cr\cr
+The KGE formula is
+\deqn{KGE = 1 - \sqrt(r - 1)^2 + (\alpha - 1)^2 + (\beta - 1)^2}{KGE = 1 - sqrt((r - 1)² + (\alpha - 1)² + (\beta - 1)²)}
+with the following sub-criteria:
+\deqn{r = the linear correlation coefficient between Q_s and Q_o}{r = the linear correlation coefficient between Q[s] and Q[o]}
+\deqn{\alpha = \frac{\sigma_s}{\sigma_o}}{\alpha = \sigma[s] / \sigma[o]}
+\deqn{\beta = \frac{\mu_s}{\mu_o}}{\beta = \mu[s] / \mu[o]}
 }
+
 \examples{
 ## see example of the ErrorCrit function
 }
+
 \author{
-Laurent Coron (June 2014)
+Laurent Coron
 }
+
 \references{
 Gupta, H. V., Kling, H., Yilmaz, K. K. and Martinez, G. F. (2009), 
       Decomposition of the mean squared error and NSE performance criteria: Implications
       for improving hydrological modelling, Journal of Hydrology, 377(1-2), 80-91, doi:10.1016/j.jhydrol.2009.08.003. \cr
 }
+
 \seealso{
-\code{\link{ErrorCrit_RMSE}}, \code{\link{ErrorCrit_NSE}}, \code{\link{ErrorCrit_KGE2}}
+\code{\link{ErrorCrit}}, \code{\link{ErrorCrit_RMSE}}, \code{\link{ErrorCrit_NSE}}, \code{\link{ErrorCrit_KGE2}}
 }
 

man/ErrorCrit_KGE2.Rd

 \encoding{UTF-8}
+
 \name{ErrorCrit_KGE2}
 \alias{ErrorCrit_KGE2}
+
 \title{Error criterion based on the KGE' formula}
+
 \usage{
 ErrorCrit_KGE2(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
 }
+
 \arguments{
 \item{InputsCrit}{[object of class \emph{InputsCrit}] see \code{\link{CreateInputsCrit}} for details}
 
@@ -26,19 +30,30 @@ ErrorCrit_KGE2(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
          \emph{$Ind_notcomputed}   \tab   [numeric] indices of the time steps where InputsCrit$BoolCrit=FALSE or no data is available \cr
          }
 }
+
 \description{
 Function which computes an error criterion based on the KGE' formula proposed by Kling et al. (2012).
 }
+
 \details{
 In addition to the criterion value, the function outputs include a multiplier (-1 or +1) which allows 
-the use of the function for model calibration: the product CritValue*Multiplier is the criterion to be minimised (Multiplier=-1 for KGE2).
+the use of the function for model calibration: the product CritValue*Multiplier is the criterion to be minimised (Multiplier=-1 for KGE2).\cr\cr
+The KGE' formula is
+\deqn{KGE' = 1 - \sqrt{(r - 1)^2 + (\gamma - 1)^2 + (\beta - 1)^2}}{KGE' = 1 - sqrt((r - 1)² + (\gamma - 1)² + (\beta - 1)²)}
+with the following sub-criteria:
+\deqn{r = the linear correlation coefficient between Q_s and Q_o}{r = is the linear correlation coefficient between Q[s] and Q[o]}
+\deqn{\alpha = \frac{CV_s}{CV_o}}{\alpha = CV[s] / CV[o]}
+\deqn{\beta = \frac{\mu_s}{\mu_o}}{\beta = \mu[s] / \mu[o]}
 }
+
 \examples{
 ## see example of the ErrorCrit function
 }
+
 \author{
-Laurent Coron (June 2014)
+Laurent Coron
 }
+
 \references{
 Gupta, H. V., Kling, H., Yilmaz, K. K. and Martinez, G. F. (2009), 
       Decomposition of the mean squared error and NSE performance criteria: Implications
@@ -47,7 +62,8 @@ Gupta, H. V., Kling, H., Yilmaz, K. K. and Martinez, G. F. (2009),
       Runoff conditions in the upper Danube basin under an ensemble of climate change scenarios,
       Journal of Hydrology, 424-425, 264-277, doi:10.1016/j.jhydrol.2012.01.011.
 }
+
 \seealso{
-\code{\link{ErrorCrit_RMSE}}, \code{\link{ErrorCrit_NSE}}, \code{\link{ErrorCrit_KGE}}
+\code{\link{ErrorCrit}}, \code{\link{ErrorCrit_RMSE}}, \code{\link{ErrorCrit_NSE}}, \code{\link{ErrorCrit_KGE}}
 }