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 :doc:`period-based series <../userguide/periods>` 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 :class:`Timeseries `.) Get the latest instance ----------------------- Method reference: :py:meth:`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 , 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 ----------------------- Method reference: :py:meth:`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 Load instances -------------- Method reference: :py:meth:`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 [, 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">] The return type from ``load()`` is a :py:class:`~energyquantified.data.PeriodseriesList`. This is a subclass of Python's built-in list with two helpful methods: * :py:meth:`~energyquantified.data.PeriodseriesList.to_timeseries` converts the list of :py:meth:`~energyquantified.data.Periodseries` to a :py:class:`~energyquantified.data.TimeseriesList` of :py:class:`~energyquantified.data.Timeseries`. It requires you to specify a **frequency** for the output time series. * :py:meth:`~energyquantified.data.PeriodseriesList.to_dataframe` converts the list of period-bsed series to a ``pandas.DataFrame``. Like the :py:meth:`~energyquantified.data.PeriodseriesList.to_timeseries` method above, it also requires you to specify a **frequency** for the time series in the output data frame. 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 ^^^^^^^^^^^^^^ Method reference: :py:meth:`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 >>> ) [, , , , , , , , , ] Relative queries (day-ahead forecasts) -------------------------------------- Method reference: :py:meth:`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 [, , ] ----- Next steps ---------- Learn how to load :doc:`time series <../userguide/timeseries>`, :doc:`time series instances <../userguide/instances>`, and :doc:`period-based series <../userguide/periods>`.