# Structure file to describe data in Belvis instance.
# Comments are used to indicate the expected specification format.
#
# This is a *complex* example, showcasing the full possibilities.

########
# Header
########

tz: Europe/Berlin 
freq: D                 # frequency to convert all data into before returning

#################
# Portfolio lines
#################

pflines:

# Here we define the portfolio lines we want to access for each portfolio. (We can make
# portfolio-specific corrections further below.) The keys ("pfline ids") in this section
# can be freely chosen; they point to timeseries names that exist in belvis.

  current_offtake: Offtake volume in MW
  # A pfline id can point to a single timeseries name. The unit of the timeseries is used 
  # to determine what information we have. (In this case, assuming the name is sensible, 
  # this is a volume timeseries, which is used to create a volume-only portfolio line).

  expected_offtake: 
  - Offtake volume in MW
  - Expected churn in MW
  # It can also point to a list of timeseries. In that case, timeseries with the same unit
  # unit are added. In this case, we again obtain a volume-only portfolio line...

  forward_sourced:
  - Procurement forward volume NCG in MW
  - Procurement forward volume Gaspool in MW
  - Procurement forward cost NCG in EUR
  - Procurement forward cost Gaspool in EUR
  # ...and in this case, due to the distinct units, a price-and-volume portfolio line.

  sourced_by_market:
    dayahead:
    - Procurement dayahead volume in MW
    - Procurement dayahead cost in EUR
    forward: forward_sourced # we can reuse definitions
  # Nesting is allowed. In this case, we obtain a nested portfolio line with children 
  # "forward" and "dayahead".

  sourced_by_market_and_product:
    dayahead:
    - Procurement dayahead volume in MW
    - Procurement dayahead cost in EUR
    forward:
      NCG:
      - Procurement forward volume NCG in MW
      - Procurement forward cost NCG in EUR
      Gaspool:
      - Procurement forward volume Gaspool in MW
      - Procurement forward cost Gaspool in EUR
  # Nesting is not limited to one level. Here, we have children "forward" and "dayahead",
  # with the "forward" child again having 2 children "NCG" and "Gaspool".

############
# Portfolios
############

portfolios:

# The portfolios we are interested in.
# This section has one part "original", and possibly also a part "sythetic".

  original: 
  - B2C_household
  - B2C_Spot
  - B2B_backtoback
  - B2B_Spot
  # This is a list of portfolio ids that are present in belvis. The list elements are the
  # portfolio ids (or "portfolio abbreviations", or "short names") as they are present in 
  # belvis. 

  synthetic:
  # In the sythetic part, we can create portfolios that do not exist in belvis but that we
  # are interested in nonetheless; they extend the portfolio ids that are available to the user.
  # The keys ("pfids") in this section can be freely chosen; they point to portfolio ids
  # that exist in belvis.

    B2B_BtB: B2B_backtoback  # Specifies an alias.
    # A pfid can point to a single existing portfolio id.

    B2B_all: [B2B_backtoback, B2B_Spot]
    B2C_all: [B2C_household, B2C_Spot]
    Spot_all: [B2C_Spot, B2B_Spot]
    all: [B2B_all, B2C_all] # We can reuse definitions.
    # It can also point to a several portfolio ids. These are added.

    # In order to avoid complexity, nesting is not allowed for portfolios.
    # This way, only the portfolio lines can cause nesting, and we don't have to think
    # about the nesting order.


##########################################
# Corrections: portfolio line vs portfolio 
##########################################

corrections: 

# This is a dictionary to make portfolio-specific corrections to the default portfolio 
# lines defined above. The keys are one or more of the pfids from the "original" list,
# above. If the default pfline definitions are correct for each of the original portfolios,
# no corrections are needed and this section can be removed.

  B2B_Spot: # pfid

    current_offtake: # existing pfline id
    - Initially contracted offtake volume in MW
    - Additional churn due to price increase
    # We can override the default definition by reusing the pfline id.

    expected_offtake: none
    # By setting it to none, we indicate it is not available for this portfolio.


  B2C_household:

    high_offtake_scenario: # new pfline id
    - expected_offtake
    - offtake growth bull market
    # We can also specify a new/additional pfline id that is only available in this portfolio.

########
# Prices
########

prices:

# This section points to where market price timeseries are located in belvis.
# The keys ("price ids") in this section can be freely chosen; each is a dictionary 
# with keys 'pfid' and 'tsnames', indicating the belvis portfolio id and the timeseries 
# name of the price timeseries. Just as above; we can specify a single timeseries, an array
# of timeseries, or a nested structure.

  fwc_monthly_DE:
    pfid: Germany
    tsnames: MPFC (THE)
  # Just as above, we can specify a single timeseries...

  fwc_daily_DE:
    pfid: Germany
    tsnames: 
    - MPFC (THE)
    - M2D profile
  # ...or multiple ones, as long as they are in the same folder...

  fwc_daily_DE_nested:
    pfid: Germany
    tsnames: 
      monthly: MPFC (THE)
      month_2_day: M2D profile
  # ...or multiple ones from the same folder, forming a nested structure.
