feat: export data in the package

.Rbuildignore

 ^rvgest\.Rproj$
 ^\.Rproj\.user$
 ^LICENSE\.md$
+^data-raw$

DESCRIPTION

@@ -19,3 +19,5 @@ Imports:
     lubridate,
     TSstudio
 VignetteBuilder: knitr
+Depends: 
+    R (>= 2.10)

NAMESPACE

@@ -9,10 +9,12 @@ S3method(vgest_read_chrono,Objectives)
 S3method(vgest_read_chrono,default)
 S3method(vgest_run_store,Objectives)
 S3method(vgest_run_store,character)
-export(get_objectives)
 export(get_vobj_ts)
+export(lakes)
+export(objectives)
 export(plot_isofrequency)
 export(plot_isofrequency_lake)
+export(rulesets)
 export(vgest_cost)
 export(vgest_read)
 export(vgest_read_all)

R/get_objectives.R

-#' Load objective data for \code{\link{vgest_run}}
-#'
-#' @param objective_thresholds File location of threshold table
-#' @param objective_stations File location of objective station table
-#' @param lakes File location of lake table
-#'
-#' @return A dataframe containing one line by objective and the following columns:
-#' 
-#' - station  (character): identifier of the objective station
-#' - flood (boolean): TRUE for high flow mitigation objective, and FALSE for low flow support
-#' - level (character): code composed with "l" for low-flow and "h" for high flow followed by the number of the level 
-#' - threshold (numeric): value of the threshold in m3/s
-#' - lakes (dataframe): Dataframe containing lake details (name, min storage, max storage)
-#' 
-#' @export
-#'
-#' @examples
-#' # Get objectives stored in IRMaRA package
-#' df <- get_objectives()
-#' # Objectives at Paris
-#' df[df[,"station"] == "PARIS_05",]
-#' # Lake details concerning the 40th objective in the table
-#' df[57, "lakes"]
-get_objectives <- function(
-  objective_thresholds = app_sys("seine", "objective_thresholds.txt"),
-  objective_stations = app_sys("seine", "objective_stations.json"), 
-  lakes = app_sys("seine", "lakes.txt")
-) {
-  thresholds <- read.delim(objective_thresholds)
-  stations <- jsonlite::fromJSON(
-    readLines(objective_stations)
-  )
-  dfLakes <- read.delim(lakes)
-  row.names(dfLakes) <- dfLakes$name
-  bFirst = TRUE
-  for(iStation in 1:nrow(thresholds)) {
-    station <- thresholds[iStation, 1]
-    for(type in c("l", "h")) {
-      bFlood = (type == "h")
-      for(level in grep(paste0(type, ".*"), names(thresholds))) {
-        threshold <- thresholds[iStation, level]
-        df1 <- data.frame(
-          station = station,
-          flood = bFlood,
-          level = names(thresholds)[level],
-          threshold = threshold
-        )
-        df1$lakes <- list(dfLakes[stations[[station]]$lakes,])
-        if(bFirst) {
-          df <- df1
-          bFirst <- FALSE
-        } else {
-          df <- rbind(df, df1)
-        }
-      }
-    }
-  }
-  class(df) <- c("Objectives", class(df))
-  return(df)
-}
\ No newline at end of file

R/get_vobj_ts.R

@@ -10,7 +10,7 @@
 #'
 #' @examples
 #' \dontrun{
