Ant765/add vignette geographic trimming (#122)

* Add 'geographic.trimming' parameter in updateGeneralSettings() * Add vignette 'Edit geographic trimming' * Add opts in vignette 'Edit geographic trimming' * Complete unit tests of updateGeneralSettings() * Clarify updateGeneralSettings() documentation * Correct updateGeneralSettings() documentation
rte-antares-rpackage · Jan 22, 2024 · 270e14e · 270e14e
1 parent e873cf0
commit 270e14e
Show file tree

Hide file tree

Showing 5 changed files with 73 additions and 6 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -2,7 +2,8 @@
 
 NEW FEATURES :
 
-* Complete function `deleteStudy()` with new parameter `simulation` to delete a simulation in an Antares study
+* Complete function `deleteStudy()` with new parameter `simulation` to delete a simulation in an Antares study.
+* New parameter `geographic.trimming` in `updateGeneralSettings()`to activate or deactivate this general parameter.
 
 ### Breaking changes
 

diff --git a/R/updateGeneralSettings.R b/R/updateGeneralSettings.R
@@ -38,7 +38,7 @@
 #' @param refreshintervalthermal See Antares General Reference Guide.
 #' @param refreshintervalsolar See Antares General Reference Guide.
 #' @param readonly See Antares General Reference Guide.
-#' 
+#' @param geographic.trimming \code{logical} indicates whether to store the results for all time spans (FALSE) or for custom time spans (TRUE)
 #' @template opts
 #' 
 #' @export
@@ -88,6 +88,7 @@ updateGeneralSettings <- function(mode = NULL,
                                   refreshintervalthermal = NULL, 
                                   refreshintervalsolar = NULL, 
                                   readonly = NULL,
+                                  geographic.trimming = NULL,
                                   opts = antaresRead::simOptions()) {
 
   assertthat::assert_that(inherits(opts, "simOptions"))
@@ -132,7 +133,8 @@ updateGeneralSettings <- function(mode = NULL,
     refreshintervalwind = refreshintervalwind,
     refreshintervalthermal = refreshintervalthermal,
     refreshintervalsolar = refreshintervalsolar,
-    readonly = readonly
+    readonly = readonly,
+    geographic.trimming = geographic.trimming
   )
   new_params <- dropNulls(new_params)
   for (i in seq_along(new_params)) {
@@ -252,7 +254,7 @@ dicoGeneralSettings <- function(arg) {
       "nbtimeserieshydro", "nbtimeserieswind", "nbtimeseriesthermal", 
       "nbtimeseriessolar", "refreshtimeseries", "intra-modal", "inter-modal", 
       "refreshintervalload", "refreshintervalhydro", "refreshintervalwind", 
-      "refreshintervalthermal", "refreshintervalsolar", "readonly")
+      "refreshintervalthermal", "refreshintervalsolar", "readonly", "geographic-trimming")
   )
   names(antares_params) <- c("mode", "horizon", "nbyears", "simulation.start", "simulation.end", 
                              "january.1st", "first.month.in.year", "first.weekday", "leapyear", 
@@ -261,7 +263,7 @@ dicoGeneralSettings <- function(arg) {
                              "nbtimeserieshydro", "nbtimeserieswind", "nbtimeseriesthermal", 
                              "nbtimeseriessolar", "refreshtimeseries", "intra.modal", "inter.modal", 
                              "refreshintervalload", "refreshintervalhydro", "refreshintervalwind", 
-                             "refreshintervalthermal", "refreshintervalsolar", "readonly")
+                             "refreshintervalthermal", "refreshintervalsolar", "readonly", "geographic.trimming")
   antares_params[[arg]]
 }
 

diff --git a/man/updateGeneralSettings.Rd b/man/updateGeneralSettings.Rd
diff --git a/tests/testthat/test-updateGeneralSettings.R b/tests/testthat/test-updateGeneralSettings.R
@@ -12,10 +12,15 @@ sapply(studies, function(study) {
 
   test_that("Update a general parameter", {
 
+    # year-by-year
+    expect_true(getOption("antares")$parameters$general$`year-by-year`)
     updateGeneralSettings(year.by.year = FALSE)
-
     expect_false(getOption("antares")$parameters$general$`year-by-year`)
 
+    # geographic-trimming
+    expect_true(getOption("antares")$parameters$general$`geographic-trimming`)
+    updateGeneralSettings(geographic.trimming = FALSE)
+    expect_false(getOption("antares")$parameters$general$`geographic-trimming`)
   })
 
   # remove temporary study

diff --git a/vignettes/antaresEditObject.Rmd b/vignettes/antaresEditObject.Rmd
@@ -301,3 +301,59 @@ writeInputTS(area = my_area,
             opts = opts
 )
 ```
+
+## Edit geographic trimming
+
+```r
+# set the path to an Antares study
+my_study <- file.path("", "", "")
+opts <- setSimulationPath(my_study, simulation ="input")
+
+# choose geographic trimming when creating new Antares areas
+# default filtering : c("hourly","daily","weekly","monthly","annual")
+initial_filtering_synthesis <- c("weekly","monthly")
+initial_filtering_year_by_year <- c("monthly","annual")
+
+
+opts <- createArea(name = "area1",
+                   filtering = filteringOptions(
+                     filter_synthesis = initial_filtering_synthesis,
+                     filter_year_by_year = initial_filtering_year_by_year),
+                   opts = opts)
+opts <- createArea(name = "area2",opts = opts)
+opts <- createLink(from = "area1", 
+                   to = "area2", 
+                   propertiesLink = propertiesLinkOptions(
+                     filter_synthesis = initial_filtering_synthesis,
+                     filter_year_by_year = initial_filtering_year_by_year),
+                   opts = opts)
+
+# check the initial filters
+initial_GT <- getGeographicTrimming(areas="area1",links=TRUE,opts=opts)
+print(initial_GT$areas[["area1"]])
+print(initial_GT$links[["area1 - area2"]])
+
+# edit geographic trimming of an existing area or link
+new_filtering_synthesis <- c("monthly")
+new_filtering_year_by_year <- c("annual")
+
+opts <- editArea(name = "area1", 
+                 filtering = filteringOptions(
+                   filter_synthesis = new_filtering_synthesis,
+                   filter_year_by_year = new_filtering_year_by_year),
+                 opts = opts)
+opts <- editLink(from = "area1",
+                 to = "area2",
+                 filter_year_by_year = new_filtering_year_by_year,
+                 filter_synthesis = new_filtering_synthesis,
+                 opts = opts) 
+
+# check the new filters
+new_GT <- antaresRead::getGeographicTrimming(areas="area1",links=TRUE,opts=opts)
+print(new_GT$areas[["area1"]])
+print(new_GT$links[["area1 - area2"]])
+
+# important : make sure that `geographic-trimming` parameter is activated in general settings
+opts <- updateGeneralSettings(geographic.trimming = TRUE,opts = opts)
+```
+