bolster.data_sources.nisra.marriages ==================================== .. py:module:: bolster.data_sources.nisra.marriages .. autoapi-nested-parse:: NISRA Marriage and Civil Partnership Registrations Data Source. Provides access to monthly marriage and civil partnership registration data for Northern Ireland. Data includes: - Monthly marriage registrations from 2006 to present - Monthly civil partnership registrations from 2006 to present - Total registrations by month and year - Historical time series for trend analysis Registrations represent when the event was registered, not when the ceremony occurred. The data is published monthly with provisional figures for the current year and final figures for previous years. Data Source: **Marriages Mother Page**: https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/marriages **Civil Partnerships Page**: https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/civil-partnerships These pages list all relevant statistics publications in reverse chronological order (newest first). The module automatically scrapes these pages to find the latest publications, then downloads the Excel files. Update Frequency: Monthly (published around 11th of the following month) Geographic Coverage: Northern Ireland Reference Date: Month of registration .. rubric:: Example >>> from bolster.data_sources.nisra import marriages >>> # Get latest marriage registrations >>> df = marriages.get_latest_marriages() >>> sorted(df.columns.tolist()) ['date', 'marriages', 'month', 'year'] >>> # Get latest civil partnership registrations >>> cp_df = marriages.get_latest_civil_partnerships() >>> sorted(cp_df.columns.tolist()) ['civil_partnerships', 'date', 'month', 'year'] >>> # Filter for a specific year >>> df_2024 = df[df['year'] == 2024] >>> len(df_2024) > 0 True Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.marriages.logger bolster.data_sources.nisra.marriages.MARRIAGES_BASE_URL bolster.data_sources.nisra.marriages.CIVIL_PARTNERSHIPS_BASE_URL Functions --------- .. autoapisummary:: bolster.data_sources.nisra.marriages.get_latest_marriages_publication_url bolster.data_sources.nisra.marriages.parse_marriages_file bolster.data_sources.nisra.marriages.get_latest_marriages bolster.data_sources.nisra.marriages.validate_marriages_temporal_continuity bolster.data_sources.nisra.marriages.get_marriages_by_year bolster.data_sources.nisra.marriages.get_marriages_summary_by_year bolster.data_sources.nisra.marriages.get_latest_civil_partnerships_publication_url bolster.data_sources.nisra.marriages.parse_civil_partnerships_file bolster.data_sources.nisra.marriages.get_latest_civil_partnerships bolster.data_sources.nisra.marriages.get_civil_partnerships_by_year bolster.data_sources.nisra.marriages.get_civil_partnerships_summary_by_year Module Contents --------------- .. py:data:: logger .. py:data:: MARRIAGES_BASE_URL :value: 'https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/marriages' .. py:data:: CIVIL_PARTNERSHIPS_BASE_URL :value: 'https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/civil-partnerships' .. py:function:: get_latest_marriages_publication_url() Scrape NISRA marriages mother page to find the latest monthly marriages file. Navigates the publication structure: 1. Scrapes mother page for latest "Monthly Marriages" publication 2. Follows link to publication detail page 3. Finds marriages Excel file :returns: Tuple of (excel_file_url, publication_date) :raises NISRADataNotFoundError: If publication or file not found .. py:function:: parse_marriages_file(file_path) Parse NISRA monthly marriages Excel file. The marriages file contains a single "Marriages" sheet with a wide-format table: - Rows: Months (January-December) - Columns: Years (2006-present) - Values: Number of marriage registrations :param file_path: Path to the marriages Excel file :returns: - month: datetime (first day of month) - year: int (year of registration) - marriages: int (number of marriage registrations) :rtype: DataFrame with columns :raises NISRAValidationError: If file structure is unexpected .. py:function:: get_latest_marriages(force_refresh = False) Get the latest monthly marriage registrations data. Automatically discovers and downloads the most recent marriage registrations from the NISRA website. :param force_refresh: If True, bypass cache and download fresh data :returns: - date: datetime (first day of month) - year: int (year of registration) - month: str (month name) - marriages: int (number of marriage registrations) :rtype: DataFrame with columns :raises NISRADataNotFoundError: If latest publication cannot be found :raises NISRAValidationError: If file structure is unexpected .. rubric:: Example >>> df = get_latest_marriages() >>> sorted(df.columns.tolist()) ['date', 'marriages', 'month', 'year'] >>> df_2024 = df[df['year'] == 2024] >>> total_2024 = df_2024['marriages'].sum() >>> bool(total_2024 > 0) True .. py:function:: validate_marriages_temporal_continuity(df) Validate that marriage data has no unexpected gaps in time series. :param df: DataFrame from parse_marriages_file or get_latest_marriages :returns: True if validation passes :raises NISRAValidationError: If validation fails .. py:function:: get_marriages_by_year(df, year) Filter marriage data for a specific year. :param df: DataFrame from get_latest_marriages() :param year: Year to filter :returns: Filtered DataFrame .. rubric:: Example >>> df = get_latest_marriages() >>> df_2024 = get_marriages_by_year(df, 2024) >>> total = df_2024['marriages'].sum() >>> bool(total > 0) True .. py:function:: get_marriages_summary_by_year(df) Calculate annual marriage totals and statistics. :param df: DataFrame from get_latest_marriages() :returns: - year: int - total_marriages: int (sum for the year) - months_reported: int (number of months with data) - avg_per_month: float (average marriages per month) :rtype: DataFrame with columns .. rubric:: Example >>> df = get_latest_marriages() >>> summary = get_marriages_summary_by_year(df) >>> sorted(summary.columns.tolist()) ['avg_per_month', 'months_reported', 'total_marriages', 'year'] .. py:function:: get_latest_civil_partnerships_publication_url() Scrape NISRA civil partnerships page to find the latest monthly civil partnerships file. :returns: Tuple of (excel_file_url, publication_date) :raises NISRADataNotFoundError: If publication or file not found .. py:function:: parse_civil_partnerships_file(file_path) Parse NISRA monthly civil partnerships Excel file. The civil partnerships file contains a "Civil Partnerships" sheet with a wide-format table: - Rows: Months (January-December) - Columns: Years (2006-present) - Values: Number of civil partnership registrations :param file_path: Path to the civil partnerships Excel file :returns: - date: datetime (first day of month) - year: int (year of registration) - month: str (month name) - civil_partnerships: int (number of civil partnership registrations) :rtype: DataFrame with columns :raises NISRAValidationError: If file structure is unexpected .. py:function:: get_latest_civil_partnerships(force_refresh = False) Get the latest monthly civil partnership registrations data. Automatically discovers and downloads the most recent civil partnership registrations from the NISRA website. :param force_refresh: If True, bypass cache and download fresh data :returns: - date: datetime (first day of month) - year: int (year of registration) - month: str (month name) - civil_partnerships: int (number of civil partnership registrations) :rtype: DataFrame with columns :raises NISRADataNotFoundError: If latest publication cannot be found :raises NISRAValidationError: If file structure is unexpected .. rubric:: Example >>> df = get_latest_civil_partnerships() >>> sorted(df.columns.tolist()) ['civil_partnerships', 'date', 'month', 'year'] >>> df_2024 = df[df['year'] == 2024] >>> total = df_2024['civil_partnerships'].sum() >>> bool(total >= 0) True .. py:function:: get_civil_partnerships_by_year(df, year) Filter civil partnership data for a specific year. :param df: DataFrame from get_latest_civil_partnerships() :param year: Year to filter :returns: Filtered DataFrame .. py:function:: get_civil_partnerships_summary_by_year(df) Calculate annual civil partnership totals and statistics. :param df: DataFrame from get_latest_civil_partnerships() :returns: - year: int - total_civil_partnerships: int - months_reported: int - avg_per_month: float :rtype: DataFrame with columns