Severn_02: Calibration of a GR4J semi-distributed model network

David Dorchies

airGRiwrm automates the execution of airGR semi-distributed models. The steps for running or calibrating the model are the same as the ones of ‘airGR’.

Load library

library(airGRiwrm)

Preparation of function inputs

To run a model, as for airGR, the functions of the airGRiwrm package (e.g. the models, calibration and criteria calculation functions) require data and options with specific formats.

To facilitate the use of the package, there are several functions dedicated to the creation of these objects:

GRiwrmInputsModel object

The method used for producing the GRiwrmInputsModel object is detailed in the vignette “V01_Structure_SD_model” of the package. The following code chunk resumes all the steps of this vignette:

data(Severn)
nodes <- Severn$BasinsInfo[, c("gauge_id", "downstream_id", "distance_downstream", "area")]
nodes$distance_downstream <- nodes$distance_downstream
nodes$model <- "RunModel_GR4J"
griwrm <- CreateGRiwrm(nodes, list(id = "gauge_id", down = "downstream_id", length = "distance_downstream"))
BasinsObs <- Severn$BasinsObs
DatesR <- BasinsObs[[1]]$DatesR
PrecipTot <- cbind(sapply(BasinsObs, function(x) {x$precipitation}))
PotEvapTot <- cbind(sapply(BasinsObs, function(x) {x$peti}))
Qobs <- cbind(sapply(BasinsObs, function(x) {x$discharge_spec}))
Precip <- ConvertMeteoSD(griwrm, PrecipTot)
PotEvap <- ConvertMeteoSD(griwrm, PotEvapTot)
InputsModel <- CreateInputsModel(griwrm, DatesR, Precip, PotEvap)
#> CreateInputsModel.GRiwrm: Treating sub-basin 54095...
#> CreateInputsModel.GRiwrm: Treating sub-basin 54002...
#> CreateInputsModel.GRiwrm: Treating sub-basin 54029...
#> CreateInputsModel.GRiwrm: Treating sub-basin 54001...
#> CreateInputsModel.GRiwrm: Treating sub-basin 54032...
#> CreateInputsModel.GRiwrm: Treating sub-basin 54057...
str(InputsModel)
#> List of 6
#>  $ 54095:List of 7
#>   ..$ DatesR    : POSIXlt[1:11536], format: "1984-03-01" "1984-03-02" ...
#>   ..$ Precip    : num [1:11536] 4.01 0.57 2 0.37 0.01 0.3 0.12 0 0.12 0.07 ...
#>   ..$ PotEvap   : num [1:11536] 0.59 1.64 1.42 0.31 0.59 0.73 0.59 0.66 0.57 0.61 ...
#>   ..$ id        : chr "54095"
#>   ..$ down      : chr "54001"
#>   ..$ BasinAreas: num 3723
#>   ..$ FUN_MOD   : chr "RunModel_GR4J"
#>   ..- attr(*, "class")= chr [1:3] "InputsModel" "daily" "GR"
#>  $ 54002:List of 7
#>   ..$ DatesR    : POSIXlt[1:11536], format: "1984-03-01" "1984-03-02" ...
#>   ..$ Precip    : num [1:11536] 1.58 0.47 1.35 1.92 0.06 0 0.01 0 0.08 0.34 ...
#>   ..$ PotEvap   : num [1:11536] 0.61 1.7 1.61 0.3 0.44 0.69 0.52 0.71 0.73 0.57 ...
#>   ..$ id        : chr "54002"
#>   ..$ down      : chr "54057"
#>   ..$ BasinAreas: num 2208
#>   ..$ FUN_MOD   : chr "RunModel_GR4J"
#>   ..- attr(*, "class")= chr [1:3] "InputsModel" "daily" "GR"
#>  $ 54029:List of 7
#>   ..$ DatesR    : POSIXlt[1:11536], format: "1984-03-01" "1984-03-02" ...
#>   ..$ Precip    : num [1:11536] 2.38 0.33 2.16 0.38 0.01 0.12 0.08 0.05 0.05 0.29 ...
#>   ..$ PotEvap   : num [1:11536] 0.58 1.64 1.49 0.23 0.56 0.72 0.63 0.72 0.62 0.64 ...
#>   ..$ id        : chr "54029"
#>   ..$ down      : chr "54032"
#>   ..$ BasinAreas: num 1484
#>   ..$ FUN_MOD   : chr "RunModel_GR4J"
#>   ..- attr(*, "class")= chr [1:3] "InputsModel" "daily" "GR"
#>  $ 54001:List of 11
#>   ..$ DatesR          : POSIXlt[1:11536], format: "1984-03-01" "1984-03-02" ...
#>   ..$ Precip          : num [1:11536] 1.3 0.427 2.642 0.441 0.01 ...
#>   ..$ PotEvap         : num [1:11536] 0.59 1.711 1.563 0.239 0.519 ...
#>   ..$ Qupstream       : num [1:11536, 1] 0 0 0 0 0 0 0 0 0 0 ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : NULL
#>   .. .. ..$ : chr "54095"
#>   ..$ LengthHydro     : Named num 42
#>   .. ..- attr(*, "names")= chr "54095"
#>   ..$ BasinAreas      : Named num [1:2] 3723 607
#>   .. ..- attr(*, "names")= chr [1:2] "54095" "54001"
#>   ..$ id              : chr "54001"
#>   ..$ down            : chr "54032"
#>   ..$ UpstreamNodes   : chr "54095"
#>   ..$ UpstreamIsRunoff: logi TRUE
#>   ..$ FUN_MOD         : chr "RunModel_GR4J"
#>   ..- attr(*, "class")= chr [1:4] "InputsModel" "daily" "GR" "SD"
#>  $ 54032:List of 11
#>   ..$ DatesR          : POSIXlt[1:11536], format: "1984-03-01" "1984-03-02" ...
#>   ..$ Precip          : num [1:11536] 1.737 0.469 2.187 1.229 0.01 ...
#>   ..$ PotEvap         : num [1:11536] 0.604 1.599 1.565 0.203 0.543 ...
#>   ..$ Qupstream       : num [1:11536, 1:2] 0 0 0 0 0 0 0 0 0 0 ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : NULL
#>   .. .. ..$ : chr [1:2] "54001" "54029"
#>   ..$ LengthHydro     : Named num [1:2] 45 32
#>   .. ..- attr(*, "names")= chr [1:2] "54001" "54029"
#>   ..$ BasinAreas      : Named num [1:3] 4330 1484 1051
#>   .. ..- attr(*, "names")= chr [1:3] "54001" "54029" "54032"
#>   ..$ id              : chr "54032"
#>   ..$ down            : chr "54057"
#>   ..$ UpstreamNodes   : chr [1:2] "54001" "54029"
#>   ..$ UpstreamIsRunoff: logi [1:2] TRUE TRUE
#>   ..$ FUN_MOD         : chr "RunModel_GR4J"
#>   ..- attr(*, "class")= chr [1:4] "InputsModel" "daily" "GR" "SD"
#>  $ 54057:List of 11
#>   ..$ DatesR          : POSIXlt[1:11536], format: "1984-03-01" "1984-03-02" ...
#>   ..$ Precip          : num [1:11536] 1.523 0.179 1.536 1.545 0 ...
#>   ..$ PotEvap         : num [1:11536] 0.536 1.599 1.576 0.31 0.437 ...
#>   ..$ Qupstream       : num [1:11536, 1:2] 0 0 0 0 0 0 0 0 0 0 ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : NULL
#>   .. .. ..$ : chr [1:2] "54032" "54002"
#>   ..$ LengthHydro     : Named num [1:2] 15 43
#>   .. ..- attr(*, "names")= chr [1:2] "54032" "54002"
#>   ..$ BasinAreas      : Named num [1:3] 6865 2208 813
#>   .. ..- attr(*, "names")= chr [1:3] "54032" "54002" "54057"
#>   ..$ id              : chr "54057"
#>   ..$ down            : chr NA
#>   ..$ UpstreamNodes   : chr [1:2] "54032" "54002"
#>   ..$ UpstreamIsRunoff: logi [1:2] TRUE TRUE
#>   ..$ FUN_MOD         : chr "RunModel_GR4J"
#>   ..- attr(*, "class")= chr [1:4] "InputsModel" "daily" "GR" "SD"
#>  - attr(*, "class")= chr [1:2] "GRiwrmInputsModel" "list"
#>  - attr(*, "GRiwrm")=Classes 'GRiwrm' and 'data.frame':  6 obs. of  5 variables:
#>   ..$ id    : chr [1:6] "54057" "54032" "54001" "54095" ...
#>   ..$ down  : chr [1:6] NA "54057" "54032" "54001" ...
#>   ..$ length: num [1:6] NA 15 45 42 43 32
#>   ..$ model : chr [1:6] "RunModel_GR4J" "RunModel_GR4J" "RunModel_GR4J" "RunModel_GR4J" ...
#>   ..$ area  : num [1:6] 9885 6865 4330 3723 2208 ...
#>  - attr(*, "TimeStep")= num 86400

