bolster.data_sources.ons_cpi
============================

.. py:module:: bolster.data_sources.ons_cpi

.. autoapi-nested-parse::

   ONS UK inflation indices (CPI, CPIH, RPI).

   Wraps the Office for National Statistics (ONS) open time-series API to provide
   standardised access to the headline UK inflation measures:

   - **CPIH** — Consumer Prices Index including owner-occupiers' housing costs
   - **CPI** — Consumer Prices Index
   - **RPI** — Retail Prices Index (longest run, back to 1948)

   Each measure is available both as a 12-month annual rate (``%``) and as a price
   index. Data is published at monthly, quarterly and annual resolutions.

   This is the first of three macroeconomic context modules and emits a **fixed
   output schema** so that inflation, and the other macro modules, can be joined
   and resampled against one another:

   ==========  ==========================================================
   Column      Description
   ==========  ==========================================================
   date        ``datetime64[ns]`` period-start (Jan 2024 -> 2024-01-01,
               Q1 2024 -> 2024-01-01, year 2024 -> 2024-01-01)
   year        ``int`` calendar year
   quarter     ``str`` "Q1".."Q4", or ``pd.NA`` for annual/monthly
   month       ``int`` 1-12, or ``pd.NA`` for quarterly/annual
   resolution  ``str`` "annual" | "quarterly" | "monthly"
   series      ``str`` ONS series code, e.g. "D7G7"
   value       ``float`` observation value
   unit        ``str`` e.g. "%" or "Index 2015=100"
   geography   ``str`` always "UK"
   source      ``str`` always "ONS"
   ==========  ==========================================================

   Source:
       https://www.ons.gov.uk/economy/inflationandpriceindices

   .. rubric:: Example

   >>> from bolster.data_sources import ons_cpi
   >>> df = ons_cpi.get_series("D7G7", resolution="annual")  # doctest: +SKIP
   >>> sorted(df.columns)  # doctest: +SKIP
   ['date', 'geography', 'month', 'quarter', 'resolution', 'series', 'source', 'unit', 'value', 'year']



Attributes
----------

.. autoapisummary::

   bolster.data_sources.ons_cpi.logger
   bolster.data_sources.ons_cpi.BASE_URL
   bolster.data_sources.ons_cpi.GEOGRAPHY
   bolster.data_sources.ons_cpi.SOURCE
   bolster.data_sources.ons_cpi.SCHEMA_COLUMNS
   bolster.data_sources.ons_cpi.SERIES


Exceptions
----------

.. autoapisummary::

   bolster.data_sources.ons_cpi.ONSDataError
   bolster.data_sources.ons_cpi.ONSValidationError


Functions
---------

.. autoapisummary::

   bolster.data_sources.ons_cpi.get_series
   bolster.data_sources.ons_cpi.get_latest_data
   bolster.data_sources.ons_cpi.validate_data


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

.. py:data:: logger

.. py:data:: BASE_URL
   :value: 'https://www.ons.gov.uk/economy/inflationandpriceindices/timeseries/{code}/data'


.. py:data:: GEOGRAPHY
   :value: 'UK'


.. py:data:: SOURCE
   :value: 'ONS'


.. py:data:: SCHEMA_COLUMNS
   :value: ['date', 'year', 'quarter', 'month', 'resolution', 'series', 'value', 'unit', 'geography', 'source']


.. py:data:: SERIES

.. py:exception:: ONSDataError

   Bases: :py:obj:`Exception`


   Base exception for ONS data errors.

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


.. py:exception:: ONSValidationError

   Bases: :py:obj:`ONSDataError`


   Raised when a DataFrame fails :func:`validate_data`.

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


.. py:function:: get_series(code, resolution = 'monthly', force_refresh = False)

   Fetch a single ONS inflation series at a given resolution.

   :param code: ONS series code (case-insensitive). One of :data:`SERIES`.
   :param resolution: "monthly" (default), "quarterly" or "annual".
   :param force_refresh: Bypass the page cache and re-download.

   :returns: DataFrame conforming to :data:`SCHEMA_COLUMNS`, sorted by ``date``.

   :raises ValueError: If ``code`` or ``resolution`` is not recognised.
   :raises ONSDataError: If the underlying API request fails.

   .. rubric:: Example

   >>> df = get_series("D7G7", resolution="annual")  # doctest: +SKIP
   >>> df.iloc[-1][["series", "unit", "geography"]].tolist()  # doctest: +SKIP
   ['D7G7', '%', 'UK']


.. py:function:: get_latest_data(resolution = 'monthly', force_refresh = False)

   Fetch all supported series at a given resolution, concatenated.

   :param resolution: "monthly" (default), "quarterly" or "annual".
   :param force_refresh: Bypass the page cache and re-download each series.

   :returns: DataFrame conforming to :data:`SCHEMA_COLUMNS` containing every code in
             :data:`SERIES`, sorted by ``series`` then ``date``.

   :raises ValueError: If ``resolution`` is not recognised.

   .. rubric:: Example

   >>> df = get_latest_data(resolution="annual")  # doctest: +SKIP
   >>> sorted(df["series"].unique())  # doctest: +SKIP
   ['CHAW', 'CZBH', 'D7BT', 'D7G7', 'L522', 'L55O']


.. py:function:: validate_data(df)

   Validate that a DataFrame conforms to the macroeconomic schema.

   Checks performed:

   - All :data:`SCHEMA_COLUMNS` are present.
   - At least one row is present.
   - ``geography`` is exclusively "UK" and ``source`` exclusively "ONS".
   - ``resolution`` only contains known values.
   - ``value`` is numeric with no nulls.

   :param df: DataFrame to validate.

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

   :raises ONSValidationError: If any check fails.

   .. rubric:: Example

   >>> df = get_series("D7G7", resolution="annual")  # doctest: +SKIP
   >>> validate_data(df)  # doctest: +SKIP
   True