Full reference

This part of the documentation covers the public classes and methods for Energy Quantified’s Python library. All interaction with the API happens through the energyquantified.EnergyQuantified class:

The main client

The default client

class energyquantified.EnergyQuantified(api_key=None, api_key_file=None, ssl_verify=True, timeout=20.0, http_delay=0.0667, api_url='https://app.energyquantified.com/api', proxies=None)

The Time Series API client.

Wraps the Energy Quantified Time Series API. Handles validation, network errors, rate limiting, and parsing of the API responses.

Exactly one of api_key and api_key_file must be set at the same time. api_key_file shall be the file path to a file that contains just the API key (blank lines a stripped when read).

Parameters

  • api_key (string, optional) – The API key for your user account

  • api_key_file (string, file, optional) – A file path to a file that contains the API key

  • ssl_verify (bool, optional) – Whether or not to verify the server certificate, defaults to True

  • timeout (float, optional) – Maximum timeout per HTTP request, defaults to 20.0

  • http_delay (float, optional) – The minimum number of seconds between the start of each HTTP request, defaults to 0.0667 seconds (15 req/s)

  • proxies (dict, optional) – Map of proxies, defaults to None (no proxy)

Basic usage:

>>> from energyquantified import EnergyQuantified
>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.metadata.curves(q="de wind power actual")
instances

See energyquantified.api.InstancesAPI. For loading time series instances.

is_api_key_valid()

Check if the supplied API key is valid/user account can sign in.

Does so by trying to load the categories list. If it succeeds, then the user has supplied a valid API key.

Returns

True if API key is valid, otherwise False

Return type

bool

Raises

APIError – If there were any network- or server-related issues while check the API key

metadata

See energyquantified.api.MetadataAPI. For metadata queries (such as curve search and place lookups).

ohlc

See energyquantified.api.OhlcAPI. For loading OHLC data in various ways

period_instances

See energyquantified.api.PeriodInstancesAPI. For loading instances of period-based series.

periods

See energyquantified.api.PeriodsAPI. For loading period-based series.

srmc

See energyquantified.api.SrmcAPI. For loading and calculating short-run marginal costs (SRMC) from OHLC data.

timeseries

See energyquantified.api.TimeseriesAPI. For loading time series data.

The Realto client

class energyquantified.RealtoConnection(api_url=None, api_key=None, api_key_file=None, ssl_verify=True, timeout=20.0, http_delay=0.1, proxies=None)

The Time Series API client for customers subscribing via Realto.

Wraps a Energy Quantified Time Series API on Realto. Handles validation, network errors, rate limiting, and parsing of the API responses.

You must specify the api_url. There are

Exactly one of api_key and api_key_file must be set at the same time. api_key_file shall be the file path to a file that contains just the API key (blank lines a stripped when read).

Parameters

  • api_url (string, optional) – The root URL for the API, such as

  • api_key (string, optional) – The API key for your user account

  • api_key_file (string, file, optional) – A file path to a file that contains the API key

  • ssl_verify (bool, optional) – Whether or not to verify the server certificate, defaults to True

  • timeout (float, optional) – Maximum timeout per HTTP request, defaults to 20.0

  • http_delay (float, optional) – The minimum number of seconds between the start of each HTTP request, defaults to 0.1 seconds (10 req/s)

  • proxies (dict, optional) – Map of proxies, defaults to None (no proxy)

Basic usage:

>>> from energyquantified import RealtoConnection
>>> eq = RealtoConnection(
>>>     api_url=RealtoConnection.API_URL_GERMANY,
>>>     api_key="aaaa-bbbb-cccc-dddd"
>>> )
>>> eq.metadata.curves(q="de wind power actual")
API_URL_BELGIUM = 'https://api.realto.io/energyquantified-belgium'

The base URL for the Belgium data API on Realto.

API_URL_FRANCE = 'https://api.realto.io/energyquantified-france'

The base URL for the French data API on Realto.

API_URL_GERMANY = 'https://api.realto.io/energyquantified-germany'

The base URL for the German data API on Realto.

API_URL_NETHERLANDS = 'https://api.realto.io/energyquantified-netherlands'

The base URL for the Netherlands data API on Realto.

API_URL_UK = 'https://api.realto.io/energyquantified-greatbritain'

The base URL for the UK data API on Realto.

instances

See energyquantified.api.InstancesAPI. For loading time series instances.

is_api_key_valid()

Check if the supplied API key is valid/user account can sign in.

Does so by trying to load the categories list. If it succeeds, then the user has supplied a valid API key.

Returns

True if API key is valid, otherwise False

Return type

bool

Raises

APIError – If there were any network- or server-related issues while check the API key

metadata

See energyquantified.api.MetadataAPI. For metadata queries (such as curve search and place lookups).

period_instances

See energyquantified.api.PeriodInstancesAPI. For loading instances of period-based series.

periods

See energyquantified.api.PeriodsAPI. For loading period-based series.

timeseries

See energyquantified.api.TimeseriesAPI. For loading time series data.

API operations

The API operations are grouped into sections similar to the way the API is organized. Each of those sections are implemented in their own class.

Here are the different API section classes:

class energyquantified.api.MetadataAPI(*args, **kwargs)

Operations for curve search and place lookups. It also includes operations for listing attributes on energyquantified.metadata.Curve objects.

categories()

List all available categories.

Results are cached on repeated calls.

Returns

A set of available categories (strings)

Return type

set

curve(name)

Fetch a Curve object for a given curve name.

Parameters

name (str, required) – Freetext search, defaults to None

Returns

A Curve for the provided name

Return type

energyquantified.metadata.Curve

curves(q=None, area=None, data_type=None, category=None, exact_category=None, frequency=None, commodity=None, has_place=None, page=1, page_size=50)

Search for curves. Supports paging.

Parameters

  • q (str, optional) – Freetext search, defaults to None

  • area (Area, str, optional) – Filter on an area, defaults to None

  • data_type (DataType, str, optional) – Filter on a DataType, defaults to None

  • category (list[str], optional) – List of one or more categories that the curves must have, defaults to None

  • exact_category (str, optional) – An exact string of the category list for a curve, defaults to None

  • frequency (Frequency, str, optional) – Filter by frequency, defaults to None

  • commodity (str, optional) – Filter by commodity, defaults to None

  • has_place (bool, optional) – True – only curves for places, False – only curves without places, defaults to None

  • page (int, optional) – Set the page, defaults to 1

  • page_size (int, optional) – Set the page size, defaults to 50

Returns

A page of energyquantified.metadata.Curve

Return type

energyquantified.utils.Page (subclass of list)

exact_categories()

List available exact combinations of categories (meaning combinations that exists in curve names). You can use this response for filtering curves on the exact_category parameter in MetadataAPI.curves.

Results are cached on repeated calls.

Returns

A set of category combinations (strings)

Return type

set

places(q=None, area=None, fuel=None, kind=None, tree=False, page=1, page_size=50)

Search for places. Supports places.

Parameters

  • q (str, optional) – Freetext search, defaults to None

  • area (Area, str, optional) – Filter on an area, defaults to None

  • fuel (str, optional) – Filter by fuel type, defaults to None

  • kind (str, optional) – Type of place (producer, consumer, river, etc.), defaults to None

  • tree (bool, optional) – Enable to return as a hierachy, defaults to False

  • page (int, optional) – Set the page, defaults to 1

  • page_size (int, optional) – Set the page size, defaults to 50

Returns

A page of energyquantified.metadata.Place

Return type

energyquantified.utils.Page (subclass of list)

class energyquantified.api.TimeseriesAPI(*args, **kwargs)

Time series API operations. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.timeseries.load(curve, begin, end)
load(curve, begin=None, end=None, frequency=None, aggregation=None, hour_filter=None)

Load time series data for a energyquantified.metadata.Curve.

This operation works for curves with curve_type = TIMESERIES | SCENARIO_TIMESERIES only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

Returns

A time series

Return type

energyquantified.data.Timeseries

class energyquantified.api.InstancesAPI(*args, **kwargs)

Instance API operations. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.timeseries.load(curve, begin, end)
get(curve, issued=None, tag='', frequency=None, aggregation=None, hour_filter=None, ensembles=False)

