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

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

.. autoapi-nested-parse::

   NISRA Monthly Stillbirth Registrations Data Source.

   Provides access to monthly stillbirth registration statistics for Northern Ireland.
   A stillbirth is defined as a baby born after 24 weeks of pregnancy that did not
   show any signs of life.

   Data covers registrations by month from 2006 to present, updated monthly.

   Data Source:
       **Mother Page**: https://www.nisra.gov.uk/publications/monthly-stillbirths

       The monthly Excel file contains a single "Stillbirths" sheet with counts
       by month of registration (rows) and year (columns), covering 2006 to present.

   Update Frequency: Monthly (published ~6 weeks after reference month)
   Geographic Coverage: Northern Ireland (resident stillbirths)

   .. rubric:: Example

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

   >>> # Total stillbirths in 2024
   >>> total_2024 = df[df['year'] == 2024]['stillbirths'].sum()
   >>> bool(total_2024 >= 0)
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.stillbirths.logger
   bolster.data_sources.nisra.stillbirths.STILLBIRTHS_PUBLICATION_URL
   bolster.data_sources.nisra.stillbirths.MONTH_ORDER


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.stillbirths.get_latest_stillbirths_publication_url
   bolster.data_sources.nisra.stillbirths.parse_stillbirths_file
   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_stillbirth_rate
   bolster.data_sources.nisra.stillbirths.get_annual_summary


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

.. py:data:: logger

.. py:data:: STILLBIRTHS_PUBLICATION_URL
   :value: 'https://www.nisra.gov.uk/publications/monthly-stillbirths'


.. py:data:: MONTH_ORDER
   :value: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September',...


.. py:function:: get_latest_stillbirths_publication_url()

   Scrape NISRA stillbirths publication page to find the latest Excel file.

   :returns: URL of the latest monthly stillbirths Excel file

   :raises NISRADataNotFoundError: If publication or file not found


.. py:function:: parse_stillbirths_file(file_path)

   Parse NISRA monthly stillbirths Excel file into long-format DataFrame.

   The file has a single "Stillbirths" sheet with months as rows and years
   as columns (wide format). This function melts it into long format.

   :param file_path: Path to the downloaded stillbirths Excel file

   :returns:     - date: Timestamp (first day of registration month)
                 - year: int
                 - month: str (e.g. "January")
                 - stillbirths: int
   :rtype: DataFrame with columns

   :raises NISRAValidationError: If file structure is unexpected


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

   Get the latest monthly stillbirth registrations for Northern Ireland.

   :param force_refresh: If True, bypass cache and download fresh data

   :returns:     - date: Timestamp (first of registration month)
                 - year: int
                 - month: str
                 - stillbirths: int
   :rtype: DataFrame with columns

   :raises NISRADataNotFoundError: If latest publication cannot be found
   :raises NISRAValidationError: If file structure is unexpected

   .. rubric:: Example

   >>> df = get_latest_stillbirths()
   >>> sorted(df.columns.tolist())
   ['date', 'month', 'stillbirths', 'year']
   >>> annual = df.groupby('year')['stillbirths'].sum()
   >>> len(annual) > 0
   True


.. py:function:: validate_stillbirths_data(df)

   Validate stillbirths DataFrame for basic integrity.

   :param df: DataFrame from get_latest_stillbirths()

   :returns: True if validation passes

   :raises NISRAValidationError: If validation fails


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

   Filter stillbirths data to a specific year.

   :param df: DataFrame from 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_stillbirth_rate(stillbirths_df, births_df)

   Calculate monthly stillbirth rate per 1,000 total births (live + still).

   :param stillbirths_df: DataFrame from get_latest_stillbirths()
   :param births_df: DataFrame from births.get_latest_births(event_type='registration')

   :returns: date, year, month, stillbirths, live_births,
             total_births, stillbirth_rate
   :rtype: DataFrame with columns

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import stillbirths, births
   >>> sb = stillbirths.get_latest_stillbirths()
   >>> lb = births.get_latest_births(event_type='registration')
   >>> rate = stillbirths.get_stillbirth_rate(sb, lb)


.. py:function:: get_annual_summary(df)

   Calculate annual totals and trends for stillbirths.

   :param df: DataFrame from 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']