CreateInputsCrit.Rd 5.83 KB
Newer Older
Delaigue Olivier's avatar
Delaigue Olivier committed
1
\encoding{UTF-8}
2
3


Delaigue Olivier's avatar
Delaigue Olivier committed
4
5
\name{CreateInputsCrit}
\alias{CreateInputsCrit}
6
7


Delaigue Olivier's avatar
Delaigue Olivier committed
8
\title{Creation of the InputsCrit object required to the ErrorCrit functions}
9
10


Delaigue Olivier's avatar
Delaigue Olivier committed
11
12
\usage{
CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions, Qobs, BoolCrit = NULL,
13
  transfo = "", Ind_zeroes = NULL, epsilon = NULL, verbose = TRUE)
Delaigue Olivier's avatar
Delaigue Olivier committed
14
}
15
16


Delaigue Olivier's avatar
Delaigue Olivier committed
17
18
19
20
21
22
23
\arguments{
\item{FUN_CRIT}{[function] error criterion function (e.g. ErrorCrit_RMSE, 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}

24
\item{Qobs}{[numeric] series of observed discharges [mm/time step]}
Delaigue Olivier's avatar
Delaigue Olivier committed
25
26
27

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

28
\item{transfo}{(optional) [character] name of the transformation (e.g. \code{""}, \code{"sqrt"}, \code{"log"}, \code{"inv"}, \code{"sort"})}
Delaigue Olivier's avatar
Delaigue Olivier committed
29

30
\item{Ind_zeroes}{(optional) [numeric] indices of the time steps where zeroes are observed}
Delaigue Olivier's avatar
Delaigue Olivier committed
31
32

\item{epsilon}{(optional) [numeric] epsilon to add to all Qobs and Qsim if \emph{$Ind_zeroes} is not empty}
33
34

\item{verbose}{(optional) [boolean] boolean indicating if the function is run in verbose mode or not, default = \code{TRUE}}
Delaigue Olivier's avatar
Delaigue Olivier committed
35
}
36
37


Delaigue Olivier's avatar
Delaigue Olivier committed
38
39
40
\value{
[list] object of class \emph{InputsCrit} containing the data required to evaluate the model outputs; it can include the following:
         \tabular{ll}{
41
42
         \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
Delaigue Olivier's avatar
Delaigue Olivier committed
43
         \emph{$transfo   }  \tab   [character] name of the transformation (e.g. "", "sqrt", "log", "inv", "sort") \cr
44
         \emph{$Ind_zeroes}  \tab   [numeric] indices of the time steps where zeroes are observed \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
45
46
47
         \emph{$epsilon   }  \tab   [numeric] epsilon to add to all Qobs and Qsim if \emph{$Ind_zeroes} is not empty \cr
         }
}
48
49


Delaigue Olivier's avatar
Delaigue Olivier committed
50
\description{
51
Creation of the \emph{InputsCrit} object required to the \code{ErrorCrit*} functions.
Delaigue Olivier's avatar
Delaigue Olivier committed
52
}
53
54


Delaigue Olivier's avatar
Delaigue Olivier committed
55
\details{
56
Users wanting to use \code{FUN_CRIT} functions that are not included in 
57
58
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).
Delaigue Olivier's avatar
Delaigue Olivier committed
59
}
60
61


Delaigue Olivier's avatar
Delaigue Olivier committed
62
\examples{
63
library(airGR)
unknown's avatar
unknown committed
64
65

## loading catchment data
Delaigue Olivier's avatar
Delaigue Olivier committed
66
67
68
data(L0123001)

## preparation of the InputsModel object
69
70
InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR, 
                                 Precip = BasinObs$P, PotEvap = BasinObs$E)
Delaigue Olivier's avatar
Delaigue Olivier committed
71
72

## run period selection
73
74
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"))
Delaigue Olivier's avatar
Delaigue Olivier committed
75
76

## preparation of the RunOptions object
77
78
RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J,
                               InputsModel = InputsModel, IndPeriod_Run = Ind_Run)
Delaigue Olivier's avatar
Delaigue Olivier committed
79
80

## simulation
81
82
83
Param <- c(734.568, -0.840, 109.809, 1.971)
OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions, 
                         Param = Param, FUN = RunModel_GR4J)
Delaigue Olivier's avatar
Delaigue Olivier committed
84
85

## efficiency criterion: Nash-Sutcliffe Efficiency
86
87
88
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
                               RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
Delaigue Olivier's avatar
Delaigue Olivier committed
89
90
91

## efficiency criterion: Nash-Sutcliffe Efficiency on log-transformed flows
transfo <- "log"
92
93
94
95
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
                               RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run],
                               transfo = transfo)
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
Delaigue Olivier's avatar
Delaigue Olivier committed
96
97

## efficiency criterion: Nash-Sutcliffe Efficiency above a threshold (q75\%)
98
99
100
101
102
103
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)
Delaigue Olivier's avatar
Delaigue Olivier committed
104
105

## efficiency criterion: Kling-Gupta Efficiency
106
107
108
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel, 
                               RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
Delaigue Olivier's avatar
Delaigue Olivier committed
109

110
## efficiency criterion: Kling-Gupta Efficiency below a threshold (q10\%) on log-transformed flows
Delaigue Olivier's avatar
Delaigue Olivier committed
111
transfo  <- "log"
112
113
114
115
116
117
BoolCrit <- rep(TRUE, length(BasinObs$Qmm[Ind_Run])); 
BoolCrit[BasinObs$Qmm[Ind_Run]>quantile(BasinObs$Qmm[Ind_Run], 0.10, na.rm = TRUE)] <- FALSE
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE,
                               InputsModel = InputsModel,RunOptions = RunOptions, 
                               Qobs = BasinObs$Qmm[Ind_Run], BoolCrit = BoolCrit, transfo = transfo)
OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
Delaigue Olivier's avatar
Delaigue Olivier committed
118
}
119
120


Delaigue Olivier's avatar
Delaigue Olivier committed
121
\author{
122
Laurent Coron, Olivier Delaigue, Guillaume Thirel
Delaigue Olivier's avatar
Delaigue Olivier committed
123
}
124

125
126
127
128
129
130
\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.
}

131

Delaigue Olivier's avatar
Delaigue Olivier committed
132
133
134
135
\seealso{
\code{\link{RunModel}}, \code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}}, \code{\link{CreateCalibOptions}}
}