Period-based instances ====================== This page shows how to load period-based series instances. All examples below expects you to have an initialized and authenticated 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:: All operations under ``eq.period_instances.*`` return period-based series or lists of period-based series. We recommend reading the section on :doc:`period-based series <../userguide/periods>` before continuing to learn how to convert a :py:class:`energyquantified.data.Periodseries` to a :py:class:`energyquantified.data.Timeseries`. A note on REMIT data -------------------- We generate a new instances when new outage messages arrive. The series start at 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 plain time series.) Get the latest instance ----------------------- ``eq.instances.latest(curve, begin=None, end=None)`` Load the latest instance like shown below. Unlike the operations for ``eq.instances.*``-operations, you must specify **begin** and **end** for period-based instances. >>> 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 , curve="DE Nuclear Capacity Available MW REMIT", instance=, 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 Get a specific instance ----------------------- ``eq.instances.latest(curve, begin=None, end=None, issued=None, tag=None)`` 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 Load instances -------------- ``eq.instances.load(curve, begin=None, end=None, issued_at_latest=None, issued_at_earliest=None, tags=None, exclude_tags=None, limit=3)`` 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 [, curve="DE Nuclear Capacity Available MW REMIT", instance=, begin="2020-01-01 00:00:00+01:00", end="2020-06-01 00:00:00+02:00">, , curve="DE Nuclear Capacity Available MW REMIT", instance=, begin="2020-01-01 00:00:00+01:00", end="2020-06-01 00:00:00+02:00">, , curve="DE Nuclear Capacity Available MW REMIT", instance=, begin="2020-01-01 00:00:00+01:00", end="2020-06-01 00:00:00+02:00">] 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] [, , , , , , , , , ] List instances ^^^^^^^^^^^^^^ Similar to the ``load()``-method, but this method only lists the *instances* instead of loading the 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 >>> ) [, , , , , , , , , ] ----- Next steps ^^^^^^^^^^ Learn how to load :doc:`time series <../userguide/timeseries>`, :doc:`time series instances <../userguide/instances>`, and :doc:`period-based series <../userguide/periods>`.