Get an instance specified by a issued (issue date) and tag. The default tag is blank and tags are case-insensitive.

Supports aggregation by specifying a frequency. Optionally, you can specify the aggregation method (default is average) and the hourly filter (base, peak, etc.).

This operation works for curves with curve_type = INSTANCE only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • issued (datetime, date, str, optional) – The issue date-time, defaults to None

  • tag (str, optional) – The instance tag, defaults to “”

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

  • ensembles (bool, optional) – Whether or not to include ensembles where available, defaults to False

Returns

A time series instance

Return type

energyquantified.data.Timeseries

latest(curve, tags=None, issued_at_latest=None, frequency=None, aggregation=None, hour_filter=None, ensembles=False)

Get the latest time series instance with filtering on tags and issued_at_latest.

Supports aggregation by specifying a frequency. Optionally, you can specify the aggregation method (default is average) and the hourly filter (base, peak, etc.).

This operation works for curves with curve_type = INSTANCE only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • issued_at_latest ([type], optional) – [description], defaults to None

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

  • ensembles (bool, optional) – Whether or not to include ensembles where available, defaults to False

Returns

A time series instance

Return type

energyquantified.data.Timeseries

list(curve, tags=None, exlude_tags=None, limit=25, issued_at_latest=None, issued_at_earliest=None)

List instances for the curve. Does not load any time series data.

Filter on the instance tags or exclude_tags (list of values allowed), or restrict the instance issue date by setting issued_at_latest and/or issued_at_earliest.

Limit the maximum number of returned instances by setting limit anywhere between 1 and 25.

This operation works for curves with curve_type = INSTANCE only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • exlude_tags (list, str, optional) – Exclude instance tags, defaults to None

  • limit (int, optional) – Number of instances returned, defaults to 25

  • issued_at_latest (datetime, date, str, optional) – Filter by issue date, defaults to None

  • issued_at_earliest (datetime, date, str, optional) – Filter by issue date, defaults to None

Returns

A list of energyquantified.metadata.Instance

Return type

list

load(curve, tags=None, exlude_tags=None, limit=5, issued_at_latest=None, issued_at_earliest=None, frequency=None, aggregation=None, hour_filter=None, ensembles=False)

Load time series instances.

Filter on the instance tags or exclude_tags (list of values allowed), or restrict the instance issue date by setting issued_at_latest and/or issued_at_earliest.

When ensembles is False: Adjust the maximum number of returned time series instances by setting limit between 1 and 25.

When ensembles is True: limit must be between 1 and 10.

Supports aggregation by specifying a frequency. Optionally, you can specify the aggregation method (default is average) and the hourly filter (base, peak, etc.).

This operation works for curves with curve_type = INSTANCE only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • exlude_tags (list, str, optional) – Exclude instance tags, defaults to None

  • limit (int, optional) – Maximum number of instances returned, defaults to 5

  • issued_at_latest ([type], optional) – [description], defaults to None

  • issued_at_earliest ([type], optional) – [description], defaults to None

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

  • ensembles (bool, optional) – Whether or not to include ensembles where available, defaults to False

Returns

A list energyquantified.data.Timeseries instances

Return type

list

relative(curve, begin=None, end=None, tag=None, days_ahead=1, issued='latest', time_of_day=None, after_time_of_day=None, before_time_of_day=None, frequency=None, aggregation=None, hour_filter=None)

Load one instance for each day based on some common criteria, stitch them together and return a continuous time series.

By default, this method selects the day-ahead instances (forecasts), but you can set days_ahead to 0 or higher. 0 means intraday, 1 means the day-ahead (default), 2 means the day after day-ahead, and so on.

You may control the time of the day the instance is issued by setting exactly one of the follow parameters: time_of_day, after_time_of_day or before_time_of_day. These should be set to a time (HH:MM:SS). You can use the datetime.time.

This operation works for curves with curve_type = INSTANCE only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • days_ahead (int, optional) – The number of leading days (0 or higher), defaults to 1

  • issued (str, optional) – Whether to select the earliest or latest matching instance per day, allowed values “earliest” | “latest”, defaults to “earliest”

  • time_of_day (time, str, optional) – The exact time of the instance is issued, defaults to None

  • after_time_of_day (time, str, optional) – The instance must be issued at this time of day or after, defaults to None

  • before_time_of_day (time, str, optional) – The instance must be issued before this time of day, defaults to None

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

Returns

A time series

Return type

energyquantified.data.Timeseries

tags(curve)

Get all tags available for a curve.

This operation works for curves with curve_type = INSTANCE only.

Parameters

curve (energyquantified.metadata.Curve, str) – The curve or curve name

Returns

A set available tags for provded curve

Return type

set

class energyquantified.api.PeriodsAPI(*args, **kwargs)

Period-based series API operations. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.periods.load(curve, begin, end)
load(curve, begin=None, end=None)

Load period-based series data for a curve.

This operation works for curves with curve_type = PERIOD only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

Returns

A period-based series

Return type

energyquantified.data.Periodseries

class energyquantified.api.PeriodInstancesAPI(*args, **kwargs)

Period-based series instances API operations. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.period_instances.load(curve, begin, end)
get(curve, begin=None, end=None, issued=None, tag='')

Get a specific period-based series instance.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • issued (datetime, date, str, required) – The instance issue date

  • tag (str, required) – The instance tag

Returns

A period-based series

Return type

energyquantified.data.Periodseries

latest(curve, begin=None, end=None, issued_at_latest=None)

Get the latest period-based series instance.

This operation works for curves with curve_type = INSTANCE_PERIOD only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • issued_at_latest (date, datetime, str, optional) – The latest issue date for the loaded instance, defaults to None

Returns

A period-based series

Return type

energyquantified.data.Periodseries

list(curve, tags=None, exlude_tags=None, limit=20, issued_at_latest=None, issued_at_earliest=None)

List instances for the curve. Does not lad any period-based series.

Filter on the instance tags or exclude_tags (list of values allowed), or restrict the instance issue date by setting issued_at_latest and/or issued_at_earliest.

Limit the maximum number of returned instances by setting limit anywhere between 1 and 20.

This operation works for curves with curve_type = INSTANCE_PERIOD only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • exlude_tags (list, str, optional) – Exclude instance tags, defaults to None

  • limit (int, optional) – Number of instances returned, defaults to 25

  • issued_at_latest (datetime, date, str, optional) – Filter by issue date, defaults to None

  • issued_at_earliest (datetime, date, str, optional) – Filter by issue date, defaults to None

Returns

A list of energyquantified.metadata.Instance

Return type

list

load(curve, begin=None, end=None, tags=None, exlude_tags=None, limit=3, issued_at_latest=None, issued_at_earliest=None)

Load period-based series instances.

Filter on the instance tags or exclude_tags (list of values allowed), or restrict the instance issue date by setting issued_at_latest and/or issued_at_earliest.

This operation works for curves with curve_type = INSTANCE_PERIOD only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • exlude_tags (list, str, optional) – Exclude instance tags, defaults to None

  • limit (int, optional) – Number of instances returned, defaults to 3

  • issued_at_latest (datetime, date, str, optional) – Filter by issue date, defaults to None

  • issued_at_earliest (datetime, date, str, optional) – Filter by issue date, defaults to None

Returns

List of energyquantified.data.Periodseries objects

Return type

list

class energyquantified.api.OhlcAPI(client)

Operations for OHLC data retrieval. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.ohlc.load(curve, begin, end)
latest(curve, date=None)

Select all OHLC for specific trading day, while defaulting to the latest available OHLC data.

If date is given, this method will try to fetch OHLC data for that trading day. When there is no data for the given day, OHLC data will be loaded for the closest trading day earlier in time with data.

This operation works for curves with curve_type = OHLC only.

Parameters
Returns

A list of OHLC objects

Return type

energyquantified.data.OHLCList

latest_as_periods(curve, field=SETTLEMENT, date=None)

Load all OHLC rows from a single trading day, sort them, and merge/convert them to a continuous series.

It defaults to using the latest prices available, therefore “latest_as_period”.

