Tenant

The Tenant class uses a structure specification (an instance of the Structure class) and an interface (an instance of the Api class) to retrieve timeseries (more specifically portfolyo.PfLine instances) from Belvis.

It also allows for some custom bespoke handling of the data which may be necessary due to the specifics of the Belvis implementation.

Initialisation

A tenant can be initialised using a Structure and an Api instance. Continuing the examples provided on their documentation pages:

import belvys

# Define the structure of the belvis tenant and the timeseries we're interested in.
structure = belvys.Structure.from_file('structureconf.yaml')

# Define where and how to access the rest api.
api = belvys.Api.from_file("apispec.yaml")
api.access_from_usr_pwd("Myfirst.Lastname", "my_5tr0ngp@ssw0rd")

# Create Tenant instance to query the data.
tenant = belvys.Tenant(structure, api)

Usage

The most important methods are .portfolio_pfl(), .price_pfl(), and general_pfl(). All return a portfolyo.PfLine (see here) instance. Here we see how they are used to get data for the 3-day (left-closed) time period from midnight 2024-09-05 until midnight 2024-09-08.

Portfolio data

.portfolio_pfl() returns timeseries data in a specific portfolio. The portfolio and the timeseries must specified in the Structure instance used in the initialisation.

# Continuation of previous example.
start, end = pd.Timestamp("2024-09-05"), pd.Timestamp("2024-09-08")
offtake = tenant.portfolio_pfl("B2C_household", "current_offtake", start, end)
offtake

PfLine object with volume information.
. Start: 2024-09-05 00:00:00+02:00 (incl)    . Timezone    : Europe/Berlin
. End  : 2024-09-08 00:00:00+02:00 (excl)    . Start-of-day: 00:00:00
. Freq : <15 * Minutes> (288 datapoints)
                                    w            q
                                   MW          MWh

2024-09-05 00:00:00 +0200        -67.8         -17
2024-09-05 00:15:00 +0200        -61.3         -15
2024-09-05 00:30:00 +0200        -55.5         -14
2024-09-05 00:45:00 +0200        -50.9         -13
..                                  ..          ..
2024-09-07 23:00:00 +0200       -105.7         -26
2024-09-07 23:15:00 +0200        -98.9         -25
2024-09-07 23:30:00 +0200        -91.4         -23
2024-09-07 23:45:00 +0200        -84.0         -21

Prices

.price_pfl() returns timeseries data for a certain price line. The price id must also be specified in the Structure instance.

# Continuation of previous example.
prices = tenant.price_pfl("fwc_monthly_DE", start, end)
prices

PfLine object with price information.
. Start: 2024-09-05 00:00:00+02:00 (incl)    . Timezone    : Europe/Berlin
. End  : 2024-09-08 00:00:00+02:00 (excl)    . Start-of-day: 00:00:00
. Freq : <15 * Minutes> (288 datapoints)
                                    p
                              Eur/MWh

2024-09-05 00:00:00 +0200      209.31
2024-09-05 00:15:00 +0200      189.06
2024-09-05 00:30:00 +0200      169.01
2024-09-05 00:45:00 +0200      147.89
..                                 ..
2024-09-07 23:00:00 +0200      198.68
2024-09-07 23:15:00 +0200      175.70
2024-09-07 23:30:00 +0200      152.81
2024-09-07 23:45:00 +0200      123.77

General

For convenience, the method .general_pfl() exists. It can be used to fetch data using the timeseries name. This is useful if data is needed from a timeseries that is not specified in the Structure instance.

# Continuation of previous example.
churn = tenant.general_pfl("B2C_Household", "Expected churn in MW", start, end)
churn

PfLine object with volume information.
. Start: 2024-09-05 00:00:00+02:00 (incl)    . Timezone    : Europe/Berlin
. End  : 2024-09-08 00:00:00+02:00 (excl)    . Start-of-day: 00:00:00
. Freq : <15 * Minutes> (288 datapoints)
                                     w           q
                                    MW         MWh

2024-09-05 00:00:00 +0200         -6.8          -2
2024-09-05 00:15:00 +0200         -6.1          -2
2024-09-05 00:30:00 +0200         -5.6          -1
2024-09-05 00:45:00 +0200         -5.1          -1
..                                  ..          ..
2024-09-07 23:00:00 +0200        -10.6          -3
2024-09-07 23:15:00 +0200         -9.9          -2
2024-09-07 23:30:00 +0200         -9.1          -2
2024-09-07 23:45:00 +0200         -8.4          -2

Cache

