bolster.data_sources.electricity_renewables
===========================================

.. py:module:: bolster.data_sources.electricity_renewables

.. autoapi-nested-parse::

   NI Electricity Consumption and Renewable Generation Statistics.

   Published quarterly by the Department for the Economy (DfE) Northern Ireland
   in partnership with NISRA.  Reports progress toward NI's renewable electricity
   targets (80% of consumption from renewables by 2030 under the Climate Change
   Act (Northern Ireland) 2022).

   Data Source:
       **Interactive report** (data embedded as base64 CSV):
       https://datavis.nisra.gov.uk/Economy/electricity-consumption-and-renewable-generation-report.html

       The report embeds ten figures as base64-encoded UTF-16 LE CSV data-URIs.
       This module extracts and parses the four headline time series:

       * **renewable_pct**: Rolling 12-month renewable generation as a
         proportion of gross final electricity consumption (%) and monthly %.
       * **consumption**: Total consumption, renewable and non-renewable
         generation, and net imports (rolling 12-month GWh).
       * **generation_by_technology**: Rolling 12-month generation (GWh)
         by technology — wind, hydro, bioenergy, landfill gas, solar PV.
       * **generation_monthly**: Monthly renewable and non-renewable
         generation (GWh) going back to February 2018.

   Update Frequency:
       Quarterly (March, June, September, December).

   Coverage:
       Rolling 12-month figures: January 2019 – present.
       Monthly generation figures: February 2018 – present.

   .. rubric:: Example

   >>> from bolster.data_sources import electricity_renewables
   >>> data = electricity_renewables.get_latest_data()
   >>> 'renewable_pct' in data
   True
   >>> 'renewable_pct_rolling_12m' in data['renewable_pct'].columns
   True
   >>> (data['renewable_pct']['renewable_pct_rolling_12m'] > 0).all()
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.electricity_renewables.logger


Exceptions
----------

.. autoapisummary::

   bolster.data_sources.electricity_renewables.ElectricityDataNotFoundError
   bolster.data_sources.electricity_renewables.ElectricityValidationError


Functions
---------

.. autoapisummary::

   bolster.data_sources.electricity_renewables.get_latest_data
   bolster.data_sources.electricity_renewables.validate_data


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

.. py:data:: logger

.. py:exception:: ElectricityDataNotFoundError

   Bases: :py:obj:`Exception`


   Electricity statistics page or data could not be retrieved.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:exception:: ElectricityValidationError

   Bases: :py:obj:`Exception`


   Electricity DataFrame failed validation checks.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:function:: get_latest_data(force_refresh = False)

   Download and parse the latest NI electricity and renewables statistics.

   Returns four DataFrames covering the headline series from the DfE/NISRA
   quarterly electricity report.

   :param force_refresh: If ``True``, bypass the local cache and re-download.

   :returns:

             * ``"renewable_pct"`` — rolling 12-month and monthly renewable
               generation as % of gross final consumption.
             * ``"consumption"`` — rolling 12-month total consumption, renewable
               generation, non-renewable generation, and net imports (GWh).
             * ``"generation_by_technology"`` — rolling 12-month renewable
               generation (GWh) by technology: wind, hydro, bioenergy,
               landfill gas, solar PV.
             * ``"generation_monthly"`` — monthly renewable and non-renewable
               generation (GWh) going back to February 2018.
   :rtype: Dictionary with keys

   :raises ElectricityDataNotFoundError: If the datavis page cannot be fetched
       or no figure data is found in the HTML.
   :raises ElectricityValidationError: If the parsed data fails validation.

   .. rubric:: Example

   >>> data = get_latest_data()
   >>> sorted(data.keys())
   ['consumption', 'generation_by_technology', 'generation_monthly', 'renewable_pct']
   >>> 'total_consumption_gwh' in data['consumption'].columns
   True


.. py:function:: validate_data(df, key = 'renewable_pct')

   Validate an electricity statistics DataFrame.

   :param df: DataFrame from :func:`get_latest_data`.
   :param key: Which sub-dataset to validate (controls required-column check).
               One of ``"renewable_pct"``, ``"consumption"``,
               ``"generation_by_technology"``, ``"generation_monthly"``.

   :returns: ``True`` if all checks pass.

   :raises ElectricityValidationError: If the DataFrame is empty, missing
       required columns, has implausible values, or is too short.

   .. rubric:: Example

   >>> data = get_latest_data()
   >>> validate_data(data['renewable_pct'], 'renewable_pct')
   True