GRiwrmRunOptions object

The CreateRunOptions() function allows to prepare the options required for the RunModel() function.

The user must at least define the following arguments:

Below, we define a one-year warm up period and we start the run period just after the warm up period.

IndPeriod_Run <- seq(
  which(InputsModel[[1]]$DatesR == (InputsModel[[1]]$DatesR[1] + 365*24*60*60)), # Set aside warm-up period
  length(InputsModel[[1]]$DatesR) # Until the end of the time series
)
IndPeriod_WarmUp <- seq(1, IndPeriod_Run[1] - 1)

Arguments of the CreateRunOptions function for airGRiwrm are the same as for the function in airGR and are copied for each node running a rainfall-runoff model.

RunOptions <- CreateRunOptions(
  InputsModel,
  IndPeriod_WarmUp = IndPeriod_WarmUp,
  IndPeriod_Run = IndPeriod_Run
)

GRiwrmInputsCrit object

The CreateInputsCrit() function allows to prepare the input in order to calculate a criterion. We use composed criterion with a parameter regularization based on @delavenneRegularizationApproachImprove2019.

It needs the following arguments:

InputsCrit <- CreateInputsCrit(
  InputsModel = InputsModel,
  FUN_CRIT = ErrorCrit_KGE2,
  RunOptions = RunOptions,
  Obs = Qobs[IndPeriod_Run, ],
  AprioriIds = c(
      "54057" = "54032",
      "54032" = "54001",
      "54001" = "54095"
  ),
  transfo = "sqrt",
  k = 0.15
)
str(InputsCrit)
#> List of 6
#>  $ 54095:List of 8
#>   ..$ FUN_CRIT:function (InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)  
#>   .. ..- attr(*, "class")= chr [1:2] "FUN_CRIT" "function"
#>   ..$ Obs     : num [1:11171] 1.19 1.17 1.25 1.51 2.05 1.61 1.34 1.34 1.17 1.06 ...
#>   ..$ VarObs  : chr "Q"
#>   ..$ BoolCrit: logi [1:11171] TRUE TRUE TRUE TRUE TRUE TRUE ...
#>   ..$ idLayer : logi NA
#>   ..$ transfo : chr "sqrt"
#>   ..$ epsilon : NULL
#>   ..$ Weights : NULL
#>   ..- attr(*, "class")= chr [1:2] "Single" "InputsCrit"
#>  $ 54002:List of 8
#>   ..$ FUN_CRIT:function (InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)  
#>   .. ..- attr(*, "class")= chr [1:2] "FUN_CRIT" "function"
#>   ..$ Obs     : num [1:11171] 1.09 1.13 1.07 1.04 0.82 0.68 0.87 0.88 0.77 0.68 ...
#>   ..$ VarObs  : chr "Q"
#>   ..$ BoolCrit: logi [1:11171] TRUE TRUE TRUE TRUE TRUE TRUE ...
#>   ..$ idLayer : logi NA
#>   ..$ transfo : chr "sqrt"
#>   ..$ epsilon : NULL
#>   ..$ Weights : NULL
#>   ..- attr(*, "class")= chr [1:2] "Single" "InputsCrit"
#>  $ 54029:List of 8
#>   ..$ FUN_CRIT:function (InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)  
#>   .. ..- attr(*, "class")= chr [1:2] "FUN_CRIT" "function"
#>   ..$ Obs     : num [1:11171] 1.37 1.31 1.52 1.6 1.29 1.14 1.45 1.47 1.23 1.12 ...
#>   ..$ VarObs  : chr "Q"
#>   ..$ BoolCrit: logi [1:11171] TRUE TRUE TRUE TRUE TRUE TRUE ...
#>   ..$ idLayer : logi NA
#>   ..$ transfo : chr "sqrt"
#>   ..$ epsilon : NULL
#>   ..$ Weights : NULL
#>   ..- attr(*, "class")= chr [1:2] "Single" "InputsCrit"
#>  $ 54001:List of 8
#>   ..$ FUN_CRIT:function (InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)  
#>   .. ..- attr(*, "class")= chr [1:2] "FUN_CRIT" "function"
#>   ..$ Obs     : num [1:11171] 1.1 1.05 1.19 1.29 1.77 1.49 1.31 1.27 1.1 0.97 ...
#>   ..$ VarObs  : chr "Q"
#>   ..$ BoolCrit: logi [1:11171] TRUE TRUE TRUE TRUE TRUE TRUE ...
#>   ..$ idLayer : logi NA
#>   ..$ transfo : chr "sqrt"
#>   ..$ epsilon : NULL
#>   ..$ Weights : NULL
#>   ..- attr(*, "class")= chr [1:3] "InputsCritLavenneFunction" "Single" "InputsCrit"
#>   ..- attr(*, "Lavenne_FUN")=function (AprParamR, AprCrit)  
#>   ..- attr(*, "AprioriId")= Named chr "54095"
#>   .. ..- attr(*, "names")= chr "54001"
#>   ..- attr(*, "AprCelerity")= num 1
#>  $ 54032:List of 8
#>   ..$ FUN_CRIT:function (InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)  
#>   .. ..- attr(*, "class")= chr [1:2] "FUN_CRIT" "function"
#>   ..$ Obs     : num [1:11171] 1.19 1.19 1.23 1.35 1.43 1.37 1.32 1.35 1.21 1.07 ...
#>   ..$ VarObs  : chr "Q"
#>   ..$ BoolCrit: logi [1:11171] TRUE TRUE TRUE TRUE TRUE TRUE ...
#>   ..$ idLayer : logi NA
#>   ..$ transfo : chr "sqrt"
#>   ..$ epsilon : NULL
#>   ..$ Weights : NULL
#>   ..- attr(*, "class")= chr [1:3] "InputsCritLavenneFunction" "Single" "InputsCrit"
#>   ..- attr(*, "Lavenne_FUN")=function (AprParamR, AprCrit)  
#>   ..- attr(*, "AprioriId")= Named chr "54001"
#>   .. ..- attr(*, "names")= chr "54032"
#>   ..- attr(*, "AprCelerity")= num 1
#>  $ 54057:List of 8
#>   ..$ FUN_CRIT:function (InputsCrit, OutputsModel, warnings = TRUE, verbose = TRUE)  
#>   .. ..- attr(*, "class")= chr [1:2] "FUN_CRIT" "function"
#>   ..$ Obs     : num [1:11171] 1.06 1.1 1.09 1.22 1.23 1.21 1.18 1.25 1.13 0.98 ...
#>   ..$ VarObs  : chr "Q"
#>   ..$ BoolCrit: logi [1:11171] TRUE TRUE TRUE TRUE TRUE TRUE ...
#>   ..$ idLayer : logi NA
#>   ..$ transfo : chr "sqrt"
#>   ..$ epsilon : NULL
#>   ..$ Weights : NULL
#>   ..- attr(*, "class")= chr [1:3] "InputsCritLavenneFunction" "Single" "InputsCrit"
#>   ..- attr(*, "Lavenne_FUN")=function (AprParamR, AprCrit)  
#>   ..- attr(*, "AprioriId")= Named chr "54032"
#>   .. ..- attr(*, "names")= chr "54057"
#>   ..- attr(*, "AprCelerity")= num 1
#>  - attr(*, "class")= chr [1:2] "GRiwrmInputsCrit" "list"

