Commit 76600c38 authored by Delaigue Olivier's avatar Delaigue Olivier Committed by unknown
Browse files

test

Showing with 1040 additions and 175 deletions
+1040 -175
airGR.Rproj 0 → 100644
Version: 1.0
RestoreWorkspace: Default
SaveWorkspace: Default
AlwaysSaveHistory: Default
EnableCodeIndexing: Yes
UseSpacesForTab: Yes
NumSpacesForTab: 2
Encoding: UTF-8
RnwWeave: Sweave
LaTeX: pdfLaTeX
BuildType: Package
PackageUseDevtools: Yes
PackageInstallArgs: --no-multiarch --with-keep.source
airGR airGR
BasinInfo BasinInfo
BasinObs BasinObs
Calibration Calibration
Calibration_HBAN Calibration_HBAN
Calibration_optim Calibration_optim
CreateCalibOptions CreateCalibOptions
CreateInputsCrit CreateInputsCrit
CreateInputsModel CreateInputsModel
CreateRunOptions CreateRunOptions
DataAltiExtrapolation_HBAN DataAltiExtrapolation_HBAN
ErrorCrit ErrorCrit
ErrorCrit_KGE ErrorCrit_KGE
ErrorCrit_KGE2 ErrorCrit_KGE2
ErrorCrit_NSE ErrorCrit_NSE
ErrorCrit_RMSE ErrorCrit_RMSE
PEdaily_Oudin PEdaily_Oudin
plot_OutputsModel plot_OutputsModel
RunModel RunModel
RunModel_CemaNeige RunModel_CemaNeige
RunModel_CemaNeigeGR4J RunModel_CemaNeigeGR4J
RunModel_CemaNeigeGR5J RunModel_CemaNeigeGR5J
RunModel_CemaNeigeGR6J RunModel_CemaNeigeGR6J
RunModel_GR4J RunModel_GR4J
RunModel_GR5J RunModel_GR5J
RunModel_GR6J RunModel_GR6J
TransfoParam TransfoParam
TransfoParam_CemaNeige TransfoParam_CemaNeige
TransfoParam_GR4J TransfoParam_GR4J
TransfoParam_GR5J TransfoParam_GR5J
TransfoParam_GR6J TransfoParam_GR6J
File deleted
File deleted
File deleted
File deleted
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>R: Modelling tools used at Irstea-HBAN (France), including GR4J,
GR5J, GR6J and CemaNeige</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="R.css">
</head><body>
<h1> Modelling tools used at Irstea-HBAN (France), including GR4J,
GR5J, GR6J and CemaNeige
<img class="toplogo" src="../../../doc/html/logo.jpg" alt="[R logo]">
</h1>
<hr>
<div align="center">
<a href="../../../doc/html/packages.html"><img src="../../../doc/html/left.jpg" alt="[Up]" width="30" height="30" border="0"></a>
<a href="../../../doc/html/index.html"><img src="../../../doc/html/up.jpg" alt="[Top]" width="30" height="30" border="0"></a>
</div><h2>Documentation for package &lsquo;airGR&rsquo; version 0.7.4</h2>
<ul><li><a href="../DESCRIPTION">DESCRIPTION file</a>.</li>
</ul>
<h2>Help Pages</h2>
<table width="100%">
<tr><td width="25%"><a href="airGR.html">airGR</a></td>
<td>Modelling tools used at Irstea-HBAN (France), including GR4J, GR5J, GR6J and CemaNeige</td></tr>
<tr><td width="25%"><a href="BasinInfo.html">BasinInfo</a></td>
<td>Data sample: characteristics of a fictional catchment (L0123001, L0123002 or L0123003)</td></tr>
<tr><td width="25%"><a href="BasinObs.html">BasinObs</a></td>
<td>Data sample: time series of observations of a fictional catchment (L0123001, L0123002 or L0123003)</td></tr>
<tr><td width="25%"><a href="Calibration.html">Calibration</a></td>
<td>Calibration algorithm which minimises an error criterion on the model outputs using the provided functions</td></tr>
<tr><td width="25%"><a href="Calibration_HBAN.html">Calibration_HBAN</a></td>
<td>Calibration algorithm which minimises the error criterion using the Irstea-HBAN procedure</td></tr>
<tr><td width="25%"><a href="Calibration_optim.html">Calibration_optim</a></td>
<td>Calibration algorithm which minimises the error criterion using the stats::optim function</td></tr>
<tr><td width="25%"><a href="CreateCalibOptions.html">CreateCalibOptions</a></td>
<td>Creation of the CalibOptions object required to the Calibration functions</td></tr>
<tr><td width="25%"><a href="CreateInputsCrit.html">CreateInputsCrit</a></td>
<td>Creation of the InputsCrit object required to the ErrorCrit functions</td></tr>
<tr><td width="25%"><a href="CreateInputsModel.html">CreateInputsModel</a></td>
<td>Creation of the InputsModel object required to the RunModel functions</td></tr>
<tr><td width="25%"><a href="CreateRunOptions.html">CreateRunOptions</a></td>
<td>Creation of the RunOptions object required to the RunModel functions</td></tr>
<tr><td width="25%"><a href="DataAltiExtrapolation_HBAN.html">DataAltiExtrapolation_HBAN</a></td>
<td>Altitudinal extrapolation of precipitation and temperature series</td></tr>
<tr><td width="25%"><a href="ErrorCrit.html">ErrorCrit</a></td>
<td>Error criterion using the provided function</td></tr>
<tr><td width="25%"><a href="ErrorCrit_KGE.html">ErrorCrit_KGE</a></td>
<td>Error criterion based on the KGE formula</td></tr>
<tr><td width="25%"><a href="ErrorCrit_KGE2.html">ErrorCrit_KGE2</a></td>
<td>Error criterion based on the KGE' formula</td></tr>
<tr><td width="25%"><a href="ErrorCrit_NSE.html">ErrorCrit_NSE</a></td>
<td>Error criterion based on the NSE formula</td></tr>
<tr><td width="25%"><a href="ErrorCrit_RMSE.html">ErrorCrit_RMSE</a></td>
<td>Error criterion based on the RMSE</td></tr>
<tr><td width="25%"><a href="PEdaily_Oudin.html">PEdaily_Oudin</a></td>
<td>Computation of daily series of potential evapotranspiration with Oudin's formula</td></tr>
<tr><td width="25%"><a href="plot_OutputsModel.html">plot_OutputsModel</a></td>
<td>Default preview of model outputs</td></tr>
<tr><td width="25%"><a href="RunModel.html">RunModel</a></td>
<td>Run with the provided hydrological model function</td></tr>
<tr><td width="25%"><a href="RunModel_CemaNeige.html">RunModel_CemaNeige</a></td>
<td>Run with the CemaNeige snow module</td></tr>
<tr><td width="25%"><a href="RunModel_CemaNeigeGR4J.html">RunModel_CemaNeigeGR4J</a></td>
<td>Run with the CemaNeigeGR4J hydrological model</td></tr>
<tr><td width="25%"><a href="RunModel_CemaNeigeGR5J.html">RunModel_CemaNeigeGR5J</a></td>
<td>Run with the CemaNeigeGR5J hydrological model</td></tr>
<tr><td width="25%"><a href="RunModel_CemaNeigeGR6J.html">RunModel_CemaNeigeGR6J</a></td>
<td>Run with the CemaNeigeGR6J hydrological model</td></tr>
<tr><td width="25%"><a href="RunModel_GR4J.html">RunModel_GR4J</a></td>
<td>Run with the GR4J hydrological model</td></tr>
<tr><td width="25%"><a href="RunModel_GR5J.html">RunModel_GR5J</a></td>
<td>Run with the GR5J hydrological model</td></tr>
<tr><td width="25%"><a href="RunModel_GR6J.html">RunModel_GR6J</a></td>
<td>Run with the GR6J hydrological model</td></tr>
<tr><td width="25%"><a href="TransfoParam.html">TransfoParam</a></td>
<td>Transformation of the parameters using the provided function</td></tr>
<tr><td width="25%"><a href="TransfoParam_CemaNeige.html">TransfoParam_CemaNeige</a></td>
<td>Transformation of the parameters from the CemaNeige module</td></tr>
<tr><td width="25%"><a href="TransfoParam_GR4J.html">TransfoParam_GR4J</a></td>
<td>Transformation of the parameters from the GR4J model</td></tr>
<tr><td width="25%"><a href="TransfoParam_GR5J.html">TransfoParam_GR5J</a></td>
<td>Transformation of the parameters from the GR5J model</td></tr>
<tr><td width="25%"><a href="TransfoParam_GR6J.html">TransfoParam_GR6J</a></td>
<td>Transformation of the parameters from the GR6J model</td></tr>
</table>
</body></html>
BODY{ background: white;
color: black }
A:link{ background: white;
color: blue }
A:visited{ background: white;
color: rgb(50%, 0%, 50%) }
H1{ background: white;
color: rgb(55%, 55%, 55%);
font-family: monospace;
font-size: x-large;
text-align: center }
H2{ background: white;
color: rgb(40%, 40%, 40%);
font-family: monospace;
font-size: large;
text-align: center }
H3{ background: white;
color: rgb(40%, 40%, 40%);
font-family: monospace;
font-size: large }
H4{ background: white;
color: rgb(40%, 40%, 40%);
font-family: monospace;
font-style: italic;
font-size: large }
H5{ background: white;
color: rgb(40%, 40%, 40%);
font-family: monospace }
H6{ background: white;
color: rgb(40%, 40%, 40%);
font-family: monospace;
font-style: italic }
IMG.toplogo{ vertical-align: middle }
IMG.arrow{ width: 30px;
height: 30px;
border: 0 }
span.acronym{font-size: small}
span.env{font-family: monospace}
span.file{font-family: monospace}
span.option{font-family: monospace}
span.pkg{font-weight: bold}
span.samp{font-family: monospace}
div.vignettes a:hover {
background: rgb(85%, 85%, 85%);
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\docType{data}
\encoding{UTF-8}
\name{BasinInfo}
\alias{BasinInfo}
\title{Data sample: characteristics of a fictional catchment (L0123001, L0123002 or L0123003)}
\format{List named 'BasinInfo' containing
\itemize{
\item two strings: catchment's code and station's name
\item one float: catchment's area in km2
\item one numeric vector: catchment's hypsometric curve (min, quantiles 01 to 99 and max) in metres
}}
\description{
R-object containing the code, station's name, area and hypsometric curve of the catchment.
}
\examples{
require(airGR)
data(L0123001)
str(BasinInfo)
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\docType{data}
\encoding{UTF-8}
\name{BasinObs}
\alias{BasinObs}
\title{Data sample: time series of observations of a fictional catchment (L0123001, L0123002 or L0123003)}
\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]
}}
\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.
}
\examples{
require(airGR)
data(L0123001)
str(BasinObs)
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\encoding{UTF-8}
\name{Calibration}
\alias{Calibration}
\title{Calibration algorithm which minimises an error criterion on the model outputs using the provided functions}
\usage{
Calibration(InputsModel, RunOptions, InputsCrit, CalibOptions, FUN_MOD,
FUN_CRIT, FUN_CALIB = Calibration_HBAN, FUN_TRANSFO = NULL,
quiet = FALSE)
}
\arguments{
\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{InputsCrit}{[object of class \emph{InputsCrit}] see \code{\link{CreateInputsCrit}} for details}
\item{CalibOptions}{[object of class \emph{CalibOptions}] see \code{\link{CreateCalibOptions}} for details}
\item{FUN_MOD}{[function] hydrological model function (e.g. RunModel_GR4J, RunModel_CemaNeigeGR4J)}
\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_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}}
}
\description{
Calibration algorithm which minimises the error criterion using the provided functions. \cr
}
\examples{
## load of catchment data
require(airGR)
data(L0123001)
## preparation of InputsModel object
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"))
## preparation of RunOptions object
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])
## preparation of CalibOptions object
CalibOptions <- CreateCalibOptions(FUN_MOD=RunModel_GR4J,FUN_CALIB=Calibration_HBAN)
## calibration
OutputsCalib <- Calibration(InputsModel=InputsModel,RunOptions=RunOptions,InputsCrit=InputsCrit,
CalibOptions=CalibOptions,FUN_MOD=RunModel_GR4J,FUN_CRIT=ErrorCrit_NSE,
FUN_CALIB=Calibration_HBAN)
## simulation
Param <- OutputsCalib$ParamFinalR
OutputsModel <- RunModel(InputsModel=InputsModel,RunOptions=RunOptions,Param=Param,FUN=RunModel_GR4J)
## results preview
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=""))
## 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=""))
}
\author{
Laurent Coron (June 2014)
}
\seealso{
\code{\link{Calibration_HBAN}}, \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}}.
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\encoding{UTF-8}
\name{Calibration_HBAN}
\alias{Calibration_HBAN}
\title{Calibration algorithm which minimises the error criterion using the Irstea-HBAN procedure}
\usage{
Calibration_HBAN(InputsModel, RunOptions, InputsCrit, CalibOptions, FUN_MOD,
FUN_CRIT, FUN_TRANSFO = NULL, quiet = FALSE)
}
\arguments{
\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{InputsCrit}{[object of class \emph{InputsCrit}] see \code{\link{CreateInputsCrit}} for details}
\item{CalibOptions}{[object of class \emph{CalibOptions}] see \code{\link{CreateCalibOptions}} for details}
\item{FUN_MOD}{[function] hydrological model function (e.g. RunModel_GR4J, RunModel_CemaNeigeGR4J)}
\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{quiet}{(optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE}
}
\value{
[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{$NIter } \tab [numeric] number of iterations during the calibration \cr
\emph{$NRuns } \tab [numeric] number of model runs done during the calibration \cr
\emph{$HistParamR } \tab [numeric] table showing the progression steps in the search for optimal set: parameter values \cr
\emph{$HistCrit } \tab [numeric] table showing the progression steps in the search for optimal set: criterion values \cr
\emph{$MatBoolCrit } \tab [boolean] table giving the requested and actual time steps when the model is calibrated \cr
\emph{$CritName } \tab [character] name of the calibration criterion \cr
\emph{$CritBestValue} \tab [numeric] theoretical best criterion value \cr
}
}
\description{
Calibration algorithm which minimises the error criterion. \cr
\cr
The algorithm is based on a local search procedure.
First, a screening is performed using either a rough predefined grid or a list of parameter sets
and then a simple steepest descent local search algorithm is performed.
}
\details{
A screening is first performed either from a rough predefined grid (considering various initial
values for each paramete) or from a list of initial parameter sets. \cr
The best set identified in this screening is then used as a starting point for the steepest
descent local search algorithm. \cr
For this search, the parameters are used in a transformed version, to obtain uniform
variation ranges (and thus a similar pace), while the true ranges might be quite different. \cr
At each iteration, we start from a parameter set of NParam values (NParam being the number of
free parameters of the chosen hydrological model) and we determine the 2*NParam-1 new candidates
by changing one by one the different parameters (+/- pace). \cr
All these candidates are tested and the best one kept to be the starting point for the next
iteration. At the end of each iteration, the pace is either increased or decreased to adapt
the progression speed. A diagonal progress can occasionally be done. \cr
The calibration algorithm stops when the pace becomes too small. \cr
To optimise the exploration of the parameter space, transformation functions are used to convert
the model parameters. This is done using the TransfoParam functions.
}
\examples{
## load of catchment data
require(airGR)
data(L0123001)
## preparation of InputsModel object
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"))
## preparation of RunOptions object
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])
## preparation of CalibOptions object
CalibOptions <- CreateCalibOptions(FUN_MOD=RunModel_GR4J,FUN_CALIB=Calibration_HBAN)
## calibration
OutputsCalib <- Calibration_HBAN(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)
## results preview
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=""))
## 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=""))
}
\author{
Laurent Coron (August 2013)
}
\references{
Michel, C. (1991),
Hydrologie appliquée aux petits bassins ruraux, Hydrology handout (in French), Cemagref, Antony, France.
}
\seealso{
\code{\link{Calibration}}, \code{\link{Calibration_optim}},
\code{\link{RunModel_GR4J}}, \code{\link{TransfoParam_GR4J}}, \code{\link{ErrorCrit_RMSE}},
\code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}},
\code{\link{CreateInputsCrit}}, \code{\link{CreateCalibOptions}}.
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\encoding{UTF-8}
\name{Calibration_optim}
\alias{Calibration_optim}
\title{Calibration algorithm which minimises the error criterion using the stats::optim function}
\usage{
Calibration_optim(InputsModel, RunOptions, InputsCrit, CalibOptions, FUN_MOD,
FUN_CRIT, FUN_TRANSFO = NULL, quiet = FALSE)
}
\arguments{
\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{InputsCrit}{[object of class \emph{InputsCrit}] see \code{\link{CreateInputsCrit}} for details}
\item{CalibOptions}{[object of class \emph{CalibOptions}] see \code{\link{CreateCalibOptions}} for details}
\item{FUN_MOD}{[function] hydrological model function (e.g. RunModel_GR4J, RunModel_CemaNeigeGR4J)}
\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{quiet}{(optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE}
}
\value{
[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{$Nruns } \tab [numeric] number of model runs done during the calibration \cr
\emph{$CritName } \tab [character] name of the calibration criterion \cr
\emph{$CritBestValue} \tab [numeric] theoretical best criterion value \cr
}
}
\description{
Calibration algorithm which minimises the error criterion. \cr
\cr
The algorithm is based on the "optim" function from the "stats" R-package
(using method="L-BFGS-B", i.e. a local optimization quasi-Newton method).
}
\details{
To optimise the exploration of the parameter space, transformation functions are used to convert
the model parameters. This is done using the TransfoParam functions.
}
\examples{
## load of catchment data
require(airGR)
data(L0123001)
## preparation of InputsModel object
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"))
## preparation of RunOptions object
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])
## preparation of CalibOptions object
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)
## simulation
Param <- OutputsCalib$ParamFinalR
OutputsModel <- RunModel_GR4J(InputsModel=InputsModel,RunOptions=RunOptions,Param=Param)
## results preview
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=""))
## 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=""))
}
\author{
Laurent Coron (August 2013)
}
\seealso{
\code{\link{Calibration}}, \code{\link{Calibration_HBAN}},
\code{\link{RunModel_GR4J}}, \code{\link{TransfoParam_GR4J}}, \code{\link{ErrorCrit_RMSE}},
\code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}},
\code{\link{CreateInputsCrit}}, \code{\link{CreateCalibOptions}}.
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\encoding{UTF-8}
\name{CreateCalibOptions}
\alias{CreateCalibOptions}
\title{Creation of the CalibOptions object required to the Calibration functions}
\usage{
CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_HBAN,
FUN_TRANSFO = NULL, RunOptions = NULL, OptimParam = NULL,
FixedParam = NULL, SearchRanges = NULL, StartParam = NULL,
StartParamList = NULL, StartParamDistrib = NULL)
}
\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_TRANSFO}{(optional) [function] model parameters transformation function, if the FUN_MOD used is native in the package FUN_TRANSFO is automatically defined}
\item{RunOptions}{(optional) [object of class \emph{RunOptions}] see \code{\link{CreateRunOptions}} for details}
\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{SearchRanges}{(optional) [numeric] matrix giving the ranges of real parameters (NParam columns, 2 lines)
\tabular{llllll}{
\tab [X1] \tab [X2] \tab [X3] \tab [...] \tab [Xi] \cr
[1,] \tab 0 \tab -1 \tab 0 \tab ... \tab 0.0 \cr
[2,] \tab 3000 \tab +1 \tab 100 \tab ... \tab 3.0 \cr
}}
\item{StartParam}{(optional) [numeric] vector of parameter values used to start global search calibration procedure (e.g. Calibration_optim)
\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)
\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
[set2] \tab 1000 \tab -0.5 \tab 22 \tab ... \tab 1.1 \cr
[...] \tab ... \tab ... \tab ... \tab ... \tab ... \cr
[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
\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
[value2] \tab 1000 \tab NA \tab 50 \tab ... \tab 1.2 \cr
[value3] \tab 1200 \tab NA \tab NA \tab ... \tab 1.6 \cr
}}
}
\value{
[list] object of class \emph{CalibOptions} containing the data required to evaluate the model outputs; it can include the following:
\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{$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.
}
\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)
data(L0123001)
## preparation of InputsModel object
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"))
## preparation of RunOptions object
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])
## preparation of CalibOptions object
CalibOptions <- CreateCalibOptions(FUN_MOD=RunModel_GR4J,FUN_CALIB=Calibration_HBAN)
## calibration
OutputsCalib <- Calibration(InputsModel=InputsModel,RunOptions=RunOptions,InputsCrit=InputsCrit,
CalibOptions=CalibOptions,FUN_MOD=RunModel_GR4J,FUN_CRIT=ErrorCrit_NSE,
FUN_CALIB=Calibration_HBAN)
## simulation
Param <- OutputsCalib$ParamFinalR
OutputsModel <- RunModel(InputsModel=InputsModel,RunOptions=RunOptions,Param=Param,FUN=RunModel_GR4J)
## results preview
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=""))
## 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=""))
}
\author{
Laurent Coron (June 2014)
}
\seealso{
\code{\link{RunModel}}, \code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}}, \code{\link{CreateInputsCrit}}
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\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)
}
\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}
\item{Qobs}{[numeric] series of observed discharges [mm]}
\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{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{$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{$epsilon } \tab [numeric] epsilon to add to all Qobs and Qsim if \emph{$Ind_zeroes} is not empty \cr
}
}
\description{
Creation of the InputsCrit object required to the ErrorCrit functions.
}
\details{
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)
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 \%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)
## 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)
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=""))
## 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=""))
## 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=""))
## 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=""))
}
\author{
Laurent Coron (June 2014)
}
\seealso{
\code{\link{RunModel}}, \code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}}, \code{\link{CreateCalibOptions}}
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\encoding{UTF-8}
\name{CreateInputsModel}
\alias{CreateInputsModel}
\title{Creation of the InputsModel object required to the RunModel functions}
\usage{
CreateInputsModel(FUN_MOD, DatesR, Precip, PotEvap = NULL, TempMean = NULL,
TempMin = NULL, TempMax = NULL, ZInputs = NULL, HypsoData = NULL,
NLayers = 5, quiet = FALSE)
}
\arguments{
\item{FUN_MOD}{[function] hydrological model function (e.g. RunModel_GR4J, RunModel_CemaNeigeGR4J)}
\item{DatesR}{[POSIXlt] vector of dates required to create the GR model and CemaNeige module inputs}
\item{Precip}{[numeric] time series of daily total precipitation (catchment average) [mm], required to create the GR model and CemaNeige module inputs}
\item{PotEvap}{[numeric] time series of daily potential evapotranspiration (catchment average) [mm], required to create the GR model inputs}
\item{TempMean}{[numeric] time series of daily mean air temperature [degC], required to create the CemaNeige module inputs}
\item{TempMin}{(optional) [numeric] time series of daily min air temperature [degC], possibly used to create the CemaNeige module inputs}
\item{TempMax}{(optional) [numeric] time series of daily max air temperature [degC], possibly used to create the CemaNeige module inputs}
\item{ZInputs}{(optional) [numeric] real giving the mean elevation of the Precip and Temp series (before extrapolation) [m]}
\item{HypsoData}{(optional) [numeric] vector of 101 reals: min, q01 to q99 and max of catchment elevation distribution [m], required to create the GR model inputs, if not defined a single elevation is used for CemaNeige}
\item{NLayers}{(optional) [numeric] integer giving the number of elevation layers requested [-], required to create the GR model inputs, default=5}
\item{quiet}{(optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE}
}
\value{
[list] object of class \emph{InputsModel} containing the data required to evaluate the model outputs; it can include the following:
\tabular{ll}{
\emph{$DatesR } \tab [POSIXlt] vector of dates \cr
\emph{$Precip } \tab [numeric] time series of daily total precipitation (catchment average) [mm] \cr
\emph{$PotEvap } \tab [numeric] time series of daily potential evapotranspiration (catchment average) [mm], \cr\tab defined if FUN_MOD includes GR4J, GR5J or GR6J \cr \cr
\emph{$LayerPrecip } \tab [list] list of time series of daily precipitation (layer average) [mm], \cr\tab defined if FUN_MOD includes CemaNeige \cr \cr
\emph{$LayerTempMean } \tab [list] list of time series of daily 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 daily solid precip. fract. (layer average) [-], \cr\tab defined if FUN_MOD includes CemaNeige \cr \cr
}
}
\description{
Creation of the InputsModel object required to the RunModel functions.
}
\details{
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)
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 \%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)
## simulation
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])
## 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=""))
}
\author{
Laurent Coron (June 2014)
}
\seealso{
\code{\link{RunModel}}, \code{\link{CreateRunOptions}}, \code{\link{CreateInputsCrit}}, \code{\link{CreateCalibOptions}}, \code{\link{DataAltiExtrapolation_HBAN}}
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\encoding{UTF-8}
\name{CreateRunOptions}
\alias{CreateRunOptions}
\title{Creation of the RunOptions object required to the RunModel functions}
\usage{
CreateRunOptions(FUN_MOD, InputsModel, IndPeriod_WarmUp = NULL, IndPeriod_Run,
IniStates = NULL, IniResLevels = NULL, Outputs_Cal = NULL,
Outputs_Sim = "all", RunSnowModule = TRUE, MeanAnSolidPrecip = NULL,
quiet = FALSE)
}
\arguments{
\item{FUN_MOD}{[function] hydrological model function (e.g. RunModel_GR4J, RunModel_CemaNeigeGR4J)}
\item{InputsModel}{[object of class \emph{InputsModel}] see \code{\link{CreateInputsModel}} for details}
\item{IndPeriod_WarmUp}{(optional) [numeric] index of period to be used for the model warm-up [-]}
\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{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_Sim}{(optional) [character] vector giving the requested outputs \cr (e.g. c("DatesR","Qsim","SnowPack")), default="all"}
\item{RunSnowModule}{(optional) [boolean] option indicating whether CemaNeige should be activated, default=TRUE}
\item{MeanAnSolidPrecip}{(optional) [numeric] vector giving the annual mean of average solid precipitation for each layer (computed from InputsModel if not defined) [mm/y]}
\item{quiet}{(optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE}
}
\value{
[list] object of class \emph{RunOptions} containing the data required to evaluate the model outputs; it can include the following:
\tabular{ll}{
\emph{IndPeriod_WarmUp } \tab [numeric] index of period to be used for the model warm-up [-] \cr
\emph{IndPeriod_Run } \tab [numeric] index of period to be used for the model run [-] \cr
\emph{IniStates } \tab [numeric] vector of initial model states [mm] \cr
\emph{IniResLevels } \tab [numeric] vector of initial filling rates for production and routing stores [-] \cr
\emph{Outputs_Cal } \tab [character] character vector giving only the outputs needed for the calibration \cr
\emph{Outputs_Sim } \tab [character] character vector giving the requested outputs \cr
\emph{RunSnowModule } \tab [boolean] option indicating whether CemaNeige should be activated \cr
\emph{MeanAnSolidPrecip} \tab [numeric] vector giving the annual mean of average solid precipitation for each layer [mm/y] \cr
}
}
\description{
Creation of the RunOptions object required to the RunModel functions.
}
\details{
Users wanting to use FUN_MOD functions that are not included in
the package must create their own RunOptions object accordingly.
##### Initialisation options #####
The model initialisation options can either be set to a default configuration or be defined by the user.
This is done via three vectors: \cr \emph{IndPeriod_WarmUp}, \emph{IniStates}, \emph{IniResLevels}. \cr
A default configuration is used for initialisation if these vectors are not defined.
(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}.
The actual length of this warm-up might be shorter depending on data availability (no missing value being allowed on model input series).
\item \emph{IniStates} and \emph{IniResLevels} are automatically set to initialise all the model states at 0, except for the production and routing stores which are initialised at 50\% of their capacity. This initialisation is made at the very beginning of the model call (i.e. at the beginning of \emph{IndPeriod_WarmUp} or at the beginning of IndPeriod_Run if the warm-up period is disabled).
}
(2) Customisation of initialisation options:
\itemize{
\item \emph{IndPeriod_WarmUp} can be used to specify the indices of the warm-up period (within the time-series prepared in InputsModel). \cr
- remark 1: for most common cases, indices corresponding to one or several years preceding \emph{IndPeriod_Run} are used (e.g. \emph{IndPeriod_WarmUp <- 1000:1365} and \emph{IndPeriod_Run <- 1366:5000)}. \cr
However, it is also possible to perform a long-term initialisation if other indices than the warm-up ones are set in \emph{IndPeriod_WarmUp} (e.g. \emph{IndPeriod_WarmUp <- c( 1:5000 , 1:5000 , 1:5000 ,1000:1365 )}). \cr
- remark 2: it is also possible to completely disable the warm-up period when using \emph{IndPeriod_WarmUp <- 0}.
\item \emph{IniStates} and \emph{IniResLevels} can be used to specify the initial model states. \cr
- remark 1: if \emph{IniStates} is used, all model states must be provided (e.g. 60 floats [mm] are required for GR4J, GR5J and GR6J; 60+2*NLayers floats [mm] are required for CemaNeigeGR4J, CemaNeigeGR5J and CemaNeigeGR6J; see fortran source code for details). \cr
- remark 2: in addition to \emph{IniStates}, \emph{IniResLevels} allows to set the filling rate of the production and routing stores for the GR models. For instance for GR4J, GR5J and GR6J: \emph{IniResLevels <- c(0.3,0.5)} should be used to obtain initial fillings of 30\% and 50\% for the production and routing stores, respectively. \emph{IniResLevels} is optional and can only be used if \emph{IniStates} is also defined (the state values corresponding to these two stores in \emph{IniStates} are not used in such case). \cr \cr
}
}
\examples{
## load of catchment data
require(airGR)
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 \%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)
## simulation
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])
## 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=""))
}
\author{
Laurent Coron (June 2014)
}
\seealso{
\code{\link{RunModel}}, \code{\link{CreateInputsModel}}, \code{\link{CreateInputsCrit}}, \code{\link{CreateCalibOptions}}
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\encoding{UTF-8}
\name{DataAltiExtrapolation_HBAN}
\alias{DataAltiExtrapolation_HBAN}
\title{Altitudinal extrapolation of precipitation and temperature series}
\usage{
DataAltiExtrapolation_HBAN(DatesR, Precip, TempMean, TempMin = NULL,
TempMax = NULL, ZInputs, HypsoData, NLayers, quiet = FALSE)
}
\arguments{
\item{DatesR}{[POSIXlt] vector of dates}
\item{Precip}{[numeric] time series of daily total precipitation (catchment average) [mm]}
\item{TempMean}{[numeric] time series of daily mean air temperature [degC]}
\item{TempMin}{(optional) [numeric] time series of daily min air temperature [degC]}
\item{TempMax}{(optional) [numeric] time series of daily max air temperature [degC]}
\item{ZInputs}{[numeric] real giving the mean elevation of the Precip and Temp series (before extrapolation) [m]}
\item{HypsoData}{[numeric] vector of 101 reals: min, q01 to q99 and max of catchment elevation distribution [m]}
\item{NLayers}{[numeric] integer giving the number of elevation layers requested [-]}
\item{quiet}{(optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE}
}
\value{
list containing the extrapolated series of precip. and air temp. on each elevation layer
\tabular{ll}{
\emph{$LayerPrecip } \tab [list] list of time series of daily precipitation (layer average) [mm] \cr
\emph{$LayerTempMean } \tab [list] list of time series of daily mean air temperature (layer average) [degC] \cr
\emph{$LayerTempMin } \tab [list] list of time series of daily min air temperature (layer average) [degC] \cr
\emph{$LayerTempMax } \tab [list] list of time series of daily max air temperature (layer average) [degC] \cr
\emph{$LayerFracSolidPrecip} \tab [list] list of time series of daily solid precip. fract. (layer average) [-] \cr
\emph{$ZLayers } \tab [numeric] vector of median elevation for each layer \cr
}
}
\description{
Function which extrapolates the precipitation and air temperature series for different elevation layers (method from Valery, 2010).
}
\details{
Elevation layers of equal surface are created the 101 elevation quantiles (\emph{HypsoData})
and the number requested elevation layers (\emph{NLayers}). \cr
Forcing data (precipitation and air temperature) are extrapolated using gradients from Valery (2010).
(e.g. gradP=0.0004 [m-1] for France and gradT=0.434 [degreC/100m] for January, 1st). \cr
This function is used by the \emph{CreateInputsModel} function. \cr
}
\author{
Laurent Coron, Pierre Brigode (June 2014)
}
\references{
Turcotte, R., L.-G. Fortin, V. Fortin, J.-P. Fortin and J.-P. Villeneuve (2007),
Operational analysis of the spatial distribution and the temporal evolution of the snowpack water equivalent
in southern Quebec, Canada, Nordic Hydrology, 38(3), 211, doi:10.2166/nh.2007.009. \cr
Valéry, A. (2010), Modélisation précipitations-débit sous influence nivale ? : Elaboration d'un module neige
et évaluation sur 380 bassins versants, PhD thesis (in french), AgroParisTech, Paris, France. \cr
USACE (1956), Snow Hydrology, pp. 437, U.S. Army Coprs of Engineers (USACE) North Pacific Division, Portland, Oregon, USA.
}
\seealso{
\code{\link{CreateInputsModel}}, \code{\link{RunModel_CemaNeigeGR4J}}
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\encoding{UTF-8}
\name{ErrorCrit}
\alias{ErrorCrit}
\title{Error criterion using the provided function}
\usage{
ErrorCrit(InputsCrit, OutputsModel, FUN_CRIT, quiet = FALSE)
}
\arguments{
\item{InputsCrit}{[object of class \emph{InputsCrit}] see \code{\link{CreateInputsCrit}} for details}
\item{OutputsModel}{[object of class \emph{OutputsModel}] see \code{\link{RunModel_GR4J}} or \code{\link{RunModel_CemaNeigeGR4J}} for details}
\item{FUN_CRIT}{[function] error criterion function (e.g. ErrorCrit_RMSE, ErrorCrit_NSE)}
\item{quiet}{(optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE}
}
\value{
[list] list containing the function outputs, see \code{\link{ErrorCrit_RMSE}} or \code{\link{ErrorCrit_NSE}} for details
}
\description{
Function which computes an error criterion with the provided function.
}
\examples{
## load of catchment data
require(airGR)
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 \%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)
## 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)
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=""))
## 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=""))
## 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=""))
## 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=""))
}
\author{
Laurent Coron (June 2014)
}
\seealso{
\code{\link{ErrorCrit_RMSE}}, \code{\link{ErrorCrit_NSE}}, \code{\link{ErrorCrit_KGE}}
}
% Generated by roxygen2 (4.0.1): do not edit by hand
\encoding{UTF-8}
\name{ErrorCrit_KGE}
\alias{ErrorCrit_KGE}
\title{Error criterion based on the KGE formula}
\usage{
ErrorCrit_KGE(InputsCrit, OutputsModel, quiet = FALSE)
}
\arguments{
\item{InputsCrit}{[object of class \emph{InputsCrit}] see \code{\link{CreateInputsCrit}} for details}
\item{OutputsModel}{[object of class \emph{OutputsModel}] see \code{\link{RunModel_GR4J}} or \code{\link{RunModel_CemaNeigeGR4J}} for details}
\item{quiet}{(optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE}
}
\value{
[list] list containing the function outputs organised as follows:
\tabular{ll}{
\emph{$CritValue } \tab [numeric] value of the criterion \cr
\emph{$CritName } \tab [character] name of the criterion \cr
\emph{$SubCritValues } \tab [numeric] values of the sub-criteria \cr
\emph{$SubCritNames } \tab [character] names of the sub-criteria \cr
\emph{$CritBestValue } \tab [numeric] theoretical best criterion value \cr
\emph{$Multiplier } \tab [numeric] integer indicating whether the criterion is indeed an error (+1) or an efficiency (-1) \cr
\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
(e.g. Multiplier=+1 for RMSE, Multiplier=-1 for NSE).
}
\examples{
## see example of the ErrorCrit function
}
\author{
Laurent Coron (June 2014)
}
\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}}
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment