annular.tariffs
===============

.. py:module:: annular.tariffs


Attributes
----------

.. autoapisummary::

   annular.tariffs.T
   annular.tariffs.TEMPORAL_INDEXERS


Classes
-------

.. autoapisummary::

   annular.tariffs.TariffManager


Functions
---------

.. autoapisummary::

   annular.tariffs.parse_weekday_weekend
   annular.tariffs.filter_dataframe
   annular.tariffs.is_dutch_holiday


Module Contents
---------------

.. py:data:: T

.. py:function:: parse_weekday_weekend(date: datetime.date) -> str

   Parse the weekday weekend from a date.

   :param date: Date to parse.

   :returns: Whether the given date is a weekday or a weekend day.


.. py:data:: TEMPORAL_INDEXERS
   :type:  dict[str, Callable]

.. py:class:: TariffManager(tariff_data: dict[str, pandas.Series | numbers.Real] | None = None)

   A manager object for energy network tariffs.

   Includes support for intelligently parsing timestamps to various
   time-based indexing options. Tariffs are retrievable by
   (case-insensitive) name through various `fetch_*` methods.

   Time related index names can be provided case-insensitive, since any
   case-sensitivity will be removed from index names using the ``casefold``
   string method.

   :param tariff_data: Dictionary where keys are tariff names and
                       values are series of tariff values and indices.


   .. py:attribute:: data


   .. py:method:: from_folder(path: pathlib.Path, preselect: collections.abc.Mapping[str, str | numbers.Real]) -> T
      :classmethod:


      Create a TariffManager from csv files in a folder.

      :param path: Path to the folder with tariff data in csv format.
      :param preselect: Dictionary specifying the category within the tariff.
                        Any tariff may be indexed both categorically and temporally.
                        This `preselect` argument should at least specify a value for
                        each categorical index, i.e., column in the tariff file.
                        E.g.: `{"grid level": "distribution", "consumer type": "small"}`.
                        If any of the categories given to `preselect` are not present in
                        the tariff data, they are silently ignored.



   .. py:method:: __contains__(item: str) -> bool

      Check if a tariff is present in the TariffManager.



   .. py:method:: fetch_value(name: str) -> numbers.Real

      Fetch a single-valued tariff.

      :param name: Name of the tariff.

      :returns: Value for a specific tariff.



   .. py:method:: fetch_timeseries(name: str, timestamps: pandas.Index) -> pandas.Series

      Fetch tariff value for each given timestamp.

      :param name: Name of the tariff.
      :param timestamps: Datetime to use for selecting temporal index levels.

      :returns: Series of values for the specified tariff, indexed by the given timestamps.



   .. py:method:: fetch_indexed(name: str, timestamps: Iterable[pandas.Timestamp]) -> pandas.Series

      Fetch collection of tariff values, relevant to the given timestamps.

      :param name: Name of the tariff.
      :param timestamps: Datetime to use for selecting temporal index levels.

      :returns: Series of tariff values, maintaining its original index, pre-selected with only the relevant values .



.. py:function:: filter_dataframe(data: pandas.DataFrame, select: collections.abc.Mapping[str, str | numbers.Real]) -> pandas.Series | numbers.Real

   Filter a dataframe by multiple columns.

   .. rubric:: Example

   Preselect ``{"Foo": "high", "Bar": "old"}`` with data =

   ==== === === =====
   Foo  Bar Baz value
   ==== === === =====
   high new yes 1
   high new no  2
   high old yes 3
   high old no  4
   low  new yes 5
   low  new no  6
   low  old yes 7
   low  old no  8
   ==== === === =====

   Result:

   === =====
   Baz value
   === =====
   yes 3
   no  4
   === =====

   Note: Column names can be given case-insensitively, but the values to match
   on are still case-sensitive. So the previous example would work the same if
   ``select={"foo": "high", "BAR": "old"}`` was used, but not
   ``select={"Foo": "High", "Bar": "OLD"}``.

   :param data: pandas DataFrame to filter. Must have at least one column named 'value'.
   :param select: Dictionary where keys are strings or integers, used to select
                  only the desired rows from the given data. If a key is present as
                  a column name, then only those rows are kept where that column
                  matches the matching value from this dictionary.

   :returns: A pd.Series of the ``value`` column, where rows are filtered based on
             matching values in `select`. Any columns that were filtered on are
             removed, and any remaining columns are used as a pd.MultiIndex. If the
             series only consists of a single row, then it only returns the value.


.. py:function:: is_dutch_holiday(date: datetime.date) -> bool

   Check if date is a Dutch holiday, if not already a weekend by definition.

   As of 2013, Dutch holidays are:
   - New Year's Day
   - Good Friday
   - Easter (Sunday and Monday)
   - King's Day
   - Ascension Day
   - Pentecost (sunday and Monday)
   - Christmas (25th and 26th)

   :param date: Date to check.

   :returns: True if the given date is a Dutch holiday, False otherwise.