bolster.data_sources.nisra.registrar_general ============================================ .. py:module:: bolster.data_sources.nisra.registrar_general .. autoapi-nested-parse:: 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) .. rubric:: 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 ---------- .. autoapisummary:: bolster.data_sources.nisra.registrar_general.logger bolster.data_sources.nisra.registrar_general.REGISTRAR_GENERAL_BASE_URL bolster.data_sources.nisra.registrar_general.NI_LGDS Functions --------- .. autoapisummary:: bolster.data_sources.nisra.registrar_general.get_latest_publication_url bolster.data_sources.nisra.registrar_general.parse_quarterly_births bolster.data_sources.nisra.registrar_general.parse_quarterly_deaths bolster.data_sources.nisra.registrar_general.parse_lgd_statistics bolster.data_sources.nisra.registrar_general.parse_quarterly_tables bolster.data_sources.nisra.registrar_general.get_quarterly_vital_statistics bolster.data_sources.nisra.registrar_general.get_quarterly_births bolster.data_sources.nisra.registrar_general.get_quarterly_deaths bolster.data_sources.nisra.registrar_general.get_lgd_statistics bolster.data_sources.nisra.registrar_general.validate_against_monthly_births bolster.data_sources.nisra.registrar_general.validate_against_monthly_marriages bolster.data_sources.nisra.registrar_general.get_validation_report bolster.data_sources.nisra.registrar_general.validate_data Module Contents --------------- .. py:data:: logger .. py:data:: REGISTRAR_GENERAL_BASE_URL :value: 'https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/registrar-general-quarterly-report' .. py:data:: NI_LGDS :value: ['Antrim and Newtownabbey', 'Ards and North Down', 'Armagh City, Banbridge and Craigavon',... .. py:function:: get_latest_publication_url() 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 .. py:function:: parse_quarterly_births(sheet) 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 %) :param sheet: openpyxl worksheet object for Table 1a :returns: DataFrame with quarterly births data .. py:function:: parse_quarterly_deaths(sheet) 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 :param sheet: openpyxl worksheet object for Table 1b :returns: DataFrame with quarterly deaths/marriages data .. py:function:: parse_lgd_statistics(sheet) 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 :param sheet: openpyxl worksheet object for Table 3b :returns: DataFrame with LGD-level statistics .. py:function:: parse_quarterly_tables(file_path) 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 :param file_path: Path to the quarterly tables Excel file :returns: Dict with keys 'births', 'deaths', 'lgd' containing DataFrames .. py:function:: get_quarterly_vital_statistics(force_refresh = False) Get all quarterly vital statistics from the Registrar General Tables. Automatically discovers and downloads the most recent quarterly tables publication from NISRA. :param force_refresh: 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 :rtype: Dict with keys :raises NISRADataNotFoundError: If latest publication cannot be found .. rubric:: Example >>> data = get_quarterly_vital_statistics() >>> sorted(data.keys()) ['births', 'deaths', 'lgd'] .. py:function:: get_quarterly_births(force_refresh = False) Get quarterly births data. Convenience function to get only the births table. :param force_refresh: 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) :rtype: DataFrame with columns .. rubric:: Example >>> births = get_quarterly_births() >>> 'total_births' in births.columns True .. py:function:: get_quarterly_deaths(force_refresh = False) Get quarterly deaths and marriages data. Convenience function to get only the deaths table. :param force_refresh: 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 :rtype: DataFrame with columns .. rubric:: Example >>> deaths = get_quarterly_deaths() >>> 'deaths' in deaths.columns True .. py:function:: get_lgd_statistics(force_refresh = False) Get current quarter LGD-level statistics. Convenience function to get the LGD breakdown table. :param force_refresh: 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 :rtype: DataFrame with columns .. rubric:: Example >>> lgd = get_lgd_statistics() >>> 'lgd' in lgd.columns True .. py:function:: validate_against_monthly_births(quarterly_df, monthly_df = None) 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. :param quarterly_df: Quarterly births DataFrame from get_quarterly_births() :param monthly_df: 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) :rtype: DataFrame with columns .. rubric:: Example >>> births_q = get_quarterly_births() >>> validation = validate_against_monthly_births(births_q) >>> 'quarterly_total' in validation.columns True .. py:function:: validate_against_monthly_marriages(quarterly_df, monthly_df = None) Compare quarterly marriages totals against aggregated monthly marriages. Cross-validates quarterly data against monthly data to verify consistency. :param quarterly_df: Quarterly deaths DataFrame from get_quarterly_deaths() :param monthly_df: Monthly marriages DataFrame from marriages module :returns: DataFrame with comparison columns .. rubric:: Example >>> deaths_q = get_quarterly_deaths() >>> validation = validate_against_monthly_marriages(deaths_q) >>> 'quarterly_total' in validation.columns True .. py:function:: get_validation_report(force_refresh = False) Run all cross-validations and return comprehensive report. Compares quarterly data against monthly data sources to verify consistency. :param force_refresh: 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 :rtype: Dict with keys .. rubric:: Example >>> report = get_validation_report() >>> 'summary' in report True .. py:function:: validate_data(df, data_type = 'births') Validate quarterly data for consistency and reasonable values. :param df: DataFrame to validate :param data_type: Type of data ('births', 'deaths', or 'lgd') :returns: True if validation passes :raises NISRAValidationError: If validation fails