bolster.data_sources.nisra.stillbirths
======================================

.. py:module:: bolster.data_sources.nisra.stillbirths

.. autoapi-nested-parse::

   NISRA Stillbirths and Infant Deaths Data Source.

   Provides access to annual stillbirth and infant death statistics for Northern
   Ireland via the NISRA PxStat API, with geographic breakdowns by HSC Trust and
   Local Government District.

   A stillbirth is defined as a baby born after 24 weeks of pregnancy that did not
   show any signs of life.  Infant deaths are deaths of children under one year old.

   Original data source:
       https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/stillbirths

   PxStat matrices used:
       - SBAIDHSCT — annual stillbirths and infant deaths by HSC Trust (5 trusts + NI total)
       - SBAIDLGD  — annual stillbirths and infant deaths by LGD (11 districts + NI total)

   Update Frequency: Annual
   Geographic Coverage: Northern Ireland

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import stillbirths
   >>> df = stillbirths.get_latest_stillbirths()
   >>> sorted(df.columns.tolist())
   ['geography', 'geography_code', 'infant_deaths', 'stillbirths', 'year']

   >>> # NI total stillbirths in 2024
   >>> ni_2024 = df[(df["geography"] == "Northern Ireland") & (df["year"] == 2024)]
   >>> bool(ni_2024["stillbirths"].iloc[0] > 0)
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.stillbirths.logger


Exceptions
----------

.. autoapisummary::

   bolster.data_sources.nisra.stillbirths.NISRAValidationError


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.stillbirths.get_latest_stillbirths
   bolster.data_sources.nisra.stillbirths.validate_stillbirths_data
   bolster.data_sources.nisra.stillbirths.get_stillbirths_by_year
   bolster.data_sources.nisra.stillbirths.get_annual_summary


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

.. py:data:: logger

.. py:exception:: NISRAValidationError

   Bases: :py:obj:`Exception`


   Raised when stillbirths data fails validation.

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


.. py:function:: get_latest_stillbirths(dimension = 'hsct', force_refresh = False)

   Get the latest annual stillbirth and infant death data for Northern Ireland.

   Fetches annual data from the NISRA PxStat API for the chosen geographic
   breakdown.  Returns the full time series available (HSCT from 1974, LGD
   from 2008).

   .. note::

      ``force_refresh`` is accepted for API compatibility but is ignored —
      the PxStat API is called directly with no local cache layer.

   :param dimension: Geographic breakdown to return.  One of:

                     - ``"hsct"`` — 5 HSC Trusts + NI total (default, data from 1974)
                     - ``"lgd"``  — 11 Local Government Districts + NI total (data from 2008)
   :param force_refresh: Ignored.  Retained for API compatibility.

   :returns:     - ``year``: Registration year (int)
                 - ``geography_code``: geography identifier code
                 - ``geography``: geography name label
                 - ``stillbirths``: Annual stillbirth count (int)
                 - ``infant_deaths``: Annual infant death count (int)
   :rtype: DataFrame with columns

   :raises ValueError: If ``dimension`` is not a supported value.

   .. rubric:: Example

   >>> df = get_latest_stillbirths()
   >>> sorted(df.columns.tolist())
   ['geography', 'geography_code', 'infant_deaths', 'stillbirths', 'year']
   >>> annual = df[df["geography"] == "Northern Ireland"].groupby("year")["stillbirths"].sum()
   >>> len(annual) > 0
   True


.. py:function:: validate_stillbirths_data(df)

   Validate stillbirths DataFrame for basic integrity.

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

   :returns: True if validation passes.

   :raises NISRAValidationError: If validation fails.

   .. rubric:: Example

   >>> import pandas as pd
   >>> validate_stillbirths_data(pd.DataFrame())
   Traceback (most recent call last):
       ...
   bolster.data_sources.nisra.stillbirths.NISRAValidationError: DataFrame is empty


.. py:function:: get_stillbirths_by_year(df, year)

   Filter stillbirths data to a specific year.

   :param df: DataFrame from :func:`get_latest_stillbirths`.
   :param year: Year to filter.

   :returns: Filtered DataFrame.

   .. rubric:: Example

   >>> df = get_latest_stillbirths()
   >>> df_2024 = get_stillbirths_by_year(df, 2024)
   >>> "stillbirths" in df_2024.columns
   True


.. py:function:: get_annual_summary(df)

   Calculate annual NI totals and trends for stillbirths.

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

   :returns:     ``year``, ``total_stillbirths``, ``yoy_change``, ``yoy_pct_change``.
   :rtype: DataFrame with columns

   .. rubric:: Example

   >>> df = get_latest_stillbirths()
   >>> summary = get_annual_summary(df)
   >>> sorted(summary.columns.tolist())
   ['total_stillbirths', 'year', 'yoy_change', 'yoy_pct_change']