If date is given, this method will try to fetch OHLC data for that trading day. When there is no data for the given day, OHLC data will be loaded for the closest trading day earlier in time with data.

By default, this method uses the settlement price. Select another field, such as close price, by setting the field parameter.

This operation works for curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • field (OHLCField, str, optional) – The field to generate the series from, defaults to OHLCField.SETTLEMENT

  • date (date, str, required) – The trading date, defaults to today

Returns

A period-based series

Return type

energyquantified.data.Periodseries

load(curve, begin=None, end=None, period=None, delivery=None, front=None)

Load OHLC data for a energyquantified.metadata.Curve.

This operation works for curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, optional) – Filter on contract period (day, week, month etc.), defaults to None

  • delivery (date, str, optional) – Filter on delivery date, requires parameter period to be set; cannot be used together with front, defaults to None

  • front (int, optional) – Filter on front contract, requires parameter period to be set; cannot be used together with delivery, defaults to None

Returns

A list of OHLC objects

Return type

energyquantified.data.OHLCList

load_delivery_as_timeseries(curve, begin=None, end=None, period=None, delivery=None, field=SETTLEMENT, fill=None)

Load historical OHLC data for specific contract, and convert it to a energyquantified.data.Timeseries.

Defaults to use the settlement field, but you can select any field you want. All other parameters are required.

This operation works for curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – The contract period (week, month, quarter)

  • delivery (date, str, required) – The delivery date for the contract

  • field (OHLCField, str, required) – The field (close, settlement, etc.) to extract to a time series, defaults to OHLCField.SETTLEMENT

  • fill (str, optional) – How to handle days without trades. Allowed values are: no-fill do nothing, fill-holes fill in holes with data from previous trading day, forward-fill fill in all blanks with data from the previous trading day (also into the future). Defaults to no-fill.

Returns

A time series

Return type

energyquantified.data.Timeseries

load_front_as_timeseries(curve, begin=None, end=None, period=None, front=None, field=SETTLEMENT, fill=None)

Load historical OHLC data for a continuous front contract, and convert it to a energyquantified.data.Timeseries.

Defaults to use the settlement field, but you can select any field you want. All other parameters are required.

This operation works for curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – The contract period (week, month, quarter)

  • front (int, required) – The front contract (1=front, 2=second front, etc.)

  • field (OHLCField, str, required) – The field (close, settlement, etc.) to extract to a time series, defaults to OHLCField.SETTLEMENT

  • fill (str, optional) – How to handle days without trades. Allowed values are: no-fill do nothing, fill-holes fill in holes with data from previous trading day, forward-fill fill in all blanks with data from the previous trading day (also into the future). Defaults to no-fill.

Returns

A time series

Return type

energyquantified.data.Timeseries

class energyquantified.api.SrmcAPI(client)

Operations for SRMC calculations in the API. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.srmc.load_front(curve, begin, end, period='month', front=1)
latest(curve, date=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None)

Calculate short-run margincal costs (SRMC) for all settlement prices from a trading day. Defaults to using OHLC data from the latest available trading day, hence latest().

If date is given, this method will try to fetch OHLC data for that trading day. When there is no data for the given day, OHLC data will be loaded for the closest trading day earlier in time with data.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • date (date, str, required) – The trading date, defaults to today

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

Returns

An SRMC object with a list of OHLC objects

Return type

energyquantified.data.SRMC

latest_as_periods(curve, date=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None)

Calculate short-run margincal costs (SRMC) for all settlement prices from a trading day, sort them, and merge/convert them to a continuous series.

Defaults to using OHLC data from the latest available trading day, hence latest in the method name.

If date is given, this method will try to fetch OHLC data for that trading day. When there is no data for the given day, OHLC data will be loaded for the closest trading day earlier in time with data.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • date (date, str, required) – The trading date, defaults to today

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

Returns

An SRMC object with a period-based series

Return type

energyquantified.data.SRMC

load_delivery(curve, begin=None, end=None, period=None, delivery=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None)

Calculate historical short-run margincal costs (SRMC) for a specific contract, such as the year 2021, the month Jan 2021, etc.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – Filter on contract period (day, week, month etc.), defaults to None

  • delivery (date, str, required) – Filter on delivery date, requires parameter period to be set; cannot be used together with front, defaults to None

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

Returns

An SRMC object with a list of OHLC objects

Return type

energyquantified.data.SRMC

load_delivery_as_timeseries(curve, begin=None, end=None, period=None, delivery=None, fill=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None)

Calculate historical short-run margincal costs (SRMC) for a specific contract and convert it to a daily time series.

A specific contract could be the year 2021, the month Jan 2021, etc.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – Filter on contract period (day, week, month etc.), defaults to None

  • delivery (date, str, required) – Filter on delivery date, requires parameter period to be set; cannot be used together with front, defaults to None

  • fill (str, optional) – How to handle days without trades. Allowed values are: no-fill do nothing, fill-holes fill in holes with data from previous trading day, forward-fill fill in all blanks with data from the previous trading day (also into the future). Defaults to no-fill.

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

Returns

An SRMC object with a timeseries object

Return type

energyquantified.data.SRMC

load_front(curve, begin=None, end=None, period=None, front=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None)

Calculate historical short-run margincal costs (SRMC) for a continuous front contract.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – Filter on contract period (day, week, month etc.), defaults to None

  • front (int, required) – The front contract (1=front, 2=second front, etc.)

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

Returns

An SRMC object with a list of OHLC objects

Return type

energyquantified.data.SRMC

load_front_as_timeseries(curve, begin=None, end=None, frequency=None, period=None, front=None, fill=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None)

Calculate historical short-run margincal costs (SRMC) for a continuous front contract and convert the result to a daily time series.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters

  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – Filter on contract period (day, week, month etc.), defaults to None

  • front (int, required) – The front contract (1=front, 2=second front, etc.)

  • fill (str, optional) – How to handle days without trades. Allowed values are: no-fill do nothing, fill-holes fill in holes with data from previous trading day, forward-fill fill in all blanks with data from the previous trading day (also into the future). Defaults to no-fill.

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

Returns

An SRMC object with a timeseries object

Return type

energyquantified.data.SRMC

Data types

There are three main groups of data types: Time series, period-based series and OHLC data:

Time series classes

class energyquantified.data.Timeseries(data=None, scenario_names=None, **kwargs)

Bases: energyquantified.data.base.Series

A time series with metadata.

Parameters

  • curve (Curve, optional) – The curve, defaults to None

  • name (str, optional) – A name which is used as column name when converted to a pandas.DataFrame, defaults to None

  • resolution (Resolution, optional) – The resolution of the time series, defaults to None

  • instance (Instance, optional) – The instance, defaults to None

  • data (list[]) – A list of values (Value, ScenariosValue, or MeanScenariosValue)

  • scenario_names (list[str], optional) – A list of scenario names, if any

begin()

Get the begin date-time in the timeseries (inclusive).

Returns

The begin date

Return type

datetime

end()

Get the end date-time in the timeseries (exclusive).

Returns

The end date

Return type

datetime

has_data()

Check if this series has any data.

Returns

True if there is at least one data point, otherwise False

Return type

bool

has_scenarios()

Check whether or not this time series has scenarios.

Returns

True when this time series has scenarios, otherwise False

Return type

bool

instance_or_contract_dataframe_column_header()

Get the instance or contract for this time series, in a format fitting for a pandas.DataFrame column header.

Returns

An instance or contract column header for a data frame

Return type

str, NoneType

property name

Return the curve name, if a energyquantified.metadata.Curve is associated with this series.

Returns

The curve.name if it exists, otherwise None

Return type

str, NoneType

