Commit 8c9c08d4 authored by Delaigue Olivier's avatar Delaigue Olivier

v1.4.3.59 DOC: doc formatting (section displacement and indentation revision)

parent d2e93c58
Package: airGR
Type: Package
Title: Suite of GR Hydrological Models for Precipitation-Runoff Modelling
Version: 1.4.3.58
Version: 1.4.3.59
Date: 2020-01-28
Authors@R: c(
person("Laurent", "Coron", role = c("aut", "trl"), comment = c(ORCID = "0000-0002-1503-6204")),
......
......@@ -2,7 +2,7 @@
### 1.4.3.58 Release Notes (2020-01-28)
### 1.4.3.59 Release Notes (2020-01-28)
#### Bug fixes
......
......@@ -9,14 +9,6 @@
\title{Data sample: characteristics of a different catchments}
\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{
L0123001, L0123002 and L0123003 are fictional catchments. \cr
X0310010 contains actual data from the Durance River at Embrun [La Clapière] (Hautes-Alpes, France). \cr
......@@ -25,6 +17,14 @@ R-object containing the code, station's name, area and hypsometric curve of the
}
\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
}}
\seealso{
\code{\link{BasinObs}}.
}
......
......@@ -7,10 +7,16 @@
\title{Calibration algorithm that optimises the error criterion selected as objective function using the provided functions}
\description{
Calibration algorithm that 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_Michel, FUN_TRANSFO = NULL,
verbose = TRUE)
Calibration(InputsModel, RunOptions, InputsCrit, CalibOptions,
FUN_MOD, FUN_CRIT, FUN_CALIB = Calibration_Michel,
FUN_TRANSFO = NULL, verbose = TRUE)
}
......@@ -40,11 +46,6 @@ Calibration(InputsModel, RunOptions, InputsCrit, CalibOptions, FUN_MOD,
}
\description{
Calibration algorithm that optimises the error criterion selected as objective function using the provided functions.
}
\examples{
library(airGR)
......
......@@ -8,9 +8,18 @@
\title{Calibration algorithm that optimises the error criterion selected as objective function using the Irstea procedure described by C. Michel}
\description{
Calibration algorithm that optimises the error criterion selected as objective function. \cr
\cr
The algorithm combines a global and a local approach.
First, a screening is performed using either a rough predefined grid or a list of parameter sets.
Then a steepest descent local search algorithm is performed, starting from the result of the screening procedure.
}
\usage{
Calibration_Michel(InputsModel, RunOptions, InputsCrit, CalibOptions,
FUN_MOD, FUN_CRIT, FUN_TRANSFO = NULL, verbose = TRUE)
FUN_MOD, FUN_CRIT, FUN_TRANSFO = NULL, verbose = TRUE)
}
......@@ -49,15 +58,6 @@ Calibration_Michel(InputsModel, RunOptions, InputsCrit, CalibOptions,
}
\description{
Calibration algorithm that optimises the error criterion selected as objective function. \cr
\cr
The algorithm combines a global and a local approach.
First, a screening is performed using either a rough predefined grid or a list of parameter sets.
Then a steepest descent local search algorithm is performed, starting from the result of the screening procedure.
}
\details{
A screening is first performed either based on a rough predefined grid (considering various initial
values for each parameter) or from a list of initial parameter sets. \cr
......
......@@ -8,11 +8,16 @@
\title{Creation of the CalibOptions object required but the Calibration functions}
\description{
Creation of the \emph{CalibOptions} object required by the \code{Calibration*} functions.
}
\usage{
CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_Michel,
FUN_TRANSFO = NULL, IsHyst = FALSE, FixedParam = NULL,
SearchRanges = NULL, StartParamList = NULL,
StartParamDistrib = NULL)
FUN_TRANSFO = NULL, IsHyst = FALSE, FixedParam = NULL,
SearchRanges = NULL, StartParamList = NULL,
StartParamDistrib = NULL)
}
......@@ -69,11 +74,6 @@ CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_Michel,
}
\description{
Creation of the \emph{CalibOptions} object required by the \code{Calibration*} functions.
}
\details{
Users wanting to use \code{FUN_MOD}, \code{FUN_CALIB} or \code{FUN_TRANSFO} functions that are not included in
the package must create their own \code{CalibOptions} object accordingly. \cr
......
......@@ -8,13 +8,18 @@
\title{Creation of the IniStates object possibly required by the CreateRunOptions functions}
\description{
Creation of the \emph{IniStates} object possibly required by the \code{\link{CreateRunOptions}} function.
}
\usage{
CreateIniStates(FUN_MOD, InputsModel, IsHyst = FALSE, IsIntStore = FALSE,
ProdStore = 350, RoutStore = 90, ExpStore = NULL, IntStore = NULL,
UH1 = NULL, UH2 = NULL,
GCemaNeigeLayers = NULL, eTGCemaNeigeLayers = NULL,
GthrCemaNeigeLayers = NULL, GlocmaxCemaNeigeLayers = NULL,
verbose = TRUE)
ProdStore = 350, RoutStore = 90, ExpStore = NULL, IntStore = NULL,
UH1 = NULL, UH2 = NULL,
GCemaNeigeLayers = NULL, eTGCemaNeigeLayers = NULL,
GthrCemaNeigeLayers = NULL, GlocmaxCemaNeigeLayers = NULL,
verbose = TRUE)
}
......@@ -62,10 +67,6 @@ CreateIniStates(FUN_MOD, InputsModel, IsHyst = FALSE, IsIntStore = FALSE,
}
\description{
Creation of the \emph{IniStates} object possibly required by the \code{\link{CreateRunOptions}} function.
}
\details{
20 numeric values are required for UH1 and 40 numeric values are required for UH2 if GR4J, GR5J or GR6J are used (respectively 20*24 and 40*24 for the hourly models GR4H and GR5H). Please note that depending on the X4 parameter value that will be provided when running the model, not all the values may be used (only the first int(X4)+1 values are used for UH1 and the first 2*int(X4)+1 for UH2). \cr
\code{GCemaNeigeLayers} and \code{eTGCemaNeigeLayers} require each numeric values as many as given in \code{\link{CreateInputsModel}} with the \code{NLayers} argument. \code{eTGCemaNeigeLayers} values can be negative.\cr
......
......@@ -8,12 +8,17 @@
\title{Creation of the InputsCrit object required to the ErrorCrit functions}
\description{
Creation of the \code{InputsCrit} object required to the \code{ErrorCrit_*} functions. This function is used to define whether the user wants to calculate a single criterion, multiple criteria in the same time, or a composite criterion, which averages several criteria.
}
\usage{
CreateInputsCrit(FUN_CRIT, InputsModel, RunOptions,
Qobs, Obs, VarObs = "Q", BoolCrit = NULL,
transfo = "", Weights = NULL,
Ind_zeroes = NULL, epsilon = NULL,
warnings = TRUE, verbose = TRUE)
Qobs, Obs, VarObs = "Q", BoolCrit = NULL,
transfo = "", Weights = NULL,
Ind_zeroes = NULL, epsilon = NULL,
warnings = TRUE, verbose = TRUE)
}
......@@ -65,11 +70,6 @@ To calculate composite or multiple criteria, it is necessary to use the \code{Er
}
\description{
Creation of the \code{InputsCrit} object required to the \code{ErrorCrit_*} functions. This function is used to define whether the user wants to calculate a single criterion, multiple criteria in the same time, or a composite criterion, which averages several criteria.
}
\details{
Users wanting to use \code{FUN_CRIT} functions that are not included in the package must create their own InputsCrit object accordingly. \cr \cr
......
......@@ -8,10 +8,15 @@
\title{Creation of the InputsModel object required to the RunModel functions}
\description{
Creation of the \emph{InputsModel} object required to the \code{RunModel*} functions.
}
\usage{
CreateInputsModel(FUN_MOD, DatesR, Precip, PrecipScale = TRUE, PotEvap = NULL,
TempMean = NULL, TempMin = NULL, TempMax = NULL, ZInputs = NULL, HypsoData = NULL,
NLayers = 5, verbose = TRUE)
TempMean = NULL, TempMin = NULL, TempMax = NULL,
ZInputs = NULL, HypsoData = NULL, NLayers = 5, verbose = TRUE)
}
......@@ -55,11 +60,6 @@ CreateInputsModel(FUN_MOD, DatesR, Precip, PrecipScale = TRUE, PotEvap = NULL,
}
\description{
Creation of the \emph{InputsModel} object required to the \code{RunModel*} functions.
}
\details{
Users wanting to use \code{FUN_MOD} functions that are not included in
the package must create their own InputsModel object accordingly. \cr
......
......@@ -8,14 +8,19 @@
\title{Creation of the RunOptions object required to the RunModel functions}
\description{
Creation of the RunOptions object required to the \code{RunModel*} functions.
}
\usage{
CreateRunOptions(FUN_MOD, InputsModel,
IndPeriod_WarmUp = NULL, IndPeriod_Run,
IniStates = NULL, IniResLevels = NULL, Imax = NULL,
Outputs_Cal = NULL, Outputs_Sim = "all",
RunSnowModule, MeanAnSolidPrecip = NULL,
IsHyst = FALSE,
warnings = TRUE, verbose = TRUE)
IndPeriod_WarmUp = NULL, IndPeriod_Run,
IniStates = NULL, IniResLevels = NULL, Imax = NULL,
Outputs_Cal = NULL, Outputs_Sim = "all",
RunSnowModule, MeanAnSolidPrecip = NULL,
IsHyst = FALSE,
warnings = TRUE, verbose = TRUE)
}
......@@ -68,11 +73,6 @@ CreateRunOptions(FUN_MOD, InputsModel,
}
\description{
Creation of the RunOptions object required to the \code{RunModel*} functions.
}
\details{
Users wanting to use \code{FUN_MOD} functions that are not included in
the package must create their own \code{RunOptions} object accordingly.
......
......@@ -8,10 +8,15 @@
\title{Altitudinal extrapolation of precipitation and temperature series described by A. Valery}
\description{
Function which extrapolates the precipitation and air temperature series for different elevation layers (method from Valéry, 2010).
}
\usage{
DataAltiExtrapolation_Valery(DatesR, Precip, PrecipScale = TRUE,
TempMean, TempMin = NULL, TempMax = NULL,
ZInputs, HypsoData, NLayers, verbose = TRUE)
TempMean, TempMin = NULL, TempMax = NULL,
ZInputs, HypsoData, NLayers, verbose = TRUE)
}
......@@ -49,11 +54,6 @@ list containing the extrapolated series of precip. and air temp. on each elevati
}
\description{
Function which extrapolates the precipitation and air temperature series for different elevation layers (method from Valéry, 2010).
}
\details{
Elevation layers of equal surface are created the 101 elevation quantiles (\code{HypsoData})
and the number requested elevation layers (\code{NLayers}). \cr
......
......@@ -8,6 +8,11 @@
\title{Error criterion using the provided function}
\description{
Function which computes an error criterion with the provided function.
}
\usage{
ErrorCrit(InputsCrit, OutputsModel, FUN_CRIT, warnings = TRUE, verbose = TRUE)
}
......@@ -26,10 +31,6 @@ ErrorCrit(InputsCrit, OutputsModel, FUN_CRIT, warnings = TRUE, verbose = TRUE)
}
\description{
Function which computes an error criterion with the provided function.
}
\value{
If \code{InputsCrit} is of class \emph{Single}:
\tabular{ll}{
......
......@@ -8,6 +8,11 @@
\title{Error criterion based on the KGE formula}
\description{
Function which computes an error criterion based on the KGE formula proposed by Gupta et al. (2009).
}
\usage{
ErrorCrit_KGE(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
}
......@@ -38,11 +43,6 @@ ErrorCrit_KGE(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
}
\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 (Multiplier = -1 for KGE).\cr\cr
......
......@@ -8,6 +8,11 @@
\title{Error criterion based on the KGE' formula}
\description{
Function which computes an error criterion based on the KGE' formula proposed by Kling et al. (2012).
}
\usage{
ErrorCrit_KGE2(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
}
......@@ -38,11 +43,6 @@ ErrorCrit_KGE2(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
}
\description{
Function which computes an error criterion based on the KGE' formula proposed by Kling et al. (2012).
}
\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 (Multiplier = -1 for KGE2).\cr\cr
......
......@@ -13,6 +13,11 @@ ErrorCrit_NSE(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
}
\description{
Function which computes an error criterion based on the NSE formula proposed by Nash & Sutcliffe (1970).
}
\arguments{
\item{InputsCrit}{[object of class \emph{InputsCrit}] see \code{\link{CreateInputsCrit}} for details}
......@@ -36,11 +41,6 @@ ErrorCrit_NSE(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
}
\description{
Function which computes an error criterion based on the NSE formula proposed by Nash & Sutcliffe (1970).
}
\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
......
......@@ -3,6 +3,8 @@
\name{ErrorCrit_RMSE}
\alias{ErrorCrit_RMSE}
\title{Error criterion based on the RMSE}
......@@ -11,6 +13,11 @@ ErrorCrit_RMSE(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
}
\description{
Function which computes an error criterion based on the root-mean-square error (RMSE).
}
\arguments{
\item{InputsCrit}{[object of class \emph{InputsCrit}] see \code{\link{CreateInputsCrit}} for details}
......@@ -34,11 +41,6 @@ ErrorCrit_RMSE(InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)
}
\description{
Function which computes an error criterion based on the root-mean-square error (RMSE).
}
\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
......
......@@ -8,6 +8,11 @@
\title{Computation of the maximum capacity of the GR5H interception store}
\description{
Function which calculates the maximal capacity of the GR5H interception store. This function compares the interception evapotranspiration from the GR5H interception store for different maximal capacity values with the interception evapotranspiration classically used in the daily GR models (e.g. GR4J). Among all the \code{TestedValues}, the value that gives the closest interception evapotranspiration flux over the whole period is kept.
}
\usage{
Imax(InputsModel, IndPeriod_Run,
TestedValues = seq(from = 0.1, to = 3, by = 0.1))
......@@ -28,11 +33,6 @@ Optimal Imax value [mm].
}
\description{
Function which calculates the maximal capacity of the GR5H interception store. This function compares the interception evapotranspiration from the GR5H interception store for different maximal capacity values with the interception evapotranspiration classically used in the daily GR models (e.g. GR4J). Among all the \code{TestedValues}, the value that gives the closest interception evapotranspiration flux over the whole period is kept.
}
\examples{
library(airGR)
......
......@@ -9,6 +9,13 @@
\title{Generalist parameter sets for the GR4J model}
\description{
These parameter sets can be used as an alternative for the grid-screening calibration procedure (i.e. first step in \code{\link{Calibration_Michel}}).
Please note that the given GR4J X4u variable does not correspond to the actual GR4J X4 parameter. As explained in Andréassian et al. (2014; section 2.1), the given GR4J X4u value has to be adjusted (rescaled) using catchment area (S) [km2] as follows: {X4 = X4u / 5.995 * S^0.3} (please note that the formula is erroneous in the publication). Please, see the example below. \cr
As shown in Andréassian et al. (2014; figure 4), only using these parameters sets as the tested values for calibration is more efficient than a classical calibration when the amount of data is low (6 months or less).
}
\format{Data frame of parameters containing four numeric vectors
\itemize{
\item {GR4J X1} {production store capacity [mm]}
......@@ -18,13 +25,6 @@
}}
\description{
These parameter sets can be used as an alternative for the grid-screening calibration procedure (i.e. first step in \code{\link{Calibration_Michel}}).
Please note that the given GR4J X4u variable does not correspond to the actual GR4J X4 parameter. As explained in Andréassian et al. (2014; section 2.1), the given GR4J X4u value has to be adjusted (rescaled) using catchment area (S) [km2] as follows: {X4 = X4u / 5.995 * S^0.3} (please note that the formula is erroneous in the publication). Please, see the example below. \cr
As shown in Andréassian et al. (2014; figure 4), only using these parameters sets as the tested values for calibration is more efficient than a classical calibration when the amount of data is low (6 months or less).
}
\seealso{
\code{\link{RunModel_GR4J}}, \code{\link{Calibration_Michel}}, \code{\link{CreateCalibOptions}}.
}
......
......@@ -3,9 +3,16 @@
\name{RunModel}
\alias{RunModel}
\title{Run with the provided hydrological model function}
\description{
Function which performs a single model run with the provided function over the selected period.
}
\usage{
RunModel(InputsModel, RunOptions, Param, FUN_MOD)
}
......@@ -27,11 +34,6 @@ RunModel(InputsModel, RunOptions, Param, FUN_MOD)
}
\description{
Function which performs a single model run with the provided function over the selected period.
}
\examples{
library(airGR)
......
......@@ -8,6 +8,11 @@
\title{Run with the CemaNeige snow module}
\description{
Function which performs a single run for the CemaNeige snow module at the daily or hourly time step.
}
\usage{
RunModel_CemaNeige(InputsModel, RunOptions, Param)
}
......@@ -50,11 +55,6 @@ CemaNeige X4 \tab (optional) percentage (between 0 and 1) of annual snowfall def
}
\description{
Function which performs a single run for the CemaNeige snow module at the daily or hourly time step.
}
\details{
The choice of the CemaNeige version (i.e. with or without hysteresis) is explained in \code{\link{CreateRunOptions}}. \cr
For further details on the model, see the references section. \cr
......
......@@ -8,6 +8,11 @@
\title{Run with the CemaNeigeGR4H hydrological model}
\description{
Function which performs a single run for the CemaNeige-GR4H hourly lumped model over the test period.
}
\usage{
RunModel_CemaNeigeGR4H(InputsModel, RunOptions, Param)
}
......@@ -72,11 +77,6 @@ CemaNeige X4 \tab (optional) percentage (between 0 and 1) of annual snowfall def
}
\description{
Function which performs a single run for the CemaNeige-GR4H hourly lumped model over the test period.
}
\details{
It is advised to run the GR5H model with an interception store (see Ficchi et al. (2019)) as it improves the consistency of the model fluxes and provides better performance. To do so, the \code{\link{Imax}} functions allows to estimates the maximal capacity of the interception store, which can then be given to \code{\link{CreateRunOptions}}. \cr
......
......@@ -8,6 +8,11 @@
\title{Run with the CemaNeigeGR4J hydrological model}
\description{
Function which performs a single run for the CemaNeige-GR4J daily lumped model over the test period.
}
\usage{
RunModel_CemaNeigeGR4J(InputsModel, RunOptions, Param)
}
......@@ -72,11 +77,6 @@ CemaNeige X4 \tab (optional) percentage (between 0 and 1) of annual snowfall def
}
\description{
Function which performs a single run for the CemaNeige-GR4J daily lumped model over the test period.
}
\details{
The choice of the CemaNeige version is explained in \code{\link{CreateRunOptions}}. \cr
For further details on the model, see the references section. \cr
......
......@@ -8,6 +8,11 @@
\title{Run with the CemaNeigeGR5H hydrological model}
\description{
Function which performs a single run for the CemaNeige-GR5H hourly lumped model over the test period.
}
\usage{
RunModel_CemaNeigeGR5H(InputsModel, RunOptions, Param)
}
......@@ -75,11 +80,6 @@ CemaNeige X4 \tab (optional) percentage (between 0 and 1) of annual snowfall def
}
\description{
Function which performs a single run for the CemaNeige-GR5H hourly lumped model over the test period.
}
\details{
The choice of the CemaNeige version is explained in \code{\link{CreateRunOptions}}. \cr
For further details on the model, see the references section. \cr
......
......@@ -8,6 +8,11 @@
\title{Run with the CemaNeigeGR5J hydrological model}
\description{
Function which performs a single run for the CemaNeige-GR5J daily lumped model.
}
\usage{
RunModel_CemaNeigeGR5J(InputsModel, RunOptions, Param)
}
......@@ -73,11 +78,6 @@ CemaNeige X4 \tab (optional) percentage (between 0 and 1) of annual snowfall def
}
\description{
Function which performs a single run for the CemaNeige-GR5J daily lumped model.
}
\details{
The choice of the CemaNeige version is explained in \code{\link{CreateRunOptions}}. \cr
For further details on the model, see the references section. \cr
......
......@@ -8,6 +8,11 @@
\title{Run with the CemaNeigeGR6J hydrological model}
\description{
Function which performs a single run for the CemaNeige-GR6J daily lumped model.
}
\usage{
RunModel_CemaNeigeGR6J(InputsModel, RunOptions, Param)
}
......@@ -76,11 +81,6 @@ CemaNeige X4 \tab (optional) percentage (between 0 and 1) of annual snowfall def
}
\description{
Function which performs a single run for the CemaNeige-GR6J daily lumped model.
}
\details{
The choice of the CemaNeige version is explained in \code{\link{CreateRunOptions}}. \cr
For further details on the model, see the references section. \cr
......
......@@ -8,6 +8,11 @@
\title{Run with the GR1A hydrological model}