GRiwrmCalibOptions object

Before using the automatic calibration tool, the user needs to prepare the calibration options with the CreateCalibOptions() function. The GRiwrmInputsModel argument contains all the necessary information:

CalibOptions <- CreateCalibOptions(InputsModel)

Calibration

The airGR calibration process is applied on each node of the GRiwrm network from upstream nodes to downstream nodes.

OutputsCalib <- suppressWarnings(
  Calibration(InputsModel, RunOptions, InputsCrit, CalibOptions))
#> Calibration.GRiwrmInputsModel: Treating sub-basin 54095...
#> Grid-Screening in progress (0% 20% 40% 60% 80% 100%)
#>   Screening completed (81 runs)
#>       Param =  247.151,   -0.020,   83.096,    2.384
#>       Crit. KGE2[sqrt(Q)] = 0.9507
#> Steepest-descent local search in progress
#>   Calibration completed (37 iterations, 377 runs)
#>       Param =  305.633,    0.061,   48.777,    2.733
#>       Crit. KGE2[sqrt(Q)] = 0.9578
#> Calibration.GRiwrmInputsModel: Treating sub-basin 54002...
#> Grid-Screening in progress (0% 20% 40% 60% 80% 100%)
#>   Screening completed (81 runs)
#>       Param =  432.681,   -0.020,   20.697,    1.944
#>       Crit. KGE2[sqrt(Q)] = 0.9264
#> Steepest-descent local search in progress
#>   Calibration completed (18 iterations, 209 runs)
#>       Param =  389.753,    0.085,   17.870,    2.098
#>       Crit. KGE2[sqrt(Q)] = 0.9370
#> Calibration.GRiwrmInputsModel: Treating sub-basin 54029...
#> Grid-Screening in progress (0% 20% 40% 60% 80% 100%)
#>   Screening completed (81 runs)
#>       Param =  247.151,   -0.020,   42.098,    1.944
#>       Crit. KGE2[sqrt(Q)] = 0.9541
#> Steepest-descent local search in progress
#>   Calibration completed (32 iterations, 333 runs)
#>       Param =  214.204,   -0.119,   46.754,    2.022
#>       Crit. KGE2[sqrt(Q)] = 0.9696
#> Calibration.GRiwrmInputsModel: Treating sub-basin 54001...
#> Crit. KGE2[sqrt(Q)] = 0.9578
#>  SubCrit. KGE2[sqrt(Q)] cor(sim, obs, "pearson") = 0.9579 
#>  SubCrit. KGE2[sqrt(Q)] cv(sim)/cv(obs)          = 1.0023 
#>  SubCrit. KGE2[sqrt(Q)] mean(sim)/mean(obs)      = 1.0007 
#> 
#> Grid-Screening in progress (0% 20% 40% 60% 80% 100%)
#>   Screening completed (243 runs)
#>       Param =   11.250,  432.681,   -2.376,   20.697,    2.384
#>       Crit. Composite    = 0.8798
#> Steepest-descent local search in progress
#>   Calibration completed (44 iterations, 663 runs)
#>       Param =    1.230,  317.348,   -2.942,   14.296,    2.559
#>       Crit. Composite    = 0.9426
#>  Formula: sum(0.86 * KGE2[sqrt(Q)], 0.14 * GAPX[ParamT])
#> Calibration.GRiwrmInputsModel: Treating sub-basin 54032...
#> Crit. KGE2[sqrt(Q)] = 0.9520
#>  SubCrit. KGE2[sqrt(Q)] cor(sim, obs, "pearson") = 0.9601 
#>  SubCrit. KGE2[sqrt(Q)] cv(sim)/cv(obs)          = 0.9997 
#>  SubCrit. KGE2[sqrt(Q)] mean(sim)/mean(obs)      = 1.0268 
#> 
#> Grid-Screening in progress (0% 20% 40% 60% 80% 100%)
#>   Screening completed (243 runs)
#>       Param =   11.250,  432.681,   -0.649,   83.096,    2.384
#>       Crit. Composite    = 0.8924
#> Steepest-descent local search in progress
#>   Calibration completed (41 iterations, 634 runs)
#>       Param =    1.290, 1211.967,   -1.175,   23.336,    2.364
#>       Crit. Composite    = 0.9598
#>  Formula: sum(0.86 * KGE2[sqrt(Q)], 0.14 * GAPX[ParamT])
#> Calibration.GRiwrmInputsModel: Treating sub-basin 54057...
#> Crit. KGE2[sqrt(Q)] = 0.9669
#>  SubCrit. KGE2[sqrt(Q)] cor(sim, obs, "pearson") = 0.9677 
#>  SubCrit. KGE2[sqrt(Q)] cv(sim)/cv(obs)          = 1.0075 
#>  SubCrit. KGE2[sqrt(Q)] mean(sim)/mean(obs)      = 1.0006 
#> 
#> Grid-Screening in progress (0% 20% 40% 60% 80% 100%)
#>   Screening completed (243 runs)
#>       Param =   11.250,  432.681,   -0.649,   42.098,    2.384
#>       Crit. Composite    = 0.8925
#> Steepest-descent local search in progress
#>   Calibration completed (40 iterations, 625 runs)
#>       Param =    1.290, 1211.967,   -1.175,   23.336,    2.364
#>       Crit. Composite    = 0.9641
#>  Formula: sum(0.85 * KGE2[sqrt(Q)], 0.15 * GAPX[ParamT])
ParamMichel <- sapply(OutputsCalib, "[[", "ParamFinalR")

Run the model with the optimized model parameters

OutputsModels <- RunModel(
  InputsModel,
  RunOptions = RunOptions,
  Param = ParamMichel
)
#> RunModel.GRiwrmInputsModel: Treating sub-basin 54095...
#> RunModel.GRiwrmInputsModel: Treating sub-basin 54002...
#> RunModel.GRiwrmInputsModel: Treating sub-basin 54029...
#> RunModel.GRiwrmInputsModel: Treating sub-basin 54001...
#> RunModel.GRiwrmInputsModel: Treating sub-basin 54032...
#> RunModel.GRiwrmInputsModel: Treating sub-basin 54057...

Plot the results for each basin

plot(OutputsModels, Qobs = Qobs[IndPeriod_Run,])

The resulting flows of each node in m3/s are directly available and can be plotted with these commands:

Qm3s <- attr(OutputsModels, "Qm3s")
plot(Qm3s[1:150,])