bolster.data_sources.nisra.population_projections

NISRA Population Projections for Northern Ireland.

Provides access to official NISRA population projections with demographic breakdowns by year, age, sex, and projection variant.

NI-level projections (2024-based, 2024-2074) are served via the PxStat API. LGD sub-area projections are not yet available via PxStat and remain Excel-based.

Data Source:

PxStat API (NI-level, used by this module):

https://ws-data.nisra.gov.uk/public/api.restful/PxStat.Data.Cube_API.ReadDataset/{MATRIX}/CSV/1.0/en

Matrix codes:

• PPMY02T01: NI projections by single year of age (0-90+) and sex — principal + variants

• PPMY02T02: NI projections by 5-year age bands and sex — principal only

• PPMY02T03: Variant projections (high/low fertility, life expectancy, migration)

Original publication pages (for reference and LGD projections):

• Principal: https://www.nisra.gov.uk/publications/2024-based-population-projections-northern-ireland

• Variants: https://www.nisra.gov.uk/publications/2024-based-population-projections-northern-ireland-variant-projections

• LGD sub-areas: https://www.nisra.gov.uk/publications/2022-based-population-projections-areas-within-northern-ireland

Update Frequency: Biennial (NI-level) Geographic Coverage: Northern Ireland overall (LGD projections not yet in PxStat) Projection Horizon: 2024-2074 (NI-level via API)

Example

>>> from bolster.data_sources.nisra import population_projections
>>> df = population_projections.get_latest_projections()
>>> 'population' in df.columns
True
>>> df_decade = population_projections.get_latest_projections(
...     start_year=2025,
...     end_year=2035
... )
>>> len(df_decade) > 0
True

Attributes

logger

Functions

get_latest_projections([start_year, end_year, ...])	Retrieve NI population projections (principal projection).
get_variant_projections([variant, start_year, ...])	Retrieve NI population projections including variant scenarios.
validate_projections(df)	Validate a projections DataFrame for basic integrity.

Module Contents

bolster.data_sources.nisra.population_projections.logger

bolster.data_sources.nisra.population_projections.get_latest_projections(start_year=None, end_year=None, age_groups='5yr', force_refresh=False)

Retrieve NI population projections (principal projection).

Parameters:

• start_year (int | None) – First projection year to include (default: first available).

• end_year (int | None) – Last projection year to include (default: last available).

• age_groups (str) – Age breakdown format: - '5yr': 5-year age bands (default) — smaller result set - 'single': Single year of age (0-90+) — larger result set

• force_refresh (bool) – Ignored — kept for API compatibility. The PxStat API always returns current data.

Returns:

year, age_group, sex, population, base_year

Return type:

DataFrame with columns

Raises:

• NISRAValidationError – If the API returns empty or invalid data.

• PxStatError – If the API request fails.

Example

>>> df = get_latest_projections()
>>> 'population' in df.columns
True

bolster.data_sources.nisra.population_projections.get_variant_projections(variant=None, start_year=None, end_year=None, force_refresh=False)

Retrieve NI population projections including variant scenarios.

Parameters:

• variant (str | None) – Filter to a specific variant label (partial match, case-insensitive). E.g. 'high fertility', 'low fertility', 'high life expectancy'. If None, all variants are returned.

• start_year (int | None) – First projection year to include.

• end_year (int | None) – Last projection year to include.

• force_refresh (bool) – Ignored — kept for API compatibility.

Returns:

year, age_group, sex, variant, population

Return type:

DataFrame with columns

bolster.data_sources.nisra.population_projections.validate_projections(df)

Validate a projections DataFrame for basic integrity.

Parameters:

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

Returns:

True if valid.

Raises:

NISRAValidationError – If validation fails.

Return type:

bool