bolster.data_sources.nisra.marriages

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

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

logger

MARRIAGES_BASE_URL

CIVIL_PARTNERSHIPS_BASE_URL

Functions

get_latest_marriages_publication_url()

Scrape NISRA marriages mother page to find the latest monthly marriages file.

parse_marriages_file(file_path)

Parse NISRA monthly marriages Excel file.

get_latest_marriages([force_refresh])

Get the latest monthly marriage registrations data.

validate_marriages_temporal_continuity(df)

Validate that marriage data has no unexpected gaps in time series.

get_marriages_by_year(df, year)

Filter marriage data for a specific year.

get_marriages_summary_by_year(df)

Calculate annual marriage totals and statistics.

get_latest_civil_partnerships_publication_url()

Scrape NISRA civil partnerships page to find the latest monthly civil partnerships file.

parse_civil_partnerships_file(file_path)

Parse NISRA monthly civil partnerships Excel file.

get_latest_civil_partnerships([force_refresh])

Get the latest monthly civil partnership registrations data.

get_civil_partnerships_by_year(df, year)

Filter civil partnership data for a specific year.

get_civil_partnerships_summary_by_year(df)

Calculate annual civil partnership totals and statistics.

Module Contents

bolster.data_sources.nisra.marriages.logger[source]
bolster.data_sources.nisra.marriages.MARRIAGES_BASE_URL = 'https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/marriages'[source]
bolster.data_sources.nisra.marriages.CIVIL_PARTNERSHIPS_BASE_URL = 'https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/civil-partnerships'[source]
bolster.data_sources.nisra.marriages.get_latest_marriages_publication_url()[source]

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

Return type:

tuple[str, str]

bolster.data_sources.nisra.marriages.parse_marriages_file(file_path)[source]

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

Parameters:

file_path (str | pathlib.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)

Return type:

DataFrame with columns

Raises:

NISRAValidationError – If file structure is unexpected

bolster.data_sources.nisra.marriages.get_latest_marriages(force_refresh=False)[source]

Get the latest monthly marriage registrations data.

Automatically discovers and downloads the most recent marriage registrations from the NISRA website.

Parameters:

force_refresh (bool) – 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)

Return type:

DataFrame with columns

Raises:

  • NISRADataNotFoundError – If latest publication cannot be found

  • NISRAValidationError – If file structure is unexpected

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
bolster.data_sources.nisra.marriages.validate_marriages_temporal_continuity(df)[source]

Validate that marriage data has no unexpected gaps in time series.

Parameters:

df (pandas.DataFrame) – DataFrame from parse_marriages_file or get_latest_marriages

Returns:

True if validation passes

Raises:

NISRAValidationError – If validation fails

Return type:

bool

bolster.data_sources.nisra.marriages.get_marriages_by_year(df, year)[source]

Filter marriage data for a specific year.

Parameters:

  • df (pandas.DataFrame) – DataFrame from get_latest_marriages()

  • year (int) – Year to filter

Returns:

Filtered DataFrame

Return type:

pandas.DataFrame

Example

>>> df = get_latest_marriages()
>>> df_2024 = get_marriages_by_year(df, 2024)
>>> total = df_2024['marriages'].sum()
>>> bool(total > 0)
True
bolster.data_sources.nisra.marriages.get_marriages_summary_by_year(df)[source]

Calculate annual marriage totals and statistics.

Parameters:

df (pandas.DataFrame) – 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)

Return type:

DataFrame with columns

Example

>>> df = get_latest_marriages()
>>> summary = get_marriages_summary_by_year(df)
>>> sorted(summary.columns.tolist())
['avg_per_month', 'months_reported', 'total_marriages', 'year']
bolster.data_sources.nisra.marriages.get_latest_civil_partnerships_publication_url()[source]

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

Return type:

tuple[str, str]

bolster.data_sources.nisra.marriages.parse_civil_partnerships_file(file_path)[source]

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

Parameters:

file_path (str | pathlib.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)

Return type:

DataFrame with columns

Raises:

NISRAValidationError – If file structure is unexpected

bolster.data_sources.nisra.marriages.get_latest_civil_partnerships(force_refresh=False)[source]

Get the latest monthly civil partnership registrations data.

Automatically discovers and downloads the most recent civil partnership registrations from the NISRA website.

Parameters:

force_refresh (bool) – 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)

Return type:

DataFrame with columns

Raises:

  • NISRADataNotFoundError – If latest publication cannot be found

  • NISRAValidationError – If file structure is unexpected

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
bolster.data_sources.nisra.marriages.get_civil_partnerships_by_year(df, year)[source]

Filter civil partnership data for a specific year.

Parameters:

  • df (pandas.DataFrame) – DataFrame from get_latest_civil_partnerships()

  • year (int) – Year to filter

Returns:

Filtered DataFrame

Return type:

pandas.DataFrame

bolster.data_sources.nisra.marriages.get_civil_partnerships_summary_by_year(df)[source]

Calculate annual civil partnership totals and statistics.

Parameters:

df (pandas.DataFrame) – DataFrame from get_latest_civil_partnerships()

Returns:

  • year: int

  • total_civil_partnerships: int

  • months_reported: int

  • avg_per_month: float

Return type:

DataFrame with columns