print(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Utility method to print a time series to any file handle (defaults to stdout).

set_name(name)

Set a custom name (defaults to using curve.name).

Parameters

name (str) – An user-defined name

to_dataframe(name=None, single_level_header=False)

Convert this timeseries to a pandas.DataFrame.

Parameters

  • name (str, optional) – Set a name for the value column, defaults to value

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df(name=None, single_level_header=False)

Alias for Timeseries.to_dataframe. Convert this timeseries to a pandas.DataFrame.

Parameters

  • name (str, optional) – Set a name for the value column, defaults to value

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

total_values_per_item()

Get the total number of values per item:

  • A regular time series has one value per item

  • A scenario-based time series will return number of scenarios

  • A forecast with mean and ensembles will return 1 + number of ensembles

Returns

Total number of values per date-time in this time series

Return type

int

validate()

Validate the time series.

value_type()

Return the value type of this time series.

Returns

The value type of this time series

Return type

ValueType

class energyquantified.data.TimeseriesList(iterable=(), frequency=None)

Bases: list

A list of Timeseries objects. All time series must have the same frequency.

Parameters

iterable (iterable) – Any iterable of time series

append(timeseries)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable)

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, timeseries)

Insert object before index.

pop(index=-1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Stable sort IN PLACE.

to_dataframe(single_level_header=False)

Convert this TimeseriesList to a pandas.DataFrame where all time series are placed in its own column and are lined up with the date-time as index.

Parameters

single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df(single_level_header=False)

Alias for Timeseries.to_dataframe.

Convert this TimeseriesList to a pandas.DataFrame where all time series are placed in its own column and are lined up with the date-time as index.

Parameters

single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

class energyquantified.data.ValueType(value)

Enumerator of supported value types for timeseries.data[].

MEAN_AND_SCENARIOS = 'MEAN_AND_SCENARIOS'

A value and scenarios. See energyquantified.data.MeanScenariosValue.

SCENARIOS = 'SCENARIOS'

Only scenarios. See energyquantified.data.ScenariosValue.

VALUE = 'VALUE'

Single value. See energyquantified.data.Value.

class energyquantified.data.Value(date, value)

A time series value.

Implemented as a namedtuple of (date, value).

date

The date-time for a time series value (index)

value

The numeric value

class energyquantified.data.ScenariosValue(date, scenarios)

A time series value of scenarios.

Implemented as a namedtuple of (date, scenarios).

date

The date-time for a time series value (index)

scenarios

A tuple of scenario values

class energyquantified.data.MeanScenariosValue(date, value, scenarios)

A time series value with scenarios and a mean value.

Implemented as a namedtuple of (date, value, scenarios).

date

The date-time for a time series value (index)

value

The numeric value

scenarios

A tuple of scenario values

Period-based series classes

class energyquantified.data.Periodseries(data=None, **kwargs)

Bases: energyquantified.data.base.Series

A period-based series with metadata.

Parameters

  • curve (Curve, optional) – The curve, defaults to None

  • resolution (Resolution, optional) – The resolution of the time series, defaults to None

  • instance (Instance, optional) – The instance, defaults to None

  • data (list[]) – A list of periods (Period or CapacityPeriod)

begin()

Get the begin date-time in the timeseries (inclusive).

Returns

The begin date

Return type

datetime

end()

Get the end date-time in the timeseries (exclusive).

Returns

The end date

Return type

datetime

has_data()

Check if this series has any data.

Returns

True if there is at least one data point, otherwise False

Return type

bool

instance_or_contract_dataframe_column_header()

Get the instance or contract for this time series, in a format fitting for a pandas.DataFrame column header.

Returns

An instance or contract column header for a data frame

Return type

str, NoneType

property name

Return the curve name, if a energyquantified.metadata.Curve is associated with this series.

Returns

The curve.name if it exists, otherwise None

Return type

str, NoneType

print(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Utility method to print a period-based series to any file handle (defaults to stdout).

set_name(name)

Set a custom name (defaults to using curve.name).

Parameters

name (str) – An user-defined name

to_dataframe(frequency=None, name=None, single_level_header=False, field='value')

Convert this period-based to a pandas.DataFrame as a time series in the given frequency.

Using Periodseries.to_timeseries to convert this period-based series to a regular time series first. When periods overlap the same step in the resulting time series, a weighted average is calculated down to second-precision.

Parameters

  • frequency (Frequency, required) – The frequency of the resulting pandas.DataFrame time series

  • name (str, optional) – Set a name for the column in the pandas.DataFrame, defaults to value

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df(frequency=None, name=None, single_level_header=False, field='value')

Alias for Periodseries.to_dataframe.

Convert this period-based to a pandas.DataFrame as a time series in the given frequency.

Using Periodseries.to_timeseries to convert this period-based series to a regular time series first. When periods overlap the same step in the resulting time series, a weighted average is calculated down to second-precision.

Parameters

  • frequency (Frequency, required) – The frequency of the resulting pandas.DataFrame time series

  • name (str, optional) – Set a name for the column in the pandas.DataFrame, defaults to value

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_timeseries(frequency=None, field='value')

Convert this period-based series to a regular time series.

When periods overlap the same step in the resulting time series, a weighted average is calculated down to second-precision.

Parameters

  • frequency (Frequency, required) – The frequency of the resulting time series

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A time series

Return type

Timeseries

class energyquantified.data.PeriodseriesList(iterable=())

Bases: list

A list of Periodseries objects. Have methods for converting them to a TimeseriesList or a pandas.DataFrame.

Parameters

iterable (iterable) – Any iterable of Periodseries

append(periodseries)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable)

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, periodseries)

Insert object before index.

pop(index=-1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Stable sort IN PLACE.

to_dataframe(frequency=None, single_level_header=False, field='value')

Convert this PeriodseriesList to a pandas.DataFrame where all time series are placed in its own column and are lined up with the date-time as index.

Parameters

  • frequency (Frequency, required) – The frequency of the resulting time series’

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df(frequency=None, single_level_header=False, field='value')

Alias for Timeseries.to_dataframe.

Convert this PeriodseriesList to a pandas.DataFrame where all time series are placed in its own column and are lined up with the date-time as index.

Parameters

  • frequency (Frequency, required) – The frequency of the resulting time series’

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_timeseries(frequency=None, field='value')

Convert all period-based series in this list to time series.

When periods overlap the same step in the resulting time series, a weighted average is calculated down to second-precision.

Parameters

  • frequency (Frequency, required) – The frequency of the resulting time series

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A list of time series

Return type

TimeseriesList

class energyquantified.data.Period(begin, end, value)

A period for a period-based series.

Implemented as a namedtuple of (begin, end, value).

begin

The begin date-time

end

The end date-time

value

The numeric value

class energyquantified.data.CapacityPeriod(begin, end, value, installed)

A period for a period-based series. Includes the installed capacity for the period (which may differ from the currently available capacity given in the value attribute).

Implemented as a namedtuple of (begin, end, value).

begin

The begin date-time

end

The end date-time

value

The numeric value

installed

The total installed capacity

Base class for series

class energyquantified.data.base.Series(curve=None, name=None, resolution=None, instance=None, contract=None)

Bases: object

Base class for Timeseries and Periodseries.

begin()

Get the begin date-time in the timeseries (inclusive).

Returns

The begin date

Return type

datetime

contract

The contract for OHLC operations resulting in a time series

curve

The curve

data

The data

end()

Get the end date-time in the timeseries (exclusive).

Returns

The end date

Return type

datetime

has_data()

Check if this series has any data.

Returns

True if there is at least one data point, otherwise False

Return type

bool

instance

The instance (if any)

instance_or_contract_dataframe_column_header()

Get the instance or contract for this time series, in a format fitting for a pandas.DataFrame column header.

Returns

An instance or contract column header for a data frame

Return type

str, NoneType

property name

Return the curve name, if a energyquantified.metadata.Curve is associated with this series.

Returns

The curve.name if it exists, otherwise None

Return type

str, NoneType

resolution

The resolution

set_name(name)

Set a custom name (defaults to using curve.name).

Parameters

name (str) – An user-defined name

OHLC data classes

class energyquantified.data.Product(traded: datetime.date, period: energyquantified.metadata.ohlc.ContractPeriod, front: int, delivery: datetime.date)

An energy product description with a trading date and the contract in detail.

class energyquantified.data.OHLC(product: energyquantified.data.ohlc.Product, open: float, high: float, low: float, close: float, settlement: float, volume: float, open_interest: float)

A summary for a trading day on a contract.

get_field(field)

Get an OHLC field from this object.

Parameters

field (OHLCField | str) – A OHLC field

Raises

ValueError – When the field parameter isn’t a valid OHLC field

Returns

The value on the given OHLC field or None if it isn’t set

Return type

float

class energyquantified.data.OHLCList(elements, curve=None, contract=None)

Bases: list

A collection of OHLC data. Can contain all sorts of contracts (yearly, monthly, weekly etc.) for a specific market.

append(value)

Append object to the end of the list.

clear()

Remove all items from list.

curve

The curve holding these OHLC objects

extend(iterable)

Extend list by appending elements from the iterable.

insert(index, value)

Insert object before index.

pop(index=- 1)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value)

