diff --git a/man/CreateCalibOptions.Rd b/man/CreateCalibOptions.Rd index 451315191df00fdd1913485be25a5e3e49a1e4a1..d250d6e6c7890063b935bdcb25dbfa0ba8e9e84c 100644 --- a/man/CreateCalibOptions.Rd +++ b/man/CreateCalibOptions.Rd @@ -15,7 +15,7 @@ Creation of the \emph{CalibOptions} object required by the \code{Calibration*} f \usage{ CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_Michel, - FUN_TRANSFO = NULL, IsHyst = FALSE, FixedParam = NULL, + FUN_TRANSFO = NULL, IsHyst = FALSE, IsSD = FALSE, FixedParam = NULL, SearchRanges = NULL, StartParamList = NULL, StartParamDistrib = NULL) } @@ -30,6 +30,8 @@ CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_Michel, \item{IsHyst}{[boolean] boolean indicating if the hysteresis version of CemaNeige is used. See details} +\item{IsSD}{[boolean] boolean indicating if the semi-distributed lag model is used. See details} + \item{FixedParam}{(optional) [numeric] vector giving the values set for the non-optimised parameter values (NParam columns, 1 line) \cr Example: \tabular{llllll}{ @@ -75,13 +77,15 @@ CreateCalibOptions(FUN_MOD, FUN_CALIB = Calibration_Michel, \details{ -Users wanting to use \code{FUN_MOD}, \code{FUN_CALIB} or \code{FUN_TRANSFO} functions that are not included in +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 ## ---- CemaNeige version If \code{IsHyst = FALSE}, the original CemaNeige version from Valéry et al. (2014) is used. \cr If \code{IsHyst = TRUE}, the CemaNeige version from Riboust et al. (2019) is used. Compared to the original version, this version of CemaNeige needs two more parameters and it includes a representation of the hysteretic relationship between the Snow Cover Area (SCA) and the Snow Water Equivalent (SWE) in the catchment. The hysteresis included in airGR is the Modified Linear hysteresis (LH*); it is represented on panel b) of Fig. 3 in Riboust et al. (2019). Riboust et al. (2019) advise to use the LH* version of CemaNeige with parameters calibrated using an objective function combining 75 \% of KGE calculated on discharge simulated from a rainfall-runoff model compared to observed discharge and 5 \% of KGE calculated on SCA on 5 CemaNeige elevation bands compared to satellite (e.g. MODIS) SCA (see Eq. (18), Table 3 and Fig. 6). Riboust et al. (2019)'s tests were realized with GR4J as the chosen rainfall-runoff model. \cr + +If \code{InputsModel} parameter has been created for using a semi-distributed (SD) lag model (See \code{\link{CreateInputsModel}}), the parameter \code{isSD} should be set to \code{TRUE}. } @@ -92,11 +96,11 @@ library(airGR) data(L0123001) ## preparation of InputsModel object -InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR, +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 = "\%Y-\%m-\%d")=="1990-01-01"), +Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%Y-\%m-\%d")=="1990-01-01"), which(format(BasinObs$DatesR, format = "\%Y-\%m-\%d")=="1999-12-31")) ## preparation of RunOptions object @@ -104,7 +108,7 @@ 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, +InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run]) ## preparation of CalibOptions object @@ -113,24 +117,24 @@ CalibOptions <- CreateCalibOptions(FUN_MOD = RunModel_GR4J, FUN_CALIB = Calibrat ## calibration OutputsCalib <- Calibration(InputsModel = InputsModel, RunOptions = RunOptions, InputsCrit = InputsCrit, CalibOptions = CalibOptions, - FUN_MOD = RunModel_GR4J, + FUN_MOD = RunModel_GR4J, FUN_CALIB = Calibration_Michel) ## simulation Param <- OutputsCalib$ParamFinalR -OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions, +OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions, Param = Param, FUN = RunModel_GR4J) ## results preview plot(OutputsModel, Qobs = BasinObs$Qmm[Ind_Run]) ## efficiency criterion: Nash-Sutcliffe Efficiency -InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, +InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run]) OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel) ## efficiency criterion: Kling-Gupta Efficiency -InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel, +InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_KGE, InputsModel = InputsModel, RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run]) OutputsCrit <- ErrorCrit_KGE(InputsCrit = InputsCrit, OutputsModel = OutputsModel) } diff --git a/man/CreateInputsModel.Rd b/man/CreateInputsModel.Rd index 466d9d995d5357cc95a5a957e79db5d6c8b496ef..3716e10108f338ae2be103361067424244ed5cef 100644 --- a/man/CreateInputsModel.Rd +++ b/man/CreateInputsModel.Rd @@ -16,7 +16,9 @@ Creation of the \emph{InputsModel} object required to the \code{RunModel*} funct \usage{ CreateInputsModel(FUN_MOD, DatesR, Precip, PrecipScale = TRUE, PotEvap = NULL, TempMean = NULL, TempMin = NULL, TempMax = NULL, - ZInputs = NULL, HypsoData = NULL, NLayers = 5, verbose = TRUE) + ZInputs = NULL, HypsoData = NULL, NLayers = 5, + Qupstream = NULL, LengthHydro = NULL, BasinAreas = NULL, + verbose = TRUE) } @@ -44,6 +46,13 @@ CreateInputsModel(FUN_MOD, DatesR, Precip, PrecipScale = TRUE, PotEvap = NULL, \item{NLayers}{(optional) [numeric] integer giving the number of elevation layers requested [-], required to create CemaNeige module inputs, default=5} \item{verbose}{(optional) [boolean] boolean indicating if the function is run in verbose mode or not, default = \code{TRUE}} + +\item{Qupstream}{(optional) [numerical matrix] time series of upstream flows (catchment average) [mm/time step or m3/time step, see details], required to create the SD model inputs (see details)} + +\item{LengthHydro}{(optional) [numeric] real giving the distance between the downstream outlet and each upstream inlet of the sub-catchment [m], required to create the SD model inputs (see details)} + +\item{BasinAreas}{(optional) [numeric] real giving the area of each upstream sub-catchment [km2] and the area of the downstream sub-catchment in the last item, required to create the SD model inputs (see details)} + } @@ -61,11 +70,15 @@ CreateInputsModel(FUN_MOD, DatesR, Precip, PrecipScale = TRUE, PotEvap = NULL, \details{ -Users wanting to use \code{FUN_MOD} functions that are not included in +Users wanting to use \code{FUN_MOD} functions that are not included in the package must create their own InputsModel object accordingly. \cr Please note that if CemaNeige is used, and \code{ZInputs} is different than \code{HypsoData}, then precipitation and temperature are interpolated with the \code{DataAltiExtrapolation_Valery} function. -} +Users wanting to use a semi-distributed (SD) lag model should provide valid \code{Qupstream}, \code{LengthHydro}, and \code{BasinAreas} parameters. Each upstream sub-catchment is described by an upstream flow time series (one column in \code{Qupstream} matrix), a distance between the downstream outlet and the upstream inlet (one item in \code{LengthHydro}) and an area (one item in \code{BasinAreas}). +The order of the columns or of the items should be consistent for all these parameters. \code{BasinAreas} should contain one extra information (stored in the last item) which is the area of the downstream sub-catchment. +Upstream flows that are not related to a sub-catchment such as a release or withdraw spot are identified by an area equal to \code{NA} and an upstream flow expressed in m3/time step instead of mm/time step. +Please note that the use of SD lag model require to use the \code{\link{RunModel}} function instead of \code{\link{RunModel_GR4J}} or the other \code{RunModel_*} functions. +} \examples{ library(airGR) @@ -74,11 +87,11 @@ library(airGR) data(L0123001) ## preparation of the InputsModel object -InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR, +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 = "\%Y-\%m-\%d")=="1990-01-01"), +Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%Y-\%m-\%d")=="1990-01-01"), which(format(BasinObs$DatesR, format = "\%Y-\%m-\%d")=="1999-12-31")) ## preparation of the RunOptions object @@ -87,14 +100,14 @@ RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, ## simulation Param <- c(X1 = 734.568, X2 = -0.840, X3 = 109.809, X4 = 1.971) -OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions, Param = Param, +OutputsModel <- RunModel(InputsModel = InputsModel, RunOptions = RunOptions, Param = Param, FUN_MOD = RunModel_GR4J) ## results preview plot(OutputsModel, Qobs = BasinObs$Qmm[Ind_Run]) ## efficiency criterion: Nash-Sutcliffe Efficiency -InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, +InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run]) OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel) } diff --git a/man/RunModel.Rd b/man/RunModel.Rd index 473710d595e62e4ea64957d1f92ab95cad05bb17..fab3924e9860056f0bf03c1b446f74bce2147a87 100644 --- a/man/RunModel.Rd +++ b/man/RunModel.Rd @@ -23,16 +23,22 @@ RunModel(InputsModel, RunOptions, Param, FUN_MOD) \item{RunOptions}{[object of class \emph{RunOptions}] see \code{\link{CreateRunOptions}} for details} -\item{Param}{[numeric] vector of model parameters} +\item{Param}{[numeric] vector of model parameters (See details for SD lag model)} \item{FUN_MOD}{[function] hydrological model function (e.g. \code{\link{RunModel_GR4J}}, \code{\link{RunModel_CemaNeigeGR4J}})} } + \value{ -[list] see \code{\link{RunModel_GR4J}} or \code{\link{RunModel_CemaNeigeGR4J}} for details +[list] see \code{\link{RunModel_GR4J}} or \code{\link{RunModel_CemaNeigeGR4J}} for details. + +If \code{InputsModel} parameter has been created for using a semi-distributed (SD) lag model (See \code{\link{CreateInputsModel}}), the list value contains an extra item named \code{QsimDown} which is a numeric series of simulated discharge [mm/time step] related to the run-off contribution of the downstream sub-catchment. } +\details{ +If \code{InputsModel} parameter has been created for using a semi-distributed (SD) lag model (See \code{\link{CreateInputsModel}}), \code{Param} parameter should contain one extra last parameter corresponding to a constant lag parameter expressed as a velocity in m/s. +} \examples{ library(airGR) @@ -41,13 +47,13 @@ library(airGR) data(L0123001) ## preparation of the InputsModel object -InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR, +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 = "\%Y-\%m-\%d")=="1990-01-01"), +Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%Y-\%m-\%d")=="1990-01-01"), which(format(BasinObs$DatesR, format = "\%Y-\%m-\%d")=="1999-12-31")) - + ## preparation of the RunOptions object RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, InputsModel = InputsModel, IndPeriod_Run = Ind_Run) @@ -55,14 +61,14 @@ RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J, ## simulation Param <- c(X1 = 734.568, X2 = -0.840, X3 = 109.809, X4 = 1.971) OutputsModel <- RunModel(InputsModel = InputsModel, - RunOptions = RunOptions, Param = Param, + RunOptions = RunOptions, Param = Param, FUN_MOD = RunModel_GR4J) ## results preview plot(OutputsModel, Qobs = BasinObs$Qmm[Ind_Run]) ## efficiency criterion: Nash-Sutcliffe Efficiency -InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, +InputsCrit <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, RunOptions = RunOptions, Obs = BasinObs$Qmm[Ind_Run]) OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel) } diff --git a/man/TransfoParam.Rd b/man/TransfoParam.Rd index 0bf8485c4b1dda200e315fae53bcb1ec7977f278..fe8dd15f54c02365a4c9c2dcdab0752b371d71a9 100644 --- a/man/TransfoParam.Rd +++ b/man/TransfoParam.Rd @@ -12,6 +12,7 @@ \alias{TransfoParam_GR5H} \alias{TransfoParam_CemaNeige} \alias{TransfoParam_CemaNeigeHyst} +\alias{TransfoParam_LAG} \title{Transformation of the parameters using the provided function}