v1.2.9.13 DOC: explanations clarified in CreateInputsCrit doc

DESCRIPTION

 Package: airGR
 Type: Package
 Title: Suite of GR Hydrological Models for Precipitation-Runoff Modelling
-Version: 1.2.9.12
+Version: 1.2.9.13
 Date: 2019-03-18
 Authors@R: c(
   person("Laurent", "Coron", role = c("aut", "trl"), comment = c(ORCID = "0000-0002-1503-6204")),

NEWS.rmd

@@ -13,7 +13,7 @@ output:
 
 
 
-### 1.2.9.12 Release Notes (2019-03-18) 
+### 1.2.9.13 Release Notes (2019-03-18) 
 
 
 

man/CreateInputsCrit.Rd

@@ -26,7 +26,7 @@ CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions,
 
 \item{Qobs}{(deprecated) [numeric (atomic or list)] series of observed discharges [mm/time step]}
 
-\item{obs}{[numeric (atomic or list)] series of observed variable (typically discharge [mm/time step])}
+\item{obs}{[numeric (atomic or list)] series of observed variable ([mm/time step] for discharge or SWE, [-] for SCA)}
 
 \item{varObs}{(optional) [character (atomic or list)] names of the observed variable (\code{"Q"} by default, or one of \code{"SCA"}, \code{"SWE"}])}
 
@@ -34,11 +34,11 @@ CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions,
 
 \item{transfo}{(optional) [character (atomic or list)] name of the transformation (e.g. \code{""}, \code{"sqrt"}, \code{"log"}, \code{"inv"}, \code{"sort"})}
 
-\item{weights}{(optional) [numeric (atomic or list)] vector of weights necessary to calculate a composite criterion (the same length as \code{FUN_CRIT}) giving the weights to use for elements of \code{FUN_CRIT} [-]}
+\item{weights}{(optional) [numeric (atomic or list)] vector of weights necessary to calculate a composite criterion (the same length as \code{FUN_CRIT}) giving the weights to use for elements of \code{FUN_CRIT} [-]. See details}
 
 \item{Ind_zeroes}{(deprecated) [numeric] indices of the time steps where zeroes are observed}
 
-\item{epsilon}{(optional) [numeric (atomic or list)] small value to add to all Qobs and Qsim (useful when \code{"log"} or \code{"inv"} transformations are used) [same unit as \code{obs}]}
+\item{epsilon}{(optional) [numeric (atomic or list)] small value to add to all observations and simulations when \code{"log"} or \code{"inv"} transformations are used [same unit as \code{obs}]. See details}
 
 \item{warnings}{(optional) [boolean] boolean indicating if the warning messages are shown, default = \code{TRUE}}
 
@@ -50,32 +50,34 @@ CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions,
 [list] object of class \emph{InputsCrit} containing the data required to evaluate the model outputs; it can include the following:
   \tabular{ll}{
     \emph{$FUN_CRIT  } \tab [function] error criterion function (e.g. \code{\link{ErrorCrit_RMSE}}, \code{\link{ErrorCrit_NSE}}) \cr
-    \emph{$obs       } \tab [numeric] series of observed variable (typically discharges [mm/time step]) \cr
-    \emph{$varObs    } \tab [character] names of the observed variable (\code{"Q"} by default]) \cr
+    \emph{$obs       } \tab [numeric] series of observed variable(s) ([mm/time step] for discharge or SWE, [-] for SCA) \cr
+    \emph{$varObs    } \tab [character] names of the observed variable(s) \cr
     \emph{$BoolCrit  } \tab [boolean] boolean giving the time steps considered in the computation \cr
     \emph{$transfo   } \tab [character] name of the transformation (e.g. \code{""}, \code{"sqrt"}, \code{"log"}, \code{"inv"}, \code{"sort"}) \cr
-    \emph{$epsilon   } \tab [numeric] small value to add to all Qobs and Qsim (useful when \code{"log"} or \code{"inv"} transformations are used) [same unit as \code{obs}] \cr
-    \emph{$weights   } \tab [numeric] vector of weights (the same length as x giving the weights to use for elements of \code{FUN_CRIT}) [-] \cr
+    \emph{$epsilon   } \tab [numeric] small value to add to all observations and simulations when \code{"log"} or \code{"inv"} transformations are used [same unit as \code{obs}] \cr
+    \emph{$weights   } \tab [numeric] vector (same length as \code{varObs}) giving the weights to use for elements of \code{FUN_CRIT} [-] \cr
   }
   
 When \code{weights = NULL}, \code{CreateInputsCrit} returns an object of class \emph{Single} that is  a list such as the one described above. \cr