Remove first occurrence of value.

Raises ValueError if the value is not present.

to_dataframe()

Convert this OHLCList to a pandas.DataFrame with a column for open, high, low, close, settlement, volume and open interest.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df()

Convert this OHLCList to a pandas.DataFrame with a column for open, high, low, close, settlement, volume and open interest.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

SRMC data classes

class energyquantified.data.SRMC(curve: energyquantified.metadata.curve.Curve = None, contract: Union[energyquantified.metadata.ohlc.ContinuousContract, energyquantified.metadata.ohlc.SpecificContract] = None, options: energyquantified.data.srmc.SRMCOptions = None, ohlc: energyquantified.data.ohlc.OHLCList = None, timeseries: energyquantified.data.timeseries.Timeseries = None, periodseries: energyquantified.data.periodseries.Periodseries = None)

Bases: object

A data class for the API response from an SRMC calculation. It can either contain a list of OHLC objects, a time series, or a period-based series.

contract: Union[energyquantified.metadata.ohlc.ContinuousContract, energyquantified.metadata.ohlc.SpecificContract] = None

(optional) The contract when the calculation was done for historical closing prices – either a front contract (continuous front contract), or a specific contract such as Year-2020, Year-2021, Q3-2020 etc.

curve: energyquantified.metadata.curve.Curve = None

The curve used as input to this SRMC calculation

has_ohlc()

Check whether this SRMC calculation did return OHLC objects.

Returns

True when this SRMC calculation did return OHLC objects, otherwise False

Return type

bool

has_periodseries()

Check whether this SRMC calculation did return a period-based series.

Returns

True when this SRMC calculation did return a period-based series, otherwise False

Return type

bool

has_timeseries()

Check whether this SRMC calculation did return a time series.

Returns

True when this SRMC calculation did return a time series, otherwise False

Return type

bool

ohlc: energyquantified.data.ohlc.OHLCList = None

(optional) The OHLC data when the result of the calculation returns a list of OHLC objects.

options: energyquantified.data.srmc.SRMCOptions = None

The factors used in the SRMC calculation.

periodseries: energyquantified.data.periodseries.Periodseries = None

(optional) The period-based series when the result of the calculation returns a period series.

timeseries: energyquantified.data.timeseries.Timeseries = None

(optional) The time series when the result of the calculation returns a time series.

class energyquantified.data.SRMCOptions(fuel_type: str = None, api2_tonne_to_mwh: float = None, gas_therm_to_mwh: float = None, efficiency: float = None, carbon_emissions: float = None, carbon_tax_area: energyquantified.metadata.area.Area = None)

A data class with all factors for an SRMC calculations.

api2_tonne_to_mwh: float = None

(For coal) Conversion factor between API#2 tonnes and megawatthours.

carbon_emissions: float = None

The carbon emission factor.

carbon_tax_area: energyquantified.metadata.area.Area = None

(optional) When set, carbon tax is calculated according to tax rules in given area. Typically used for Great Britain’s flat carbon tax.

efficiency: float = None

The energy efficiency factor.

fuel_type: str = None

The fuel type. Set to either COAL or GAS.

gas_therm_to_mwh: float = None

(For gas) Conversion from pence/therm to GBP/MWh.

Metadata

class energyquantified.metadata.Allocation(value)

Enumerator of border allocation types between two price areas.

EXPLICIT = ('E', 'Explicit')

Explicit exchange border

FLOW_BASED = ('F', 'Flow-based')

Flow-based exchange border

IMPLICIT = ('I', 'Implicit')

Implicit exchange border

NO_COMMERCIAL_CAPACITY = ('N', 'No commercial capacity')

No commercial exchange available

class energyquantified.metadata.Area(tag, name, short_tag=None, country=False, price_area=False, control_area=False, external=False)

A representation of a price area or country.

Areas do have a reference to all exchange borders with available commercial capacity allocation properties. Access the borders via area.borders[]. If you just want direct access neighbour listing, use area.exchange_neighbours[].

Some areas, such as Nord Pool, consist of smaller areas. In these cases, you can access their children via area.children[]. You can also find the parent area via area.parent.

All areas has a tag, which you will find in the curve names, and a full name.

classmethod all()

Return a list of all areas.

Returns

A list of all areas

Return type

list[Area]

borders

Set of exchange borders with exchange allocation types

classmethod by_tag(tag)

Look up area by tag.

Parameters

tag (str) – An area tag

Returns

The area for the given tag

Return type

Area

classmethod by_tags(*tags)

Return multiple areas by tags.

Returns

A list of areas by the provided tags

Return type

list[Area]

children

Set of child areas (set if this area is split into other, smaller areas)

control_area

True when this area is a control area/TSO area, otherwise False

country

True when this area is a country, otherwise False

exchange_neighbours

Set of neighbouring areas

external

True when this area is outside of the supported region (used for exchange areas)

get_family()

Get all descendants in a flat list for this Area.

Returns

A list of all descendants/sub-areas for this area

Return type

list[Area]

classmethod is_valid_tag(tag)

Check whether an area tag exists or not.

Parameters

tag (str) – An area tag

Returns

True if it exists, otherwise False

Return type

bool

name

The full name of the area

parent

The parent area (set if this is a sub-area of another area)

price_area

True when this area is a price area, otherwise False

short_tag

The short tag (used for context-aware tags in Javascript/corejs)

tag

The area tag (used in curve names)

class energyquantified.metadata.Border(source, sink, allocations=None)

A one-way border between two price areas.

The source area is where the power is exported from, and the sink area is where to power is imported to.

Each border has a list of capacity allocations describing how the commercial capacities on the border are set.

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

allocations

A tuple of the exchange allocation types (flow-based, implicit, etc.)

as_tuple()

Convert this border to a tuple of (source, sink, allocations)

Returns

This border as a tuple of (source, sink, allocations)

Return type

tuple

is_explicit()

Returns True if this border has explicit allocations.

Returns

True if this border has explicit allocations, otherwise False

Return type

bool

is_flow_based()

Returns True if this border is flow-based.

Returns

True if this border is flow-based, otherwise False

Return type

bool

is_implicit()

Returns True if this border has implicit allocations.

Returns

True if this border has implicit allocations, otherwise False

Return type

bool

sink

The sink area (the importer)

source

The source area (the exporter)

class energyquantified.metadata.Curve(name, curve_type=None, instance_issued_timezone=None, area=None, area_sink=None, place=None, resolution=None, frequency=None, timezone=None, categories=None, unit=None, denominator=None, data_type=None, source=None, commodity=None)

The curve identifies any type of time series data and OHLC data.

The curve.name is used in the API when loading data for a curve.

area

The area

area_sink

The importing area for exchange curves

area_source

The exporting area for exchange curves

categories

List of categories for this curve.

commodity

The curve commodity (Power, Gas, etc.)

curve_type

Curve type (the type of data this curve refers to).

data_type

The data type, DataType.

denominator

The denominator (for EUR/MWh: unit=EUR and denominator=MWh). See also Curve.unit.

frequency

The frequency of data in this curve

instance_issued_timezone

For instance-based curves: The time-zone of the issue date in the instance, see Instance.issued.

name

The curve name is the identifier.

property resolution

The resolution (combination of frequency and timezone) for this curve.

source

The source of the data.

timezone

The time-zone of date-times in this curve

unit

The unit (MW, EUR, etc.). See also Curve.denominator.

class energyquantified.metadata.CurveType(value)

Curve type is not a part of the curve name.

