Commit 0b3a0d26 authored by Dorchies David's avatar Dorchies David
Browse files

docs: improve CreateGRiwrm documentation

Refs #42
2 merge requests!93Draft: Version 0.7.0,!40Resolve "Feature request: use of non gauged stations in the network"
Pipeline #38407 passed with stage
in 6 minutes and 26 seconds
Showing with 111 additions and 95 deletions
+111 -95
......@@ -12,6 +12,7 @@
^docs
^vignettes/seinebasin
^man-roxygen
^man-examples
^dev
^CRAN-SUBMISSION$
^cran-comments\.md$
......@@ -229,7 +229,7 @@ calcSubBasinAreas <- function(IM) {
#' RunModel for a sub-network of ungauged nodes
#'
#' The function simulates a network with one set of parameters
#' shared with ungauded nodes inside the basin.
#' shared with ungauged nodes inside the basin.
#'
#' @details
#' The network should contains only one gauged station at downstream and other
......@@ -239,7 +239,7 @@ calcSubBasinAreas <- function(IM) {
#' `InputsModel` is a *GRiwrmInputsModel* containing the network of ungauged nodes
#' and direct injection in the basin.
#'
#' `Param` is adjusted for each sub-basin using the method developped by
#' `Param` is adjusted for each sub-basin using the method developed by
#' Lobligeois (2014) for GR models.
#'
#' @references Lobligeois, Florent. Mieux connaître la distribution spatiale des
......
......@@ -34,7 +34,7 @@
#'
#' @aliases GRiwrm
#' @export
#' @inherit RunModel.GRiwrmInputsModel return examples
#' @example man-examples/CreateGRiwrm.R
#'
CreateGRiwrm <- function(db,
cols = list(
......
......@@ -15,13 +15,7 @@
#'
#' @export
#'
#' @examples
#' \dontrun{
#' # Display diagram
#' plot.GRiwrm(griwrm)
#' # Is the same as
#' DiagrammeR::mermaid(plot.GRiwrm(griwrm, display = FALSE), width = "100%", height = "100%")
#' }
#' @example man-examples/CreateGRiwrm.R
#'
plot.GRiwrm <- function(x,
display = TRUE,
......
# Network of 2 nodes distant of 150 km:
# - an upstream reservoir modelled as a direct flow injection (no model)
# - a gauging station downstream a catchment of 360 km² modelled with GR4J
db <- data.frame(id = c("Reservoir", "GaugingDown"),
length = c(150, NA),
down = c("GaugingDown", NA),
area = c(NA, 360),
model = c(NA, "RunModel_GR4J"),
stringsAsFactors = FALSE)
griwrm_basic <- CreateGRiwrm(db)
str(griwrm_basic)
# Network diagram with direct flow node in red, intermediate sub-basin in green
plot(griwrm_basic)
# GR4J semi-distributed model of the Severn River
data(Severn)
nodes <- Severn$BasinsInfo
nodes$model <- "RunModel_GR4J"
str(nodes)
# Mismatch column names are renamed to stick with GRiwrm requirements
rename_columns <- list(id = "gauge_id",
down = "downstream_id",
length = "distance_downstream")
griwrm_severn <- CreateGRiwrm(nodes, rename_columns)
str(griwrm_severn)
# Network diagram with upstream basin nodes in blue, intermediate sub-basin in green
plot(griwrm_severn)
# Same model with an ungauged station at nodes 54029 and 54001
# By default the first gauged node at downstream is used for parameter calibration (54032)
nodes_ungauged <- nodes
nodes_ungauged$model[nodes_ungauged$gauge_id %in% c("54029", "54001")] <- "Ungauged"
griwrm_ungauged <- CreateGRiwrm(nodes_ungauged, rename_columns)
# The `donor` column define which node is used for parameter calibration
griwrm_ungauged
# Network diagram with gauged nodes of vivid color, and ungauged nodes of dull color
plot(griwrm_ungauged)
......@@ -56,87 +56,41 @@ runoff model output (\link{character} column \code{model})
}
}
\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:
# Network of 2 nodes distant of 150 km:
# - an upstream reservoir modelled as a direct flow injection (no model)
# - a gauging station downstream a catchment of 360 km² modelled with GR4J
db <- data.frame(id = c("Reservoir", "GaugingDown"),
length = c(LengthHydro, NA),
length = c(150, NA),
down = c("GaugingDown", NA),
area = c(NA, BasinInfo$BasinArea),
area = c(NA, 360),
model = c(NA, "RunModel_GR4J"),
stringsAsFactors = FALSE)
# Create GRiwrm object from the data.frame
griwrm <- CreateGRiwrm(db)
str(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
Qobs = matrix(Qupstream, ncol = 1)
colnames(Qobs) <- "Reservoir"
# Creation of the GRiwrmInputsModel object (= a named list of InputsModel objects)
InputsModels <- CreateInputsModel(griwrm,
DatesR = BasinObs$DatesR,
Precip = Precip,
PotEvap = PotEvap,
Qobs = Qobs)
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 Simulation with reservoir and observation of natural flow
plot(OutputsModels, data.frame(GaugingDown = BasinObs$Qmm[Ind_Run]))
griwrm_basic <- CreateGRiwrm(db)
str(griwrm_basic)
# Network diagram with direct flow node in red, intermediate sub-basin in green
plot(griwrm_basic)
# GR4J semi-distributed model of the Severn River
data(Severn)
nodes <- Severn$BasinsInfo
nodes$model <- "RunModel_GR4J"
str(nodes)
# Mismatch column names are renamed to stick with GRiwrm requirements
rename_columns <- list(id = "gauge_id",
down = "downstream_id",
length = "distance_downstream")
griwrm_severn <- CreateGRiwrm(nodes, rename_columns)
str(griwrm_severn)
# Network diagram with upstream basin nodes in blue, intermediate sub-basin in green
plot(griwrm_severn)
# Same model with an ungauged station at nodes 54029 and 54001
# By default the first gauged node at downstream is used for parameter calibration (54032)
nodes_ungauged <- nodes
nodes_ungauged$model[nodes_ungauged$gauge_id \%in\% c("54029", "54001")] <- "Ungauged"
griwrm_ungauged <- CreateGRiwrm(nodes_ungauged, rename_columns)
# The `donor` column define which node is used for parameter calibration
griwrm_ungauged
# Network diagram with gauged nodes of vivid color, and ungauged nodes of dull color
plot(griwrm_ungauged)
}
......@@ -41,11 +41,41 @@ This function only works inside RStudio because the HTMLwidget produced by Diagr
is not handled on some platforms
}
\examples{
\dontrun{
# Display diagram
plot.GRiwrm(griwrm)
# Is the same as
DiagrammeR::mermaid(plot.GRiwrm(griwrm, display = FALSE), width = "100\%", height = "100\%")
}
# Network of 2 nodes distant of 150 km:
# - an upstream reservoir modelled as a direct flow injection (no model)
# - a gauging station downstream a catchment of 360 km² modelled with GR4J
db <- data.frame(id = c("Reservoir", "GaugingDown"),
length = c(150, NA),
down = c("GaugingDown", NA),
area = c(NA, 360),
model = c(NA, "RunModel_GR4J"),
stringsAsFactors = FALSE)
griwrm_basic <- CreateGRiwrm(db)
str(griwrm_basic)
# Network diagram with direct flow node in red, intermediate sub-basin in green
plot(griwrm_basic)
# GR4J semi-distributed model of the Severn River
data(Severn)
nodes <- Severn$BasinsInfo
nodes$model <- "RunModel_GR4J"
str(nodes)
# Mismatch column names are renamed to stick with GRiwrm requirements
rename_columns <- list(id = "gauge_id",
down = "downstream_id",
length = "distance_downstream")
griwrm_severn <- CreateGRiwrm(nodes, rename_columns)
str(griwrm_severn)
# Network diagram with upstream basin nodes in blue, intermediate sub-basin in green
plot(griwrm_severn)
# Same model with an ungauged station at nodes 54029 and 54001
# By default the first gauged node at downstream is used for parameter calibration (54032)
nodes_ungauged <- nodes
nodes_ungauged$model[nodes_ungauged$gauge_id \%in\% c("54029", "54001")] <- "Ungauged"
griwrm_ungauged <- CreateGRiwrm(nodes_ungauged, rename_columns)
# The `donor` column define which node is used for parameter calibration
griwrm_ungauged
# Network diagram with gauged nodes of vivid color, and ungauged nodes of dull color
plot(griwrm_ungauged)
}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment