bolster.data_sources.nisra.deaths

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

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

logger

Functions

`get_latest_deaths`([dimension, force_refresh])	Retrieve weekly deaths data for Northern Ireland.
`get_historical_deaths`([force_refresh])	Return annual deaths totals — compatibility shim for migration.py.

Module Contents

bolster.data_sources.nisra.deaths.logger[source]

bolster.data_sources.nisra.deaths.get_latest_deaths(dimension='all', force_refresh=False)[source]

Retrieve weekly deaths data for Northern Ireland.

Parameters:

dimension (str) – 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)
force_refresh (bool) – 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.
PxStatError – If the API request fails.

Return type:

pandas.DataFrame | dict

Example

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

bolster.data_sources.nisra.deaths.get_historical_deaths(force_refresh=False)[source]

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 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.

Parameters:: force_refresh (bool) – Passed through to the underlying registrar_general module.
Returns:: DataFrame with columns year (int) and total_deaths (int).
Return type:: pandas.DataFrame