-When \code{weights} contains at least one \code{NULL} value, \code{CreateInputsCrit} returns an object of class \emph{Multi} that is a list of lists such as the one we have just described above. The \code{\link{ErrorCrit}} function will then compute the different criteria prepared by \code{CreateInputsCrit}. 
-When \code{weights} is a list of more than 2 numerical values, \code{CreateInputsCrit} returns an object of class \emph{Compo} that is a list of lists such as the one described above. This object will be useful to compute composite criterion with the \code{\link{ErrorCrit}} function. \cr
-The other \code{ErrorCrit_*} functions (e.g. \code{\link{ErrorCrit_RMSE}}, \code{\link{ErrorCrit_NSE}}) can only use objects of class \emph{Single} (and not \emph{Multi} or \emph{Compo}) \cr
+When \code{weights} contains at least one \code{NULL} value and \code{obs} contains a list of observations, \code{CreateInputsCrit} returns an object of class \emph{Multi} that is a list of lists such as the one described above. The \code{\link{ErrorCrit}} function will then compute the different criteria prepared by \code{CreateInputsCrit}. \cr 
+When \code{weights} is a list of at least 2 numerical values, \code{CreateInputsCrit} returns an object of class \emph{Compo} that is a list of lists such as the one described above. This object will be useful to compute composite criterion with the \code{\link{ErrorCrit}} function. \cr
+To calculate composite or multiple criteria, it is necessary to use the \code{ErrorCrit} function. The other \code{ErrorCrit_*} functions (e.g. \code{\link{ErrorCrit_RMSE}}, \code{\link{ErrorCrit_NSE}}) can only use objects of class \emph{Single} (and not \emph{Multi} or \emph{Compo}). \cr
 }
 
 
 \description{
-Creation of the \code{InputsCrit} object required to the \code{ErrorCrit_*} functions. It can prepare a single object, a multiple object in order to compute many criteria or a complex object in order to compute a composite criterion.
+Creation of the \code{InputsCrit} object required to the \code{ErrorCrit_*} functions. This function is used to define whether the user wants to calculate a single criterion, multiple criteria in the same time, or a composite criterion, which averages several criteria. 
 }
 
 
 \details{
-Users wanting to use \code{FUN_CRIT} functions that are not included in the package must create their own InputsCrit object accordingly. \cr
+Users wanting to use \code{FUN_CRIT} functions that are not included in the package must create their own InputsCrit object accordingly. \cr \cr
+The epsilon value is useful when \code{"log"} or \code{"inv"} transformations are used (to avoid calculation of the inverse or of the logarithm of zero). The impact of this value and a recommendation about the epsilon value to use (usually one hundredth of average observation) are discussed in Pushpalatha et al. (2012) for NSE and in Santos et al. (2018) for KGE and KGE'. \cr \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 the criterion value is dependent on the discharge unit. See Santos et al. (2018) for more details and alternative solutions (see the references list below). \cr \cr
 Users can set the following arguments as atomic or list: \code{FUN_CRIT}, \code{obs}, \code{varObs}, \code{BoolCrit}, \code{transfo}, \code{weights}. If the list format is chosen, all the lists must have the same length. \cr
-The epsilon value is useful when \code{"log"} or \code{"inv"} transformations are used (to avoid division by zero). The effect of this value and recommendation about the epsilon value to use (usually one hundredth of average Qobs) are discussed in Pushpalatha et al. (2012) for NSE and in Santos et al. (2018) for KGE and KGE'. \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. (2018) for more details and alternative solutions (see the reference list below). \cr
-When weighted values are given, \code{\link{ErrorCrit}} will calculate a composite criterion, i.e. a weighted average of criteria using normalized weights values. \cr
+Calculation of a single criterion (e.g. NSE computed on discharge) is prepared by providing to \code{CreateInputsCrit} arguments atomics only. \cr
+Calculation of multiple criteria (e.g. NSE computed on discharge and RMSE computed on discharge) is prepared by providing to \code{CreateInputsCrit} arguments lists except for \code{weights} that must be set as \code{NULL}. \cr
+Calculation of a composite criterion (e.g. the average between NSE computed on dscharge and NSE computed on log of discharge) is prepared by providing to \code{CreateInputsCrit} arguments lists including \code{weights}. \cr
 \code{\link{ErrorCrit_RMSE}} cannot be used in a composite criterion since it is not a unitless value.
 }
 
@@ -111,7 +113,7 @@ InputsCritSingle <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE,
 str(InputsCritSingle)
 invisible(ErrorCrit(InputsCrit = InputsCritSingle, OutputsModel = OutputsModel))
 
-## 2 efficiency critera:  RMSE and the Nash-Sutcliffe Efficiency
+## 2 efficiency criteria: RMSE and Nash-Sutcliffe Efficiency
 InputsCritMulti <- CreateInputsCrit(FUN_CRIT = list(ErrorCrit_RMSE, ErrorCrit_NSE),
                                     InputsModel = InputsModel, RunOptions = RunOptions,
                                     obs = list(BasinObs$Qmm[Ind_Run], BasinObs$Qmm[Ind_Run]),
@@ -136,13 +138,14 @@ invisible(ErrorCrit(InputsCrit = InputsCritCompo, OutputsModel = OutputsModel))
 Olivier Delaigue, Laurent Coron, Guillaume Thirel
 }
 
+
 \references{
 Pushpalatha, R., Perrin, C., Le Moine, N. and Andréassian, V. (2012), 
       A review of efficiency criteria suitable for evaluating low-flow simulations, 
       Journal of Hydrology, 420-421: 171-182, doi:10.1016/j.jhydrol.2011.11.055. \cr
-Santos, L., Thirel, G. and Perrin, C. (2018), 
-      Technical note: Pitfalls in using log-transformed flows within the KGE criterion, 
-      Hydrology and Earth System Sciences Discussions, 22, 4583-4591, doi:10.5194/hess-2018-298.
+Santos, L., Thirel, G. and Perrin, C. (2018),
+      Technical note: Pitfalls in using log-transformed flows within the KGE criterion,
+      Hydrol. Earth Syst. Sci., 22, 4583-4591, doi:10.5194/hess-22-4583-2018.
 }