bolster.data_sources.nisra.population_projections
=================================================

.. py:module:: bolster.data_sources.nisra.population_projections

.. autoapi-nested-parse::

   NISRA Population Projections for Northern Ireland.

   Provides access to official NISRA population projections with demographic breakdowns
   by year, age, sex, and projection variant.

   NI-level projections (2024-based, 2024-2074) are served via the PxStat API.
   LGD sub-area projections are not yet available via PxStat and remain Excel-based.

   Data Source:
       **PxStat API** (NI-level, used by this module):
           https://ws-data.nisra.gov.uk/public/api.restful/PxStat.Data.Cube_API.ReadDataset/{MATRIX}/CSV/1.0/en

       Matrix codes:
           - ``PPMY02T01``: NI projections by single year of age (0-90+) and sex — principal + variants
           - ``PPMY02T02``: NI projections by 5-year age bands and sex — principal only
           - ``PPMY02T03``: Variant projections (high/low fertility, life expectancy, migration)

       **Original publication pages** (for reference and LGD projections):
           - Principal: https://www.nisra.gov.uk/publications/2024-based-population-projections-northern-ireland
           - Variants: https://www.nisra.gov.uk/publications/2024-based-population-projections-northern-ireland-variant-projections
           - LGD sub-areas: https://www.nisra.gov.uk/publications/2022-based-population-projections-areas-within-northern-ireland

   Update Frequency: Biennial (NI-level)
   Geographic Coverage: Northern Ireland overall (LGD projections not yet in PxStat)
   Projection Horizon: 2024-2074 (NI-level via API)

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import population_projections
   >>> df = population_projections.get_latest_projections()
   >>> 'population' in df.columns
   True
   >>> df_decade = population_projections.get_latest_projections(
   ...     start_year=2025,
   ...     end_year=2035
   ... )
   >>> len(df_decade) > 0
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.population_projections.logger


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.population_projections.get_latest_projections
   bolster.data_sources.nisra.population_projections.get_variant_projections
   bolster.data_sources.nisra.population_projections.validate_projections


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

.. py:data:: logger

.. py:function:: get_latest_projections(start_year = None, end_year = None, age_groups = '5yr', force_refresh = False)

   Retrieve NI population projections (principal projection).

   :param start_year: First projection year to include (default: first available).
   :param end_year: Last projection year to include (default: last available).
   :param age_groups: Age breakdown format:
                      - ``'5yr'``: 5-year age bands (default) — smaller result set
                      - ``'single'``: Single year of age (0-90+) — larger result set
   :param force_refresh: Ignored — kept for API compatibility. The PxStat API
                         always returns current data.

   :returns:     ``year``, ``age_group``, ``sex``, ``population``, ``base_year``
   :rtype: DataFrame with columns

   :raises NISRAValidationError: If the API returns empty or invalid data.
   :raises PxStatError: If the API request fails.

   .. rubric:: Example

   >>> df = get_latest_projections()
   >>> 'population' in df.columns
   True


.. py:function:: get_variant_projections(variant = None, start_year = None, end_year = None, force_refresh = False)

   Retrieve NI population projections including variant scenarios.

   :param variant: Filter to a specific variant label (partial match, case-insensitive).
                   E.g. ``'high fertility'``, ``'low fertility'``, ``'high life expectancy'``.
                   If None, all variants are returned.
   :param start_year: First projection year to include.
   :param end_year: Last projection year to include.
   :param force_refresh: Ignored — kept for API compatibility.

   :returns:     ``year``, ``age_group``, ``sex``, ``variant``, ``population``
   :rtype: DataFrame with columns


.. py:function:: validate_projections(df)

   Validate a projections DataFrame for basic integrity.

   :param df: DataFrame from :func:`get_latest_projections`.

   :returns: True if valid.

   :raises NISRAValidationError: If validation fails.