Curve type describes the storage format of the underlying data and which operations must be used to fetch data for these curves.

  • Load time series and scenario-based time series using the EnergyQuantified.timeseries.* operations.

  • To load instances (i.e. forecasts), use the EnergyQuantified.timeseries.* operations.

  • Periods and period-instances can be loaded by using each of their respective operations located under EnergyQuantified.periods.* and EnergyQuantified.instance_periods.*.

  • OHLC means “open, high, low and close” data. To load data from these curves, use the OHLC operations.

INSTANCE = ('INSTANCE', True)

Instances (forecasts)

INSTANCE_PERIOD = ('INSTANCE_PERIOD', True)

Instances of period-based data

OHLC = ('OHLC', False)

Closing prices for market data

PERIOD = ('PERIOD', False)

Period-based data

SCENARIO_TIMESERIES = ('SCENARIO_TIMESERIES', False)

Plain, fixed-interval scenarios of time series data

TIMESERIES = ('TIMESERIES', False)

Plain, fixed-interval time series data

static by_tag(tag)

Look up curve type by tag.

Parameters

tag (str) – A curve type tag

Returns

The curve type for the given tag

Return type

CurveType

static is_valid_tag(tag)

Check whether a curve type tag exists or not.

Parameters

tag (str) – A curve type tag

Returns

True if it exists, otherwise False

Return type

bool

class energyquantified.metadata.DataType(value)

Data types describe the type of data (i.e. actuals, forecast). This is the attribute that is always set as the last word in the curve name.

ACTUAL = ('ACTUAL', 'Actual')

Third-party actuals collected by Energy Quantified, but not modified.

BACKCAST = ('BACKCAST', 'Backcast')

The forecast models run backwards.

CAPACITY = ('CAPACITY', 'Capacity')

Total installed capacity.

CLIMATE = ('CLIMATE', 'Climate')

Scenario data generated by Energy Quantified, which is based on climate data sets (synthetic weather years).

FORECAST = ('FORECAST', 'Forecast')

Forecasts generated by Energy Quantified unless another source is explicitly stated in the curve name.

FOREX = ('FOREX', 'Forex')

Currency rates.

NORMAL = ('NORMAL', 'Normal')

The seasonal normals using 40 weather years.

OHLC = ('OHLC', 'OHLC')

Closing data from the market.

REMIT = ('REMIT', 'REMIT')

Capacity data generated from REMIT outage messages.

SCENARIO = ('SCENARIO', 'Scenario')

Scenario data generated by Energy Quantified. If you are looking for weather-based scenarios, look at DataType.CLIMATE.

SYNTHETIC = ('SYNTHETIC', 'Synthetic')

A combination of third-party actuals and numbers generated by Energy Quantified, where we have filled missing with our best calculations.

VALUE = ('VALUE', 'Value')

Some model value (such as a factor).

static by_tag(tag)

Look up data type by tag.

Parameters

tag (str) – A data type tag

Returns

The data type for the given tag

Return type

DataType

static is_valid_tag(tag)

Check whether a data type tag exists or not.

Parameters

tag (str) – A data type tag

Returns

True if it exists, otherwise False

Return type

bool

class energyquantified.metadata.Instance(issued, tag='', scenarios=None, created=None, modified=None)

An instance identifies a forecast or any other time series that was issued at a specific time.

It is typically used to specify a weather forecast that a specific forecast is based on.

An instance is identified by the combination of (issued, tag).

as_dataframe_column_header()

Create a string fitting for a column header in the a pandas.DataFrame.

Returns

A DataFrame column header text for an instance

Return type

str

created

When this instance was created (if available)

issued

The issue date of this instance

modified

When this instance was modified (if available)

scenarios

The number of scenarios available in this instance (default=0)

tag

The tag for this instance

class energyquantified.metadata.Place(kind, key, name, unit=None, fuels=None, area=None, areas=None, location=None, children=None, curves=None)

A place is a general concept of a physical location, such as a powerplant, a weather station, a position on a river etc.

area

The area in which this place lies, see Area. This field is deprecated and will be removed in future releases.

areas

The list areas in which this place lies (mulitple when it’s on a border), see Area.

children

A list of children (typically used for a powerplants with sub-units)

curves

A list of curves with data for this place. See Curve.

fuels

The fuel types (if it is a powerplant unit)

key

The identifier

kind

The place type. See PlaceType.

property latitude

The latitude of this place.

location

The geolocation of this place: (latitude, longitude)

property longitude

The longitude of this place.

name

The name of the place

unit

The unit name (if it is a powerplant unit)

class energyquantified.metadata.PlaceType(value)

Enumerator of place types. Used to describe type type of a Place.

CITY = ('city',)

A city

CONSUMER = ('consumer',)

A power consumer, such as a factory

GAS_INTERCONNECTOR = ('gas-interconnector',)

Gas interconnector

GAS_LNG_TERMINAL = ('gas-lng-terminal',)

Gas LNG terminal

GAS_STORAGE = ('gas-storage',)

Gas storage

OTHER = ('other',)

Unspecified

PRODUCER = ('producer',)

A power producer (power plant)

RIVER = ('river',)

A river location

WEATHERSTATION = ('weatherstation',)

A weather station

static by_tag(tag)

Look up place type by tag.

Parameters

tag (str) – A place type tag

Returns

The place type for the given tag

Return type

PlaceType

static is_valid_tag(tag)

Check whether a place type tag exists or not.

Parameters

tag (str) – A place type tag

Returns

True if it exists, otherwise False

Return type

bool

class energyquantified.metadata.Aggregation(value)

Supported aggregations in the API. Includes simple implementations of the different aggregation types for learning purposes.

AVERAGE = (<function Aggregation.<lambda>>,)

Calculate the mean value

MAX = (<built-in function max>,)

Find the maximum value

MIN = (<built-in function min>,)

Find the minimum value

SUM = (<built-in function sum>,)

Calculate the sum of all values

aggregate(iterable)

Perform an aggregation on any iterable of numbers (such as lists, tuples, generators etc.).

Parameters

iterable (iterable) – Any iterable of numbers

Returns

An aggregate

Return type

float

static by_tag(tag)

Look up aggregation by tag.

Parameters

tag (str) – An aggregation tag

Returns

The aggregation for the given tag

Return type

Aggregation

static is_valid_tag(tag)

Check whether an aggregation tag exists or not.

Parameters

tag (str) – An aggregation tag

Returns

True if it exists, otherwise False

Return type

bool

property tag

Get the tag for this aggregation type.

Returns

The aggregation tag (name)

Return type

str

class energyquantified.metadata.Filter(value)

Supported filters in the API.

Includes simple implementations of the filters for learning purposes.

Note: The API automatically separates futures peak and offpeak by looking at the selected frequency for aggregations:

  • For weekly, monthly, quartly and yearly frequency, the futures peak and offpeak are used.

  • For daily or higher frequencies, the standard peak and offpeak are used.

BASE = (<function Filter.<lambda>>, <function Filter.<lambda>>)

All hours

OFFPEAK = (<function Filter.<lambda>>, <function Filter.<lambda>>)

Offpeak hours

PEAK = (<function Filter.<lambda>>, <function Filter.<lambda>>)

Peak hours

WEEKEND = (<function Filter.<lambda>>, <function Filter.<lambda>>)

Saturday and Sunday

WORKDAYS = (<function Filter.<lambda>>, <function Filter.<lambda>>)

Monday–Friday

static by_tag(tag)

Look up a filter by tag.

Parameters

tag (str) – A filter tag

Returns

The filter for the given tag

Return type

Filter

get_filter_function(frequency)

Given a frequency, return the appropriate filter function:

  • For weekly, monthly, quartly and yearly frequency, the futures peak and offpeak function is used.

  • For daily or higher frequencies, the standard peak and offpeak function is used.

Parameters

frequency (Frequency) – The resulting frequency of an aggregation

Returns

A filter function

Return type

function

is_in_filter(datetime_obj)

Check whether or not a datetime object is in a filter.

Parameters

datetime_obj (datetime) – A date-time

Returns

True if the date-time object falls into filter, otherwise False

Return type

bool

is_in_future_filter(datetime_obj)

Check whether or not a datetime object is in a filter for futures-contracts (weekly, monthly, quarterly, yearly).

Parameters

datetime_obj (datetime) – A date-time

Returns

