bolster.data_sources.nisra.index_of_services

NISRA Index of Services (IOS) for Northern Ireland.

Provides quarterly index of services sector output, comparing Northern Ireland against the UK average. Base year 2020=100.

Services sectors covered: - Wholesale and retail trade; repair of motor vehicles - Accommodation and food service activities - Information and communication - Financial and insurance activities - Professional, scientific and technical activities - Public administration and defence - Education - Human health and social work activities - Other services

Data Source:

Statistics page: https://www.nisra.gov.uk/statistics/economic-output/index-services The module scrapes this page to find the latest quarterly publication, then downloads the Excel tables file.

Update Frequency: Quarterly (published ~3 months after reference quarter) Geographic Coverage: Northern Ireland and UK comparison Base Year: 2020=100

Example

>>> from bolster.data_sources.nisra import index_of_services as ios
>>> df = ios.get_latest_ios()
>>> 'ni_index' in df.columns
True
>>> growth = ios.get_ios_growth(df)
>>> 'ni_yoy' in growth.columns
True

Attributes

logger

IOS_STATS_URL

IOS_BASE_URL

Functions

get_latest_ios_publication_url()

Scrape the IOS statistics page to find the latest quarterly Excel file.

parse_ios_file(file_path)

Parse IOS Excel tables file into long-format DataFrame.

get_latest_ios([force_refresh])

Get the latest NI Index of Services quarterly series.

validate_ios_data(df)

Validate IOS DataFrame for basic integrity.

get_ios_by_year(df, year)

Filter IOS data to a specific year.

get_ios_by_quarter(df, quarter, year)

Filter IOS data to a specific quarter.

get_ios_summary_statistics(df[, start_year, end_year])

Calculate summary statistics for a period of IOS data.

get_ios_growth(df)

Calculate quarter-on-quarter and year-on-year growth rates.

Module Contents

bolster.data_sources.nisra.index_of_services.logger[source]
bolster.data_sources.nisra.index_of_services.IOS_STATS_URL = 'https://www.nisra.gov.uk/statistics/economic-output/index-services'[source]
bolster.data_sources.nisra.index_of_services.IOS_BASE_URL = 'https://www.nisra.gov.uk'[source]
bolster.data_sources.nisra.index_of_services.get_latest_ios_publication_url()[source]

Scrape the IOS statistics page to find the latest quarterly Excel file.

Returns:

Tuple of (excel_url, year, quarter)

Raises:

NISRADataNotFoundError – If publication cannot be found

Return type:

tuple[str, int, int]

bolster.data_sources.nisra.index_of_services.parse_ios_file(file_path)[source]

Parse IOS Excel tables file into long-format DataFrame.

Reads Table_1_1 which contains the headline NI and UK services index series.

Parameters:

file_path (str | pathlib.Path) – Path to downloaded IOS tables Excel file

Returns:

  • date: Timestamp (first day of quarter)

  • year: int

  • quarter: int (1-4)

  • quarter_label: str (e.g. “Q1 2025”)

  • ni_index: float (NI Index of Services, 2020=100)

  • uk_index: float (UK Index of Services, 2020=100)

Return type:

DataFrame with columns

Raises:

NISRAValidationError – If file structure is unexpected

bolster.data_sources.nisra.index_of_services.get_latest_ios(force_refresh=False)[source]

Get the latest NI Index of Services quarterly series.

Parameters:

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

Returns:

date, year, quarter, quarter_label, ni_index, uk_index (base year 2020=100)

Return type:

DataFrame with columns

Raises:

  • NISRADataNotFoundError – If latest publication cannot be found

  • NISRAValidationError – If file structure is unexpected

Example

>>> df = get_latest_ios()
>>> 'ni_index' in df.columns
True
bolster.data_sources.nisra.index_of_services.validate_ios_data(df)[source]

Validate IOS DataFrame for basic integrity.

Parameters:

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

Returns:

True if validation passes

Raises:

NISRAValidationError – If validation fails

Return type:

bool

bolster.data_sources.nisra.index_of_services.get_ios_by_year(df, year)[source]

Filter IOS data to a specific year.

Parameters:
Returns:

Filtered DataFrame (up to 4 quarters)

Return type:

pandas.DataFrame

Example

>>> df = get_latest_ios()
>>> df_2024 = get_ios_by_year(df, 2024)
>>> len(df_2024) <= 4
True
bolster.data_sources.nisra.index_of_services.get_ios_by_quarter(df, quarter, year)[source]

Filter IOS data to a specific quarter.

Parameters:

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

  • quarter (int) – Quarter number (1-4)

  • year (int) – Year

Returns:

Filtered DataFrame (single row)

Return type:

pandas.DataFrame

Example

>>> df = get_latest_ios()
>>> q1_2024 = get_ios_by_quarter(df, 1, 2024)
>>> len(q1_2024) == 1
True
bolster.data_sources.nisra.index_of_services.get_ios_summary_statistics(df, start_year=None, end_year=None)[source]

Calculate summary statistics for a period of IOS data.

Parameters:

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

  • start_year (int | None) – Optional start year filter (inclusive)

  • end_year (int | None) – Optional end year filter (inclusive)

Returns:

period, ni_mean, ni_min, ni_max, uk_mean, uk_min, uk_max, quarters_count

Return type:

Dictionary with keys

Example

>>> df = get_latest_ios()
>>> stats = get_ios_summary_statistics(df, start_year=2020)
>>> 'ni_mean' in stats
True
bolster.data_sources.nisra.index_of_services.get_ios_growth(df)[source]

Calculate quarter-on-quarter and year-on-year growth rates.

Parameters:

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

Returns:

  • ni_qoq: NI quarter-on-quarter % change

  • ni_yoy: NI year-on-year % change

  • uk_qoq: UK quarter-on-quarter % change

  • uk_yoy: UK year-on-year % change

Return type:

DataFrame with additional columns

Example

>>> df = get_latest_ios()
>>> growth = get_ios_growth(df)
>>> 'ni_yoy' in growth.columns
True