Period-based instances

This page shows how to load period-based series instances. All examples below expects you to have an initialized instance of the client called eq.

Operations described here are available under eq.period_instances.*.

Requirements: Use these operations for curves with curve_type set to any of the following:

  • INSTANCE_PERIOD

Important

We recommend reading the section on period-based series before continuing, as all operations here return period-based series or lists of period-based series.

A note on REMIT data

We generate new instances when new outage messages arrive. The series’ start on 1 January 2019 and goes up to 5 years into the future.

So the instance’s issue date will be the same as the issue date for the latest outage message and the tag will be the outage message ID.

All REMIT curves for powerplants and aggregated production capacity are period-based series instances.

(Exchange capacities reported via REMIT are stored as Timeseries.)

Get the latest instance

Method reference: eq.period_instances.latest()

Load the latest instance like shown below. curve, begin and end are required parameters:

>>> from datetime import date
>>> periodseries = eq.period_instances.latest(
>>>    'DE Nuclear Capacity Available MW REMIT',
>>>    begin=date(2020, 1, 1),
>>>    end=date(2020, 6, 1)
>>> )

>>> periodseries
<Periodseries: resolution=<Resolution: frequency=NONE, timezone=CET>, curve="DE Nuclear Capacity Available MW REMIT", instance=<Instance: issued="2020-07-16 05:20:00+00:00", tag="pgQCAPKo09HUBl9szRWmkA">, begin="2020-01-01 00:00:00+01:00", end="2020-06-01 00:00:00+02:00">

If you would like to know what the nuclear capacity in Germany was on, say, 1 April 2020 at 12:00, provide the issued_at_latest parameter:

>>> from datetime import date, datetime
>>> periodseries = eq.period_instances.latest(
>>>    'DE Nuclear Capacity Available MW REMIT',
>>>    begin=date(2020, 1, 1),
>>>    end=date(2020, 6, 1),
>>>    issued_at_latest=datetime(2020, 4, 1, 12, 0, 0) # 1 April at 12:00
>>> )

As you can see, the latest message for 1 April 2020 at 12:00 was published on 30 March at 12:54 CEST. Here we print the instance only for clarity:

>>> periodseries.instance
<Instance: issued="2020-03-30 10:54:51+00:00", tag="GGXXxM8VKmeHWrbHHx3rAg">

Get a specific instance

Method reference: eq.period_instances.get()

If you know the issue date and tag for an instance, you can load it like seen below. You must always specify the issue date, but you can leave the tag unspecified (which will default to a blank tag; this requires the instance’s tag to be blank).

Remember that begin and end are required.

Here we are loading the same instance as shown in the previous section, namely an instance for the REMIT message published on 30 March 2020 at 12:54 CEST:

>>> from datetime import date
>>> from energyquantified.time import get_datetime, UTC
>>> periodseries = eq.period_instances.get(
>>>    'DE Nuclear Capacity Available MW REMIT',
>>>    issued=get_datetime(2020, 3, 30, 10, 54, 51, tz=UTC),
>>>    tag='GGXXxM8VKmeHWrbHHx3rAg',
>>>    begin=date(2020, 1, 1),
>>>    end=date(2020, 6, 1)
>>> )

>>> periodseries.instance
<Instance: issued="2020-03-30 10:54:51+00:00", tag="GGXXxM8VKmeHWrbHHx3rAg">

Load instances

Method reference: eq.period_instances.load()

To load multiple period-based series instances, you need to specify the curve, begin and end.

To load the latest three updates for nuclear capacity in Germany, you can do something like this:

>>> from datetime import date
>>> periodseries_list = eq.period_instances.load(
>>>    'DE Nuclear Capacity Available MW REMIT',
>>>    begin=date(2020, 1, 1),
>>>    end=date(2020, 6, 1)
>>> )

>>> periodseries_list
[<Periodseries: resolution=<Resolution: frequency=NONE, timezone=CET>, curve="DE Nuclear Capacity Available MW REMIT", instance=<Instance: issued="2020-07-16 05:20:00+00:00", tag="pgQCAPKo09HUBl9szRWmkA">, begin="2020-01-01 00:00:00+01:00", end="2020-06-01 00:00:00+02:00">,
 <Periodseries: resolution=<Resolution: frequency=NONE, timezone=CET>, curve="DE Nuclear Capacity Available MW REMIT", instance=<Instance: issued="2020-07-15 07:30:54+00:00", tag="FKqarmJMZUBbe-VcFtYczA">, begin="2020-01-01 00:00:00+01:00", end="2020-06-01 00:00:00+02:00">,
 <Periodseries: resolution=<Resolution: frequency=NONE, timezone=CET>, curve="DE Nuclear Capacity Available MW REMIT", instance=<Instance: issued="2020-07-13 19:07:48+00:00", tag="fj6UVXudDMsgXhzVIxWuFQ">, begin="2020-01-01 00:00:00+01:00", end="2020-06-01 00:00:00+02:00">]

The return type from load() is a PeriodseriesList. This is a subclass of Python’s built-in list with two helpful methods:

Like with the load() method for time series instances, specify issued_at_latest, issued_at_earliest, tags and exclude_tags for further filtering. You can also set limit to limit the number of returned instances.

Here we load the 10 instances from the very end of 2019:

