bolster.data_sources.nisra.registrar_general

NISRA Registrar General Quarterly Tables Data Source.

Provides access to quarterly vital statistics for Northern Ireland, including: - Quarterly births and stillbirths (from Q1 2009) - Quarterly deaths, marriages, and civil partnerships - LGD-level breakdowns for the current quarter - Birth and death rates per 1,000 population

These quarterly tables provide higher-level aggregated statistics compared to the monthly data, with additional metrics like stillbirths, infant deaths, and rates.

Data Source:

Publications page: https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/registrar-general-quarterly-report

The quarterly tables are published approximately 6 weeks after the end of each quarter. Historical data is available from Q1 2009.

Update Frequency: Quarterly (February, May, August, November) Geographic Coverage: Northern Ireland (with LGD breakdowns)

Example

>>> from bolster.data_sources.nisra import registrar_general
>>> data = registrar_general.get_quarterly_vital_statistics()
>>> sorted(data.keys())
['births', 'deaths', 'lgd']
>>> births = registrar_general.get_quarterly_births()
>>> 'total_births' in births.columns
True
>>> lgd_df = registrar_general.get_lgd_statistics()
>>> 'lgd' in lgd_df.columns
True

Attributes

logger

REGISTRAR_GENERAL_BASE_URL

NI_LGDS

Functions

get_latest_publication_url()

Scrape NISRA to find the latest Registrar General Quarterly Tables file.

parse_quarterly_births(sheet)

Parse Table 1a - Quarterly Births from the Excel sheet.

parse_quarterly_deaths(sheet)

Parse Table 1b - Quarterly Deaths from the Excel sheet.

parse_lgd_statistics(sheet)

Parse Table 3b - LGD-level statistics from the Excel sheet.

parse_quarterly_tables(file_path)

Parse the Registrar General Quarterly Tables Excel file.

get_quarterly_vital_statistics([force_refresh])

Get all quarterly vital statistics from the Registrar General Tables.

get_quarterly_births([force_refresh])

Get quarterly births data.

get_quarterly_deaths([force_refresh])

Get quarterly deaths and marriages data.

get_lgd_statistics([force_refresh])

Get current quarter LGD-level statistics.

validate_against_monthly_births(quarterly_df[, monthly_df])

Compare quarterly births totals against aggregated monthly births.

validate_against_monthly_marriages(quarterly_df[, ...])

Compare quarterly marriages totals against aggregated monthly marriages.

get_validation_report([force_refresh])

Run all cross-validations and return comprehensive report.

validate_data(df[, data_type])

Validate quarterly data for consistency and reasonable values.

Module Contents

