doc(RunModel_Lag): improvement of the example

Refs #99

man/RunModel_Lag.Rd

@@ -38,53 +38,64 @@ The list value contains an extra item named \code{QsimDown} which is a copy of \
 
 
 \examples{
-library(airGR)
+#####################################################################
+## Simulation of a reservoir with a purpose of low-flow mitigation ##
+#####################################################################
+
+## Preparation of the InputsModel object
 
-## loading catchment data
+# loading package and catchment data
+library(airGR)
 data(L0123001)
 
-## Simulating a reservoir
-# Withdrawing 1 m3/s with an instream flow of 1 m3/s
+# The reservoir withdraws 1 m3/s when it's possible considering the flow observed in the basin
 Qupstream <- matrix(- unlist(lapply(BasinObs$Qls / 1000 - 1, function(x) {
   min(1, max(0,x, na.rm = TRUE))
 })), ncol = 1)
-# Except between July and November when releasing 3 m3/s
+
+# Except between July and September when the reservoir releases 3 m3/s for low-flow mitigation
 month <- as.numeric(format(BasinObs$DatesR,"\%m"))
 Qupstream[month >= 7 & month <= 9] <- 3
 # Conversion in m3/day
 Qupstream <- Qupstream * 86400
 
-## The reservoir is not an upstream subcachment: its areas is NA
+# The reservoir is not an upstream subcachment: its areas is NA
 BasinAreas <- c(NA, BasinInfo$BasinArea)
 
-## Delay time between the reservoir and the catchment outlet is 2 days and the distance is 150 km
+# Delay time between the reservoir and the catchment outlet is 2 days and the distance is 150 km
 LengthHydro <- 150000
-Lag <- LengthHydro / 2 / 86400 * 1000 # Conversion km/day -> m/s
 
-## preparation of the InputsModel object
 InputsModel <- CreateInputsModel(FUN_MOD = RunModel_GR4J, DatesR = BasinObs$DatesR,
                                  Precip = BasinObs$P, PotEvap = BasinObs$E,
                                  Qupstream = Qupstream, LengthHydro = LengthHydro,
                                  BasinAreas = BasinAreas)
 
-## run period selection
+## Simulation of the basin with the reservoir influence
+
+# Run period selection
 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
+# Creation of the RunOptions object
 RunOptions <- CreateRunOptions(FUN_MOD = RunModel_GR4J,
                                InputsModel = InputsModel, IndPeriod_Run = Ind_Run)
 
-## simulation of downstream subcatchment
+# Simulation of the runoff of the catchment with a GR4J model
 Param <- c(X1 = 257.238, X2 = 1.012, X3 = 88.235, X4 = 2.208)
 OutputsModelDown <- RunModel_GR4J(InputsModel = InputsModel,
                                   RunOptions = RunOptions, Param = Param)
 
+# With a delay of 2 days for 150 km, the flow velocity is 75 km per day
+Velocity <- (LengthHydro / 2) / 86400 # Conversion m/day -> m/s
+
+# Add the output of the precipitation-runoff model in the InputsModel object
 InputsModel$OutputsModel <- OutputsModelDown
+
+# Run the lag model which routes precipitation-runoff model and upstream flows
 OutputsModel <- RunModel_Lag(InputsModel = InputsModel,
-                             RunOptions = RunOptions, Param = Lag)
+                             RunOptions = RunOptions, Param = Velocity)
 
-## results preview of comparison between naturalised (observed) and influenced flow (simulated)
+## Results preview of comparison between naturalised (observed) and influenced flow (simulated)
 plot(OutputsModel, Qobs = OutputsModel$QsimDown)
 }