Commit 6e4a2c89 authored by Delaigue Olivier's avatar Delaigue Olivier
Browse files

Révision générale de la documentation #4109

parent 23af6c18
......@@ -8,15 +8,15 @@
\format{Data frame named 'BasinObs' containing
\itemize{
\item one POSIXlt vector: time series dates in the POSIXlt format
\item five numeric vectors: time series of catchment average precipitation [mm], catchment average air temperature [degC], catchment average potential evapotranspiration [mm], outlet discharge [l/s], outlet discharge [mm]
\item five numeric vectors: time series of catchment average precipitation [mm/time step], catchment average air temperature [degC], catchment average potential evapotranspiration [mm/time step], outlet discharge [l/s], outlet discharge [mm/time step]
}}
\description{
R-object containing the times series of precipitation, temperature, potential evapotranspiration and discharges. \cr
Times series for L0123001 or L0123002 are at the daily time-step for use with daily models such as GR4J, GR5J, GR6J, CemaNeigeGR4J, CemaNeigeGR5J and CemaNeigeGR6J.
Times series for L0123003 are at the hourly time-step for use with hourly models such as GR4H.
Times series for L0123001 or L0123002 are at the daily time step for use with daily models such as GR4J, GR5J, GR6J, CemaNeigeGR4J, CemaNeigeGR5J and CemaNeigeGR6J.
Times series for L0123003 are at the hourly time step for use with hourly models such as GR4H.
}
\examples{
require(airGR)
library(airGR)
data(L0123001)
str(BasinObs)
}
......
......@@ -3,10 +3,10 @@
\encoding{UTF-8}
\name{Calibration}
\alias{Calibration}
\title{Calibration algorithm which minimises an error criterion on the model outputs using the provided functions}
\title{Calibration algorithm which optimises the error criterion selected as objective function using the provided functions}
\usage{
Calibration(InputsModel, RunOptions, InputsCrit, CalibOptions, FUN_MOD,
FUN_CRIT, FUN_CALIB = Calibration_HBAN, FUN_TRANSFO = NULL,
FUN_CRIT, FUN_CALIB = Calibration_Michel, FUN_TRANSFO = NULL,
quiet = FALSE)
}
\arguments{
......@@ -22,65 +22,69 @@ Calibration(InputsModel, RunOptions, InputsCrit, CalibOptions, FUN_MOD,
\item{FUN_CRIT}{[function] error criterion function (e.g. ErrorCrit_RMSE, ErrorCrit_NSE)}
\item{FUN_CALIB}{(optional) [function] calibration algorithm function (e.g. Calibration_HBAN, Calibration_optim), default=Calibration_HBAN}
\item{FUN_CALIB}{(optional) [function] calibration algorithm function (e.g. Calibration_Michel, Calibration_optim), default=Calibration_Michel}
\item{FUN_TRANSFO}{(optional) [function] model parameters transformation function, if the FUN_MOD used is native in the package FUN_TRANSFO is automatically defined}
\item{quiet}{(optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE}
}
\value{
[list] see \code{\link{Calibration_HBAN}} or \code{\link{Calibration_optim}}
[list] see \code{\link{Calibration_Michel}} or \code{\link{Calibration_optim}}
}
\description{
Calibration algorithm which minimises the error criterion using the provided functions. \cr
Calibration algorithm which optimises the error criterion selected as objective function using the provided functions. \cr
}
\examples{
## load of catchment data
require(airGR)
## loading catchment data
library(airGR)
data(L0123001)
## preparation of InputsModel object
InputsModel <- CreateInputsModel(FUN_MOD=RunModel_GR4J,DatesR=BasinObs$DatesR,
Precip=BasinObs$P,PotEvap=BasinObs$E)
InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR,
Precip = BasinObs$P, PotEvap = BasinObs$E)
## calibration period selection
Ind_Run <- seq(which(format(BasinObs$DatesR,format="\%d/\%m/\%Y \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR,format="\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
## preparation of RunOptions object
RunOptions <- CreateRunOptions(FUN_MOD=RunModel_GR4J,InputsModel=InputsModel,IndPeriod_Run=Ind_Run)
RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J,
InputsModel = InputsModel, IndPeriod_Run = Ind_Run)
## calibration criterion: preparation of the InputsCrit object
InputsCrit <- CreateInputsCrit(FUN_CRIT=ErrorCrit_NSE,InputsModel=InputsModel,
RunOptions=RunOptions,Qobs=BasinObs$Qmm[Ind_Run])
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
## preparation of CalibOptions object
CalibOptions <- CreateCalibOptions(FUN_MOD=RunModel_GR4J,FUN_CALIB=Calibration_HBAN)
CalibOptions <- CreateCalibOptions(FUN_MOD = RunModel_GR4J, FUN_CALIB = Calibration_Michel)
## calibration
OutputsCalib <- Calibration(InputsModel=InputsModel,RunOptions=RunOptions,InputsCrit=InputsCrit,
CalibOptions=CalibOptions,FUN_MOD=RunModel_GR4J,FUN_CRIT=ErrorCrit_NSE,
FUN_CALIB=Calibration_HBAN)
OutputsCalib <- Calibration(InputsModel = InputsModel, RunOptions = RunOptions,
InputsCrit = InputsCrit, CalibOptions = CalibOptions,
FUN_MOD = RunModel_GR4J, FUN_CRIT = ErrorCrit_NSE,
FUN_CALIB = Calibration_Michel)
## simulation
Param <- OutputsCalib$ParamFinalR
OutputsModel <- RunModel(InputsModel=InputsModel,RunOptions=RunOptions,
Param=Param,FUN=RunModel_GR4J)
OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions,
Param = Param, FUN = RunModel_GR4J)
## results preview
plot_OutputsModel(OutputsModel=OutputsModel,Qobs=BasinObs$Qmm[Ind_Run])
plot_OutputsModel(OutputsModel = OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ",
round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ",
round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
}
......@@ -88,7 +92,7 @@ cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\
Laurent Coron (June 2014)
}
\seealso{
\code{\link{Calibration_HBAN}}, \code{\link{Calibration_optim}},
\code{\link{Calibration_Michel}}, \code{\link{Calibration_optim}},
\code{\link{RunModel}}, \code{\link{ErrorCrit}}, \code{\link{TransfoParam}},
\code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}},
\code{\link{CreateInputsCrit}}, \code{\link{CreateCalibOptions}}.
......
......@@ -3,7 +3,7 @@
\encoding{UTF-8}
\name{Calibration_optim}
\alias{Calibration_optim}
\title{Calibration algorithm which minimises the error criterion using the stats::optim function}
\title{Calibration algorithm which optimises the error criterion selected as objective function using the stats::optim function}
\usage{
Calibration_optim(InputsModel, RunOptions, InputsCrit, CalibOptions, FUN_MOD,
FUN_CRIT, FUN_TRANSFO = NULL, quiet = FALSE)
......@@ -21,7 +21,7 @@ Calibration_optim(InputsModel, RunOptions, InputsCrit, CalibOptions, FUN_MOD,
\item{FUN_CRIT}{[function] error criterion function (e.g. ErrorCrit_RMSE, ErrorCrit_NSE)}
\item{FUN_TRANSFO}{(optional) [function] model parameters transformation function, if the FUN_MOD used is native in the package FUN_TRANSFO is automatically defined}
\item{FUN_TRANSFO}{(optional) [function] model parameters transformation function, if the FUN_MOD used is native in the package, FUN_TRANSFO is automatically defined}
\item{quiet}{(optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE}
}
......@@ -29,16 +29,16 @@ Calibration_optim(InputsModel, RunOptions, InputsCrit, CalibOptions, FUN_MOD,
[list] list containing the function outputs organised as follows:
\tabular{ll}{
\emph{$ParamFinalR } \tab [numeric] parameter set obtained at the end of the calibration \cr
\emph{$CritFinal } \tab [numeric] error criterion obtained at the end of the calibration \cr
\emph{$CritFinal } \tab [numeric] error criterion selected as objective function obtained at the end of the calibration \cr
\emph{$Nruns } \tab [numeric] number of model runs done during the calibration \cr
\emph{$CritName } \tab [character] name of the calibration criterion \cr
\emph{$CritName } \tab [character] name of the calibration criterion selected as objective function \cr
\emph{$CritBestValue} \tab [numeric] theoretical best criterion value \cr
}
}
\description{
Calibration algorithm which minimises the error criterion. \cr
Calibration algorithm which optimises the error criterion selected as objective function. \cr
\cr
The algorithm is based on the "optim" function from the "stats" R-package
The algorithm is based on the \code{\link{optim}} function from the "stats" R-package
(using method="L-BFGS-B", i.e. a local optimization quasi-Newton method).
}
\details{
......@@ -46,57 +46,62 @@ To optimise the exploration of the parameter space, transformation functions are
the model parameters. This is done using the TransfoParam functions.
}
\examples{
## load of catchment data
require(airGR)
## loading catchment data
library(airGR)
data(L0123001)
## preparation of InputsModel object
InputsModel <- CreateInputsModel(FUN_MOD=RunModel_GR4J,DatesR=BasinObs$DatesR,
Precip=BasinObs$P,PotEvap=BasinObs$E)
InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR,
Precip = BasinObs$P, PotEvap = BasinObs$E)
## calibration period selection
Ind_Run <- seq(which(format(BasinObs$DatesR,format="\%d/\%m/\%Y \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR,format="\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR, format="\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
## preparation of RunOptions object
RunOptions <- CreateRunOptions(FUN_MOD=RunModel_GR4J,InputsModel=InputsModel,IndPeriod_Run=Ind_Run)
RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J,
InputsModel = InputsModel, IndPeriod_Run = Ind_Run)
## calibration criterion: preparation of the InputsCrit object
InputsCrit <- CreateInputsCrit(FUN_CRIT=ErrorCrit_NSE,InputsModel=InputsModel,
RunOptions=RunOptions,Qobs=BasinObs$Qmm[Ind_Run])
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
## preparation of CalibOptions object
CalibOptions <- CreateCalibOptions(FUN_MOD=RunModel_GR4J,FUN_CALIB=Calibration_optim)
CalibOptions <- CreateCalibOptions(FUN_MOD = RunModel_GR4J,
FUN_CALIB = Calibration_optim)
## calibration
OutputsCalib <- Calibration_optim(InputsModel=InputsModel,RunOptions=RunOptions,
InputsCrit=InputsCrit,CalibOptions=CalibOptions,
FUN_MOD=RunModel_GR4J,FUN_CRIT=ErrorCrit_NSE)
OutputsCalib <- Calibration_optim(InputsModel = InputsModel, RunOptions = RunOptions,
InputsCrit = InputsCrit, CalibOptions = CalibOptions,
FUN_MOD = RunModel_GR4J, FUN_CRIT = ErrorCrit_NSE)
## simulation
Param <- OutputsCalib$ParamFinalR
OutputsModel <- RunModel_GR4J(InputsModel=InputsModel,RunOptions=RunOptions,Param=Param)
OutputsModel <- RunModel_GR4J(InputsModel = InputsModel,
RunOptions = RunOptions, Param = Param)
## results preview
plot_OutputsModel(OutputsModel=OutputsModel,Qobs=BasinObs$Qmm[Ind_Run])
plot_OutputsModel(OutputsModel = OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ",
round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ",
round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
}
\author{
Laurent Coron (August 2013)
}
\seealso{
\code{\link{Calibration}}, \code{\link{Calibration_HBAN}},
\code{\link{Calibration}}, \code{\link{Calibration_Michel}},
\code{\link{RunModel_GR4J}}, \code{\link{TransfoParam_GR4J}}, \code{\link{ErrorCrit_RMSE}},
\code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}},
\code{\link{CreateInputsCrit}}, \code{\link{CreateCalibOptions}}.
......
......@@ -3,9 +3,9 @@
\encoding{UTF-8}
\name{CreateCalibOptions}
\alias{CreateCalibOptions}
\title{Creation of the CalibOptions object required to the Calibration functions}
\title{Creation of the CalibOptions object required bu the Calibration functions}
\usage{
CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_HBAN,
CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_Michel,
FUN_TRANSFO = NULL, OptimParam = NULL, FixedParam = NULL,
SearchRanges = NULL, StartParam = NULL, StartParamList = NULL,
StartParamDistrib = NULL)
......@@ -13,15 +13,16 @@ CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_HBAN,
\arguments{
\item{FUN_MOD}{[function] hydrological model function (e.g. RunModel_GR4J, RunModel_CemaNeigeGR4J)}
\item{FUN_CALIB}{(optional) [function] calibration algorithm function (e.g. Calibration_HBAN, Calibration_optim), default=Calibration_HBAN}
\item{FUN_CALIB}{(optional) [function] calibration algorithm function (e.g. Calibration_Michel, Calibration_optim), default=Calibration_Michel}
\item{FUN_TRANSFO}{(optional) [function] model parameters transformation function, if the FUN_MOD used is native in the package FUN_TRANSFO is automatically defined}
\item{FUN_TRANSFO}{(optional) [function] model parameters transformation function, if the FUN_MOD used is native in the package, FUN_TRANSFO is automatically defined}
\item{OptimParam}{(optional) [boolean] vector of booleans indicating which parameters must be optimised (NParam columns, 1 line)}
\item{FixedParam}{(optional) [numeric] vector giving the values to allocate to non-optimised parameter values (NParam columns, 1 line)}
\item{FixedParam}{(optional) [numeric] vector giving the values set for the non-optimised parameter values (NParam columns, 1 line)}
\item{SearchRanges}{(optional) [numeric] matrix giving the ranges of real parameters (NParam columns, 2 lines)
\cr Example:
\tabular{llllll}{
\tab [X1] \tab [X2] \tab [X3] \tab [...] \tab [Xi] \cr
[1,] \tab 0 \tab -1 \tab 0 \tab ... \tab 0.0 \cr
......@@ -29,12 +30,14 @@ CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_HBAN,
}}
\item{StartParam}{(optional) [numeric] vector of parameter values used to start global search calibration procedure (e.g. Calibration_optim)
\cr Example:
\tabular{llllll}{
\tab [X1] \tab [X2] \tab [X3] \tab [...] \tab [Xi] \cr
\tab 1000 \tab -0.5 \tab 22 \tab ... \tab 1.1 \cr
}}
\item{StartParamList}{(optional) [numeric] matrix of parameter sets used for grid-screening calibration procedure (values in columns, sets in line)
\cr Example:
\tabular{llllll}{
\tab [X1] \tab [X2] \tab [X3] \tab [...] \tab [Xi] \cr
[set1] \tab 800 \tab -0.7 \tab 25 \tab ... \tab 1.0 \cr
......@@ -43,7 +46,8 @@ CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_HBAN,
[set n] \tab 200 \tab -0.3 \tab 17 \tab ... \tab 1.0 \cr
}}
\item{StartParamDistrib}{(optional) [numeric] matrix of parameter values used for grid-screening calibration procedure (values in columns, percentiles in line) \cr
\item{StartParamDistrib}{(optional) [numeric] matrix of parameter values used for grid-screening calibration procedure (values in columns, percentiles in line)
\cr Example:
\tabular{llllll}{
\tab [X1] \tab [X2] \tab [X3] \tab [...] \tab [Xi] \cr
[value1] \tab 800 \tab -0.7 \tab 25 \tab ... \tab 1.0 \cr
......@@ -56,66 +60,68 @@ CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_HBAN,
\tabular{ll}{
\emph{$OptimParam } \tab [boolean] vector of booleans indicating which parameters must be optimised \cr
\emph{$FixedParam } \tab [numeric] vector giving the values to allocate to non-optimised parameter values \cr
\emph{$SearchRanges } \tab [numeric] matrix giving the ranges of real parameters \cr
\emph{$SearchRanges } \tab [numeric] matrix giving the ranges of raw parameters \cr
\emph{$StartParam } \tab [numeric] vector of parameter values used to start global search calibration procedure \cr
\emph{$StartParamList } \tab [numeric] matrix of parameter sets used for grid-screening calibration procedure \cr
\emph{$StartParamDistrib} \tab [numeric] matrix of parameter values used for grid-screening calibration procedure \cr
}
}
\description{
Creation of the CalibOptions object required to the Calibration functions.
Creation of the CalibOptions object required by the Calibration functions.
}
\details{
Users wanting to use FUN_MOD, FUN_CALIB or FUN_TRANSFO functions that are not included in
the package must create their own CalibOptions object accordingly.
}
\examples{
## load of catchment data
require(airGR)
## loading catchment data
library(airGR)
data(L0123001)
## preparation of InputsModel object
InputsModel <- CreateInputsModel(FUN_MOD=RunModel_GR4J,DatesR=BasinObs$DatesR,
Precip=BasinObs$P,PotEvap=BasinObs$E)
InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR,
Precip = BasinObs$P, PotEvap = BasinObs$E)
## calibration period selection
Ind_Run <- seq(which(format(BasinObs$DatesR,format="\%d/\%m/\%Y \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR,format="\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
## preparation of RunOptions object
RunOptions <- CreateRunOptions(FUN_MOD=RunModel_GR4J,InputsModel=InputsModel,IndPeriod_Run=Ind_Run)
RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J,
InputsModel = InputsModel, IndPeriod_Run = Ind_Run)
## calibration criterion: preparation of the InputsCrit object
InputsCrit <- CreateInputsCrit(FUN_CRIT=ErrorCrit_NSE,InputsModel=InputsModel,
RunOptions=RunOptions,Qobs=BasinObs$Qmm[Ind_Run])
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
## preparation of CalibOptions object
CalibOptions <- CreateCalibOptions(FUN_MOD=RunModel_GR4J,FUN_CALIB=Calibration_HBAN)
CalibOptions <- CreateCalibOptions(FUN_MOD = RunModel_GR4J, FUN_CALIB = Calibration_Michel)
## calibration
OutputsCalib <- Calibration(InputsModel=InputsModel,RunOptions=RunOptions,InputsCrit=InputsCrit,
CalibOptions=CalibOptions,FUN_MOD=RunModel_GR4J,FUN_CRIT=ErrorCrit_NSE,
FUN_CALIB=Calibration_HBAN)
OutputsCalib <- Calibration(InputsModel = InputsModel, RunOptions = RunOptions,
InputsCrit = InputsCrit, CalibOptions = CalibOptions,
FUN_MOD = RunModel_GR4J, FUN_CRIT = ErrorCrit_NSE,
FUN_CALIB = Calibration_Michel)
## simulation
Param <- OutputsCalib$ParamFinalR
OutputsModel <- RunModel(InputsModel=InputsModel,RunOptions=RunOptions,
Param=Param,FUN=RunModel_GR4J)
OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions,
Param = Param, FUN = RunModel_GR4J)
## results preview
plot_OutputsModel(OutputsModel=OutputsModel,Qobs=BasinObs$Qmm[Ind_Run])
plot_OutputsModel(OutputsModel = OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ", round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ", round(OutputsCrit$CritValue, 4), "\\n",sep = ""))
}
......
......@@ -15,23 +15,23 @@ CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions, Qobs, BoolCrit = NULL,
\item{RunOptions}{[object of class \emph{RunOptions}] see \code{\link{CreateRunOptions}} for details}
\item{Qobs}{[numeric] series of observed discharges [mm]}
\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. "", "sqrt", "log", "inv", "sort")}
\item{Ind_zeroes}{(optional) [numeric] indices of the time-steps where zeroes are observed}
\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}
}
\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 to consider in the computation \cr
\emph{$Qobs } \tab [numeric] series of observed discharges [mm] \cr
\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. "", "sqrt", "log", "inv", "sort") \cr
\emph{$Ind_zeroes} \tab [numeric] indices of the time-steps where zeroes are observed \cr
\emph{$Ind_zeroes} \tab [numeric] indices of the time steps where zeroes are observed \cr
\emph{$epsilon } \tab [numeric] epsilon to add to all Qobs and Qsim if \emph{$Ind_zeroes} is not empty \cr
}
}
......@@ -43,65 +43,70 @@ Users wanting to use FUN_CRIT functions that are not included in
the package must create their own InputsCrit object accordingly.
}
\examples{
## load of catchment data
require(airGR)
## loading catchment data
library(airGR)
data(L0123001)
## preparation of the InputsModel object
InputsModel <- CreateInputsModel(FUN_MOD=RunModel_GR4J,DatesR=BasinObs$DatesR,
Precip=BasinObs$P,PotEvap=BasinObs$E)
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 \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR,format="\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
## preparation of the RunOptions object
RunOptions <- CreateRunOptions(FUN_MOD=RunModel_GR4J,InputsModel=InputsModel,IndPeriod_Run=Ind_Run)
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)
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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ", round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run],
transfo = transfo)
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ",
round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
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)
cat(paste(" Crit ", OutputsCrit$CritName, " ", round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
cat(paste("SubCrit ",OutputsCrit$SubCritNames," ",round(OutputsCrit$SubCritValues,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ", round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
cat(paste("SubCrit ", OutputsCrit$SubCritNames, " ",
round(OutputsCrit$SubCritValues, 4), "\\n", sep = ""))
## efficiency criterion: Kling-Gupta Efficiency below a threshold (q10\%) on log-trqansformed flows
transfo <- "log"
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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
cat(paste("SubCrit ",OutputsCrit$SubCritNames," ",round(OutputsCrit$SubCritValues,4),"\\n",sep=""))
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)
cat(paste(" Crit ", OutputsCrit$CritName, " ", round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
cat(paste("SubCrit ", OutputsCrit$SubCritNames, " ",
round(OutputsCrit$SubCritValues, 4), "\\n", sep = ""))
}
......
......@@ -40,7 +40,7 @@ CreateInputsModel(FUN_MOD, DatesR, Precip, PotEvap = NULL, TempMean = NULL,
\emph{$PotEvap } \tab [numeric] time series of potential evapotranspiration (catchment average) [mm], \cr\tab defined if FUN_MOD includes GR4H, GR4J, GR5J, GR6J, GR2M or GR1A \cr \cr
\emph{$LayerPrecip } \tab [list] list of time series of precipitation (layer average) [mm], \cr\tab defined if FUN_MOD includes CemaNeige \cr \cr
\emph{$LayerTempMean } \tab [list] list of time series of mean air temperature (layer average) [degC], \cr\tab defined if FUN_MOD includes CemaNeige \cr \cr
\emph{$LayerFracSolidPrecip} \tab [list] list of time series of solid precip. fract. (layer average) [-], \cr\tab defined if FUN_MOD includes CemaNeige \cr \cr
\emph{$LayerFracSolidPrecip} \tab [list] list of time series of solid precipitation fraction (layer average) [-], \cr\tab defined if FUN_MOD includes CemaNeige \cr \cr
}
}
\description{
......@@ -51,40 +51,41 @@ Users wanting to use FUN_MOD functions that are not included in
the package must create their own InputsModel object accordingly.
}
\examples{
## load of catchment data
require(airGR)
## loading catchment data
library(airGR)
data(L0123001)
## preparation of the InputsModel object
InputsModel <- CreateInputsModel(FUN_MOD=RunModel_GR4J,DatesR=BasinObs$DatesR,
Precip=BasinObs$P,PotEvap=BasinObs$E)
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 \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR,format="\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y \%H:\%M")=="01/01/1990 00:00"),
which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y \%H:\%M")=="31/12/1999 00:00"))
## preparation of the RunOptions object
RunOptions <- CreateRunOptions(FUN_MOD=RunModel_GR4J,InputsModel=InputsModel,IndPeriod_Run=Ind_Run)
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_MOD=RunModel_GR4J)
Param <- c(734.568, -0.840, 109.809, 1.971)
OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions, Param = Param,
FUN_MOD = RunModel_GR4J)
## results preview
plot_OutputsModel(OutputsModel=OutputsModel,Qobs=BasinObs$Qmm[Ind_Run])
plot_OutputsModel(OutputsModel = OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])
## 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)
cat(paste(" Crit ",OutputsCrit$CritName," ",round(OutputsCrit$CritValue,4),"\\n",sep=""))
InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel,
RunOptions = RunOptions, Qobs = BasinObs$Qmm[Ind_Run])
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
cat(paste(" Crit ", OutputsCrit$CritName, " ", round(OutputsCrit$CritValue, 4), "\\n", sep = ""))
}
\author{
Laurent Coron (June 2014)
}
\seealso{
\code{\link{RunModel}}, \code{\link{CreateRunOptions}}, \code{\link{CreateInputsCrit}}, \code{\link{CreateCalibOptions}}, \code{\link{DataAltiExtrapolation_HBAN}}
\code{\link{RunModel}}, \code{\link{CreateRunOptions}}, \code{\link{CreateInputsCrit}}, \code{\link{CreateCalibOptions}}, \code{\link{DataAltiExtrapolation_Valery}}
}
......@@ -19,11 +19,12 @@ CreateRunOptions(FUN_MOD, InputsModel, IndPeriod_WarmUp = NULL, IndPeriod_Run,
\item{IndPeriod_Run}{[numeric] index of period to be used for the model run [-]}
\item{IniStates}{(optional) [numeric] vector of initial model states [mm]}
\item{IniStates}{(optional) [numeric] vector of initial model internal states [mm]}
\item{IniResLevels}{(optional) [numeric] vector of initial filling rates for production and routing stores (2 values between 0 and 1) [-]}
\item{Outputs_Cal}{(optional) [character] vector giving the outputs needed for the calibration \cr (e.g. c("Qsim")), the least outputs the fastest the calibration}
\item{Outputs_Cal}{(optional) [character] vector giving the outputs needed for the calibration \cr (e.g. c("Qsim")), the fewer outputs
the fastest the calibration}
\item{Outputs_Sim}{(optional) [character] vector giving the requested outputs \cr (e.g. c("DatesR","Qsim","SnowPack")), default="all"}
......@@ -63,19 +64,19 @@ A default configuration is used for initialisation if these vectors are not defi
(1) Default initialisation options:
\itemize{
\item \emph{IndPeriod_WarmUp} default setting ensures a one-year warm-up using the time-steps preceding the \emph{IndPeriod_Run}.