Generate a new calendar object from — newCalendar • energyRt

Sub-annual time resolution is represented by nested, named time-frames and time-slices.

Usage

newCalendar(timetable = NULL, year_fraction = 1, ...)

make_timetable(
  struct = list(ANNUAL = "ANNUAL"),
  year_fraction = 1,
  warn = FALSE
)

Arguments

timetable: data.frame with the calendar structure.
year_fraction: numeric scalar, used for validation or calculation (if missing) of the `share` column in the given `timetable`. The default value is `1L` meaning the sum of shares of all slices in the table is equal to one (year). Lower than one value indicates that the calendar represents not a full year. Assigning the parameter to `NULL` will drop the validation.
...: optional `name`, `desc`, strings, character `default_timeframe`, and list `misc` with any relevant content. All other arguments will be ignored.
struct: named list of timeframes with sets of timeslices and optional shares of every slice or frame in the nest
warn: logical, if TRUE, warning will be issued if `ANNUAL` level does not exists in the given structure. The level will be auto-created to complete the time-structure.

Value

an object of class `calendar` with the specified structure.

an data.frame with the specified structure.

Slots

name

character, (optional) name of the calendar for own references

desc

character, (optional) description of the calendar

timeframes

a named list of nested sub-annual levels with vectors of individual elements.

timetable

data.frame with levels of timeframes in the named columns, and number of rows equal to the total number of time-slices on the lowest level. Every timeframe is a set of timeslices ("slices") - a named fragment of time with a year-share. Timeframes have nested structure. Though every slice may have different sub-slices (similar to the real-world calendar).

ANNUAL: character, annual, the top level of timeframes
TIMEFRAME2: character, (optional) first subannual level of timeframes
TIMEFRAME3: character, (optional) second subannual level of timeframes
...: character, (optional) further subannual levels of timeframes
slice: character, name of the time-slices used in sets to refer to the lowest level of timeframes. If not specified, will be auto-created with the formula: `SLICE2_SLICE3...`

year_fraction

numeric, the fraction of a year covered by the calendar, e.g. 1 for annual calendar (default), 0.5 for semi-annual, 0.25 for quarterly, etc. If not specified, will be calculated as sum of `timetable$share` or used default value (1).

slice_share

two column data.frame with slices from all levels with their individual share in a year.

default_timeframe

character, the name of the default level of the time-slices used in the model.

timeframe_rank

named character vector with ranks of the timeframes.

slices_in_frame

(!!! to depreciate)

slice_family

data.frame mapping "parent" to "child" slices in two nearest timeframes in the nested hierarchy. Autocalculated based on the `@timetable`.

next_in_timeframe

data.frame mapping chronological sequence between time-slices in the same timeframe. The first timeslice folows the last in the same timeframe. Autocalculated based on the `@timetable`.

next_in_year

data.frame mapping chronological sequence between time-slices in the same timeframe through the whole year. Autocalculated based on the `@timetable`.

misc

list with additional data and calculated mappings.

Examples

newCalendar()
#> An object of class "calendar"
#> Slot "name":
#> character(0)
#> 
#> Slot "desc":
#> character(0)
#> 
#> Slot "timeframes":
#> $ANNUAL
#> [1] "ANNUAL"
#> 
#> 
#> Slot "year_fraction":
#> [1] 1
#> 
#> Slot "timetable":
#>    ANNUAL  slice share weight
#>    <char> <char> <num>  <num>
#> 1: ANNUAL ANNUAL     1      1
#> 
#> Slot "slice_share":
#>     slice share weight
#>    <char> <num>  <num>
#> 1: ANNUAL     1      1
#> 
#> Slot "default_timeframe":
#> [1] "ANNUAL"
#> 
#> Slot "timeframe_rank":
#> ANNUAL 
#>      1 
#> 
#> Slot "slices_in_frame":
#> ANNUAL 
#>      1 
#> 
#> Slot "slice_family":
#> Empty data.table (0 rows and 2 cols): parent,child
#> 
#> Slot "slice_ancestry":
#> Empty data.table (0 rows and 2 cols): parent,child
#> 
#> Slot "next_in_timeframe":
#> Empty data.table (0 rows and 2 cols): slice,slicep
#> 
#> Slot "next_in_year":
#> Empty data.table (0 rows and 2 cols): slice,slicep
#> 
#> Slot "misc":
#> list()
#> 
make_timetable()
#>    ANNUAL  slice share weight
#>    <char> <char> <num>  <num>
#> 1: ANNUAL ANNUAL     1      1
make_timetable(list("SEASON" = c("WINTER", "SUMMER")))
#>    ANNUAL SEASON  slice share weight
#>    <char> <char> <char> <num>  <num>
#> 1: ANNUAL SUMMER SUMMER   0.5      1
#> 2: ANNUAL WINTER WINTER   0.5      1
make_timetable(list("SEASON" = c("WINTER" = .6, "SUMMER" = .4)))
#>    ANNUAL SEASON  slice share weight
#>    <char> <char> <char> <num>  <num>
#> 1: ANNUAL SUMMER SUMMER   0.4      1
#> 2: ANNUAL WINTER WINTER   0.6      1
make_timetable(list(
  "SEASON" = list(
    "WINTER" = list(.3, DAY = c("MORNING", "EVENING")),
    "SUMMER" = list(.7, DAY = c("MORNING", "EVENING"))
  )
))
#>    ANNUAL SEASON     DAY          slice share weight
#>    <char> <char>  <char>         <char> <num>  <num>
#> 1: ANNUAL SUMMER EVENING SUMMER_EVENING  0.35      1
#> 2: ANNUAL SUMMER MORNING SUMMER_MORNING  0.35      1
#> 3: ANNUAL WINTER EVENING WINTER_EVENING  0.15      1
#> 4: ANNUAL WINTER MORNING WINTER_MORNING  0.15      1

make_timetable(list(
  "SEASON" = list("WINTER" = .3, "SUMMER" = .7),
  "DAY" = c("MORNING", "EVENING")
))
#>    ANNUAL SEASON     DAY          slice share weight
#>    <char> <char>  <char>         <char> <num>  <num>
#> 1: ANNUAL SUMMER EVENING SUMMER_EVENING  0.35      1
#> 2: ANNUAL SUMMER MORNING SUMMER_MORNING  0.35      1
#> 3: ANNUAL WINTER EVENING WINTER_EVENING  0.15      1
#> 4: ANNUAL WINTER MORNING WINTER_MORNING  0.15      1