feat: handle multi time step supervision and debug multi variable controller

Refs #19

R/CreateSupervisor.R

 #' Create a Supervisor for handling regulation in a model
 #'
 #' @param InputsModel `GRiwrmInputsModel` The inputs of the basin model
+#' @param TimeStep [integer] The number of time steps between each supervision
 #'
 #' @return `Supervisor` object
 #' @export
@@ -23,8 +24,12 @@
 #' PotEvap <- ConvertMeteoSD(griwrm, PotEvapTot)
 #' InputsModel <- CreateInputsModel(griwrm, DatesR, Precip, PotEvap, Qobs)
 #' sv <- CreateSupervisor(InputsModel)
-CreateSupervisor <- function(InputsModel) {
-  if(!inherits(InputsModel, "GRiwrmInputsModel")) stop("`InputsModel` parameter must of class 'GRiwrmInputsModel' (See ?CreateInputsModel.GRiwrm)")
+CreateSupervisor <- function(InputsModel, TimeStep = 1L) {
+  if(!inherits(InputsModel, "GRiwrmInputsModel")) {
+    stop("`InputsModel` parameter must of class 'GRiwrmInputsModel' (See ?CreateInputsModel.GRiwrm)")
+  }
+  if(!is.integer(TimeStep)) stop("`TimeStep` parameter must be an integer")
+
   # Create Supervisor environment from the parent of GlobalEnv
   e <- new.env(parent = parent.env(globalenv()))
   class(e) <- c("Supervisor", class(e))
@@ -39,14 +44,15 @@ CreateSupervisor <- function(InputsModel) {
   e$InputsModel <- InputsModel
   e$griwrm <- attr(InputsModel, "GRiwrm")
   e$OutputsModel <- list()
+  e$.TimeStep <- TimeStep
 
   # Controller list
   e$controllers <- list()
   class(e$controllers) <- c("Controllers", class(e$controllers))
 
   # Copy functions to be used enclosed in the Supervisor environment
-  e$createController <- createController
-  environment(e$createController) <- e
+  e$CreateController <- CreateController
+  environment(e$CreateController) <- e
 
   # Time steps handling: these data are provided by RunModel
   # Index of the current time steps in the modelled time series between 1 and length(RunOptions$Ind_Period)

R/GRiwrm.R

@@ -42,7 +42,6 @@ GRiwrm <- function(db,
                         length = "double",
                         model = "character",
                         area = "double"))
-  rownames(db) <- db$id
   class(db) <- c("GRiwrm", class(db))
   db
 }

R/RunModel.Supervisor.R

@@ -9,7 +9,18 @@
 #' @export
 RunModel.Supervisor <- function(x, RunOptions, Param, ...) {
 
+  # Time steps handling
   x$ts.index0 <- RunOptions[[1]]$IndPeriod_Run[1] - 1
+  ts.start <- RunOptions[[1]]$IndPeriod_Run[1]
+  ts.end <- RunOptions[[1]]$IndPeriod_Run[length(RunOptions[[1]]$IndPeriod_Run)]
+  superTSstarts <- seq(ts.start, ts.end, x$.TimeStep)
+  lSuperTS <- lapply(
+    superTSstarts, function(x, TS, xMax) {
+      seq(x, min(x + TS - 1, xMax))
+    },
+    TS = x$.TimeStep,
+    xMax = ts.end
+  )
 
   # Run runoff model for each sub-basin
   x$OutputsModel <- lapply(X = x$InputsModel, FUN = function(IM) {
@@ -36,19 +47,18 @@ RunModel.Supervisor <- function(x, RunOptions, Param, ...) {
     RunOptions[[id]]$Outputs_Sim <- "StateEnd"
   }
 
-  # Loop over time steps
-  for(iTS in RunOptions[[1]]$IndPeriod_Run) {
+  # Loop over time steps with a step equal to the supervision time step
+  for(iTS in lSuperTS) {
     # Run regulation on the whole basin for the current time step
     x$ts.index <- iTS - x$ts.index0
     x$ts.date <- x$InputsModel[[1]]$DatesR[iTS]
     # Regulation occurs from second time step
-    if(iTS > RunOptions[[1]]$IndPeriod_Run[1]) {
+    if(iTS[1] > ts.start) {
       doSupervision(x)
     }
 
     # Loop over sub-basin using SD model
     for(id in getSD_Ids(x$InputsModel)) {
-
       # Run the SD model for the sub-basin and one time step
       RunOptions[[id]]$IndPeriod_Run <- iTS
       RunOptions[[id]]$IniStates <- unlist(x$OutputsModel[[id]]$StateEnd)
@@ -70,6 +80,6 @@ RunModel.Supervisor <- function(x, RunOptions, Param, ...) {
   for(id in getSD_Ids(x$InputsModel)) {
     x$OutputsModel[[id]]$Qsim <- Qsim[[id]]
   }
-  attr(x$OutputsModel, "Qm3s") <- OutputsModelQsim(x$InputsModel, x$OutputsModel)
+  attr(x$OutputsModel, "Qm3s") <- OutputsModelQsim(x$InputsModel, x$OutputsModel, RunOptions[[1]]$IndPeriod_Run)
   return(x$OutputsModel)
 }

R/createController.R

-#' Create a controller
+#' Create and add a controller in a supervisor
 #'
 #' @details
 #' `ctrl.id` parameter is a unique id for finding the controller in the supervisor.
@@ -24,8 +24,8 @@
 #' # A controller which usually releases 0.1 m3/s and provides
 #' # extra release if the downstream flow is below 0.5 m3/s
 #' logicDamRelease <- function(Y) max(0.5 - Y[1], 0.1)
-#' createController(sv, "DamRelease", Y = c("54001"), U = c("54095"), FUN = logicDamRelease)
-createController <- function(supervisor, ctrl.id, Y, U, FUN){
+#' CreateController(sv, "DamRelease", Y = c("54001"), U = c("54095"), FUN = logicDamRelease)
+CreateController <- function(supervisor, ctrl.id, Y, U, FUN){
 
   if(!is.character(ctrl.id)) stop("Parameter `ctrl.id` should be character")
 
@@ -34,7 +34,9 @@ createController <- function(supervisor, ctrl.id, Y, U, FUN){
   ctrlr <- list(
     id = ctrl.id,
     U = createControl(U),
+    Unames = U,
     Y = createControl(Y),
+    Ynames = Y,
     FUN = FUN
   )
   class(ctrlr) <- c("Controller", class(ctrlr))
@@ -53,9 +55,8 @@ createController <- function(supervisor, ctrl.id, Y, U, FUN){
 #'
 #' @param locations vector of [character] containing the location of the variable in the model (see details)
 #'
-#' @return [data.frame] of two columns:
-#' - 'loc' [character]: the locations of the variables
-#' - 'v' [numeric]: the value of the variable for the current time step which is [NA] at its creation
+#' @return a [matrix] with each column is the location of the variables and the rows
+#' the values of the variable for the current time steps (empty by default)
 #' @export
 #'
 #' @examples
@@ -65,5 +66,6 @@ createControl <- function(locations) {
   if(!is.character(locations)) {
     stop("Parameter `locations` should be character")
   }
-  data.frame(loc = locations, v = rep(NA, length(locations)))
+  m <- matrix(NA, ncol = length(locations), nrow = 0)
+  return(m)
 }

R/utils.R

@@ -50,15 +50,16 @@ getDataFromLocation <- function(loc, sv) {
 
 #' Write data to model input for the current time step
 #'
-#' @param control [vector] A row of the `U` [data.frame] from a `Controller`
+#' @param ctrlr a `Controller` object (See [CreateController])
 #' @param sv `Supervisor` (See [CreateSupervisor])
 #'
 #' @return [NULL]
-setDataToLocation <- function(control, sv) {
-  node <- sv$griwrm$down[sv$griwrm$id == control[1]]
-  # ! Qupstream contains warm up period and run period => the index is shifted
-  sv$InputsModel[[node]]$Qupstream[sv$ts.index0 + sv$ts.index, control[1]] <-
-    as.numeric(control[2])
+setDataToLocation <- function(ctrlr, sv) {
+  l <- lapply(seq(length(ctrlr$Unames)), function(i) {
+    node <- sv$griwrm$down[sv$griwrm$id == ctrlr$Unames[i]]
+    # ! Qupstream contains warm up period and run period => the index is shifted
+    sv$InputsModel[[node]]$Qupstream[sv$ts.index0 + sv$ts.index, ctrlr$Unames[i]] <- ctrlr$U[,i]
+  })
 }
 
 
@@ -66,21 +67,22 @@ setDataToLocation <- function(control, sv) {
 #'
 #' @param supervisor `Supervisor` (See [CreateSupervisor])
 #'
-#' @return [NULL]
 doSupervision <- function(supervisor) {
   for (id in names(supervisor$controllers)) {
     # Read Y from locations in the model
-    supervisor$controllers[[id]]$Y$v <-
-      sapply(supervisor$controllers[[id]]$Y$loc, getDataFromLocation, sv = supervisor)
+    supervisor$controllers[[id]]$Y <- do.call(
+      cbind,
+      lapply(supervisor$controllers[[id]]$Ynames, getDataFromLocation, sv = supervisor)
+    )
     # Run logic
-    supervisor$controllers[[id]]$U$v <-
-      sapply(supervisor$controllers[[id]]$Y$v, supervisor$controllers[[id]]$FUN)
+    supervisor$controllers[[id]]$U <-
+      supervisor$controllers[[id]]$FUN(supervisor$controllers[[id]]$Y)
     # Write U to locations in the model
-    apply(supervisor$controllers[[id]]$U, 1, setDataToLocation, sv = supervisor)
+    setDataToLocation(supervisor$controllers[[id]], sv = supervisor)
   }
-  return()
 }
 
+
 #' Check the parameters of RunModel methods
 #'
 #' Stop the execution if an error is detected.
@@ -89,13 +91,10 @@ doSupervision <- function(supervisor) {
 #' @param RunOptions a `GRiwrmRunOptions` object (See [CreateRunOptions.GRiwrmInputsModel])
 #' @param Param a [list] of [numeric] containing model parameters of each node of the network
 #'
-#' @return [NULL]
-#'
 checkRunModelParameters <- function(InputsModel, RunOptions, Param) {
   if(!inherits(InputsModel, "GRiwrmInputsModel")) stop("`InputsModel` parameter must of class 'GRiwrmRunoptions' (See ?CreateRunOptions.GRiwrmInputsModel)")
   if(!inherits(RunOptions, "GRiwrmRunOptions")) stop("Argument `RunOptions` parameter must of class 'GRiwrmRunOptions' (See ?CreateRunOptions.GRiwrmInputsModel)")
   if(!is.list(Param) || !all(names(InputsModel) %in% names(Param))) stop("Argument `Param` must be a list with names equal to nodes IDs")
-  return()
 }
 
 

tests/testthat/test-RunModel.R

@@ -50,29 +50,32 @@ test_that("RunModelSupervisor with no regulation should returns same results as
   expect_equal(OM_Supervisor[["54057"]]$Qsim, OM_GriwrmInputs[["54057"]]$Qsim)
 })
 
+# Add 2 nodes to the network
+griwrm2 <- rbind(griwrm,
+                 data.frame(
+                   id = c("R1", "R2"),
+                   down = "54057",
+                   length = 100000,
+                   area = NA,
+                   model = NA
+                 ))
+# Add Qobs for the 2 new nodes and create InputsModel
+Qobs2 <- cbind(Qobs, matrix(data = rep(0, 2*nrow(Qobs)), ncol = 2))
+colnames(Qobs2) <- c(colnames(Qobs2)[1:6], "R1", "R2")
+InputsModel <- CreateInputsModel(griwrm2, DatesR, Precip, PotEvap, Qobs2)
+
 test_that("RunModelSupervisor with two regulations that cancel each other out should returns same results as RunModel.GRiwrmInputsModel", {
-  # Add 2 nodes to the network
-  griwrm2 <- rbind(griwrm,
-                  data.frame(
-                    id = c("R1", "R2"),
-                    down = "54057",
-                    length = 100000,
-                    area = NA,
-                    model = NA
-                  ))
-  # Add Qobs for the 2 new nodes
-  Qobs2 <- cbind(Qobs, matrix(data = rep(0, 2*nrow(Qobs)), ncol = 2))
-  colnames(Qobs2) <- c(colnames(Qobs2)[1:6], "R1", "R2")
-  InputsModel <- CreateInputsModel(griwrm2, DatesR, Precip, PotEvap, Qobs2)
+  # Create Supervisor
   sv <- CreateSupervisor(InputsModel)
   # Function to withdraw half of the measured flow
   fWithdrawal <- function(y) { -y/2 }
   # Function to release half of the the measured flow
   fRelease <- function(y) { y/2 }
   # Controller that withdraw half of the flow measured at node "54002" at location "R1"
-  createController(sv, "Withdrawal", Y = c("54002"), U = c("R1"), FUN = fWithdrawal)
+  CreateController(sv, "Withdrawal", Y = c("54002"), U = c("R1"), FUN = fWithdrawal)
   # Controller that release half of the flow measured at node "54002" at location "R2"
-  createController(sv, "Release", Y = c("54002"), U = c("R2"), FUN = fRelease)
+  CreateController(sv, "Release", Y = c("54002"), U = c("R2"), FUN = fRelease)
+
   OM_Supervisor <- RunModel(
     sv,
     RunOptions = RunOptions,
@@ -81,3 +84,16 @@ test_that("RunModelSupervisor with two regulations that cancel each other out sh
   expect_equal(OM_Supervisor[["54057"]]$Qsim, OM_GriwrmInputs[["54057"]]$Qsim)
 })
 
+test_that("RunModelSupervisor with multi time steps controller, two regulations in 1 centralised controller that cancel each other out should returns same results as RunModel.GRiwrmInputsModel", {
+  sv <- CreateSupervisor(InputsModel, TimeStep = 10L)
+  fEverything <- function(y) {
+    matrix(c(y[,1]/2, -y[,1]/2), ncol = 2)
+  }
+  CreateController(sv, "Everything", Y = c("54002", "54032"), U = c("R1", "R2"), FUN = fEverything)
+  OM_Supervisor <- RunModel(
+    sv,
+    RunOptions = RunOptions,
+    Param = Param
+  )
+  expect_equal(OM_Supervisor[["54057"]]$Qsim, OM_GriwrmInputs[["54057"]]$Qsim)
+})

vignettes/V01_Structure_SD_model.Rmd

@@ -16,7 +16,7 @@ knitr::opts_chunk$set(echo = TRUE)
 library(airGRiwrm)
 ```
 
-The package **airGRiwrm** is a modeling tool for integrated water resource management based on the package **airGR** package [See @coron_airgr_2020].
+The package **airGRiwrm** is a modeling tool for integrated water resource management based on the package **airGR** package [See @coronSuiteLumpedGR2017].
 
 In a semi-distributive model, the catchment is divided into several sub-catchments. Each sub-catchment is an hydrological entity where a runfall-runoff model produces a flow time series at the outlet of the sub-catchment. Then a hydraulic link is set between sub-catchment outlets to model the flow at the outlet of the whole catchment. The aim of **airGRiwrm** is to organise the structure and schedule the execution of the hydrological and hydraulic sub-models contained in the semi-distributive model.
 
@@ -24,7 +24,7 @@ In this vignette, we show how to prepare observation data for the model.
 
 ## Description of the example used in this tutorial
 
-The example of this tutorial takes place on the Severn River in United Kingdom. The data set comes from the CAMEL GB database [See @coxon_catchment_2020].
+The example of this tutorial takes place on the Severn River in United Kingdom. The data set comes from the CAMEL GB database [See @coxonCatchmentAttributesHydrometeorological2020].
 
 ```{r}
 data(Severn)

vignettes/V03_Open-loop_influenced_flow.Rmd

@@ -23,7 +23,7 @@ library(airGRiwrm)
 
 
 
-We can see in vignette 'V02_Calibration_SD_model' that calibration result for the flow simulated on the Avon at Evesham (Gauging station '54002') and on the Severn at Buildwas (Gauging station '54095') is not satisfactory. These upper basins are heavily influenced by impoundments and inter-basin transfers [@higgs_hydrological_1988].
+We can see in vignette 'V02_Calibration_SD_model' that calibration result for the flow simulated on the Avon at Evesham (Gauging station '54002') and on the Severn at Buildwas (Gauging station '54095') is not satisfactory. These upper basins are heavily influenced by impoundments and inter-basin transfers [@higgsHydrologicalChangesRiver1988].
 
 To cope with this influenced flow, we won't try to simulate it with a hydrological model and we will directly inject in the model the observed flow at these nodes.
 
@@ -42,10 +42,10 @@ load("_cache/V01.RData")
 To notify the SD model that the provided flow on a node should be directly used instead of an hydrological model, you only need to declare its model as `NA`:
 
 ```{r}
-griwrm_OL <- griwrm
-griwrm_OL$model[griwrm$id == "54002"] <- NA
-griwrm_OL$model[griwrm$id == "54095"] <- NA
-griwrm_OL
+griwrmV03 <- griwrm
+griwrmV03$model[griwrm$id == "54002"] <- NA
+griwrmV03$model[griwrm$id == "54095"] <- NA
+griwrmV03
 ```
 
 Here, we keep the area of this basin which means that the discharge will be provided in mm per time step. If the discharge is provided in m<sup>3</sup>/s, then the area should be set to `NA` and downstream basin areas should be modified subsequently. 
@@ -57,7 +57,7 @@ The diagram of the network structure is represented below with:
   * in red the node with direct flow injection (no hydrological model)
 
 ```{r diagram}
-DiagramGRiwrm(griwrm_OL)
+DiagramGRiwrm(griwrmV03)
 ```
 
 ### Generate the GRiwrmInputsModel object
@@ -66,7 +66,7 @@ Since the network description has changed, the `GRiwrmInputsModel` should be gen
 
 ```{r}
 load("_cache/V01b.RData")
-IM_OL <- CreateInputsModel(griwrm_OL, DatesR, Precip, PotEvap, Qobs)
+IM_OL <- CreateInputsModel(griwrmV03, DatesR, Precip, PotEvap, Qobs)
 ```
 
 ## Calibration of the new model
@@ -82,16 +82,21 @@ The **airGR** calibration process is applied on each hydrological node of the `G
 ```{r Calibration}
 OC_OL <- suppressWarnings(
   Calibration(IM_OL, RunOptions, InputsCrit, CalibOptions))
-Param_OL <- sapply(griwrm$id, function(x) {OC_OL[[x]]$Param})
+ParamV03 <- sapply(griwrm$id, function(x) {OC_OL[[x]]$Param})
 ```
 
+```{r}
+save(griwrmV03, ParamV03, file = "_cache/V03.RData")
+```
+
+
 ## Run model with this newly calibrated parameters
 
 ```{r RunModel}
 OM_OL <- RunModel(
   IM_OL,
   RunOptions = RunOptions,
-  Param = Param_OL
+  Param = ParamV03
 )
 ```
 

vignettes/airGRiwrm.bib

 
-@misc{coxon_catchment_2020,
-	title = {Catchment attributes and hydro-meteorological timeseries for 671 catchments across Great Britain ({CAMELS}-{GB})},
-	rights = {This resource is available under the terms of the Open Government Licence},
-	url = {https://catalogue.ceh.ac.uk/id/8344e4f3-d2ea-44f5-8afa-86d2987543a9},
-	abstract = {This dataset provides hydro-meteorological timeseries and landscape attributes for 671 catchments across Great Britain. It collates river flows, catchment attributes and catchment boundaries from the {UK} National River Flow Archive together with a suite of new meteorological timeseries and catchment attributes. Daily timeseries for the time period 1st October 1970 to the 30th September 2015 are provided for a range of hydro-meteorological data (including rainfall, potential evapotranspiration, temperature, radiation, humidity and flow). A comprehensive set of catchment attributes are quantified describing a range of catchment characteristics including topography, climate, hydrology, land cover, soils, hydrogeology, human influences and discharge uncertainty. This dataset is intended for the community as a freely available, easily accessible dataset to use in a wide range of environmental data and modelling analyses. A research paper (Coxon et al, {CAMELS}-{GB}: Hydrometeorological time series and landscape attributes for 671 catchments in Great Britain) describing the dataset in detail will be made available in Earth System Science Data (https://www.earth-system-science-data.net/).},
-	publisher = {{NERC} Environmental Information Data Centre},
-	author = {Coxon, G. and Addor, N. and Bloomfield, J.P. and Freer, J. and Fry, M. and Hannaford, J. and Howden, N.J.K. and Lane, R. and Lewis, M. and Robinson, E.L. and Wagener, T. and Woods, R.},
-	editora = {Coxon, Gemma and Environmental Information Data Centre},
-	editoratype = {collaborator},
-	urldate = {2020-12-18},
-	date = {2020},
-	langid = {english},
-	doi = {10.5285/8344E4F3-D2EA-44F5-8AFA-86D2987543A9},
-	note = {Medium: text/csv Comma-separated values ({CSV}),Shapefile
-type: dataset},
-	keywords = {Hydrology}
+@article{burtIrrigationPerformanceMeasures1997,
+  title = {Irrigation {{Performance Measures}}: {{Efficiency}} and {{Uniformity}}},
+  shorttitle = {Irrigation {{Performance Measures}}},
+  author = {Burt, C. M. and Clemmens, A. J. and Strelkoff, T. S. and Solomon, K. H. and Bliesner, R. D. and Hardy, L. A. and Howell, T. A. and Eisenhauer, D. E.},
+  year = {1997},
+  month = nov,
+  volume = {123},
+  pages = {423--442},
+  publisher = {{American Society of Civil Engineers}},
+  issn = {0733-9437},
+  doi = {10.1061/(ASCE)0733-9437(1997)123:6(423)},
+  abstract = {It is essential to standardize the definitions and approaches to quantifying various irrigation performance measures. The ASCE Task Committee on Defining Irrigation Efficiency and Uniformity provides a comprehensive examination of various performance indices such as irrigation efficiency, application efficiency, irrigation sagacity, distribution uniformity, and others. Consistency is provided among different irrigation methods and different scales. Clarification of common points of confusion is provided, and methods are proposed whereby the accuracy of numerical values of the performance indicators can be assessed. This issue has two companion papers that provide more detailed information on statistical distribution uniformity and the accuracy of irrigation efficiency estimates.},
+  copyright = {Copyright \textcopyright{} 1997 American Society of Civil Engineers},
+  file = {C\:\\Users\\david.dorchies\\Zotero\\storage\\D9Q9VV6J\\Burt et al. - 1997 - Irrigation Performance Measures Efficiency and Un.pdf;C\:\\Users\\david.dorchies\\Zotero\\storage\\5NLYUVSN\\(ASCE)0733-9437(1997)1236(423).html},
+  journal = {Journal of Irrigation and Drainage Engineering},
+  language = {EN},
+  number = {6}
 }
 
-@article{coron_suite_2017,
-	title = {The suite of lumped {GR} hydrological models in an R package},
-	volume = {94},
-	issn = {13648152},
-	url = {https://linkinghub.elsevier.com/retrieve/pii/S1364815217300208},
-	doi = {10.1016/j.envsoft.2017.05.002},
-	pages = {166--171},
-	journaltitle = {Environmental Modelling \& Software},
-	shortjournal = {Environmental Modelling \& Software},
-	author = {Coron, L. and Thirel, G. and Delaigue, O. and Perrin, C. and Andréassian, V.},
-	urldate = {2020-12-18},
-	date = {2017-08},
-	langid = {english}
+@article{coronSuiteLumpedGR2017,
+  title = {The Suite of Lumped {{GR}} Hydrological Models in an {{R}} Package},
+  author = {Coron, L. and Thirel, G. and Delaigue, O. and Perrin, C. and Andr{\'e}assian, V.},
+  year = {2017},
+  month = aug,
+  volume = {94},
+  pages = {166--171},
+  issn = {1364-8152},
+  doi = {10.1016/j.envsoft.2017.05.002},
+  abstract = {Lumped hydrological models are catchment-scale representations of the transformation of precipitation into discharge. They are widely-used tools for real-time flow forecasting, flood design and climate change impact assessment, and they are often used for training and educational purposes. This article presents an R-package, airGR, to facilitate the implementation of the GR lumped hydrological models (including GR4J) and a snow-accumulation and melt model. The package allows users to calibrate and run hourly to annual models on catchment sets and to analyse their outputs. While the core of the models is implemented in Fortran, the user can manage the input/output data within R. A number of options and plotting functions are proposed to ease automate tests and analyses of the results. The codes are flexible enough to include external models, other calibration routines or efficiency criteria. To illustrate the features of airGR, we present one application example for a French mountainous catchment.},
+  file = {C\:\\Users\\david.dorchies\\Zotero\\storage\\J94F6IEJ\\Coron et al. - 2017 - The suite of lumped GR hydrological models in an R.pdf;C\:\\Users\\david.dorchies\\Zotero\\storage\\47JDT6WA\\S1364815217300208.html},
+  journal = {Environmental Modelling \& Software},
+  keywords = {Calibration,Flow simulation,Hydrological modelling,Lumped models,Parsimony,R package},
+  language = {en}
 }
 
-@misc{coron_airgr_2020,
-	title = {{airGR}: Suite of {GR} Hydrological Models for Precipitation-Runoff Modelling. R package version 1.4.3.65.},
-	url = {https://data.inra.fr/citation?persistentId=doi:10.15454/EX11NA},
-	shorttitle = {{airGR}},
-	abstract = {Hydrological modelling tools developed at {INRAE}-Antony ({HYCAR} Research Unit, France). The package includes several conceptual rainfall-runoff models ({GR}4H, {GR}5H, {GR}4J, {GR}5J, {GR}6J, {GR}2M, {GR}1A), a snow accumulation and melt model ({CemaNeige}) and the associated functions for their calibration and evaluation. Use help({airGR}) for package description and references.},
-	publisher = {Portail Data {INRAE}},
-	author = {Coron, Laurent and Delaigue, Olivier and Thirel, Guillaume and Perrin, Charles and Michel, Claude},
-	editora = {Delaigue, Olivier},
-	editoratype = {collaborator},
-	urldate = {2020-12-18},
-	date = {2020},
-	doi = {10.15454/EX11NA},
-	note = {type: dataset}
+@misc{coxonCatchmentAttributesHydrometeorological2020,
+  title = {Catchment Attributes and Hydro-Meteorological Timeseries for 671 Catchments across {{Great Britain}} ({{CAMELS}}-{{GB}})},
+  author = {Coxon, G. and Addor, N. and Bloomfield, J.P. and Freer, J. and Fry, M. and Hannaford, J. and Howden, N.J.K. and Lane, R. and Lewis, M. and Robinson, E.L. and Wagener, T. and Woods, R.},
+  year = {2020},
+  publisher = {{NERC Environmental Information Data Centre}},
+  doi = {10.5285/8344E4F3-D2EA-44F5-8AFA-86D2987543A9},
+  abstract = {This dataset provides hydro-meteorological timeseries and landscape attributes for 671 catchments across Great Britain. It collates river flows, catchment attributes and catchment boundaries from the UK National River Flow Archive together with a suite of new meteorological timeseries and catchment attributes. Daily timeseries for the time period 1st October 1970 to the 30th September 2015 are provided for a range of hydro-meteorological data (including rainfall, potential evapotranspiration, temperature, radiation, humidity and flow). A comprehensive set of catchment attributes are quantified describing a range of catchment characteristics including topography, climate, hydrology, land cover, soils, hydrogeology, human influences and discharge uncertainty. This dataset is intended for the community as a freely available, easily accessible dataset to use in a wide range of environmental data and modelling analyses. A research paper (Coxon et al, CAMELS-GB: Hydrometeorological time series and landscape attributes for 671 catchments in Great Britain) describing the dataset in detail will be made available in Earth System Science Data (https://www.earth-system-science-data.net/).},
+  collaborator = {Coxon, Gemma and Environmental Information Data Centre},
+  copyright = {This resource is available under the terms of the Open Government Licence},
+  keywords = {Hydrology},
+  language = {en}
 }
 
-@article{higgs_hydrological_1988,
-	title = {Hydrological changes and river regulation in the {UK}},
-	volume = {2},
-	issn = {1099-1646},
-	url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/rrr.3450020312},
-	doi = {https://doi.org/10.1002/rrr.3450020312},
-	abstract = {Water levels of streams and rivers in the United Kingdom have been regulated by weirs for more than one thousand years, but regulation of the flow regime by impoundments began in the latter half on the 19th Century. Organized river flow measurements were not undertaken until 1935, and today the average record length is about 20 years. Only three gauging stations have provided data suitable for pre- and post-impoundment comparisons. Other studies have relied on the comparison of regulated and naturalized discharges. In either case climate and land-use changes make evaluation of the hydrological effect of impoundments problematic. This paper reviews research on hydrological changes due to river regulation in the {UK}, and presents a case study of the River Severn to evaluate the influence of Clywedog Reservoir on flood magnitude and frequency. Consequent upon dam completion, on average, median flows have been reduced by about 50per cent; mean annual floods have been reduced by about 30per cent; and low flows have been maintained at about 22 per cent higher than the natural Q95 discharge. However, marked differences exist between rivers. The direct effect of reservoir compensation flows and the indirect effect of inter basin transfers for supply have significantly increased minimum flows in most rivers, although in the case of the latter this involves the discharge of treated effluents. In contrast, the effects of impoundments on flood magnitude and frequency is less clear and on the River Severn, at least, changes in flood hydrology during the past two decades are shown to be more related to climate change than to river regulation.},
-	pages = {349--368},
-	number = {3},
-	journaltitle = {Regulated Rivers: Research \& Management},
-	author = {Higgs, Gary and Petts, Geoff},
-	urldate = {2020-12-26},
-	date = {1988},
-	langid = {english},
-	note = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1002/rrr.3450020312},
-	keywords = {Floods, Dry weather flow, Flow regime},
-	file = {Higgs et Petts - 1988 - Hydrological changes and river regulation in the U.pdf:C\:\\Users\\david.dorchies\\Zotero\\storage\\VIG8TKGU\\Higgs et Petts - 1988 - Hydrological changes and river regulation in the U.pdf:application/pdf;Snapshot:C\:\\Users\\david.dorchies\\Zotero\\storage\\74LGCRCE\\rrr.html:text/html}
+@article{graftonParadoxIrrigationEfficiency2018,
+  title = {The Paradox of Irrigation Efficiency},
+  author = {Grafton, R. Q. and Williams, J. and Perry, C. J. and Molle, F. and Ringler, C. and Steduto, P. and Udall, B. and Wheeler, S. A. and Wang, Y. and Garrick, D. and Allen, R. G.},
+  year = {2018},
+  month = aug,
+  volume = {361},
+  pages = {748--750},
+  publisher = {{American Association for the Advancement of Science}},
+  issn = {0036-8075, 1095-9203},
+  doi = {10.1126/science.aat9314},
+  abstract = {Higher efficiency rarely reduces water consumption Higher efficiency rarely reduces water consumption},
+  chapter = {Policy Forum},
+  copyright = {Copyright \textcopyright{} 2018, American Association for the Advancement of Science. http://www.sciencemag.org/about/science-licenses-journal-article-reuseThis is an article distributed under the terms of the Science Journals Default License.},
+  file = {C\:\\Users\\david.dorchies\\Zotero\\storage\\VIHQIB84\\Grafton et al. - 2018 - The paradox of irrigation efficiency.pdf;C\:\\Users\\david.dorchies\\Zotero\\storage\\XDKSCJIX\\748.html},
+  journal = {Science},
+  language = {en},
+  number = {6404},
+  pmid = {30139857}
 }
 
-@article{reynard_flood_2001,
-	title = {The Flood Characteristics of Large U.K. Rivers: Potential Effects of Changing Climate and Land Use},
-	volume = {48},
-	issn = {1573-1480},
-	url = {https://doi.org/10.1023/A:1010735726818},
-	doi = {10.1023/A:1010735726818},
-	shorttitle = {The Flood Characteristics of Large U.K. Rivers},
-	abstract = {A continuous flow simulation model({CLASSIC}) has been used to assess the potential impactof climate and land use changes on the flood regimesof large U.K. catchments. Climate change scenarios,based on the {HadCM}2 experiments from the {HadleyCentre}, are applied to the Severn and Thames rivers.The analysis shows that, for the 2050s, the climatechange scenarios result in an increase in both thefrequency and magnitude of flooding events in theserivers. The various ways of applying the rainfallscenario can have a significant effect on thesegeneral conclusions, although generally do not affecteither the direction or consistency of the changes.While ‘best guess’ land use changes show little impacton flood response, a 50\% increase in forest covercould counter-act the impact of climate change. Aswould be expected, a large change in the urban coverof the catchments does have a large effect on theflood regimes, increasing both the frequency andmagnitude of floods significantly beyond the changesdue to climate alone. Further research is requiredinto the potential impacts of seasonal changes in thedaily rainfall and potential evaporation regimes, landuse changes and the interaction between the two.},
-	pages = {343--359},
-	number = {2},
-	journaltitle = {Climatic Change},
-	shortjournal = {Climatic Change},
-	author = {Reynard, N. S. and Prudhomme, C. and Crooks, S. M.},
-	urldate = {2020-12-26},
-	date = {2001-02-01},
-	langid = {english},
-	file = {Reynard et al. - 2001 - The Flood Characteristics of Large U.K. Rivers Po.pdf:C\:\\Users\\david.dorchies\\Zotero\\storage\\6CMCZNJV\\Reynard et al. - 2001 - The Flood Characteristics of Large U.K. Rivers Po.pdf:application/pdf}
+@techreport{gustardStudyCompensationFlows1987,
+  title = {A Study of Compensation Flows in the {{UK}}},
+  author = {Gustard, Alan and Cole, Gwyneth and Marshall, David and Bayliss, Adrian},
+  year = {1987},
+  month = nov,
+  pages = {170},
+  institution = {{Institute of Hydrology}},
+  file = {C\:\\Users\\david.dorchies\\Zotero\\storage\\Z3VSBM2Y\\Gustard et al. - 1987 - A study of compensation flows in the UK.pdf}
 }
 
-@article{jolley_large-scale_1996,
-	title = {A Large-Scale Grid-Based Hydrological Model of the Severn and Thames Catchments},
-	volume = {10},
-	issn = {1747-6593},
-	url = {https://onlinelibrary.wiley.com/doi/abs/10.1111/j.1747-6593.1996.tb00043.x},
-	doi = {https://doi.org/10.1111/j.1747-6593.1996.tb00043.x},
-	abstract = {This paper addresses the issues of scale and appropriate model complexity for large-scale hydrological models. A grid-based hydrological model, which employs the {UK} Meteorological Office Rainfall and Evaporation Calculation System, is applied to the Severn and Thames catchments using a grid scale of 40 km, and is shown to reproduce the observed mean annual runoff over a 10-year period to within 6\% with no prior calibration. The variation in the model performance is strongly correlated with the linearity of the annual rainfall/runoff relationship and a climate index. At the monthly scale, runoff routing becomes significant, and the introduction of a two-parameter routeing algorithm significantly improves the monthly runoff simulations giving efficiencies of 90\% and 88\% for the Severn and Thames respectively. The results provide guidance to climate modellers looking for efficient and robust land-surface parameterizations, and indicate the potential application of such a modelling scheme to water resource managers.},
-	pages = {253--262},
-	number = {4},
-	journaltitle = {Water and Environment Journal},
-	author = {Jolley, T. J. and Wheater, H. S.},
-	urldate = {2020-12-26},
-	date = {1996},
-	langid = {english},
-	note = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1747-6593.1996.tb00043.x},
-	keywords = {Climate models, runoff, Severn, Thames, water resources, water-balance model},
-	file = {Jolley et Wheater - 1996 - A Large-Scale Grid-Based Hydrological Model of the.pdf:C\:\\Users\\david.dorchies\\Zotero\\storage\\AKJEZFAY\\Jolley et Wheater - 1996 - A Large-Scale Grid-Based Hydrological Model of the.pdf:application/pdf;Snapshot:C\:\\Users\\david.dorchies\\Zotero\\storage\\4G5L69X5\\j.1747-6593.1996.tb00043.html:text/html}
-}
\ No newline at end of file
+@article{higgsHydrologicalChangesRiver1988,
+  title = {Hydrological Changes and River Regulation in the {{UK}}},
+  author = {Higgs, Gary and Petts, Geoff},
+  year = {1988},
+  volume = {2},
+  pages = {349--368},
+  issn = {1099-1646},
+  doi = {10.1002/rrr.3450020312},
+  abstract = {Water levels of streams and rivers in the United Kingdom have been regulated by weirs for more than one thousand years, but regulation of the flow regime by impoundments began in the latter half on the 19th Century. Organized river flow measurements were not undertaken until 1935, and today the average record length is about 20 years. Only three gauging stations have provided data suitable for pre- and post-impoundment comparisons. Other studies have relied on the comparison of regulated and naturalized discharges. In either case climate and land-use changes make evaluation of the hydrological effect of impoundments problematic. This paper reviews research on hydrological changes due to river regulation in the UK, and presents a case study of the River Severn to evaluate the influence of Clywedog Reservoir on flood magnitude and frequency. Consequent upon dam completion, on average, median flows have been reduced by about 50per cent; mean annual floods have been reduced by about 30per cent; and low flows have been maintained at about 22 per cent higher than the natural Q95 discharge. However, marked differences exist between rivers. The direct effect of reservoir compensation flows and the indirect effect of inter basin transfers for supply have significantly increased minimum flows in most rivers, although in the case of the latter this involves the discharge of treated effluents. In contrast, the effects of impoundments on flood magnitude and frequency is less clear and on the River Severn, at least, changes in flood hydrology during the past two decades are shown to be more related to climate change than to river regulation.},
+  annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1002/rrr.3450020312},
+  file = {C\:\\Users\\david.dorchies\\Zotero\\storage\\Q4EWWR7A\\Higgs et Petts - 1988 - Hydrological changes and river regulation in the U.pdf;C\:\\Users\\david.dorchies\\Zotero\\storage\\CI9TWW3V\\rrr.html},
+  journal = {Regulated Rivers: Research \& Management},
+  keywords = {Dry weather flow,Floods,Flow regime},
+  language = {en},
+  number = {3}
+}
+
+@article{jolleyLargeScaleGridBasedHydrological1996,
+  title = {A {{Large}}-{{Scale Grid}}-{{Based Hydrological Model}} of the {{Severn}} and {{Thames Catchments}}},
+  author = {Jolley, T. J. and Wheater, H. S.},
+  year = {1996},
+  volume = {10},
+  pages = {253--262},
+  issn = {1747-6593},
+  doi = {10.1111/j.1747-6593.1996.tb00043.x},
+  abstract = {This paper addresses the issues of scale and appropriate model complexity for large-scale hydrological models. A grid-based hydrological model, which employs the UK Meteorological Office Rainfall and Evaporation Calculation System, is applied to the Severn and Thames catchments using a grid scale of 40 km, and is shown to reproduce the observed mean annual runoff over a 10-year period to within 6\% with no prior calibration. The variation in the model performance is strongly correlated with the linearity of the annual rainfall/runoff relationship and a climate index. At the monthly scale, runoff routing becomes significant, and the introduction of a two-parameter routeing algorithm significantly improves the monthly runoff simulations giving efficiencies of 90\% and 88\% for the Severn and Thames respectively. The results provide guidance to climate modellers looking for efficient and robust land-surface parameterizations, and indicate the potential application of such a modelling scheme to water resource managers.},
+  annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1111/j.1747-6593.1996.tb00043.x},
+  file = {C\:\\Users\\david.dorchies\\Zotero\\storage\\NIH9WIPD\\Jolley et Wheater - 1996 - A Large-Scale Grid-Based Hydrological Model of the.pdf;C\:\\Users\\david.dorchies\\Zotero\\storage\\2T597AZG\\j.1747-6593.1996.tb00043.html},
+  journal = {Water and Environment Journal},
+  keywords = {Climate models,runoff,Severn,Thames,water resources,water-balance model},
+  language = {en},
+  number = {4}
+}
+
+@article{klaarDevelopingHydroecologicalModels2014,
+  title = {Developing Hydroecological Models to Inform Environmental Flow Standards: A Case Study from {{England}}},
+  shorttitle = {Developing Hydroecological Models to Inform Environmental Flow Standards},
+  author = {Klaar, Megan J. and Dunbar, Michael J. and Warren, Mark and Soley, Rob},
+  year = {2014},
+  volume = {1},
+  pages = {207--217},
+  issn = {2049-1948},
+  doi = {10.1002/wat2.1012},
+  abstract = {The concept of defining environmental flow regimes to balance the provision of water resources for both human and environmental needs has gained wide recognition. As the authority responsible for water resource management within England, the Environment Agency (EA) uses the Environmental Flow Indicator (EFI), which represents an allowable percentage deviation from the natural flow to determine where water may be available for new abstractions. In a simplified form, the EFI has been used as the hydrological supporting component of Water Framework Directive classification, to flag where hydrological alteration may be contributing to failure to achieve good ecological status, and to guide further ecological investigation. As the primary information source for the EFI was expert opinion, the EA aims to improve the evidence base linking flow alteration and ecological response, and to use this evidence to develop improved environmental flow criteria and implementation tools. Such tools will be required to make predictions at locations with no or limited ecological monitoring data. Hence empirical statistical models are required that provide a means to describe observed variation in ecological sensitivity to flow change. Models must also strike a balance between generic and local relationships. Multilevel (mixed effects) regression models provide a rich set of capabilities suitable for this purpose. Three brief examples of the application of these techniques in defining empirical relationships between flow alteration and ecological response are provided. Establishment of testable hydrological\textendash ecological relationships provides the framework for improving data collection, analysis, and ultimately water resources management models. This article is categorized under: Water and Life {$>$} Conservation, Management, and Awareness},
+  annotation = {\_eprint: https://onlinelibrary.wiley.com/doi/pdf/10.1002/wat2.1012},
+  copyright = {\textcopyright{} 2014 Wiley Periodicals, Inc.},
+  file = {C\:\\Users\\david.dorchies\\Zotero\\storage\\RNDY5IW9\\wat2.html},
+  journal = {WIREs Water},
+  language = {en},
+  number = {2}
+}
+
+@article{reynardFloodCharacteristicsLarge2001,
+  title = {The {{Flood Characteristics}} of {{Large U}}.{{K}}. {{Rivers}}: {{Potential Effects}} of {{Changing Climate}} and {{Land Use}}},
+  shorttitle = {The {{Flood Characteristics}} of {{Large U}}.{{K}}. {{Rivers}}},
+  author = {Reynard, N. S. and Prudhomme, C. and Crooks, S. M.},
+  year = {2001},
+  month = feb,
+  volume = {48},
+  pages = {343--359},
+  issn = {1573-1480},
+  doi = {10.1023/A:1010735726818},
+  abstract = {A continuous flow simulation model(CLASSIC) has been used to assess the potential impactof climate and land use changes on the flood regimesof large U.K. catchments. Climate change scenarios,based on the HadCM2 experiments from the HadleyCentre, are applied to the Severn and Thames rivers.The analysis shows that, for the 2050s, the climatechange scenarios result in an increase in both thefrequency and magnitude of flooding events in theserivers. The various ways of applying the rainfallscenario can have a significant effect on thesegeneral conclusions, although generally do not affecteither the direction or consistency of the changes.While `best guess' land use changes show little impacton flood response, a 50\% increase in forest covercould counter-act the impact of climate change. Aswould be expected, a large change in the urban coverof the catchments does have a large effect on theflood regimes, increasing both the frequency andmagnitude of floods significantly beyond the changesdue to climate alone. Further research is requiredinto the potential impacts of seasonal changes in thedaily rainfall and potential evaporation regimes, landuse changes and the interaction between the two.},
+  file = {C\:\\Users\\david.dorchies\\Zotero\\storage\\PZTI9ZQE\\Reynard et al. - 2001 - The Flood Characteristics of Large U.K. Rivers Po.pdf},
+  journal = {Climatic Change},
+  language = {en},
+  number = {2}
+}
+
+@incollection{secklerConceptEfficiencyWaterresources2003,
+  title = {The Concept of Efficiency in Water-Resources Management and Policy.},
+  booktitle = {Water Productivity in Agriculture: Limits and Opportunities for Improvement},
+  author = {Seckler, D. and Molden, D. and Sakthivadivel, R.},
+  editor = {Kijne, J. W. and Barker, R. and Molden, D.},
+  year = {2003},
+  pages = {37--51},
+  publisher = {{CABI}},
+  address = {{Wallingford}},
+  doi = {10.1079/9780851996691.0037},
+  file = {C\:\\Users\\david.dorchies\\Zotero\\storage\\FM69CIK3\\Seckler et al. - 2003 - The concept of efficiency in water-resources manag.pdf},
+  isbn = {978-0-85199-669-1},
+  language = {en}
+}
+
+