From 277010dbefb746a579444c532f826f8d0cf5b85d Mon Sep 17 00:00:00 2001 From: David <david.dorchies@inrae.fr> Date: Thu, 1 Aug 2024 07:19:46 +0200 Subject: [PATCH] fix(docs): doc and example issues with plot.GRiwrm - Improve documentation on mermaid directives - add dontrun to any plot.GRiwrm has it can take time in case of mermaid server latency and can raises a note on CRAN for timeout examples - concentrate examples on RunModel.GRiwrmInputsModel only to limit repetition of same examples in PDF documentation Refs #163 --- R/CreateGRiwrm.R | 10 +- R/CreateInputsModel.GRiwrm.R | 7 +- R/CreateRunOptions.R | 4 +- R/plot.GRiwrm.R | 10 +- R/plot.GRiwrmOutputsModel.R | 5 +- R/plot.Qm3s.R | 5 +- man-examples/CreateGRiwrm.R | 21 ++- man-examples/RunModel.GRiwrmInputsModel.R | 6 + man-examples/RunModel.Supervisor.R | 2 + man-examples/RunModel_Reservoir.R | 2 + man/CreateGRiwrm.Rd | 23 ++- man/CreateInputsModel.GRiwrm.Rd | 219 +--------------------- man/CreateRunOptions.Rd | 214 +-------------------- man/RunModel.GRiwrmInputsModel.Rd | 6 + man/RunModel.Supervisor.Rd | 2 + man/RunModel_Reservoir.Rd | 2 + man/plot.GRiwrm.Rd | 30 ++- man/plot.GRiwrmOutputsModel.Rd | 215 +-------------------- man/plot.OutputsModelReservoir.Rd | 2 + man/plot.Qm3s.Rd | 215 +-------------------- 20 files changed, 121 insertions(+), 879 deletions(-) diff --git a/R/CreateGRiwrm.R b/R/CreateGRiwrm.R index 9173974..2f37ca4 100644 --- a/R/CreateGRiwrm.R +++ b/R/CreateGRiwrm.R @@ -18,15 +18,15 @@ #' #' The "model" column should be filled by one of the following: #' -#' * One of the hydrological models available in the *airGR* package defined by its +#' - One of the hydrological models available in the **airGR** package defined by its #' `RunModel` function (i.e.: `RunModel_GR4J`, `RunModel_GR5HCemaneige`...) -#' * `RunModel_Reservoir` for simulating a reservoir (See: [RunModel_Reservoir]) -#' * `Ungauged` for an ungauged node. The sub-basin inherits hydrological model and +#' - `RunModel_Reservoir` for simulating a reservoir (See: [RunModel_Reservoir]) +#' - `Ungauged` for an ungauged node. The sub-basin inherits hydrological model and #' parameters from a "donor" sub-basin. If not defined by the user in the column `donor`, #' the donor is automatically set to the first gauged node at downstream -#' * `NA` for injecting (or abstracting) a flow time series at the location of the node +#' - `NA` for injecting (or abstracting) a flow time series at the location of the node #' (direct flow injection) -#' * `Diversion` for abstracting a flow time series from an existing node transfer it +#' - `Diversion` for abstracting a flow time series from an existing node transfer it #' to another node. As a `Diversion` is attached to an existing node, this node is #' then described with 2 lines: one for the hydrological model and another one for the #' diversion diff --git a/R/CreateInputsModel.GRiwrm.R b/R/CreateInputsModel.GRiwrm.R index 1607a82..17ddd9f 100644 --- a/R/CreateInputsModel.GRiwrm.R +++ b/R/CreateInputsModel.GRiwrm.R @@ -57,17 +57,20 @@ #' `TempMax` must be the same of the length of `DatesR` (each row corresponds to #' a time step defined in `DatesR`). #' +#' For examples of use see topics [RunModel.GRiwrmInputsModel], [RunModel_Reservoir], +#' and [RunModel.Supervisor]. +#' #' For example of use of Direct Injection nodes, see vignettes #' "V03_Open-loop_influenced_flow" and "V04_Closed-loop_regulated_withdrawal". #' -#' For example of use of Diversion nodes, see example below and vignette +#' For example of use of Diversion nodes, see example in +#' [RunModel.GRiwrmInputsModel] topic and vignette #' "V06_Modelling_regulated_diversion". #' #' @return A \emph{GRiwrmInputsModel} object which is a list of \emph{InputsModel} #' objects created by [airGR::CreateInputsModel] with one item per modeled sub-catchment. #' @export #' @seealso [CreateGRiwrm()], [CreateRunOptions()], [RunModel.GRiwrmInputsModel()] -#' @example man-examples/RunModel.GRiwrmInputsModel.R #' CreateInputsModel.GRiwrm <- function(x, DatesR, Precip = NULL, diff --git a/R/CreateRunOptions.R b/R/CreateRunOptions.R index 02086b4..9f02806 100644 --- a/R/CreateRunOptions.R +++ b/R/CreateRunOptions.R @@ -17,6 +17,9 @@ #' With a \emph{GRiwrmInputsModel} object, all arguments are applied on each #' sub-catchments of the network. #' +#' For examples of use see topics [RunModel.GRiwrmInputsModel], [RunModel_Reservoir], +#' and [RunModel.Supervisor]. +#' #' @return Depending on the class of `InputsModel` argument (respectively #' \emph{InputsModel} and \emph{GRiwrmInputsModel} object), the returned value is respectively: #' - a `RunOptions` object (See [airGR::CreateRunOptions]) @@ -25,7 +28,6 @@ #' @rdname CreateRunOptions #' @export #' @seealso [CreateGRiwrm()], [CreateInputsModel.GRiwrm()], [RunModel.GRiwrmInputsModel()] -#' @example man-examples/RunModel.GRiwrmInputsModel.R CreateRunOptions <- function(x, ...) { UseMethod("CreateRunOptions", x) } diff --git a/R/plot.GRiwrm.R b/R/plot.GRiwrm.R index e0618a5..88d71d2 100644 --- a/R/plot.GRiwrm.R +++ b/R/plot.GRiwrm.R @@ -1,5 +1,13 @@ #' Plot of a diagram representing the network structure of a GRiwrm object #' +#' @details +#' `header` parameter allows to add any mermaid code injected before the `graph` +#' instruction. It is notably useful for injecting directives that impact the +#' format of the graph. See https://mermaid.js.org/config/directives.html for +#' more details on directives and +# https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/schemas/config.schema.yaml#L1878 +#' for a complete list of available directives. +#' #' @param x \[GRiwrm object\] data to display. See [CreateGRiwrm] for details #' @param display [logical] if `TRUE` plots the diagram, returns the mermaid code otherwise #' @param orientation [character] orientation of the graph. Possible values are @@ -7,7 +15,7 @@ #' @param with_donors [logical] for drawing boxes around ungauged nodes and their donors #' @param box_colors [list] containing the color used for the different types of nodes #' @param defaultClassDef [character] default style apply to all boxes -#' @param header mermaid script to add before the generated script (init configuration) +#' @param header mermaid script to add before the generated script (see Details) #' @param footer mermaid script to add after the generated script #' @param ... further parameters passed to [mermaid] #' diff --git a/R/plot.GRiwrmOutputsModel.R b/R/plot.GRiwrmOutputsModel.R index b8d3bfc..6290e28 100644 --- a/R/plot.GRiwrmOutputsModel.R +++ b/R/plot.GRiwrmOutputsModel.R @@ -1,5 +1,9 @@ #' Function which creates screen plots giving an overview of the model outputs in the GRiwrm network #' +#' @details +#' For examples of use see topics [RunModel.GRiwrmInputsModel], [RunModel_Reservoir], +#' and [RunModel.Supervisor]. +#' #' @param x \[object of class *GRiwrmOutputsModel*\] see [RunModel.GRiwrmInputsModel] for details #' @param Qobs (optional) [matrix] time series of observed flows #' (for the same time steps than simulated) (mm/time step) with one column @@ -12,7 +16,6 @@ #' @importFrom graphics plot par title #' @export #' -#' @example man-examples/RunModel.GRiwrmInputsModel.R #' plot.GRiwrmOutputsModel <- function(x, Qobs = NULL, unit = "m3/s", ...) { diff --git a/R/plot.Qm3s.R b/R/plot.Qm3s.R index 754833c..287fec0 100644 --- a/R/plot.Qm3s.R +++ b/R/plot.Qm3s.R @@ -4,6 +4,9 @@ #' of class "Qm3s" which can be directly called by `plot`. It can also be called #' as a function `plot.Qm3s` if the first parameter has the good format. #' +#' For examples of use see topics [RunModel.GRiwrmInputsModel], [RunModel_Reservoir], +#' and [RunModel.Supervisor]. +#' #' @param x [data.frame] with a first column with [POSIXt] dates and followings #' columns with flows at each node of the network #' @param type [character] plot type (See [plot.default]), default "l" @@ -21,8 +24,6 @@ #' #' @return Screen plot window. #' -#' @example man-examples/RunModel.GRiwrmInputsModel.R -#' #' @export plot.Qm3s #' @export #' diff --git a/man-examples/CreateGRiwrm.R b/man-examples/CreateGRiwrm.R index 2425624..2806ca3 100644 --- a/man-examples/CreateGRiwrm.R +++ b/man-examples/CreateGRiwrm.R @@ -14,7 +14,9 @@ db <- data.frame(id = c("Reservoir", "GaugingDown"), griwrm_basic <- CreateGRiwrm(db) griwrm_basic # Network diagram with direct flow node in red, intermediate sub-basin in green +\dontrun{ plot(griwrm_basic) +} ################################################### # GR4J semi-distributed model of the Severn River # @@ -30,7 +32,9 @@ rename_columns <- list(id = "gauge_id", griwrm_severn <- CreateGRiwrm(nodes, rename_columns) griwrm_severn # Network diagram with upstream basin nodes in blue, intermediate sub-basin in green +\dontrun{ plot(griwrm_severn) +} #################################################################### # Severn network with an ungauged station at nodes 54029 and 54001 # @@ -44,7 +48,9 @@ nodes_ungauged$donor[nodes_ungauged$id == "54001"] <- "54095" griwrm_ungauged <- CreateGRiwrm(nodes_ungauged, rename_columns) griwrm_ungauged # Network diagram with gauged nodes of vivid color, and ungauged nodes of dull color +\dontrun{ plot(griwrm_ungauged) +} ########################################################### # Severn network with a Diversion on the node "54029" # @@ -62,10 +68,15 @@ nodes_div <- rbind( ) griwrm_div <- CreateGRiwrm(nodes_div, rename_columns) # Network diagram figures Diversion node by a red frame and a red arrow +\dontrun{ plot(griwrm_div, orientation = "TB") +} -# It's also possible to custom the diagram's look with mermaid instructions -# See https://mermaid.js.org/config/directives.html and -# https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/schemas/config.schema.yaml#L1878 -plot(griwrm_div, - header = "%%{init: {'flowchart': {'nodeSpacing': 30, 'rankSpacing': 30, 'curve': 'linear'}}}%%") +# It's also possible to custom the diagram's look with mermaid directives +# (See details in plot.GRiwrm help topic) +\dontrun{ +plot( + griwrm_div, + header = "%%{init: {'flowchart': {'nodeSpacing': 30, 'rankSpacing': 30, 'curve': 'linear'}}}%%" +) +} diff --git a/man-examples/RunModel.GRiwrmInputsModel.R b/man-examples/RunModel.GRiwrmInputsModel.R index 243cd24..8758834 100644 --- a/man-examples/RunModel.GRiwrmInputsModel.R +++ b/man-examples/RunModel.GRiwrmInputsModel.R @@ -39,7 +39,9 @@ db <- data.frame(id = c("Reservoir", "GaugingDown"), # Create GRiwrm object from the data.frame griwrm <- CreateGRiwrm(db) +\dontrun{ plot(griwrm) +} # Formatting observations for the hydrological models # Each input data should be a matrix or a data.frame with the good id in the name of the column @@ -103,7 +105,9 @@ rename_columns <- list(id = "gauge_id", g_severn <- CreateGRiwrm(nodes, rename_columns) # Network diagram with upstream basin nodes in blue, intermediate sub-basin in green +\dontrun{ plot(g_severn) +} # Format CAMEL-GB meteorological dataset for airGRiwrm inputs BasinsObs <- Severn$BasinsObs @@ -164,7 +168,9 @@ nodes_div <- rbind(nodes_div, g_div <- CreateGRiwrm(nodes_div) # The node "54001" is surrounded in red to show the diverted node +\dontrun{ plot(g_div) +} # Computation of the irrigation withdraw objective irrigMonthlyPlanning <- c(0.0, 0.0, 1.2, 2.4, 3.2, 3.6, 3.6, 2.8, 1.8, 0.0, 0.0, 0.0) diff --git a/man-examples/RunModel.Supervisor.R b/man-examples/RunModel.Supervisor.R index 5cfdf26..2a745ba 100644 --- a/man-examples/RunModel.Supervisor.R +++ b/man-examples/RunModel.Supervisor.R @@ -28,7 +28,9 @@ griwrm <- CreateGRiwrm(nodes, list(id = "gauge_id", down = "downstream_id", length = "distance_downstream")) +\dontrun{ plot(griwrm) +} # Format meteorological inputs for CreateInputs BasinsObs <- Severn$BasinsObs diff --git a/man-examples/RunModel_Reservoir.R b/man-examples/RunModel_Reservoir.R index 7c4ff80..5e62445 100644 --- a/man-examples/RunModel_Reservoir.R +++ b/man-examples/RunModel_Reservoir.R @@ -15,7 +15,9 @@ db <- data.frame(id = c(BasinInfo$BasinCode, "Reservoir"), model = c("RunModel_GR4J", "RunModel_Reservoir"), stringsAsFactors = FALSE) griwrm <- CreateGRiwrm(db) +\dontrun{ plot(griwrm) +} # Formatting of GR4J inputs for airGRiwrm (matrix or data.frame with one # column by sub-basin and node IDs as column names) diff --git a/man/CreateGRiwrm.Rd b/man/CreateGRiwrm.Rd index b7a8c60..433eb1c 100644 --- a/man/CreateGRiwrm.Rd +++ b/man/CreateGRiwrm.Rd @@ -63,7 +63,7 @@ will give its parameters to an ungauged node (See \code{Ungauged} model below). The "model" column should be filled by one of the following: \itemize{ -\item One of the hydrological models available in the \emph{airGR} package defined by its +\item One of the hydrological models available in the \strong{airGR} package defined by its \code{RunModel} function (i.e.: \code{RunModel_GR4J}, \code{RunModel_GR5HCemaneige}...) \item \code{RunModel_Reservoir} for simulating a reservoir (See: \link{RunModel_Reservoir}) \item \code{Ungauged} for an ungauged node. The sub-basin inherits hydrological model and @@ -95,7 +95,9 @@ db <- data.frame(id = c("Reservoir", "GaugingDown"), griwrm_basic <- CreateGRiwrm(db) griwrm_basic # Network diagram with direct flow node in red, intermediate sub-basin in green +\dontrun{ plot(griwrm_basic) +} ################################################### # GR4J semi-distributed model of the Severn River # @@ -111,7 +113,9 @@ rename_columns <- list(id = "gauge_id", griwrm_severn <- CreateGRiwrm(nodes, rename_columns) griwrm_severn # Network diagram with upstream basin nodes in blue, intermediate sub-basin in green +\dontrun{ plot(griwrm_severn) +} #################################################################### # Severn network with an ungauged station at nodes 54029 and 54001 # @@ -125,7 +129,9 @@ nodes_ungauged$donor[nodes_ungauged$id == "54001"] <- "54095" griwrm_ungauged <- CreateGRiwrm(nodes_ungauged, rename_columns) griwrm_ungauged # Network diagram with gauged nodes of vivid color, and ungauged nodes of dull color +\dontrun{ plot(griwrm_ungauged) +} ########################################################### # Severn network with a Diversion on the node "54029" # @@ -143,11 +149,16 @@ nodes_div <- rbind( ) griwrm_div <- CreateGRiwrm(nodes_div, rename_columns) # Network diagram figures Diversion node by a red frame and a red arrow +\dontrun{ plot(griwrm_div, orientation = "TB") +} -# It's also possible to custom the diagram's look with mermaid instructions -# See https://mermaid.js.org/config/directives.html and -# https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/schemas/config.schema.yaml#L1878 -plot(griwrm_div, - header = "\%\%{init: {'flowchart': {'nodeSpacing': 30, 'rankSpacing': 30, 'curve': 'linear'}}}\%\%") +# It's also possible to custom the diagram's look with mermaid directives +# (See details in plot.GRiwrm help topic) +\dontrun{ +plot( + griwrm_div, + header = "\%\%{init: {'flowchart': {'nodeSpacing': 30, 'rankSpacing': 30, 'curve': 'linear'}}}\%\%" +) +} } diff --git a/man/CreateInputsModel.GRiwrm.Rd b/man/CreateInputsModel.GRiwrm.Rd index 7c31fe3..7727d6c 100644 --- a/man/CreateInputsModel.GRiwrm.Rd +++ b/man/CreateInputsModel.GRiwrm.Rd @@ -106,225 +106,16 @@ Number of rows of \code{Precip}, \code{PotEvap}, \code{Qinf}, \code{Qmin}, \code \code{TempMax} must be the same of the length of \code{DatesR} (each row corresponds to a time step defined in \code{DatesR}). +For examples of use see topics \link{RunModel.GRiwrmInputsModel}, \link{RunModel_Reservoir}, +and \link{RunModel.Supervisor}. + For example of use of Direct Injection nodes, see vignettes "V03_Open-loop_influenced_flow" and "V04_Closed-loop_regulated_withdrawal". -For example of use of Diversion nodes, see example below and vignette +For example of use of Diversion nodes, see example in +\link{RunModel.GRiwrmInputsModel} topic and vignette "V06_Modelling_regulated_diversion". } -\examples{ -################################################################### -# Run the `airGR::RunModel_Lag` example in the GRiwrm fashion way # -# Simulation of a reservoir with a purpose of low-flow mitigation # -################################################################### - -## ---- preparation of the InputsModel object - -## loading package and catchment data -library(airGRiwrm) -data(L0123001) - -## ---- specifications of the reservoir - -## the reservoir withdraws 1 m3/s when it's possible considering the flow observed in the basin -Qupstream <- matrix(-sapply(BasinObs$Qls / 1000 - 1, function(x) { - min(1, max(0, x, na.rm = TRUE)) -}), ncol = 1) - -## 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 -Qupstream <- Qupstream * 86400 ## Conversion in m3/day - -## 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 -LengthHydro <- 150 -## with a delay of 2 days for 150 km, the flow velocity is 75 km per day -Velocity <- (LengthHydro * 1e3 / 2) / (24 * 60 * 60) ## Conversion km/day -> m/s - -# This example is a network of 2 nodes which can be describe like this: -db <- data.frame(id = c("Reservoir", "GaugingDown"), - length = c(LengthHydro, NA), - down = c("GaugingDown", NA), - area = c(NA, BasinInfo$BasinArea), - model = c(NA, "RunModel_GR4J"), - stringsAsFactors = FALSE) - -# Create GRiwrm object from the data.frame -griwrm <- CreateGRiwrm(db) -plot(griwrm) - -# Formatting observations for the hydrological models -# Each input data should be a matrix or a data.frame with the good id in the name of the column -Precip <- matrix(BasinObs$P, ncol = 1) -colnames(Precip) <- "GaugingDown" -PotEvap <- matrix(BasinObs$E, ncol = 1) -colnames(PotEvap) <- "GaugingDown" - -# Observed flows contain flows that are directly injected in the model -Qinf = matrix(Qupstream, ncol = 1) -colnames(Qinf) <- "Reservoir" - -# Creation of the GRiwrmInputsModel object (= a named list of InputsModel objects) -InputsModels <- CreateInputsModel(griwrm, - DatesR = BasinObs$DatesR, - Precip = Precip, - PotEvap = PotEvap, - Qinf = Qinf) -str(InputsModels) - -## 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")) - -# Creation of the GRiwmRunOptions object -RunOptions <- CreateRunOptions(InputsModels, - IndPeriod_Run = Ind_Run) -str(RunOptions) - -# Parameters of the SD models should be encapsulated in a named list -ParamGR4J <- c(X1 = 257.238, X2 = 1.012, X3 = 88.235, X4 = 2.208) -Param <- list(`GaugingDown` = c(Velocity, ParamGR4J)) - -# RunModel for the whole network -OutputsModels <- RunModel(InputsModels, - RunOptions = RunOptions, - Param = Param) -str(OutputsModels) - -# Compare regimes of the simulation with reservoir and observation of natural flow -plot(OutputsModels, - data.frame(GaugingDown = BasinObs$Qmm[Ind_Run]), - which = "Regime") - -# Plot together simulated flows (m3/s) of the reservoir and the gauging station -plot(attr(OutputsModels, "Qm3s")) - - -######################################################## -# Run the Severn example provided with this package # -# A natural catchment composed with 6 gauging stations # -######################################################## - -data(Severn) -nodes <- Severn$BasinsInfo -nodes$model <- "RunModel_GR4J" -# Mismatch column names are renamed to stick with GRiwrm requirements -rename_columns <- list(id = "gauge_id", - down = "downstream_id", - length = "distance_downstream") -g_severn <- CreateGRiwrm(nodes, rename_columns) - -# Network diagram with upstream basin nodes in blue, intermediate sub-basin in green -plot(g_severn) - -# Format CAMEL-GB meteorological dataset for airGRiwrm inputs -BasinsObs <- Severn$BasinsObs -DatesR <- BasinsObs[[1]]$DatesR -PrecipTot <- cbind(sapply(BasinsObs, function(x) {x$precipitation})) -PotEvapTot <- cbind(sapply(BasinsObs, function(x) {x$peti})) - -# Precipitation and Potential Evaporation are related to the whole catchment -# at each gauging station. We need to compute them for intermediate catchments -# for use in a semi-distributed model -Precip <- ConvertMeteoSD(g_severn, PrecipTot) -PotEvap <- ConvertMeteoSD(g_severn, PotEvapTot) - -# CreateInputsModel object -IM_severn <- CreateInputsModel(g_severn, DatesR, Precip, PotEvap) - -# GRiwrmRunOptions object -# Run period is set aside the one-year warm-up period -IndPeriod_Run <- seq( - which(IM_severn[[1]]$DatesR == (IM_severn[[1]]$DatesR[1] + 365*24*60*60)), - length(IM_severn[[1]]$DatesR) # Until the end of the time series -) -IndPeriod_WarmUp <- seq(1, IndPeriod_Run[1] - 1) - -RO_severn <- CreateRunOptions( - IM_severn, - IndPeriod_WarmUp = IndPeriod_WarmUp, - IndPeriod_Run = IndPeriod_Run -) - -# Load parameters of the model from Calibration in vignette V02 -P_severn <- readRDS(system.file("vignettes", "ParamV02.RDS", package = "airGRiwrm")) - -# Run the simulation -OM_severn <- RunModel(IM_severn, - RunOptions = RO_severn, - Param = P_severn) - -# Plot results of simulated flows in m3/s -Qm3s <- attr(OM_severn, "Qm3s") -plot(Qm3s[1:150, ]) - - -################################################################## -# An example of water withdrawal for irrigation with restriction # -# modeled with a Diversion node on the Severn river # -################################################################## - -# A diversion is added at gauging station "54001" -nodes_div <- nodes[, c("gauge_id", "downstream_id", "distance_downstream", "area", "model")] -names(nodes_div) <- c("id", "down", "length", "area", "model") -nodes_div <- rbind(nodes_div, - data.frame(id = "54001", # location of the diversion - down = NA, # the abstracted flow goes outside - length = NA, # down=NA, so length=NA - area = NA, # no area, diverted flow is in m3/day - model = "Diversion")) - -g_div <- CreateGRiwrm(nodes_div) -# The node "54001" is surrounded in red to show the diverted node -plot(g_div) - -# Computation of the irrigation withdraw objective -irrigMonthlyPlanning <- c(0.0, 0.0, 1.2, 2.4, 3.2, 3.6, 3.6, 2.8, 1.8, 0.0, 0.0, 0.0) -names(irrigMonthlyPlanning) <- month.abb -irrigMonthlyPlanning -DatesR_month <- as.numeric(format(DatesR, "\%m")) -# Withdrawn flow calculated for each day is negative -Qirrig <- matrix(-irrigMonthlyPlanning[DatesR_month] * 86400, ncol = 1) -colnames(Qirrig) <- "54001" - -# Minimum flow to remain downstream the diversion is 12 m3/s -Qmin <- matrix(12 * 86400, nrow = length(DatesR), ncol = 1) -colnames(Qmin) = "54001" - -# Creation of GRimwrInputsModel object -IM_div <- CreateInputsModel(g_div, DatesR, Precip, PotEvap, Qinf = Qirrig, Qmin = Qmin) - -# RunOptions and parameters are unchanged, we can directly run the simulation -OM_div <- RunModel(IM_div, - RunOptions = RO_severn, - Param = P_severn) - -# Retrieve diverted flow at "54001" and convert it from m3/day to m3/s -Qdiv_m3s <- OM_div$`54001`$Qdiv_m3 / 86400 - -# Plot the diverted flow for the year 2003 -Ind_Plot <- which( - OM_div[[1]]$DatesR >= as.POSIXct("2003-01-01", tz = "UTC") & - OM_div[[1]]$DatesR <= as.POSIXct("2003-12-31", tz = "UTC") -) -dfQdiv <- as.Qm3s(DatesR = OM_div[[1]]$DatesR[Ind_Plot], - Diverted_flow = Qdiv_m3s[Ind_Plot]) - -oldpar <- par(mfrow=c(2,1), mar = c(2.5,4,1,1)) -plot(dfQdiv) - -# Plot natural and influenced flow at station "54001" -df54001 <- cbind(attr(OM_div, "Qm3s")[Ind_Plot, c("DatesR", "54001")], - attr(OM_severn, "Qm3s")[Ind_Plot, "54001"]) -names(df54001) <- c("DatesR", "54001 with irrigation", "54001 natural flow") -df54001 <- as.Qm3s(df54001) -plot(df54001, ylim = c(0,70)) -abline(h = 12, col = "green", lty = "dotted") -par(oldpar) -} \seealso{ \code{\link[=CreateGRiwrm]{CreateGRiwrm()}}, \code{\link[=CreateRunOptions]{CreateRunOptions()}}, \code{\link[=RunModel.GRiwrmInputsModel]{RunModel.GRiwrmInputsModel()}} } diff --git a/man/CreateRunOptions.Rd b/man/CreateRunOptions.Rd index 308c904..368a795 100644 --- a/man/CreateRunOptions.Rd +++ b/man/CreateRunOptions.Rd @@ -50,219 +50,9 @@ list of \link{numeric} object of class \emph{IniStates} with one item per modele With a \emph{GRiwrmInputsModel} object, all arguments are applied on each sub-catchments of the network. -} -\examples{ -################################################################### -# Run the `airGR::RunModel_Lag` example in the GRiwrm fashion way # -# Simulation of a reservoir with a purpose of low-flow mitigation # -################################################################### - -## ---- preparation of the InputsModel object - -## loading package and catchment data -library(airGRiwrm) -data(L0123001) - -## ---- specifications of the reservoir - -## the reservoir withdraws 1 m3/s when it's possible considering the flow observed in the basin -Qupstream <- matrix(-sapply(BasinObs$Qls / 1000 - 1, function(x) { - min(1, max(0, x, na.rm = TRUE)) -}), ncol = 1) - -## 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 -Qupstream <- Qupstream * 86400 ## Conversion in m3/day - -## 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 -LengthHydro <- 150 -## with a delay of 2 days for 150 km, the flow velocity is 75 km per day -Velocity <- (LengthHydro * 1e3 / 2) / (24 * 60 * 60) ## Conversion km/day -> m/s - -# This example is a network of 2 nodes which can be describe like this: -db <- data.frame(id = c("Reservoir", "GaugingDown"), - length = c(LengthHydro, NA), - down = c("GaugingDown", NA), - area = c(NA, BasinInfo$BasinArea), - model = c(NA, "RunModel_GR4J"), - stringsAsFactors = FALSE) - -# Create GRiwrm object from the data.frame -griwrm <- CreateGRiwrm(db) -plot(griwrm) - -# Formatting observations for the hydrological models -# Each input data should be a matrix or a data.frame with the good id in the name of the column -Precip <- matrix(BasinObs$P, ncol = 1) -colnames(Precip) <- "GaugingDown" -PotEvap <- matrix(BasinObs$E, ncol = 1) -colnames(PotEvap) <- "GaugingDown" - -# Observed flows contain flows that are directly injected in the model -Qinf = matrix(Qupstream, ncol = 1) -colnames(Qinf) <- "Reservoir" - -# Creation of the GRiwrmInputsModel object (= a named list of InputsModel objects) -InputsModels <- CreateInputsModel(griwrm, - DatesR = BasinObs$DatesR, - Precip = Precip, - PotEvap = PotEvap, - Qinf = Qinf) -str(InputsModels) - -## 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")) - -# Creation of the GRiwmRunOptions object -RunOptions <- CreateRunOptions(InputsModels, - IndPeriod_Run = Ind_Run) -str(RunOptions) - -# Parameters of the SD models should be encapsulated in a named list -ParamGR4J <- c(X1 = 257.238, X2 = 1.012, X3 = 88.235, X4 = 2.208) -Param <- list(`GaugingDown` = c(Velocity, ParamGR4J)) - -# RunModel for the whole network -OutputsModels <- RunModel(InputsModels, - RunOptions = RunOptions, - Param = Param) -str(OutputsModels) - -# Compare regimes of the simulation with reservoir and observation of natural flow -plot(OutputsModels, - data.frame(GaugingDown = BasinObs$Qmm[Ind_Run]), - which = "Regime") - -# Plot together simulated flows (m3/s) of the reservoir and the gauging station -plot(attr(OutputsModels, "Qm3s")) - - -######################################################## -# Run the Severn example provided with this package # -# A natural catchment composed with 6 gauging stations # -######################################################## - -data(Severn) -nodes <- Severn$BasinsInfo -nodes$model <- "RunModel_GR4J" -# Mismatch column names are renamed to stick with GRiwrm requirements -rename_columns <- list(id = "gauge_id", - down = "downstream_id", - length = "distance_downstream") -g_severn <- CreateGRiwrm(nodes, rename_columns) - -# Network diagram with upstream basin nodes in blue, intermediate sub-basin in green -plot(g_severn) - -# Format CAMEL-GB meteorological dataset for airGRiwrm inputs -BasinsObs <- Severn$BasinsObs -DatesR <- BasinsObs[[1]]$DatesR -PrecipTot <- cbind(sapply(BasinsObs, function(x) {x$precipitation})) -PotEvapTot <- cbind(sapply(BasinsObs, function(x) {x$peti})) - -# Precipitation and Potential Evaporation are related to the whole catchment -# at each gauging station. We need to compute them for intermediate catchments -# for use in a semi-distributed model -Precip <- ConvertMeteoSD(g_severn, PrecipTot) -PotEvap <- ConvertMeteoSD(g_severn, PotEvapTot) - -# CreateInputsModel object -IM_severn <- CreateInputsModel(g_severn, DatesR, Precip, PotEvap) - -# GRiwrmRunOptions object -# Run period is set aside the one-year warm-up period -IndPeriod_Run <- seq( - which(IM_severn[[1]]$DatesR == (IM_severn[[1]]$DatesR[1] + 365*24*60*60)), - length(IM_severn[[1]]$DatesR) # Until the end of the time series -) -IndPeriod_WarmUp <- seq(1, IndPeriod_Run[1] - 1) - -RO_severn <- CreateRunOptions( - IM_severn, - IndPeriod_WarmUp = IndPeriod_WarmUp, - IndPeriod_Run = IndPeriod_Run -) - -# Load parameters of the model from Calibration in vignette V02 -P_severn <- readRDS(system.file("vignettes", "ParamV02.RDS", package = "airGRiwrm")) - -# Run the simulation -OM_severn <- RunModel(IM_severn, - RunOptions = RO_severn, - Param = P_severn) - -# Plot results of simulated flows in m3/s -Qm3s <- attr(OM_severn, "Qm3s") -plot(Qm3s[1:150, ]) - - -################################################################## -# An example of water withdrawal for irrigation with restriction # -# modeled with a Diversion node on the Severn river # -################################################################## - -# A diversion is added at gauging station "54001" -nodes_div <- nodes[, c("gauge_id", "downstream_id", "distance_downstream", "area", "model")] -names(nodes_div) <- c("id", "down", "length", "area", "model") -nodes_div <- rbind(nodes_div, - data.frame(id = "54001", # location of the diversion - down = NA, # the abstracted flow goes outside - length = NA, # down=NA, so length=NA - area = NA, # no area, diverted flow is in m3/day - model = "Diversion")) - -g_div <- CreateGRiwrm(nodes_div) -# The node "54001" is surrounded in red to show the diverted node -plot(g_div) - -# Computation of the irrigation withdraw objective -irrigMonthlyPlanning <- c(0.0, 0.0, 1.2, 2.4, 3.2, 3.6, 3.6, 2.8, 1.8, 0.0, 0.0, 0.0) -names(irrigMonthlyPlanning) <- month.abb -irrigMonthlyPlanning -DatesR_month <- as.numeric(format(DatesR, "\%m")) -# Withdrawn flow calculated for each day is negative -Qirrig <- matrix(-irrigMonthlyPlanning[DatesR_month] * 86400, ncol = 1) -colnames(Qirrig) <- "54001" - -# Minimum flow to remain downstream the diversion is 12 m3/s -Qmin <- matrix(12 * 86400, nrow = length(DatesR), ncol = 1) -colnames(Qmin) = "54001" - -# Creation of GRimwrInputsModel object -IM_div <- CreateInputsModel(g_div, DatesR, Precip, PotEvap, Qinf = Qirrig, Qmin = Qmin) - -# RunOptions and parameters are unchanged, we can directly run the simulation -OM_div <- RunModel(IM_div, - RunOptions = RO_severn, - Param = P_severn) - -# Retrieve diverted flow at "54001" and convert it from m3/day to m3/s -Qdiv_m3s <- OM_div$`54001`$Qdiv_m3 / 86400 - -# Plot the diverted flow for the year 2003 -Ind_Plot <- which( - OM_div[[1]]$DatesR >= as.POSIXct("2003-01-01", tz = "UTC") & - OM_div[[1]]$DatesR <= as.POSIXct("2003-12-31", tz = "UTC") -) -dfQdiv <- as.Qm3s(DatesR = OM_div[[1]]$DatesR[Ind_Plot], - Diverted_flow = Qdiv_m3s[Ind_Plot]) - -oldpar <- par(mfrow=c(2,1), mar = c(2.5,4,1,1)) -plot(dfQdiv) -# Plot natural and influenced flow at station "54001" -df54001 <- cbind(attr(OM_div, "Qm3s")[Ind_Plot, c("DatesR", "54001")], - attr(OM_severn, "Qm3s")[Ind_Plot, "54001"]) -names(df54001) <- c("DatesR", "54001 with irrigation", "54001 natural flow") -df54001 <- as.Qm3s(df54001) -plot(df54001, ylim = c(0,70)) -abline(h = 12, col = "green", lty = "dotted") -par(oldpar) +For examples of use see topics \link{RunModel.GRiwrmInputsModel}, \link{RunModel_Reservoir}, +and \link{RunModel.Supervisor}. } \seealso{ \code{\link[=CreateGRiwrm]{CreateGRiwrm()}}, \code{\link[=CreateInputsModel.GRiwrm]{CreateInputsModel.GRiwrm()}}, \code{\link[=RunModel.GRiwrmInputsModel]{RunModel.GRiwrmInputsModel()}} diff --git a/man/RunModel.GRiwrmInputsModel.Rd b/man/RunModel.GRiwrmInputsModel.Rd index 722c8ea..da9a6a1 100644 --- a/man/RunModel.GRiwrmInputsModel.Rd +++ b/man/RunModel.GRiwrmInputsModel.Rd @@ -73,7 +73,9 @@ db <- data.frame(id = c("Reservoir", "GaugingDown"), # Create GRiwrm object from the data.frame griwrm <- CreateGRiwrm(db) +\dontrun{ plot(griwrm) +} # Formatting observations for the hydrological models # Each input data should be a matrix or a data.frame with the good id in the name of the column @@ -137,7 +139,9 @@ rename_columns <- list(id = "gauge_id", g_severn <- CreateGRiwrm(nodes, rename_columns) # Network diagram with upstream basin nodes in blue, intermediate sub-basin in green +\dontrun{ plot(g_severn) +} # Format CAMEL-GB meteorological dataset for airGRiwrm inputs BasinsObs <- Severn$BasinsObs @@ -198,7 +202,9 @@ nodes_div <- rbind(nodes_div, g_div <- CreateGRiwrm(nodes_div) # The node "54001" is surrounded in red to show the diverted node +\dontrun{ plot(g_div) +} # Computation of the irrigation withdraw objective irrigMonthlyPlanning <- c(0.0, 0.0, 1.2, 2.4, 3.2, 3.6, 3.6, 2.8, 1.8, 0.0, 0.0, 0.0) diff --git a/man/RunModel.Supervisor.Rd b/man/RunModel.Supervisor.Rd index c884d6d..c34c029 100644 --- a/man/RunModel.Supervisor.Rd +++ b/man/RunModel.Supervisor.Rd @@ -52,7 +52,9 @@ griwrm <- CreateGRiwrm(nodes, list(id = "gauge_id", down = "downstream_id", length = "distance_downstream")) +\dontrun{ plot(griwrm) +} # Format meteorological inputs for CreateInputs BasinsObs <- Severn$BasinsObs diff --git a/man/RunModel_Reservoir.Rd b/man/RunModel_Reservoir.Rd index 0ce9640..dd4a1b3 100644 --- a/man/RunModel_Reservoir.Rd +++ b/man/RunModel_Reservoir.Rd @@ -83,7 +83,9 @@ db <- data.frame(id = c(BasinInfo$BasinCode, "Reservoir"), model = c("RunModel_GR4J", "RunModel_Reservoir"), stringsAsFactors = FALSE) griwrm <- CreateGRiwrm(db) +\dontrun{ plot(griwrm) +} # Formatting of GR4J inputs for airGRiwrm (matrix or data.frame with one # column by sub-basin and node IDs as column names) diff --git a/man/plot.GRiwrm.Rd b/man/plot.GRiwrm.Rd index 84d3c40..cb7d1b8 100644 --- a/man/plot.GRiwrm.Rd +++ b/man/plot.GRiwrm.Rd @@ -31,7 +31,7 @@ \item{defaultClassDef}{\link{character} default style apply to all boxes} -\item{header}{mermaid script to add before the generated script (init configuration)} +\item{header}{mermaid script to add before the generated script (see Details)} \item{footer}{mermaid script to add after the generated script} @@ -43,6 +43,13 @@ Mermaid code of the diagram if display is \code{FALSE}, otherwise the function r \description{ Plot of a diagram representing the network structure of a GRiwrm object } +\details{ +\code{header} parameter allows to add any mermaid code injected before the \code{graph} +instruction. It is notably useful for injecting directives that impact the +format of the graph. See https://mermaid.js.org/config/directives.html for +more details on directives and +for a complete list of available directives. +} \examples{ library(airGRiwrm) @@ -60,7 +67,9 @@ db <- data.frame(id = c("Reservoir", "GaugingDown"), griwrm_basic <- CreateGRiwrm(db) griwrm_basic # Network diagram with direct flow node in red, intermediate sub-basin in green +\dontrun{ plot(griwrm_basic) +} ################################################### # GR4J semi-distributed model of the Severn River # @@ -76,7 +85,9 @@ rename_columns <- list(id = "gauge_id", griwrm_severn <- CreateGRiwrm(nodes, rename_columns) griwrm_severn # Network diagram with upstream basin nodes in blue, intermediate sub-basin in green +\dontrun{ plot(griwrm_severn) +} #################################################################### # Severn network with an ungauged station at nodes 54029 and 54001 # @@ -90,7 +101,9 @@ nodes_ungauged$donor[nodes_ungauged$id == "54001"] <- "54095" griwrm_ungauged <- CreateGRiwrm(nodes_ungauged, rename_columns) griwrm_ungauged # Network diagram with gauged nodes of vivid color, and ungauged nodes of dull color +\dontrun{ plot(griwrm_ungauged) +} ########################################################### # Severn network with a Diversion on the node "54029" # @@ -108,13 +121,18 @@ nodes_div <- rbind( ) griwrm_div <- CreateGRiwrm(nodes_div, rename_columns) # Network diagram figures Diversion node by a red frame and a red arrow +\dontrun{ plot(griwrm_div, orientation = "TB") +} -# It's also possible to custom the diagram's look with mermaid instructions -# See https://mermaid.js.org/config/directives.html and -# https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/schemas/config.schema.yaml#L1878 -plot(griwrm_div, - header = "\%\%{init: {'flowchart': {'nodeSpacing': 30, 'rankSpacing': 30, 'curve': 'linear'}}}\%\%") +# It's also possible to custom the diagram's look with mermaid directives +# (See details in plot.GRiwrm help topic) +\dontrun{ +plot( + griwrm_div, + header = "\%\%{init: {'flowchart': {'nodeSpacing': 30, 'rankSpacing': 30, 'curve': 'linear'}}}\%\%" +) +} } \seealso{ \code{\link[=CreateGRiwrm]{CreateGRiwrm()}} diff --git a/man/plot.GRiwrmOutputsModel.Rd b/man/plot.GRiwrmOutputsModel.Rd index 520e84d..9573c2d 100644 --- a/man/plot.GRiwrmOutputsModel.Rd +++ b/man/plot.GRiwrmOutputsModel.Rd @@ -23,216 +23,7 @@ by hydrological model output named with the node ID (See \link{CreateGRiwrm} for \description{ Function which creates screen plots giving an overview of the model outputs in the GRiwrm network } -\examples{ -################################################################### -# Run the `airGR::RunModel_Lag` example in the GRiwrm fashion way # -# Simulation of a reservoir with a purpose of low-flow mitigation # -################################################################### - -## ---- preparation of the InputsModel object - -## loading package and catchment data -library(airGRiwrm) -data(L0123001) - -## ---- specifications of the reservoir - -## the reservoir withdraws 1 m3/s when it's possible considering the flow observed in the basin -Qupstream <- matrix(-sapply(BasinObs$Qls / 1000 - 1, function(x) { - min(1, max(0, x, na.rm = TRUE)) -}), ncol = 1) - -## 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 -Qupstream <- Qupstream * 86400 ## Conversion in m3/day - -## 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 -LengthHydro <- 150 -## with a delay of 2 days for 150 km, the flow velocity is 75 km per day -Velocity <- (LengthHydro * 1e3 / 2) / (24 * 60 * 60) ## Conversion km/day -> m/s - -# This example is a network of 2 nodes which can be describe like this: -db <- data.frame(id = c("Reservoir", "GaugingDown"), - length = c(LengthHydro, NA), - down = c("GaugingDown", NA), - area = c(NA, BasinInfo$BasinArea), - model = c(NA, "RunModel_GR4J"), - stringsAsFactors = FALSE) - -# Create GRiwrm object from the data.frame -griwrm <- CreateGRiwrm(db) -plot(griwrm) - -# Formatting observations for the hydrological models -# Each input data should be a matrix or a data.frame with the good id in the name of the column -Precip <- matrix(BasinObs$P, ncol = 1) -colnames(Precip) <- "GaugingDown" -PotEvap <- matrix(BasinObs$E, ncol = 1) -colnames(PotEvap) <- "GaugingDown" - -# Observed flows contain flows that are directly injected in the model -Qinf = matrix(Qupstream, ncol = 1) -colnames(Qinf) <- "Reservoir" - -# Creation of the GRiwrmInputsModel object (= a named list of InputsModel objects) -InputsModels <- CreateInputsModel(griwrm, - DatesR = BasinObs$DatesR, - Precip = Precip, - PotEvap = PotEvap, - Qinf = Qinf) -str(InputsModels) - -## 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")) - -# Creation of the GRiwmRunOptions object -RunOptions <- CreateRunOptions(InputsModels, - IndPeriod_Run = Ind_Run) -str(RunOptions) - -# Parameters of the SD models should be encapsulated in a named list -ParamGR4J <- c(X1 = 257.238, X2 = 1.012, X3 = 88.235, X4 = 2.208) -Param <- list(`GaugingDown` = c(Velocity, ParamGR4J)) - -# RunModel for the whole network -OutputsModels <- RunModel(InputsModels, - RunOptions = RunOptions, - Param = Param) -str(OutputsModels) - -# Compare regimes of the simulation with reservoir and observation of natural flow -plot(OutputsModels, - data.frame(GaugingDown = BasinObs$Qmm[Ind_Run]), - which = "Regime") - -# Plot together simulated flows (m3/s) of the reservoir and the gauging station -plot(attr(OutputsModels, "Qm3s")) - - -######################################################## -# Run the Severn example provided with this package # -# A natural catchment composed with 6 gauging stations # -######################################################## - -data(Severn) -nodes <- Severn$BasinsInfo -nodes$model <- "RunModel_GR4J" -# Mismatch column names are renamed to stick with GRiwrm requirements -rename_columns <- list(id = "gauge_id", - down = "downstream_id", - length = "distance_downstream") -g_severn <- CreateGRiwrm(nodes, rename_columns) - -# Network diagram with upstream basin nodes in blue, intermediate sub-basin in green -plot(g_severn) - -# Format CAMEL-GB meteorological dataset for airGRiwrm inputs -BasinsObs <- Severn$BasinsObs -DatesR <- BasinsObs[[1]]$DatesR -PrecipTot <- cbind(sapply(BasinsObs, function(x) {x$precipitation})) -PotEvapTot <- cbind(sapply(BasinsObs, function(x) {x$peti})) - -# Precipitation and Potential Evaporation are related to the whole catchment -# at each gauging station. We need to compute them for intermediate catchments -# for use in a semi-distributed model -Precip <- ConvertMeteoSD(g_severn, PrecipTot) -PotEvap <- ConvertMeteoSD(g_severn, PotEvapTot) - -# CreateInputsModel object -IM_severn <- CreateInputsModel(g_severn, DatesR, Precip, PotEvap) - -# GRiwrmRunOptions object -# Run period is set aside the one-year warm-up period -IndPeriod_Run <- seq( - which(IM_severn[[1]]$DatesR == (IM_severn[[1]]$DatesR[1] + 365*24*60*60)), - length(IM_severn[[1]]$DatesR) # Until the end of the time series -) -IndPeriod_WarmUp <- seq(1, IndPeriod_Run[1] - 1) - -RO_severn <- CreateRunOptions( - IM_severn, - IndPeriod_WarmUp = IndPeriod_WarmUp, - IndPeriod_Run = IndPeriod_Run -) - -# Load parameters of the model from Calibration in vignette V02 -P_severn <- readRDS(system.file("vignettes", "ParamV02.RDS", package = "airGRiwrm")) - -# Run the simulation -OM_severn <- RunModel(IM_severn, - RunOptions = RO_severn, - Param = P_severn) - -# Plot results of simulated flows in m3/s -Qm3s <- attr(OM_severn, "Qm3s") -plot(Qm3s[1:150, ]) - - -################################################################## -# An example of water withdrawal for irrigation with restriction # -# modeled with a Diversion node on the Severn river # -################################################################## - -# A diversion is added at gauging station "54001" -nodes_div <- nodes[, c("gauge_id", "downstream_id", "distance_downstream", "area", "model")] -names(nodes_div) <- c("id", "down", "length", "area", "model") -nodes_div <- rbind(nodes_div, - data.frame(id = "54001", # location of the diversion - down = NA, # the abstracted flow goes outside - length = NA, # down=NA, so length=NA - area = NA, # no area, diverted flow is in m3/day - model = "Diversion")) - -g_div <- CreateGRiwrm(nodes_div) -# The node "54001" is surrounded in red to show the diverted node -plot(g_div) - -# Computation of the irrigation withdraw objective -irrigMonthlyPlanning <- c(0.0, 0.0, 1.2, 2.4, 3.2, 3.6, 3.6, 2.8, 1.8, 0.0, 0.0, 0.0) -names(irrigMonthlyPlanning) <- month.abb -irrigMonthlyPlanning -DatesR_month <- as.numeric(format(DatesR, "\%m")) -# Withdrawn flow calculated for each day is negative -Qirrig <- matrix(-irrigMonthlyPlanning[DatesR_month] * 86400, ncol = 1) -colnames(Qirrig) <- "54001" - -# Minimum flow to remain downstream the diversion is 12 m3/s -Qmin <- matrix(12 * 86400, nrow = length(DatesR), ncol = 1) -colnames(Qmin) = "54001" - -# Creation of GRimwrInputsModel object -IM_div <- CreateInputsModel(g_div, DatesR, Precip, PotEvap, Qinf = Qirrig, Qmin = Qmin) - -# RunOptions and parameters are unchanged, we can directly run the simulation -OM_div <- RunModel(IM_div, - RunOptions = RO_severn, - Param = P_severn) - -# Retrieve diverted flow at "54001" and convert it from m3/day to m3/s -Qdiv_m3s <- OM_div$`54001`$Qdiv_m3 / 86400 - -# Plot the diverted flow for the year 2003 -Ind_Plot <- which( - OM_div[[1]]$DatesR >= as.POSIXct("2003-01-01", tz = "UTC") & - OM_div[[1]]$DatesR <= as.POSIXct("2003-12-31", tz = "UTC") -) -dfQdiv <- as.Qm3s(DatesR = OM_div[[1]]$DatesR[Ind_Plot], - Diverted_flow = Qdiv_m3s[Ind_Plot]) - -oldpar <- par(mfrow=c(2,1), mar = c(2.5,4,1,1)) -plot(dfQdiv) - -# Plot natural and influenced flow at station "54001" -df54001 <- cbind(attr(OM_div, "Qm3s")[Ind_Plot, c("DatesR", "54001")], - attr(OM_severn, "Qm3s")[Ind_Plot, "54001"]) -names(df54001) <- c("DatesR", "54001 with irrigation", "54001 natural flow") -df54001 <- as.Qm3s(df54001) -plot(df54001, ylim = c(0,70)) -abline(h = 12, col = "green", lty = "dotted") -par(oldpar) +\details{ +For examples of use see topics \link{RunModel.GRiwrmInputsModel}, \link{RunModel_Reservoir}, +and \link{RunModel.Supervisor}. } diff --git a/man/plot.OutputsModelReservoir.Rd b/man/plot.OutputsModelReservoir.Rd index 4899ec6..e3d6e0a 100644 --- a/man/plot.OutputsModelReservoir.Rd +++ b/man/plot.OutputsModelReservoir.Rd @@ -37,7 +37,9 @@ db <- data.frame(id = c(BasinInfo$BasinCode, "Reservoir"), model = c("RunModel_GR4J", "RunModel_Reservoir"), stringsAsFactors = FALSE) griwrm <- CreateGRiwrm(db) +\dontrun{ plot(griwrm) +} # Formatting of GR4J inputs for airGRiwrm (matrix or data.frame with one # column by sub-basin and node IDs as column names) diff --git a/man/plot.Qm3s.Rd b/man/plot.Qm3s.Rd index d8de7b7..d902771 100644 --- a/man/plot.Qm3s.Rd +++ b/man/plot.Qm3s.Rd @@ -55,216 +55,7 @@ This function plot time series of flow rate in m3/s. It's a method for object of class "Qm3s" which can be directly called by \code{plot}. It can also be called as a function \code{plot.Qm3s} if the first parameter has the good format. } -\examples{ -################################################################### -# Run the `airGR::RunModel_Lag` example in the GRiwrm fashion way # -# Simulation of a reservoir with a purpose of low-flow mitigation # -################################################################### - -## ---- preparation of the InputsModel object - -## loading package and catchment data -library(airGRiwrm) -data(L0123001) - -## ---- specifications of the reservoir - -## the reservoir withdraws 1 m3/s when it's possible considering the flow observed in the basin -Qupstream <- matrix(-sapply(BasinObs$Qls / 1000 - 1, function(x) { - min(1, max(0, x, na.rm = TRUE)) -}), ncol = 1) - -## 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 -Qupstream <- Qupstream * 86400 ## Conversion in m3/day - -## 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 -LengthHydro <- 150 -## with a delay of 2 days for 150 km, the flow velocity is 75 km per day -Velocity <- (LengthHydro * 1e3 / 2) / (24 * 60 * 60) ## Conversion km/day -> m/s - -# This example is a network of 2 nodes which can be describe like this: -db <- data.frame(id = c("Reservoir", "GaugingDown"), - length = c(LengthHydro, NA), - down = c("GaugingDown", NA), - area = c(NA, BasinInfo$BasinArea), - model = c(NA, "RunModel_GR4J"), - stringsAsFactors = FALSE) - -# Create GRiwrm object from the data.frame -griwrm <- CreateGRiwrm(db) -plot(griwrm) - -# Formatting observations for the hydrological models -# Each input data should be a matrix or a data.frame with the good id in the name of the column -Precip <- matrix(BasinObs$P, ncol = 1) -colnames(Precip) <- "GaugingDown" -PotEvap <- matrix(BasinObs$E, ncol = 1) -colnames(PotEvap) <- "GaugingDown" - -# Observed flows contain flows that are directly injected in the model -Qinf = matrix(Qupstream, ncol = 1) -colnames(Qinf) <- "Reservoir" - -# Creation of the GRiwrmInputsModel object (= a named list of InputsModel objects) -InputsModels <- CreateInputsModel(griwrm, - DatesR = BasinObs$DatesR, - Precip = Precip, - PotEvap = PotEvap, - Qinf = Qinf) -str(InputsModels) - -## 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")) - -# Creation of the GRiwmRunOptions object -RunOptions <- CreateRunOptions(InputsModels, - IndPeriod_Run = Ind_Run) -str(RunOptions) - -# Parameters of the SD models should be encapsulated in a named list -ParamGR4J <- c(X1 = 257.238, X2 = 1.012, X3 = 88.235, X4 = 2.208) -Param <- list(`GaugingDown` = c(Velocity, ParamGR4J)) - -# RunModel for the whole network -OutputsModels <- RunModel(InputsModels, - RunOptions = RunOptions, - Param = Param) -str(OutputsModels) - -# Compare regimes of the simulation with reservoir and observation of natural flow -plot(OutputsModels, - data.frame(GaugingDown = BasinObs$Qmm[Ind_Run]), - which = "Regime") - -# Plot together simulated flows (m3/s) of the reservoir and the gauging station -plot(attr(OutputsModels, "Qm3s")) - - -######################################################## -# Run the Severn example provided with this package # -# A natural catchment composed with 6 gauging stations # -######################################################## - -data(Severn) -nodes <- Severn$BasinsInfo -nodes$model <- "RunModel_GR4J" -# Mismatch column names are renamed to stick with GRiwrm requirements -rename_columns <- list(id = "gauge_id", - down = "downstream_id", - length = "distance_downstream") -g_severn <- CreateGRiwrm(nodes, rename_columns) - -# Network diagram with upstream basin nodes in blue, intermediate sub-basin in green -plot(g_severn) - -# Format CAMEL-GB meteorological dataset for airGRiwrm inputs -BasinsObs <- Severn$BasinsObs -DatesR <- BasinsObs[[1]]$DatesR -PrecipTot <- cbind(sapply(BasinsObs, function(x) {x$precipitation})) -PotEvapTot <- cbind(sapply(BasinsObs, function(x) {x$peti})) - -# Precipitation and Potential Evaporation are related to the whole catchment -# at each gauging station. We need to compute them for intermediate catchments -# for use in a semi-distributed model -Precip <- ConvertMeteoSD(g_severn, PrecipTot) -PotEvap <- ConvertMeteoSD(g_severn, PotEvapTot) - -# CreateInputsModel object -IM_severn <- CreateInputsModel(g_severn, DatesR, Precip, PotEvap) - -# GRiwrmRunOptions object -# Run period is set aside the one-year warm-up period -IndPeriod_Run <- seq( - which(IM_severn[[1]]$DatesR == (IM_severn[[1]]$DatesR[1] + 365*24*60*60)), - length(IM_severn[[1]]$DatesR) # Until the end of the time series -) -IndPeriod_WarmUp <- seq(1, IndPeriod_Run[1] - 1) - -RO_severn <- CreateRunOptions( - IM_severn, - IndPeriod_WarmUp = IndPeriod_WarmUp, - IndPeriod_Run = IndPeriod_Run -) - -# Load parameters of the model from Calibration in vignette V02 -P_severn <- readRDS(system.file("vignettes", "ParamV02.RDS", package = "airGRiwrm")) - -# Run the simulation -OM_severn <- RunModel(IM_severn, - RunOptions = RO_severn, - Param = P_severn) - -# Plot results of simulated flows in m3/s -Qm3s <- attr(OM_severn, "Qm3s") -plot(Qm3s[1:150, ]) - - -################################################################## -# An example of water withdrawal for irrigation with restriction # -# modeled with a Diversion node on the Severn river # -################################################################## - -# A diversion is added at gauging station "54001" -nodes_div <- nodes[, c("gauge_id", "downstream_id", "distance_downstream", "area", "model")] -names(nodes_div) <- c("id", "down", "length", "area", "model") -nodes_div <- rbind(nodes_div, - data.frame(id = "54001", # location of the diversion - down = NA, # the abstracted flow goes outside - length = NA, # down=NA, so length=NA - area = NA, # no area, diverted flow is in m3/day - model = "Diversion")) - -g_div <- CreateGRiwrm(nodes_div) -# The node "54001" is surrounded in red to show the diverted node -plot(g_div) - -# Computation of the irrigation withdraw objective -irrigMonthlyPlanning <- c(0.0, 0.0, 1.2, 2.4, 3.2, 3.6, 3.6, 2.8, 1.8, 0.0, 0.0, 0.0) -names(irrigMonthlyPlanning) <- month.abb -irrigMonthlyPlanning -DatesR_month <- as.numeric(format(DatesR, "\%m")) -# Withdrawn flow calculated for each day is negative -Qirrig <- matrix(-irrigMonthlyPlanning[DatesR_month] * 86400, ncol = 1) -colnames(Qirrig) <- "54001" - -# Minimum flow to remain downstream the diversion is 12 m3/s -Qmin <- matrix(12 * 86400, nrow = length(DatesR), ncol = 1) -colnames(Qmin) = "54001" - -# Creation of GRimwrInputsModel object -IM_div <- CreateInputsModel(g_div, DatesR, Precip, PotEvap, Qinf = Qirrig, Qmin = Qmin) - -# RunOptions and parameters are unchanged, we can directly run the simulation -OM_div <- RunModel(IM_div, - RunOptions = RO_severn, - Param = P_severn) - -# Retrieve diverted flow at "54001" and convert it from m3/day to m3/s -Qdiv_m3s <- OM_div$`54001`$Qdiv_m3 / 86400 - -# Plot the diverted flow for the year 2003 -Ind_Plot <- which( - OM_div[[1]]$DatesR >= as.POSIXct("2003-01-01", tz = "UTC") & - OM_div[[1]]$DatesR <= as.POSIXct("2003-12-31", tz = "UTC") -) -dfQdiv <- as.Qm3s(DatesR = OM_div[[1]]$DatesR[Ind_Plot], - Diverted_flow = Qdiv_m3s[Ind_Plot]) - -oldpar <- par(mfrow=c(2,1), mar = c(2.5,4,1,1)) -plot(dfQdiv) - -# Plot natural and influenced flow at station "54001" -df54001 <- cbind(attr(OM_div, "Qm3s")[Ind_Plot, c("DatesR", "54001")], - attr(OM_severn, "Qm3s")[Ind_Plot, "54001"]) -names(df54001) <- c("DatesR", "54001 with irrigation", "54001 natural flow") -df54001 <- as.Qm3s(df54001) -plot(df54001, ylim = c(0,70)) -abline(h = 12, col = "green", lty = "dotted") -par(oldpar) +\details{ +For examples of use see topics \link{RunModel.GRiwrmInputsModel}, \link{RunModel_Reservoir}, +and \link{RunModel.Supervisor}. } -- GitLab