bolster.data_sources.nisra.births

NISRA Monthly Birth Registrations Data Source.

Provides access to monthly birth registration statistics for Northern Ireland with breakdowns by: - Sex (Persons, Male, Female) - Event type (Registration date vs Birth/Occurrence date)

Births data are based on residence of mother at time of birth. Data includes both: - Births by month of registration: When the birth was officially registered - Births by month of occurrence: When the birth actually occurred

Most births are registered within 42 days in Northern Ireland, so registration data lags occurrence data slightly.

Data Source:

Mother Page: https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/births

This page lists all births statistics publications in reverse chronological order (newest first). The module automatically scrapes this page to find the latest “Monthly Births” publication, then downloads the Excel file from that publication’s detail page.

The monthly files contain complete time series from 2006 to present, updated monthly. This ensures the module always retrieves the most recent data without hardcoding dates.

Update Frequency: Monthly (published 12th of following month at 9:30 AM) Geographic Coverage: Northern Ireland (based on mother’s residence)

Example

>>> from bolster.data_sources.nisra import births
>>> # Get latest births by registration date
>>> df = births.get_latest_births(event_type='registration')
>>> sorted(df.columns.tolist())
['births', 'month', 'sex']
>>> sorted(df['sex'].unique().tolist())
['Female', 'Male', 'Persons']

>>> # Get latest births by occurrence date
>>> df = births.get_latest_births(event_type='occurrence')
>>> len(df) > 0
True

Attributes

logger

BIRTHS_BASE_URL

Functions

get_latest_births_publication_url()

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

parse_births_file(file_path[, event_type])

Parse NISRA monthly births Excel file into long-format DataFrames.

get_latest_births([event_type, force_refresh])

Get the latest monthly births data.

validate_births_totals(df)

Validate that Male + Female births equal Persons births for each month.

Module Contents

bolster.data_sources.nisra.births.logger[source]
bolster.data_sources.nisra.births.BIRTHS_BASE_URL = 'https://www.nisra.gov.uk/statistics/births-deaths-and-marriages/births'[source]
bolster.data_sources.nisra.births.get_latest_births_publication_url()[source]

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

Navigates the publication structure: 1. Scrapes mother page for “Monthly Births” publication 2. Follows link to publication detail page 3. Finds latest Excel file

Returns:

URL of the latest monthly births Excel file

Raises:

NISRADataNotFoundError – If publication or file not found

Return type:

str

bolster.data_sources.nisra.births.parse_births_file(file_path, event_type='both')[source]

Parse NISRA monthly births Excel file into long-format DataFrames.

The births file contains two main sheets: - Births_Month of Registration: Births by when registered - Births_Month of Birth: Births by when occurred

Each sheet has three stacked tables (Persons, Males, Females) in wide format (months as rows, years as columns). This function converts to long format.

Parameters:

  • file_path (str | pathlib.Path) – Path to the births Excel file

  • event_type (Literal['registration', 'occurrence', 'both']) – Which event type to parse: - “registration”: Births by registration date only - “occurrence”: Births by birth/occurrence date only - “both”: Return dict with both types

Returns:

Dict with keys “registration” and “occurrence”. Otherwise: Single DataFrame with columns:

  • month: datetime (first day of month)

  • sex: str (Persons, Male, Female)

  • births: int (number of births)

Return type:

If event_type is “both”

Raises:

NISRAValidationError – If file structure is unexpected

bolster.data_sources.nisra.births.get_latest_births(event_type='both', force_refresh=False)[source]

Get the latest monthly births data.

Automatically discovers and downloads the most recent monthly births publication from the NISRA website.

Parameters:

  • event_type (Literal['registration', 'occurrence', 'both']) – Which event type to retrieve: - “registration”: Births by month registered - “occurrence”: Births by month of birth (occurrence) - “both”: Return dict with both types

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

Returns:

Dict with keys “registration” and “occurrence”. Otherwise: Single DataFrame with columns:

  • month: datetime (first day of month)

  • sex: str (Persons, Male, Female)

  • births: int

Return type:

If event_type is “both”

Raises:

  • NISRADataNotFoundError – If latest publication cannot be found

  • NISRAValidationError – If file structure is unexpected

Example

>>> # Get births by registration date
>>> df = get_latest_births(event_type='registration')
>>> sorted(df.columns.tolist())
['births', 'month', 'sex']

>>> # Get both types
>>> data = get_latest_births(event_type='both')
>>> sorted(data.keys())
['occurrence', 'registration']
bolster.data_sources.nisra.births.validate_births_totals(df)[source]

Validate that Male + Female births equal Persons births for each month.

Parameters:

df (pandas.DataFrame) – DataFrame from parse_births_file or get_latest_births

Returns:

True if validation passes

Raises:

NISRAValidationError – If validation fails

Return type:

bool