CreateInputsCrit.Rd

\encoding{UTF-8}


\name{CreateInputsCrit}
\alias{CreateInputsCrit}


\title{Creation of the InputsCrit object required to the ErrorCrit functions}


\usage{
CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions, Qobs, BoolCrit = NULL,
  transfo = "", Ind_zeroes = NULL, epsilon = NULL, verbose = TRUE)
}


\arguments{
\item{FUN_CRIT}{[function] error criterion function (e.g. \code{\link{ErrorCrit_RMSE}}, \code{\link{ErrorCrit_NSE}})}

\item{InputsModel}{[object of class \emph{InputsModel}] see \code{\link{CreateInputsModel}} for details}

\item{RunOptions}{[object of class \emph{RunOptions}] see \code{\link{CreateRunOptions}} for details}

\item{Qobs}{[numeric] series of observed discharges [mm/time step]}

\item{BoolCrit}{(optional) [boolean] boolean giving the time steps to consider in the computation (all time steps are consider by default)}

\item{transfo}{(optional) [character] name of the transformation (e.g. \code{""}, \code{"sqrt"}, \code{"log"}, \code{"inv"}, \code{"sort"})}

\item{Ind_zeroes}{(deprecated) [numeric] indices of the time steps where zeroes are observed}

\item{epsilon}{(optional) [numeric] small value to add to all Qobs and Qsim (useful when \code{"log"} or \code{"inv"} transformations are used) [same unit as \code{Qobs}]}

\item{verbose}{(optional) [boolean] boolean indicating if the function is run in verbose mode or not, default = \code{TRUE}}
}


\value{
[list] object of class \emph{InputsCrit} containing the data required to evaluate the model outputs; it can include the following:
         \tabular{ll}{
         \emph{$BoolCrit  }  \tab   [boolean] boolean giving the time steps considered in the computation \cr
         \emph{$Qobs      }  \tab   [numeric] series of observed discharges [mm/time step] \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{Qobs}] \cr
         }
}


\description{
Creation of the \emph{InputsCrit} object required to the \code{ErrorCrit*} functions.
}


\details{
Users wanting to use \code{FUN_CRIT} functions that are not included in 
the package must create their own InputsCrit object accordingly. \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 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 below).
}


\examples{
library(airGR)

## loading catchment data
data(L0123001)

## preparation of the InputsModel object
InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR, 
                                 Precip = BasinObs$P, PotEvap = BasinObs$E)

## run period selection
Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y")=="01/01/1990"), 
               which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y")=="31/12/1999"))

## preparation of the RunOptions object
RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J,
                               InputsModel = InputsModel, IndPeriod_Run = Ind_Run)

## simulation
Param <- c(734.568, -0.840, 109.809, 1.971)
OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions, 
                         Param = Param, FUN = RunModel_GR4J)

## efficiency criterion: Nash-Sutcliffe Efficiency
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
                               RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)

## efficiency criterion: Nash-Sutcliffe Efficiency on log-transformed flows
transfo <- "log"
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
                               RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run],
                               transfo = transfo)
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)

## efficiency criterion: Nash-Sutcliffe Efficiency above a threshold (q75\%)
BoolCrit <- rep(TRUE, length(BasinObs$Qmm[Ind_Run])); 
BoolCrit[BasinObs$Qmm[Ind_Run]<quantile(BasinObs$Qmm[Ind_Run], 0.75, na.rm = TRUE)] <- FALSE
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
                               RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run],
                               BoolCrit = BoolCrit)
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)

## efficiency criterion: Kling-Gupta Efficiency
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel, 
                               RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
}


\author{
Laurent Coron, Olivier Delaigue, 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.
}


\seealso{
\code{\link{RunModel}}, \code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}}, \code{\link{CreateCalibOptions}}
}