updateScenarioBuilder() updated to use 'hfl' + doc + tests

NEWS.md

@@ -13,6 +13,7 @@ NEW FEATURES :
 * `createClusterST()`/`editClusterST()` :  
   - **New properties** (*efficiencywithdrawal*, *penalize-variation-injection*, *penalize-variation-withdrawal*, see list of properties according to study version of Antares with `storage_values_default()`)  
   - **New optional time series** (cost-injection, cost-withdrawal, cost-level, cost-variation-injection, cost-variation-withdrawal)
+* `updateScenarioBuilder()` New type of series "hfl" ("hydro final level", similar to "hydrolevels") is available   
 
 
 ### Breaking changes  :  

R/scenarioBuilder.R

@@ -12,7 +12,7 @@
 #' @param group_bc `character` Bindgind constraints's groups names to use.
 #' @param group_bc_rand `character` Bindgind constraints which to use `"rand"`.
 #' @param mode `character` "bc" to edit binding constraints.
-#' @param coef_hydro_levels Hydro levels coefficients.
+#' @param coef_hydro_levels Hydro levels or hydro final level coefficients.
 #' @param opts
 #'   List of simulation parameters returned by the function
 #'   [antaresRead::setSimulationPath()]
@@ -262,8 +262,9 @@ scenarioBuilder <- function(n_scenario = 1,
 #' @export
 create_scb_referential_series_type <- function(){
 
-  series_to_write <- c("l", "h", "w", "s", "t", "r", "ntc", "hl", "bc")
-  choices <- c("load", "hydro", "wind", "solar", "thermal", "renewables", "ntc", "hydrolevels", "binding")
+  series_to_write <- c("l", "h", "w", "s", "t", "r", "ntc", "hl", "bc", "hfl")
+  choices <- c("load", "hydro", "wind", "solar", "thermal", "renewables", 
+               "ntc", "hydrolevels", "binding", "hydro final level")
 
   # Check data consistency
   len_series_to_write <- length(series_to_write)  
@@ -415,7 +416,7 @@ extract_el <- function(l, indice) {
 
 #' @param ldata A `matrix` obtained with `scenarioBuilder`, 
 #'  or a named list of matrices obtained with `scenarioBuilder`, names must be 
-#'  'l', 'h', 'w', 's', 't', 'r', 'ntc', 'hl' or 'bc', depending on the series to update.
+#'  'l', 'h', 'w', 's', 't', 'r', 'ntc', 'hl', 'bc' or 'hfl', depending on the series to update.
 #' @param series Name(s) of the serie(s) to update if `ldata` is a single `matrix`.
 #' @param clusters_areas A `data.table` with two columns `area` and `cluster`
 #'  to identify area/cluster couple to update for thermal or renewable series.
@@ -427,7 +428,7 @@ extract_el <- function(l, indice) {
 #'  
 #' @note
 #'  - `series = "ntc"` is only available with Antares >= 8.2.0.
-#'  - For `series = "hl"`, each value must be between 0 and 1.
+#'  - For `series = "hl/hfl"`, each value must be between 0 and 1.
 #'  - User must enable/disable `custom-scenario` property in `settings/generaldata.ini` by himself.  
 #'  - `series = "bc"` is only available with Antares >= 8.7.0.
 #'
@@ -440,6 +441,7 @@ extract_el <- function(l, indice) {
 #'  - s or solar
 #'  - t or thermal
 #'  - w or wind
+#'  - hfl or hydro final level
 #' 
 #' @export
 #' 
@@ -462,15 +464,18 @@ updateScenarioBuilder <- function(ldata,
 
   if (!is.list(ldata)) {
     if (!is.null(series)) {
-      if (! all(series %in% ref_series$series)) {
+      if (! all(series %in% ref_series$series)) 
         stop("Your argument series must be one of ", paste0(ref_series$series, collapse = ", "), call. = FALSE)
-      }
       choices <- ref_series[ref_series$series %in% series, "choices"]
       if (isTRUE("ntc" %in% series) & isTRUE(opts$antaresVersion < 820))
-        stop("updateScenarioBuilder: cannot use series='ntc' with Antares < 8.2.0", call. = FALSE)
+        stop("updateScenarioBuilder: cannot use series='ntc' with Antares < 8.2.0", 
+             call. = FALSE)
       if (isTRUE("bc" %in% series) & isTRUE(opts$antaresVersion < 870))
         stop("updateScenarioBuilder: cannot use series='bc' with Antares < 8.7.0", 
              call. = FALSE)
+      if (isTRUE("hfl" %in% series) & isTRUE(opts$antaresVersion < 920))
+        stop("updateScenarioBuilder: cannot use series='hfl' with Antares < 9.2", 
+             call. = FALSE)
       series <- ref_series[ref_series$choices %in% choices & ref_series$type == "w", "series"]
     } else {
       stop("If 'ldata' isn't a named list, you must specify which serie(s) to use!", call. = FALSE)
@@ -495,6 +500,9 @@ updateScenarioBuilder <- function(ldata,
     if (isTRUE("bc" %in% series) & isTRUE(opts$antaresVersion < 870))
       stop("updateScenarioBuilder: cannot use series='bc' with Antares < 8.7.0", 
            call. = FALSE)
+    if (isTRUE("hfl" %in% series) & isTRUE(opts$antaresVersion < 920))
+      stop("updateScenarioBuilder: cannot use series='hfl' with Antares < 9.2", 
+           call. = FALSE)
     sbuild <- lapply(
       X = series,
       FUN = function(x) {
@@ -597,7 +605,7 @@ listify_sb <- function(mat,
   dtsb[, variable := as.numeric(gsub("V", "", variable)) - 1]
   dtsb <- dtsb[value != "rand"]
 
-  if (identical(series, "hl")) {
+  if (series %in% c("hl", "hfl")) {
     dtsb[, value := as.numeric(value)]
     if(min(dtsb$value) < 0 | max(dtsb$value) > 1) {
       stop("Every coefficient for hydro levels must be between 0 and 1.", call. = FALSE)

tests/testthat/test-scenarioBuilder.R

@@ -631,3 +631,64 @@ test_that("scenarioBuilder works with binding constraint (v870)", {
   # remove temporary study
   deleteStudy()
 })
+
+
+# v920----
+suppressWarnings(
+  createStudy(path = tempdir(), 
+              study_name = "scenariobuilder9.2", 
+              antares_version = "9.2"))
+
+# default area with st cluster
+area_test = c("al", "be") 
+lapply(area_test, createArea)
+
+test_that("Check minimal version", {
+  my_coef <- runif(length(getAreas()))
+
+  opts <- simOptions()
+  opts$antaresVersion <- 880
+
+  # one constraint => nb areas must be equal to nb coeff
+  ldata <- scenarioBuilder(
+    n_scenario = 10,
+    n_mc = 10,
+    areas = area_test,
+    coef_hydro_levels = my_coef
+  )
+
+  expect_error(
+    updateScenarioBuilder(ldata = ldata,
+                          series = "hfl", 
+                          opts = opts), 
+               regexp = "updateScenarioBuilder: cannot use series='hfl' with Antares < 9.2"
+  )
+})
+
+
+test_that("Add new 'hfl' equivalent to 'hl'", {
+  # nb coeff equivalent to nb areas
+  my_coef <- runif(length(getAreas()))
+
+  opts <- simOptions()
+
+  # one constraint => nb areas must be equal to nb coeff
+  ldata <- scenarioBuilder(
+    n_scenario = 10,
+    n_mc = 10,
+    areas = area_test,
+    coef_hydro_levels = my_coef
+  )
+
+  updateScenarioBuilder(ldata = ldata,
+                        series = "hfl")
+
+  newSB <- readScenarioBuilder(as_matrix = FALSE)
+  expect_true("hfl" %in% names(newSB))
+
+  values_newSB_hfl <- unique(unlist(newSB[["hfl"]], use.names = FALSE))
+  expect_equal(length(my_coef), length(values_newSB_hfl)) 
+  expect_equal(my_coef, values_newSB_hfl)
+})
+
+deleteStudy()

vignettes/Antares_new_features_v920.Rmd

@@ -229,6 +229,34 @@ updateAdequacySettings(
 updateAdequacySettings(enable_first_step = FALSE)
 ```
 
+
+## Scenario builder
+
+The scenario builder allows you to use a new code `hfl` for 'hydro final level'. 
+This new feature is similar to `hl` ('hydro levels') and is used in the same way with the 'coef_hydro_levels' parameter.
+
+```{r scenariobuilder}
+# the number of coeff is equivalent to the number of areas
+  my_coef <- runif(length(getAreas()))
+
+  opts <- simOptions()
+
+  # build data 
+  ldata <- scenarioBuilder(
+    n_scenario = 10,
+    n_mc = 10,
+    areas = getAreas(),
+    coef_hydro_levels = my_coef
+  )
+
+  # update scenearionbuilder.dat
+  updateScenarioBuilder(ldata = ldata,
+                        series = "hfl")
+
+  readScenarioBuilder(as_matrix = TRUE)
+```
+
+
 ```{r delete study, include=FALSE}
 # Delete study
 unlink(current_study_opts$studyPath, 
@@ -238,6 +266,3 @@ options(antares = NULL)
 ```
 
 
-
-
-