True if the date-time object falls into filter, otherwise False

Return type

bool

static is_valid_tag(tag)

Check whether a filter tag exists or not.

Parameters

tag (str) – A filter tag

Returns

True if it exists, otherwise False

Return type

bool

property tag

The filter tag (name)

class energyquantified.metadata.ContractPeriod(value)

Enumerator of contract periods available in for OHLC contracts in the API. The contract periods are:

  • YEAR – Yearly contract period

  • MDEC – December delivery (for ETS EUA contracts)

  • SEASON – Summer or Winter (typically for gas contracts)

  • QUARTER – Quarterly contract period

  • MONTH – Monthly contract period

  • WEEK – Weekly contract period

  • WEEKEND – Weekend contract period

  • DAY – Daily contract period

static by_tag(tag)

Look up contract periods by tag.

Parameters

tag (str) – The tag to look up

Returns

A ContractPeriod for this tag

Return type

ContractPeriod

static is_valid_tag(tag)

Check whether a contract period tag exists or not.

Parameters

tag (str) – The tag to look up

Returns

True if the contract period tag exists, otherwise False

Return type

bool

class energyquantified.metadata.OHLCField(value)

A field in an OHLC object. Used to specify which field to load or to perform an operation on.

  • OPEN – Opening trade for the trading day

  • HIGH – Highest trade for the trading day

  • LOW – Lowest trade for the trading day

  • CLOSE – Closing trade for the trading day

  • SETTLEMENT – Settlement price for the trading day

  • VOLUME – Accumulated traded volume for the trading day

  • OPEN_INTEREST – Total volume of contracts that have been entered into and not yet liquidated by an offsetting transaction or fulfilled by delivery

static by_tag(tag)

Look up OHLC field by tag.

Parameters

tag (str) – The tag to look up

Returns

An OHLCField for this tag

Return type

OHLCField

get_value(ohlc)

Get the value from an OHLC object for this field.

Parameters

ohlc (OHLC) – An OHLC object

Returns

The value for that given OHLC field

Return type

float

static is_valid_tag(tag)

Check whether a OHLC field tag exists or not.

Parameters

tag (str) – The tag to look up

Returns

True if the OHLC field tag exists, otherwise False

Return type

bool

class energyquantified.metadata.ContinuousContract(period: energyquantified.metadata.ohlc.ContractPeriod, front: int, field: energyquantified.metadata.ohlc.OHLCField = None)

Metadata class for keeping track of which contract was queried. Continuous contracts are the rolling N-front contract – relative to its trading day.

For instance, a contract with period=MONTH, front=1 is what you would typically call a front month contract. period=MONTH, front=2 is the second closest front contract, and so forth.

See also SpecificContract.

field

The field to have fetched from the OHLC objects (such as close, settlement, open, high, low, volume)

period

The contract period (i.e. week, month, quarter)

front

The front number (1 is the closest contract, 2 is the second closest, and so on)

as_dataframe_column_header()

Create a string fitting for a column header in the a pandas.DataFrame.

Returns

A DataFrame column header text for this contract

Return type

str

is_continuous()

Check whether this contract instance is continuous.

Returns

True if continuous, otherwise False

Return type

bool

is_specific()

Check whether this contract instance is specific.

Returns

True if specific, otherwise False

Return type

bool

class energyquantified.metadata.SpecificContract(period: energyquantified.metadata.ohlc.ContractPeriod, delivery: datetime.date, field: energyquantified.metadata.ohlc.OHLCField = None)

Metadata class for keeping track of which contract was queried. Specific contracts are contracts which goes to delivery on a specific date.

For instance, a contract with period=MONTH, delivery=2020-12-01 is the contract for delivery in December 2020.

See also ContinuousContract.

field

The field to have fetched from the OHLC objects (such as close, settlement, open, high, low, volume)

period

The contract period (i.e. week, month, quarter)

delivery

The delivery date of the contract

as_dataframe_column_header()

Create a string fitting for a column header in the a pandas.DataFrame.

Returns

A DataFrame column header text for this contract

Return type

str

is_continuous()

Check whether this contract instance is continuous.

Returns

True if continuous, otherwise False

Return type

bool

is_specific()

Check whether this contract instance is specific.

Returns

True if specific, otherwise False

Return type

bool

Date and time

class energyquantified.time.Frequency(value)

Enumerator of valid frequencies for Energy Quantified’s API. The supported frequencies are:

  • P1Y – Yearly

  • SEASON – Summer or winter

  • P3M – Quarterly

  • P1M – Monthly

  • P1W – Weekly

  • P1D – Daily

  • PT1H – Hourly

  • PT30M – 30 minutes

  • PT15M – 15 minutes

  • PT10M – 10 minutes

  • PT5M – 5 minutes

  • NONE – Tick-data (no frequency)

__ge__(b)

Return self>=value.

__gt__(b)

Return self>value.

__le__(b)

Return self<=value.

__lt__(b)

Return self<value.

between(datetime_obj1, datetime_obj2)

Count number of steps in this frequency between two dates.

Parameters

  • datetime_obj1 (datetime) – The first date-time

  • datetime_obj2 (datetime) – The second date-time

Returns

The number of time this frequency fits between the two dates

Return type

int

classmethod by_tag(tag)

Look up frequencies by tag.

Parameters

tag (str) – The tag to look up

Returns

A Frequency for this tag

Return type

Frequency

get_delta(num_steps)

Create a relativedelta of N steps in this frequency. 0 steps means no change. 1 step means one tick forward, -1 step means one tick backwards.

Parameters

num_steps (int) – Number of steps forward (positive) or backwards (negative)

Returns

A relativedelta (similar to timedelta)

Return type

relativedelta

classmethod is_valid_tag(tag)

Check whether a frequency tag exists or not.

Parameters

tag (str) – The tag to look up

Returns

True if the frequency tag exists, otherwise False

Return type

bool

matches(datetime_obj)

Check if a date-time aligns with this frequency.

Parameters

datetime_obj (datetime) – A date-time

Returns

True if it falls into this frequency, otherwise False

Return type

bool

shift(datetime_obj, num_steps)

Shift a date-time by N steps in this frequency. 0 steps means no change. 1 step means one tick forward, -1 step means one tick backwards.

Parameters

  • datetime_obj (datetime) – A date-time

  • num_steps (int) – Number of steps forward (positive) or backwards (negative)

Returns

A shifted date-time

Return type

datetime

property tag

The frequency tag (P1D, PT1H, etc.).

truncate(datetime_obj)

Snap a date-time down to the nearest instant in this frequency.

Parameters

datetime_obj (datetime) – A date-time

Returns

A datetime snapped down to the nearest instant in this frequency

Return type

datetime

class energyquantified.time.Resolution(frequency, timezone)

A combination of a frequency and a time zone with utility methods for iteration and snapping datetimes to given frequency.

Parameters

  • frequency (Frequency) – The frequency for this resolution

  • timezone (TzInfo (or similar pytz time-zone)) – The time-zone for this resolution

__lshift__(datetime_obj)

Move a datetime one step backward in time. Usage:

>>> datetime_obj = resolution << datetime_obj
Parameters

datetime_obj (datetime) – A date-time

Returns

The supplied date-time shifted one step backward in time

Return type

datetime

__rshift__(datetime_obj)

Move a datetime one step forward in time. Usage:

>>> datetime_obj = resolution >> datetime_obj
Parameters

datetime_obj (datetime) – A date-time

Returns

The supplied date-time shifted one step forward in time

Return type

datetime

ceil(datetime_obj)

Snap a date or datetime up to the nearest instant in this resolution’s frequency.

Parameters

datetime_obj (datetime) – A date-time

Returns

A date-time snapped up to the nearest instant in this resolution’s frequency.

Return type

datetime

datetime(year=None, month=1, day=1, hour=0, minute=0, second=0, millis=0)

Create a datetime. Only year needs to be specified. The remaining fields defaults to the lowest value. The datetime will have the same timezone as this resolution and will be snapped to the frequency.