bolster.data_sources.nisra.registrar_general.logger[source]
bolster.data_sources.nisra.registrar_general.REGISTRAR_GENERAL_BASE_URL = 'https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/registrar-general-quarterly-report'[source]
bolster.data_sources.nisra.registrar_general.NI_LGDS = ['Antrim and Newtownabbey', 'Ards and North Down', 'Armagh City, Banbridge and Craigavon',...[source]
bolster.data_sources.nisra.registrar_general.get_latest_publication_url()[source]

Scrape NISRA to find the latest Registrar General Quarterly Tables file.

Navigates the publication structure: 1. Scrapes the Registrar General Quarterly Report page 2. Finds the latest quarterly tables publication link 3. Extracts the Excel file URL

Returns:

Tuple of (excel_url, publication_page_url, year, quarter)

Raises:

NISRADataNotFoundError – If publication or file not found

Return type:

tuple[str, str, int, int]

bolster.data_sources.nisra.registrar_general.parse_quarterly_births(sheet)[source]

Parse Table 1a - Quarterly Births from the Excel sheet.

The births table contains quarterly data from Q1 2009 with: - Total births, birth rate, stillbirths - Births outside marriage (count and %) - Teenage births (count and %) - Births to mothers 30+ (count and %)

Parameters:

sheet – openpyxl worksheet object for Table 1a

Returns:

DataFrame with quarterly births data

Return type:

pandas.DataFrame

bolster.data_sources.nisra.registrar_general.parse_quarterly_deaths(sheet)[source]

Parse Table 1b - Quarterly Deaths from the Excel sheet.

The deaths table contains quarterly data with: - Total deaths and death rate - Marriages and civil partnerships - Infant deaths

Parameters:

sheet – openpyxl worksheet object for Table 1b

Returns:

DataFrame with quarterly deaths/marriages data

Return type:

pandas.DataFrame

bolster.data_sources.nisra.registrar_general.parse_lgd_statistics(sheet)[source]

Parse Table 3b - LGD-level statistics from the Excel sheet.

The LGD table contains current quarter statistics by Local Government District: - Population estimate - Births and birth rate - Deaths and death rate - Marriages

Parameters:

sheet – openpyxl worksheet object for Table 3b

Returns:

DataFrame with LGD-level statistics

Return type:

pandas.DataFrame

bolster.data_sources.nisra.registrar_general.parse_quarterly_tables(file_path)[source]

Parse the Registrar General Quarterly Tables Excel file.

The file contains multiple tables: - Table 1a: Quarterly births and stillbirths - Table 1b: Quarterly deaths, marriages, civil partnerships - Table 3b: Current quarter by LGD

Parameters:

file_path (str | pathlib.Path) – Path to the quarterly tables Excel file

Returns:

Dict with keys ‘births’, ‘deaths’, ‘lgd’ containing DataFrames

Return type:

dict[str, pandas.DataFrame]

bolster.data_sources.nisra.registrar_general.get_quarterly_vital_statistics(force_refresh=False)[source]

Get all quarterly vital statistics from the Registrar General Tables.

Automatically discovers and downloads the most recent quarterly tables publication from NISRA.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • ‘births’: DataFrame with quarterly births data

  • ’deaths’: DataFrame with quarterly deaths/marriages data

  • ’lgd’: DataFrame with LGD-level breakdowns

Return type:

Dict with keys

Raises:

NISRADataNotFoundError – If latest publication cannot be found

Example

>>> data = get_quarterly_vital_statistics()
>>> sorted(data.keys())
['births', 'deaths', 'lgd']
bolster.data_sources.nisra.registrar_general.get_quarterly_births(force_refresh=False)[source]

Get quarterly births data.

Convenience function to get only the births table.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • year: int (2009+)

  • quarter: int (1-4)

  • date: datetime (first day of quarter)

  • total_births: int

  • birth_rate: float (per 1,000 population)

  • stillbirths: int (if available)

Return type:

DataFrame with columns

Example

>>> births = get_quarterly_births()
>>> 'total_births' in births.columns
True
bolster.data_sources.nisra.registrar_general.get_quarterly_deaths(force_refresh=False)[source]

Get quarterly deaths and marriages data.

Convenience function to get only the deaths table.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • year: int (2009+)

  • quarter: int (1-4)

  • date: datetime

  • deaths: int

  • death_rate: float (per 1,000 population)

  • marriages: int

  • civil_partnerships: int

Return type:

DataFrame with columns

Example

>>> deaths = get_quarterly_deaths()
>>> 'deaths' in deaths.columns
True
bolster.data_sources.nisra.registrar_general.get_lgd_statistics(force_refresh=False)[source]

Get current quarter LGD-level statistics.

Convenience function to get the LGD breakdown table.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • lgd: str (Local Government District name)

  • population: int (mid-year estimate)

  • births: int

  • birth_rate: float

  • deaths: int

  • death_rate: float

  • marriages: int

Return type:

DataFrame with columns

Example

>>> lgd = get_lgd_statistics()
>>> 'lgd' in lgd.columns
True
bolster.data_sources.nisra.registrar_general.validate_against_monthly_births(quarterly_df, monthly_df=None)[source]

Compare quarterly births totals against aggregated monthly births.

Cross-validates quarterly data against monthly data to verify consistency. Some differences are expected due to timing of registrations.

Parameters:

  • quarterly_df (pandas.DataFrame) – Quarterly births DataFrame from get_quarterly_births()

  • monthly_df (pandas.DataFrame | None) – Monthly births DataFrame from births module (auto-loaded if None)

Returns:

  • year: int

  • quarter: int

  • quarterly_total: int

  • monthly_sum: int

  • difference: int

  • pct_diff: float (percentage difference)

Return type:

DataFrame with columns

Example

>>> births_q = get_quarterly_births()
>>> validation = validate_against_monthly_births(births_q)
>>> 'quarterly_total' in validation.columns
True
bolster.data_sources.nisra.registrar_general.validate_against_monthly_marriages(quarterly_df, monthly_df=None)[source]

Compare quarterly marriages totals against aggregated monthly marriages.

Cross-validates quarterly data against monthly data to verify consistency.

Parameters:

  • quarterly_df (pandas.DataFrame) – Quarterly deaths DataFrame from get_quarterly_deaths()

  • monthly_df (pandas.DataFrame | None) – Monthly marriages DataFrame from marriages module

Returns:

DataFrame with comparison columns

Return type:

pandas.DataFrame

Example

>>> deaths_q = get_quarterly_deaths()
>>> validation = validate_against_monthly_marriages(deaths_q)
>>> 'quarterly_total' in validation.columns
True
bolster.data_sources.nisra.registrar_general.get_validation_report(force_refresh=False)[source]

Run all cross-validations and return comprehensive report.

Compares quarterly data against monthly data sources to verify consistency.

Parameters:

force_refresh (bool) – If True, bypass cache and download fresh data

Returns:

  • ‘births_validation’: Quarterly vs monthly births comparison

  • ’marriages_validation’: Quarterly vs monthly marriages comparison

  • ’summary’: Overall validation statistics

Return type:

Dict with keys

Example

>>> report = get_validation_report()
>>> 'summary' in report
True
bolster.data_sources.nisra.registrar_general.validate_data(df, data_type='births')[source]

Validate quarterly data for consistency and reasonable values.

Parameters:

  • df (pandas.DataFrame) – DataFrame to validate

  • data_type (str) – Type of data (‘births’, ‘deaths’, or ‘lgd’)

Returns:

True if validation passes

Raises:

NISRAValidationError – If validation fails

Return type:

bool