-#' dfTs <- get_vobj_ts(vgest_read_all(get_objectives()[1,], "./database"))
+#' dfTs <- get_vobj_ts(vgest_read_all(objectives[1,], "./database"))
 #' }
 get_vobj_ts <- function(x) {
   UseMethod("get_vobj_ts", x)
@@ -27,9 +27,9 @@ get_vobj_ts <- function(x) {
 #' @examples
 #' \dontrun{
 #' # Get the first lake of the first objective
-#' dfTs <- get_vobj_ts(vgest_read_all(get_objectives()[1,], "./database")[[1]])
+#' dfTs <- get_vobj_ts(vgest_read_all(objectives[1,], "./database")[[1]])
 #' # Can also be done by
-#' dfTs <- get_vobj_ts(vgest_read_one(1, get_objectives()[1,], "./database"))
+#' dfTs <- get_vobj_ts(vgest_read_one(1, objectives[1,], "./database"))
 #' }
 get_vobj_ts.Vobj <- function(x) {
   # Build the date vector
@@ -57,7 +57,7 @@ get_vobj_ts.Vobj <- function(x) {
 #'
 #' @examples
 #' \dontrun{
-#' dfTs <- get_vobj_ts(vgest_read_all(get_objectives()[1,], "./database"))
+#' dfTs <- get_vobj_ts(vgest_read_all(objectives[1,], "./database"))
 #' }
 get_vobj_ts.ListVobj <-function(x) {
   lVobjTs <- lapply(x, get_vobj_ts.Vobj)

R/lakes.R

+#' Characteristics of the 4 lakes managed by Seine Grands Lacs
+#'
+#' @format a [data.frame] with 3 columns:
+#'
+#' - "name" the name of the river on which the lake is implemented ([character])
+#' - "min" the minimum lake storage in Mm3 ([numeric])
+#' - "max" the maximum lake storage in Mm3 ([numeric])
+#'
+#' @source \url{https://www.seinegrandslacs.fr/quatre-lacs-reservoirs-au-coeur-dun-bassin}
+#' @export
+"lakes"

R/objectives.R

+#' Objectives of reservoir management on the Seine River
+#'
+#' @format a [data.frame] with 5 columns:
+#'
+#' - "station" the id of the station ([character])
+#' - "flood" a [logical] which is `TRUE` for a flood objective and `FALSE` for a drought objective
+#' - "level" a [character] representing the severity of the threshold: "l1" to "l4" for low flow thresholds and "h1" to "h3" for high flow thresholds
+#' - "lakes" a [list] which contains a [data.frame] with informations concerning the lakes (See [lakes])
+#'
+#' @source Dorchies, D., Thirel, G., Jay-Allemand, M., Chauveau, M., Dehay, F., Bourgin, P.-Y., Perrin, C., Jost, C., Rizzoli, J.-L., Demerliac, S., Thépot, R., 2014. Climate change impacts on multi-objective reservoir management: case study on the Seine River basin, France. International Journal of River Basin Management 12, 265–283. \url{https://doi.org/10.1080/15715124.2013.865636}
+#' @export
+"objectives"

R/plot_isofrequency.R

@@ -27,7 +27,7 @@ plot_isofrequency <- function(x, freq, result.dir = "database") {
 #'
 #' @param vObj dataframe produced by [vgest_read_one()] and stored in a list by [vgest_read_all()]
 #' @param frequencies vector of frequencies to plot
-#' @param lake lake data extract from column `lakes` of objective data given by [get_objectives()]
+#' @param lake lake data extract from column `lakes` of objective data given by [objectives]
 #' @param top.margin top margin applied on the plot for the title
 #'
 #' @return [NULL]

R/rulesets.R

+#' Rule sets used in the reservoir managements
+#'
+#' @format a [list] with 2 items:
+#'
+#' - "constraints" [character] description of the constraints apply on the management of the reservoir
+#' - "rules" [character] description of rule set selections depending on which constraints are applied
+#'
+#' @source Dehay, F., 2012. Etude de l’impact du changement climatique sur la gestion des lacs-réservoirs de la Seine (other). Diplôme d’ingénieur de l’ENGEES ,Strasbourg. \url{https://hal.inrae.fr/hal-02597326}
+#' @export
+"rulesets"

R/vgest_cost.R

@@ -3,7 +3,7 @@
 #' Uses ouput of PaChrono.txt or VObj\[1-4\].dat for the calculation.
 #'
 #' @param data Data source, see details
-#' @param objective one row of the dataframe given by [get_objectives()]
+#' @param objective one row of the dataframe given by [objectives]
 #'
 #' @return the total cost for one objective at one station in m3/day
 #' @rdname vgest_cost
@@ -19,7 +19,7 @@ vgest_cost <- function(data, objective) {
 #' For each lake, it's the mean daily storage for a low-flow support objective and the mean daily available storage capacity for a high flow mitigation objective.
 #'
 #' @param Vobj A [matrix] or a [data.frame] with one column by lake, in the same order as `objective$lakes`
-#' @param objective one row of the dataframe given by [get_objectives()]
+#' @param objective one row of the dataframe given by [objectives]
 #'
 #' @return total cost of all the lakes in m3/day
 #'
@@ -39,7 +39,7 @@ vgest_cost_lakes <- function(Vobj, objective) {
 }
 
 
-#' @param objective one row of the dataframe given by [get_objectives()]
+#' @param objective one row of the dataframe given by [objectives]
 #'
 #' @rdname vgest_cost
 #' @export
@@ -47,7 +47,7 @@ vgest_cost_lakes <- function(Vobj, objective) {
 #' @examples
 #' \dontrun{
 #' # This should be done after the execution of vgest for the concerned objective
-#' objective <- get_objectives()[1,]
+#' objective <- objectives[1,]
 #' lResultVobj <- vgest_read_all(objective)
 #' vgest_cost(lResultVobj, objective)
 #' }
@@ -67,7 +67,7 @@ vgest_cost.ListVobj <- function(data, objective) {
 #' @examples
 #' \dontrun{
 #' # This should be done after the execution of vgest for the concerned objective
-#' objective <- get_objectives()[1,]
+#' objective <- objectives[1,]
 #' lChrono <- vgest_read_chrono(objective)
 #' vgest_cost(lChrono[[1]], objective)
 #' }
@@ -78,7 +78,7 @@ vgest_cost.Chrono <- function(data, objective) {
 
 #'
 #' @param data the [list] given by [vgest_read_chrono()]
-#' @param objective [data.frame] given by [get_objectives()]
+#' @param objective [data.frame] given by [objectives]
 #'
 #' @return A list with items named \[station\]_\[high/low\]_\[threshold\] containing the total cost for a list of objectives and stations in m3/day
 #' @rdname vgest_cost
@@ -87,7 +87,7 @@ vgest_cost.Chrono <- function(data, objective) {
 #' @examples
 #' \dontrun{
 #' # This should be done after the execution of vgest for the concerned objective
-#' objective <- get_objectives()[1,]
+#' objective <- objectives[1,]
 #' lChronos <- vgest_read_chrono(objective, distributionType = 2)
 #' vgest_cost(lChronos, objective)
 #' }

R/vgest_read.R

@@ -48,7 +48,7 @@ vgest_read <- function(file, bFlood) {
 #' This function is preferred to [vgest_read()] because it builds the path for the file to read.
 #'
 #' @param iLake Lake number for the current station
-#' @param x one line of the dataframe produced by [get_objectives()]
+#' @param x one line of the dataframe produced by [objectives]
 #' @param result.dir path where results of VGEST runs are stored (See [vgest_run_store()])
 #'
 #' @return dataframe with the content of the `VOBJi.DAT` file
@@ -56,7 +56,7 @@ vgest_read <- function(file, bFlood) {
 #'
 #' @examples
 #' \dontrun{
-#' vgest_read_one(1, get_objectives()[1,], "./database")
+#' vgest_read_one(1, objectives[1,], "./database")
 #' }
 vgest_read_one <- function(iLake, x, result.dir) {
   sLowHigh <- c("low", "high")
@@ -72,7 +72,7 @@ vgest_read_one <- function(iLake, x, result.dir) {
 
 #' Read all result files `VOBJi.DAT` for all the lakes of one objective at one station
 #'
-#' @param x one line of the dataframe produced by [get_objectives()]
+#' @param x one line of the dataframe produced by [objectives]
 #' @param result.dir path where results of VGEST runs are stored (See [vgest_run_store()])
 #'
 #' @return list with dataframes produced by
@@ -80,7 +80,7 @@ vgest_read_one <- function(iLake, x, result.dir) {
 #'
 #' @examples
 #' \dontrun{
-#' vgest_read_all(get_objectives()[1,], "./database")
+#' vgest_read_all(objectives[1,], "./database")
 #' }
 vgest_read_all <- function(x, result.dir = "database") {
   lObj <- lapply(1:nrow(x$lakes[[1]]), vgest_read_one, x, result.dir)

R/vgest_read_chrono.R

@@ -89,7 +89,7 @@ vgest_read_chrono.default <- function(x, nLakes, distributionType, ...) {
 #'
 #' @examples
 #' \dontrun{
-#' objective <- get_objectives()[1,]
+#' objective <- objectives[1,]
 #' distributionType <- 2
 #' vgest_run_store(objective,
 #'                 1, 1, "Q_NAT_1900-2009.txt",

R/vgest_run_store.R

@@ -45,7 +45,7 @@ vgest_run_store.character <- function(x, reservoirRuleSet, networkSet,
   cat(" - OK\n")
 }
 
-#' @param x row(s) of a [data.frame] provided by [get_objectives()]
+#' @param x row(s) of a [data.frame] provided by [objectives]
 #'
 #' @export
 #' @rdname vgest_run_store
@@ -54,13 +54,13 @@ vgest_run_store.character <- function(x, reservoirRuleSet, networkSet,
 #' \dontrun{
 #' # Example with `vgest_run_store.Objectives`
 #' # Running vgest for:
-#' # - the first objective returned by `get_objectives()`
+#' # - the first objective returned by `objectives`
 #' # - the first configuration of reservoir rules
 #' # - the first configuration of network
 #' # - the naturalized hydrological flows of the file located in DONNEES/Q_NAT_1900-2009.txt
 #' # - doing the optimization on the period between 01/01/1900 and 31/12/2009
 #' # - a task distribution function of present volumes and maximum usable volume replenishment times from the start of time steps
-#' vgest_run_store(get_objectives()[1,],
+#' vgest_run_store(objectives[1,],
 #'                 1, 1, "Q_NAT_1900-2009.txt",
 #'                 "01/01/1900", "31/12/2009", 2)
 #'

data-raw/seine_grands_lacs.R

+## code to prepare `seine_grands_lacs` dataset goes here
+
+
+# *** lakes ***
+lakes <- read.delim("data-raw/lakes.txt")
+row.names(lakes) <- lakes$name
+
+# *** objectives ***
+thresholds <- read.delim("data-raw/objective_thresholds.txt")
+stations <- jsonlite::fromJSON(
+  readLines("data-raw/objective_stations.json")
+)
+bFirst = TRUE
+for(iStation in 1:nrow(thresholds)) {
+  station <- thresholds[iStation, 1]
+  for(type in c("l", "h")) {
+    bFlood = (type == "h")
+    for(level in grep(paste0(type, ".*"), names(thresholds))) {
+      threshold <- thresholds[iStation, level]
+      df1 <- data.frame(
+        station = station,
+        flood = bFlood,
+        level = names(thresholds)[level],
+        threshold = threshold
+      )
+      df1$lakes <- list(lakes[stations[[station]]$lakes,])
+      if(bFirst) {
+        objectives <- df1
+        bFirst <- FALSE
+      } else {
+        objectives <- rbind(objectives, df1)
+      }
+    }
+  }
+}
+class(objectives) <- c("Objectives", class(objectives))
+
+# *** rulesets ***
+constraints <- c(
+  "a. Qres (minimum flow) at inlets and at Yonne outlet (inline reservoir)",
+  "b. Qres at outlets",
+  "c. Qref (maximum flow) at inlets and outlets",
+  "d. Priority to hydropower generation on Yonne reservoir (Max outflow of 16m<sup>3</sup>/s)",
+  "e. QST Gradient flow daily limitation for Yonne reservoir (+/- 2m3/s per day)"
+)
+
+rules <- c(
+  "All constraints (a+b+c+d+e)",
+  "1, without Qref (a+b+d+e)",
+  "1, without Qres at outlet (a+c+d+e)",
+  "3, without Qref (a+d+e)",
+  "4, without hydropower priority for Yonne lake (a+e)",
+  "5, without Yonne outflow variation limitation (a)"
+)
+rulesets <- list(constraints = constraints, rules = rules)
+
+# Record data in the package
+usethis::use_data(objectives, lakes, rulesets, internal = TRUE, overwrite = TRUE)