As mentioned in the Api documentation, it can be time-consuming querying the api for timeseries IDs. Even if these are cached, it might be a good idea to explicitly fill the cache beforehand. This can be done using the .update_cache() menthod. It finds all timeseries in each of the relevant portfolios, and stores their ID in the cache. Any subsequent queries will therefore only use the API to find the values of the timeseries - which cannot be cached (because there is many data, which also constantly changes).

Here too: if a file is specified when initialising the Api instance, or if the instance is initialised from a file (Api.from_file()), the cache is stored there and can be reused when the program ends.

Aftercare

Unfortunately, not always is the pandas Series that is returned by the Api.series() method perfect; it may need small changes before it can be turned into a portfolyo PfLine. This is where the “aftercare” functions come into play. For more information, see this seperate page: Aftercare.

Class Documentation

class belvys.Tenant(structure: Structure | None = None, api: Api | None = None)

Class to interact with belvis tenants and retrieve data.

Notes

An important attribute of this class is .aftercare, which is a function that is used to make small adjustments to the timeseries returned by the .api.series() method. This may be necessary due to local Belvis settings. The function must accept 4 arguments: the pandas Series, the timeseries id, the portfolio id, and the timeseries name. It must return a pandas Series from which a portfolio line (portfolyo.PfLine) can be initialized.

  • By default, the function makes three adjustments: it sets the timezone (to the one specified in .structure.tz), it infers the frequency of the timeseries, and it makes the timestamps leftbound. (by assuming the timestamps returned by Belvis are leftbound if they represent daily (or longer) time periods, and rightbound otherwise.

  • If the default is not what is needed, the user must specify a custom aftercare function. If a specific timeseries needs a special treatment, the function parameters (the timeseries id, the pfid, the timeseries name) can be used in the function definition to target that timeseries only. If they are not needed, *args may be used to “eat up” the unneeded parameters.

  • There are several ready-made adjustment functions available in the belvys.adjustment module.

If .portfolio_pfl() and .price_pfl() raise an Exception when creating the PfLine instance, inspect the series that the PfLine receives as input, by setting their output_series parameter to True.

general_pfl(pfid: str, tsname: str, ts_left: Timestamp, ts_right: Timestamp, missing2zero: bool = True, output_as_series: bool = False) → PfLine

Retrieve a portfolio line with portfolio-specific volume and/or price data from Belvis, without using the structure Use if wanted timeseries is not specified in the structure file.

Parameters:

  • pfid (str) – Id of portfolio as found in Belvis. Must be original.

  • tsname (str) – Name of the timeseries. Must be exact.

  • ts_left (pd.Timestamp) – Start of delivery period (incl)

  • ts_right (pd.Timestamp) – End of delivery period (excl)

  • missing2zero (bool, optional (default: True)) – What to do with values that are flagged as ‘missing’. True to replace with 0, False to replace with nan.

  • output_as_series (bool, optional (default: False)) – If True, stops after fetching timeseries data from api, and return those as series, list of series, or nested dictionary.

Return type:

pf.PfLine

portfolio_pfl(pfid: str, pflineid: str, ts_left: Timestamp, ts_right: Timestamp, missing2zero: bool = True, *, output_as_series: bool = False) → PfLine

Retrieve a portfolio line with portfolio-specific volume and/or price data from Belvis.

Parameters:

  • pfid (str) – Id of portfolio as defined in .Structure. May be original or synthetic.

  • pflineid (str) – Id of portfolio line as defined in .structure

  • ts_left (pd.Timestamp) – Start of delivery period (incl)

  • ts_right (pd.Timestamp) – End of delivery period (excl)

  • missing2zero (bool, optional (default: True)) – What to do with values that are flagged as ‘missing’. True to replace with 0, False to replace with nan.

  • output_as_series (bool, optional (default: False)) – If True, stops after fetching timeseries data from api, and return those as series, list of series, or nested dictionary.

Return type:

pf.PfLine

price_pfl(priceid: str, ts_left: Timestamp, ts_right: Timestamp, missing2zero: bool = True, *, output_as_series: bool = False) → PfLine

Retrieve a portfolio line with portfolio-UNspecific price data from Belvis.

Parameters:

  • priceid (str) – Id of price timeseries as defined in .structure

  • ts_left (pd.Timestamp) – Start of delivery period (incl)

  • ts_right (pd.Timestamp) – End of delivery period (excl)

  • missing2zero (bool, optional (default: True)) – What to do with values that are flagged as ‘missing’. True to replace with 0, False to replace with nan.

  • output_as_series (bool, optional (default: False)) – If True, stops after fetching timeseries data from api, and return those as series, list of series, or nested dictionary.

Return type:

pf.PfLine

update_cache() → None

Loop through all portfolios that may be fetched, find the timeseries they contain, and store all in cache. May take long time!