enhance documentations

R/modifyInvestmentVariables.R

@@ -1,18 +1,15 @@
 #' Modify Investment Variables
 #'
-#' Timesteps for investment variables represent a different year range than
-#' general REMIND reporting. This function transforms investment data to the
-#' general REMIND timesteps representation.
+#' This function transforms investment variables to the normal reporting convention.
 #'
-#' See also: https://github.com/remindmodel/remind/pull/1238.
+#' Years represented by investment variables in the energy system
+#' ('vm_deltaCap', 'vm_costInvTeDir' and 'vm_costInvTeAdj') are different from the normal
+#' reporting convention. In the current REMIND version, vm_deltacap(t) represents
+#' the average of the years t-4..t, while in the general reporting
+#' convention it represents the average of t-2.5..t+2.5 (for 5 year time steps).
 #'
-#' For investment variables, the timesteps represent the years as follows:
-#' * 5-year timesteps: t represents t .. t-4, e.g. for 2005: 2001-2005
-#  * 10-year timesteps: t represents t .. t-9, e.g. for 2070: 2061-2070
-#  * 20-year timesteps: t represents t .. t-19, e.g. for 2150: 2131-2150
+#' See also: https://github.com/remindmodel/remind/pull/1238.
 #'
-#' In REMIND, the timesteps represent the years around the timestep, taking
-#' into account the length of the period between t-1..t as well as t..t+1
 #' @seealso \code{\link{quitte::remind_timesteps}}
 #'
 #' @param x a magclass object to be manipulated, must have timesteps in 'ttot'

R/reportCapacity.R

@@ -56,6 +56,9 @@ reportCapacity <- function(gdx, regionSubsetList = NULL,
   vm_deltaCap <- vm_deltaCap[teall2rlf]
   vm_deltaCap <- vm_deltaCap[, ttot, ]
 
+  # apply 'modifyInvestmentVariables' to shift from the model-internal time coverage (deltacap and investment
+  # variables for step t represent the average of the years from t-4years to t) to the general convention for
+  # the reporting template (all variables represent the average of the years from t-2.5years to t+2.5years)
   if (!is.null(gdx_ref)) {
     cm_startyear <- as.integer(readGDX(gdx, name = "cm_startyear", format = "simplest"))
     vm_deltaCapRef <- readGDX(gdx_ref, name = c("vm_deltaCap"), field = "l", format = "first_found") * 1000

R/reportEnergyInvestment.R

@@ -73,6 +73,9 @@ reportEnergyInvestment <- function(gdx, regionSubsetList = NULL,
 
   ttot <- as.numeric(as.vector(readGDX(gdx, "ttot", format = "first_found")))
 
+  # apply 'modifyInvestmentVariables' to shift from the model-internal time coverage (deltacap and investment
+  # variables for step t represent the average of the years from t-4years to t) to the general convention for
+  # the reporting template (all variables represent the average of the years from t-2.5years to t+2.5years)
   if (!is.null(gdx_ref)) {
     v_directteinv_ref <- readGDX(gdx_ref, name = c("v_costInvTeDir", "vm_costInvTeDir", "v_directteinv"),
                              field = "l", format = "first_found")

R/reportLCOE.R

@@ -142,7 +142,6 @@ reportLCOE <- function(gdx, output.type = "both", gdx_ref = NULL) {
 
     ## variables
 
-
     ## Total direct Investment Cost in Timestep
     vm_costInvTeDir <- readGDX(gdx, name = c("vm_costInvTeDir", "v_costInvTeDir", "v_directteinv"), field = "l", format = "first_found")[, ttot, ]
 
@@ -152,12 +151,18 @@ reportLCOE <- function(gdx, output.type = "both", gdx_ref = NULL) {
     # capacity additions per year
     vm_deltaCap <- readGDX(gdx, name = c("vm_deltaCap"), field = "l", format = "first_found")[, ttot, ]
 
+    # apply 'modifyInvestmentVariables' to shift from the model-internal time coverage (deltacap and investment
+    # variables for step t represent the average of the years from t-4years to t) to the general convention for
+    # the reporting template (all variables represent the average of the years from t-2.5years to t+2.5years)
     if (!is.null(gdx_ref)) {
       cm_startyear <- as.integer(readGDX(gdx, name = "cm_startyear", format = "simplest"))
 
-      vm_costInvTeDirRef <- readGDX(gdx_ref, name = c("vm_costInvTeDir", "v_costInvTeDir", "v_directteinv"), field = "l", format = "first_found")[, ttot, ]
-      vm_costInvTeAdjRef <- readGDX(gdx_ref, name = c("vm_costInvTeAdj", "v_costInvTeAdj"), field = "l", format = "first_found")[, ttot, ]
-      vm_deltaCapRef <- readGDX(gdx_ref, name = c("vm_deltaCap"), field = "l", format = "first_found")[, ttot, ]
+      vm_costInvTeDirRef <- readGDX(gdx_ref, name = c("vm_costInvTeDir", "v_costInvTeDir", "v_directteinv"),
+                                    field = "l", format = "first_found")[, ttot, ]
+      vm_costInvTeAdjRef <- readGDX(gdx_ref, name = c("vm_costInvTeAdj", "v_costInvTeAdj"),
+                                    field = "l", format = "first_found")[, ttot, ]
+      vm_deltaCapRef <- readGDX(gdx_ref, name = c("vm_deltaCap"),
+                                field = "l", format = "first_found")[, ttot, ]
 
       vm_costInvTeDir <- modifyInvestmentVariables(vm_costInvTeDir, vm_costInvTeDirRef, cm_startyear)
       vm_costInvTeAdj <- modifyInvestmentVariables(vm_costInvTeAdj, vm_costInvTeAdjRef, cm_startyear)