>>> from datetime import date, datetime
>>> periodseries_list = eq.period_instances.load(
>>>    'DE Nuclear Capacity Available MW REMIT',
>>>    begin=date(2020, 1, 1),
>>>    end=date(2020, 6, 1),
>>>    issued_at_latest=datetime(2019, 12, 31, 23, 59, 59),
>>>    limit=10  # Maximum number of instances
>>> )

>>> [p.instance for p in periodseries_list]
[<Instance: issued="2019-12-23 14:05:48+00:00", tag="-qMu2U9NbWUz_EgHi6wRfA">,
 <Instance: issued="2019-12-22 02:39:53+00:00", tag="hi3biDstbdT4Gc9S-CBn9w">,
 <Instance: issued="2019-12-17 18:56:28+00:00", tag="qssw2izWQJtX3nmK7Zp4dg">,
 <Instance: issued="2019-12-13 00:42:15+00:00", tag="Sb01f_roj0IybuFdAJs7bA">,
 <Instance: issued="2019-12-12 21:51:57+00:00", tag="Sb01f_roj0IybuFdAJs7bA">,
 <Instance: issued="2019-12-11 09:08:55+00:00", tag="moIJ7ETPUPA04Zf3lPPaJQ">,
 <Instance: issued="2019-12-05 14:42:59+00:00", tag="3_eYOl5o6bqBC4IwNSlYPg">,
 <Instance: issued="2019-12-04 21:43:04+00:00", tag="3_eYOl5o6bqBC4IwNSlYPg">,
 <Instance: issued="2019-12-04 08:53:52+00:00", tag="c73EjiRNVVAkOwqN8l6aAg">,
 <Instance: issued="2019-12-01 09:43:58+00:00", tag="Ah-SewfIguFLydohq0efvQ">]

List instances

Method reference: eq.period_instances.list()

Similar to the load()-method, but this method only lists the instances instead of loading the period-based series with data:

>>> eq.period_instances.list(
>>>    'DE Nuclear Capacity Available MW REMIT',
>>>    issued_at_latest=datetime(2019, 12, 31, 23, 59, 59),
>>>    limit=10  # Maximum number of instances
>>> )
[<Instance: issued="2019-12-23 14:05:48+00:00", tag="-qMu2U9NbWUz_EgHi6wRfA">,
 <Instance: issued="2019-12-22 02:39:53+00:00", tag="hi3biDstbdT4Gc9S-CBn9w">,
 <Instance: issued="2019-12-17 18:56:28+00:00", tag="qssw2izWQJtX3nmK7Zp4dg">,
 <Instance: issued="2019-12-13 00:42:15+00:00", tag="Sb01f_roj0IybuFdAJs7bA">,
 <Instance: issued="2019-12-12 21:51:57+00:00", tag="Sb01f_roj0IybuFdAJs7bA">,
 <Instance: issued="2019-12-11 09:08:55+00:00", tag="moIJ7ETPUPA04Zf3lPPaJQ">,
 <Instance: issued="2019-12-05 14:42:59+00:00", tag="3_eYOl5o6bqBC4IwNSlYPg">,
 <Instance: issued="2019-12-04 21:43:04+00:00", tag="3_eYOl5o6bqBC4IwNSlYPg">,
 <Instance: issued="2019-12-04 08:53:52+00:00", tag="c73EjiRNVVAkOwqN8l6aAg">,
 <Instance: issued="2019-12-01 09:43:58+00:00", tag="Ah-SewfIguFLydohq0efvQ">]

Relative queries (day-ahead forecasts)

Method reference: eq.period_instances.relative()

When benchmarking models (forecasts), one often would like to know what a forecast was for the day ahead. And you would like to do this over a date interval. For example, we would like to know Monday’s forecast for Tuesday, and Tuesday’s forecast for Wednesday, and so on.

Energy Quantified’s API has solved this by via an operation we call relative forecasts.

The relative forecasts work for 0 or more days ahead:

  • days_ahead=0 means forecasts for intraday

  • days_ahead=1 means forecasts for day ahead

  • days_ahead=2 means forecasts for day after day ahead

  • … and so on

You can filter on the before-time-of-day the forecast was issued. When there isn’t any forecast issued for a specific day, then that day will have no values.

>>> from datetime import datetime, time
>>> day_ahead_capacity = eq.period_instances.relative(
>>>    'PT Natural Gas Power Capacity Available MW REMIT',
>>>    begin=datetime(2020, 6, 1, 0, 0, 0),
>>>    end=datetime(2020, 6, 1, 0, 0, 0),
>>>    days_ahead=1,  # The day-ahead forecast (0 or higher allowed)
>>>    before_time_of_day=time(12, 0),  # Issued before 12:00
>>> )

>>> day_ahead_capacity.data
[<Period: begin=2020-06-01 00:00:00+02:00, end=2020-06-06 02:00:00+02:00, value=3828, installed=3828>,
 <Period: begin=2020-06-06 02:00:00+02:00, end=2020-06-07 21:00:00+02:00, value=2652, installed=3828>,
 <Period: begin=2020-06-07 21:00:00+02:00, end=2020-07-01 00:00:00+02:00, value=3828, installed=3828>]

Next steps

Learn how to load time series, time series instances, and period-based series.