bolster.data_sources.nisra.deaths
=================================

.. py:module:: bolster.data_sources.nisra.deaths

.. autoapi-nested-parse::

   NISRA Weekly Death Registrations Data Source.

   Provides access to weekly death registration statistics for Northern Ireland with breakdowns by:
   - Totals (observed, expected, excess, COVID-19, flu/pneumonia deaths)
   - Demographics (age, sex)
   - Geography (Local Government Districts)
   - Place of death (hospital, home, care home, etc.)

   Data is based on registration date. Most deaths are registered within 5 days in Northern Ireland.

   Data Source:
       NISRA PxStat API — https://ws-data.nisra.gov.uk/
       No authentication required; no observed rate limits.

       Matrix codes used:
       - ``WDTHS``: Weekly totals (observed, expected, excess, COVID, flu)
       - ``WDTHSLGD``: Weekly deaths by Local Government District
       - ``WDTHSSXAG``: Weekly deaths by sex and age band
       - ``WDTHSPOD``: Weekly deaths by place of death

   Update Frequency: Weekly (published Fridays for week ending previous Friday)
   Geographic Coverage: Northern Ireland

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import deaths
   >>> df = deaths.get_latest_deaths(dimension='demographics')
   >>> sorted(df.columns.tolist())
   ['age_range', 'deaths', 'sex', 'week_ending']
   >>> len(df) > 0
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.deaths.logger


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.deaths.get_latest_deaths
   bolster.data_sources.nisra.deaths.get_historical_deaths


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

.. py:data:: logger

.. py:function:: get_latest_deaths(dimension = 'all', force_refresh = False)

   Retrieve weekly deaths data for Northern Ireland.

   :param dimension: Which dimension to retrieve. One of:
                     - ``'totals'``: Weekly totals with observed, expected, excess, COVID, flu
                     - ``'demographics'``: By sex and age band
                     - ``'geography'``: By Local Government District
                     - ``'place'``: By place of death
                     - ``'all'``: All dimensions (returns dict of DataFrames)
   :param force_refresh: Ignored — kept for API compatibility. The PxStat API
                         always returns current data.

   :returns: DataFrame for a single dimension, or ``dict[str, DataFrame]`` for ``'all'``.

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

   .. rubric:: Example

   >>> df = get_latest_deaths(dimension='demographics')
   >>> sorted(df.columns.tolist())
   ['age_range', 'deaths', 'sex', 'week_ending']


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

   Return annual deaths totals — compatibility shim for migration.py.

   Uses the Registrar General quarterly tables (back to 2009) to produce
   annual calendar-year totals with the ``year`` and ``total_deaths`` columns
   expected by :func:`bolster.data_sources.nisra.migration.calculate_annual_deaths`.

   The weekly PxStat deaths data only covers 2024 onwards and cannot be used
   for multi-year migration calculations.

   :param force_refresh: Passed through to the underlying registrar_general module.

   :returns: DataFrame with columns ``year`` (int) and ``total_deaths`` (int).