Add new function readAntaresSTClusters() (#254)

* Add condition in .giveInfoRequest(), create readAntaresSTClusters() and fix tests
* Add unit tests for eadAntaresSTClusters()

NAMESPACE

@@ -48,6 +48,7 @@ export(ponderateMcAggregation)
 export(readAntares)
 export(readAntaresAreas)
 export(readAntaresClusters)
+export(readAntaresSTClusters)
 export(readBindingConstraints)
 export(readClusterDesc)
 export(readClusterResDesc)

NEWS.md

@@ -11,6 +11,8 @@ NEW FEATURES:
 * `setSimulationPath()` return a new parameter `binding` (for studies >= v8.7.0). 
 It contains a table with group dimensions of time series for binding constraints.
 * `readAntares()` new parameter **clustersST** to read (output simulation) short-term clusters
+* New function `readAntaresSTClusters()`
+
 
 BREAKING CHANGES :
 

R/readAntares.R

@@ -897,7 +897,7 @@ readAntaresAreas <- function(areas, links = TRUE, clusters = TRUE, clustersRes =
   if ("mcYears" %in% unlist(select) & is.null(mcYears)) mcYears <- "all"
 
   # If all arguments are NULL, import all areas
-  if (is.null(areas) & is.null(links) & is.null(clusters) & is.null(districts)) {
+  if (is.null(areas) & is.null(links) & is.null(clusters) & is.null(districts) & is.null(clustersST)) {
     areas <- "all"
   }
 

R/readAntaresClusters.R

@@ -36,4 +36,56 @@ readAntaresClusters <- function(clusters, selected = c("production", "NP Cost",
 
   subset(res, cluster %in% clusters, select = c(setdiff(colnames(res),c("production", "NP Cost", "NODU", "profit")),
                                                 intersect(colnames(res),selected))) #support for up to v8.4
-}
+}
+
+
+#' Read output for a list of short-term storage clusters
+#'
+#' @param clustersST vector of short-term storage clusters to be imported
+#' @param selected vector of thematic trimming
+#' @inheritParams readAntares
+#'
+#' @return data.table of results for short-term storage clusters
+#'
+#' @export
+readAntaresSTClusters <- function(clustersST, selected = c("P.injection", "levels", "P.withdrawal"),
+                                  timeStep = c("hourly", "daily", "weekly", "monthly", "annual"),
+                                  opts = simOptions(), parallel = FALSE, showProgress = TRUE) {
+
+  if (missing(clustersST)) { 
+    stop("The function 'readAntaresSTClusters' expects a vector of short-term storage clusters names as argument.")
+  }
+  if ("Input" %in% opts$mode) {
+    stop("Cannot use 'readAntaresSTClusters' in 'Input' mode.")
+  }
+  if (opts$antaresVersion < 860) {
+    stop("Cannot use 'readAntaresSTClusters' for a study version < 860.")
+  }
+
+  ##Add check control for all
+  allSTClusters <- readClusterSTDesc(opts = opts)[, c("area","cluster")]
+  allSTClusters$lower_cluster <- tolower(allSTClusters$cluster)
+  ind_cluster <- which(allSTClusters$lower_cluster %in% .checkArg(tolower(clustersST), 
+                                                                  tolower(unique(allSTClusters$cluster)), 
+                                                                  "short-term storage clusters %s do not exist in the simulation."))
+  clustersST <- allSTClusters$cluster[ind_cluster]
+
+  ind_cluster <- which(allSTClusters$lower_cluster %in% .checkArg(tolower(clustersST), 
+                                                                  tolower(unique(allSTClusters[area %in% opts$areasWithSTClusters]$cluster)), 
+                                                                  "short-term storage clusters %s have no output."))
+  clustersST <- unique(allSTClusters$cluster[ind_cluster])
+
+  output_st_clusters <- data.table()
+  if (length(clustersST) > 0) {  
+    areas <- unique(allSTClusters[cluster %in% clustersST]$area)
+
+    res <- readAntares(clustersST = areas, timeStep = timeStep, opts = opts, 
+                       parallel = parallel, showProgress = showProgress)  
+
+    output_st_clusters <- subset(res, cluster %in% clustersST, select = c(setdiff(colnames(res),c("P.injection", "levels", "P.withdrawal")),
+                                                                    intersect(colnames(res),selected))
+                                                                    )
+  }
+
+  return(output_st_clusters)
+}

tests/testthat/test-readAntares_STclusters.R

@@ -4,13 +4,50 @@ context("Function readAntares (ST clusters)")
 
 path_study_test <- grep(pattern = "87", x = studyPathSV8, value = TRUE)
 
-opts <- setSimulationPath(path_study_test,simulation="20240105-0934eco")
+suppressWarnings(opts <- setSimulationPath(path_study_test, simulation = "20240105-0934eco"))
 
 test_that("ST clusters importation is ok", {
 
-  clustersST <- readAntares(clustersST="all",timeStep="annual",opts = opts)$clustersST
+  clustersST <- readAntares(clustersST = "all", timeStep = "annual",opts = opts)
   expect_true(all(opts$areasWithSTClusters %in% clustersST$area))
 
-  clustersST_fr <- readAntares(clustersST="fr",timeStep="annual",opts = opts)$clustersST
-  expect_true("fr"==unique(clustersST_fr$area))
+  clustersST_fr <- readAntares(clustersST = "fr", timeStep = "annual", opts = opts)
+  expect_true("fr" == unique(clustersST_fr$area))
+})
+
+
+test_that("ST clusters importation is OK", {
+  nweeks_study <- 52
+	output_cols <- c("P.injection", "levels", "P.withdrawal")
+  clusters <- readAntaresSTClusters(clusters = "fr_st_other1", selected = output_cols[1:2], timeStep = "hourly", showProgress = FALSE, opts = opts)
+  expect_is(clusters, "data.table")
+  expect_true(!is.null(clusters$cluster))
+  expect_equal(nrow(clusters), 24 * 7 * nweeks_study)
+	expect_true(all(output_cols[1:2] %in% colnames(clusters)))
+	expect_false(output_cols[3] %in% colnames(clusters))
+})
+
+
+test_that("ST clusters importation is OK for all time resolutions.", {
+  nweeks_study <- 52 
+  for (timeStep in c("hourly", "daily", "weekly", "monthly", "annual")) {
+    expected_rows = switch(timeStep,
+                           hourly = 24 * 7 * nweeks_study,
+                           daily = 7 * nweeks_study,
+                           weekly = nweeks_study,
+                           monthly = 12,
+                           annual = 1)
+
+    clusters <- readAntaresSTClusters(clusters = "fr_st_other1", showProgress = FALSE, timeStep = timeStep)
+    expect_equal(nrow(clusters), expected_rows)
+  }
+})
+
+
+test_that("ST clusters importation is KO if clusters do not belong to the study output", {
+  expect_warning(clusters <- readAntaresSTClusters(clusters = c("fake_one", "not_a_cluster"), timeStep = "hourly", showProgress = FALSE, opts = opts),
+	  regexp = "do not exist in the simulation"
+	)
+	expect_is(clusters, "data.table")
+  expect_true(nrow(clusters) == 0)
 })