Parameters

  • year (int, required) – The year

  • month (int, optional) – The month (1-12), defaults to 1

  • day (int, optional) – The day-of-month (1-31), defaults to 1

  • hour (int, optional) – The hour of the day (0-23), defaults to 0

  • minute (int, optional) – The minute (0-59), defaults to 0

  • second (int, optional) – The second (0-59), defaults to 0

  • millis (int, optional) – The millisecond (0-999), defaults to 0

Returns

A new date-time, snapped down to the frequency

Return type

datetime

enumerate(begin=None, end=None)

Returns a generator over all datetimes between begin and end in this resolution. Example:

>>> resolution = Resolution(Frequency.P1D, CET)
>>> begin = resolution.datetime(2020, 5, 16)
>>> end = resolution.datetime(2020, 5, 26)
>>> for i in resolution.enumerate(begin, end):
        print(i)
Parameters

  • begin (datetime, required) – The begin date-time (inclusive)

  • end (datetime, required) – The end date-time (exclusive)

Yield

A generator of date-times between begin and end in this resolution

Return type

datetime

floor(datetime_obj)

Snap a date or datetime down to the nearest instant in this resolution’s frequency.

Parameters

datetime_obj (datetime) – A date-time

Returns

A date-time snapped down to the nearest instant in this resolution’s frequency.

Return type

datetime

is_iterable()

Check whether or not this Resolution is iterable

Returns

True if this Resolution is iterable, otherwise False

Return type

bool

matches(datetime_obj)

Check if a datetime obj has the same time zone as this resolution and that the datetime aligns with the frequency of this resolution.

Parameters

datetime_obj (datetime) – A date-time

Returns

True if it falls into this frequency, otherwise False

Return type

bool

now()

Create a datetime, snapped to beginning of the current period of this resolution’s frequency.

Returns

A date-time of now, snapped to beginning of the resolution’s frequency

Return type

datetime

shift(datetime_obj, steps)

Shift a date-time by N steps in this resolution’s frequency. 0 steps means no change. 1 step means one tick forward, -1 step means one tick backwards.

Parameters

  • datetime_obj (datetime) – A date-time

  • steps (int) – Number of steps forward (positive) or backwards (negative)

Returns

A shifted date-time

Return type

datetime

to_dict()

Convert this resolution to a dict in the same format as data is returned from the Energy Quantified Time Series API.

Returns

A dict of this resolution in the same format as the API response

Return type

dict

Methods in energyquantified.time. These methods are wrappers around the default methods in Python’s standard library and other libraries where the time-zone is set to CET (which is used in the European power markets) by default.

energyquantified.time.now(tz=<DstTzInfo 'CET' CET+1:00:00 STD>)

Get the current datetime.

Parameters

tz (TzInfo (or similar pytz time-zone)) – The preferred time-zone, defaults to DEFAULT_TZ

Returns

A time-zone aware datetime set to now

Return type

datetime

energyquantified.time.today(tz=<DstTzInfo 'CET' CET+1:00:00 STD>)

Get a datetime set to midnight today.

Parameters

tz (TzInfo (or similar pytz time-zone)) – The preferred time-zone, defaults to DEFAULT_TZ

Returns

A time-zone aware datetime set to midnight this morning

Return type

datetime

energyquantified.time.get_datetime(year=None, month=1, day=1, hour=0, minute=0, second=0, millis=0, tz=<DstTzInfo 'CET' CET+1:00:00 STD>)

Get a datetime. Only year needs to be specified. The remaining fields defaults to the lowest value. Timezone defaults to DEFAULT_TZ.

Parameters

  • year (int, required) – The year

  • month (int, optional) – The month (1-12), defaults to 1

  • day (int, optional) – The day-of-month (1-31), defaults to 1

  • hour (int, optional) – The hour-of-day (0-23), defaults to 0

  • minute (int, optional) – The minute (0-59), defaults to 0

  • second (int, optional) – The second (0-59), defaults to 0

  • millis (int, optional) – The milliseconds (0-999), defaults to 0

  • tz (TzInfo (or similar pytz time-zone)) – The time-zone, defaults to DEFAULT_TZ

Returns

A time-zone aware datetime

Return type

datetime

energyquantified.time.get_date(year=None, month=1, day=1)

Get a date. Only year needs to be specified. The remaining fields defaults to the lowest value.

Parameters

  • year (int, required) – The year

  • month (int, optional) – The month (1-12), defaults to 1

  • day (int, optional) – The day-of-month (1-31), defaults to 1

Returns

A date

Return type

date

energyquantified.time.to_timezone(datetime_obj, tz=<DstTzInfo 'CET' CET+1:00:00 STD>)

Make a datetime object timezone-aware in given timezone. If it already has a timezone, convert the instant to provided timezone.

energyquantified.time.local_tz()

Get the local time-zone.

Returns

The time-zone for this system.

Return type

TzInfo

Constants in energyquantified.time. These are the most commonly used time-zones in the European power markets.

energyquantified.time.UTC = <UTC>

UTC

Optimized UTC implementation. It unpickles using the single module global instance defined beneath this class declaration.

energyquantified.time.CET = <DstTzInfo 'CET' CET+1:00:00 STD>
energyquantified.time.WET = <DstTzInfo 'WET' WET0:00:00 STD>
energyquantified.time.EET = <DstTzInfo 'EET' EET+2:00:00 STD>
energyquantified.time.TRT = <DstTzInfo 'Europe/Istanbul' LMT+1:56:00 STD>
energyquantified.time.DEFAULT_TZ = <DstTzInfo 'CET' CET+1:00:00 STD>

Utils

class energyquantified.utils.Page(elements, page=None, page_size=None, total_items=None, first_page=None, last_page=None, page_load_func=None)

Bases: list

A Page is a subclass of the standard list type in Python with additional attributes for paging.

It also has methods for loading the next/previous page, and to print the page to stdout.

append(value)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable)

Extend list by appending elements from the iterable.

first_page

The first page (is always 1)

get_next_page()

Get the next page. Will perform an HTTP request if data is not already in local cache.

Raises

  • PageError – When there is no next page

  • PageError – There is no support for loading the next page

Returns

The next page

Return type

Page

get_previous_page()

Get the previous page. Will perform an HTTP request if data is not already in local cache.

Raises

  • PageError – When there is no previous page

  • PageError – There is no support for loading the previous page

Returns

The previous page

Return type

Page

has_next_page()

Check if there is a next page.

Returns

True when there is a next page

Return type

bool

has_previous_page()

Check if there is a previous page.

Returns

True when there is a previous page

Return type

bool

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, value)

Insert object before index.

last_page

The last page in the search

page

The current page

page_size

The page size

pop(index=- 1)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

print(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Print the page with all its attributes.

Parameters

file (file descriptor, optional) – A file descriptor, defaults to sys.stdout

remove(value)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Stable sort IN PLACE.

total_items

Total number of items found in search across all pages

total_pages

The total number of pages

Exceptions

Even though the exceptions below are listed with full path, they are exposed in module energyquantified.exceptions.

API exceptions

exception energyquantified.exceptions.APIError(*args, **kwargs)

Base exception for all errors that may occur during an API call.

exception energyquantified.exceptions.HTTPError(*args, **kwargs)

Base class for all HTTP errors. Mostly used to wrap request’s HTTP errors.

exception energyquantified.exceptions.ValidationError(reason=None, parameter=None, *args, **kwargs)

Validation error of some kind (invalid parameter or combination of parameters).

exception energyquantified.exceptions.NotFoundError(reason=None, *args, **kwargs)

The resource was not found on the server.

exception energyquantified.exceptions.UnauthorizedError(reason=None, *args, **kwargs)

Authentication errors such as invalid API key or that the user is blocked.

exception energyquantified.exceptions.ForbiddenError(reason=None, *args, **kwargs)

The resource is not accessible for the user.

exception energyquantified.exceptions.InternalServerError(*args, **kwargs)

The server failed to process the request.

Initialization errors

exception energyquantified.exceptions.InitializationError(reason=None, *args, **kwargs)

Initialization error for the Energy Quantified Python client.

Pagination exceptions

exception energyquantified.exceptions.PageError(reason=None, *args, **kwargs)

A page error.

Parser exceptions

exception energyquantified.exceptions.ParseException(*args, **kwargs)

Failed to parse an API response.