bolster.data_sources.nisra.composite_index ========================================== .. py:module:: bolster.data_sources.nisra.composite_index .. autoapi-nested-parse:: NISRA Northern Ireland Composite Economic Index Module. This module provides access to the Northern Ireland Composite Economic Index (NICEI), an experimental quarterly measure of economic performance based on official statistics. The NICEI tracks five key sectors of the NI economy: - Services - Production (manufacturing and mining) - Construction - Agriculture - Public Sector Data Source: Northern Ireland Statistics and Research Agency provides the Northern Ireland Composite Economic Index through their Economic Output statistics at https://www.nisra.gov.uk/statistics. The NICEI is an experimental quarterly indicator that combines official statistics across five key economic sectors to provide an overall measure of economic performance for Northern Ireland. Update Frequency: Quarterly publications are released approximately 3 months after the end of each quarter. The NICEI data is published as part of NISRA's Economic Output statistics series by the Economic & Labour Market Statistics Branch, with data updated four times per year. Data Coverage: - Quarterly time series from Q1 2006 to present - Indices and sector contributions to quarterly change - Private and public sector breakdowns - Base period: 2022=100 .. rubric:: Examples >>> from bolster.data_sources.nisra import composite_index >>> nicei_df = composite_index.get_latest_nicei() >>> 'nicei' in nicei_df.columns True >>> contrib_df = composite_index.get_latest_nicei_contributions() >>> 'services_contribution' in contrib_df.columns True >>> nicei_2024 = composite_index.get_nicei_by_year(nicei_df, 2024) >>> len(nicei_2024) <= 4 True Publication Details: - Frequency: Quarterly (published ~3 months after quarter end) - Published by: NISRA Economic & Labour Market Statistics Branch - Contact: economicstats@nisra.gov.uk - Mother page: https://www.nisra.gov.uk/statistics/economic-output/ni-composite-economic-index - Note: NICEI is an experimental statistic subject to revision Author: Claude Code Date: 2025-12-22 Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.composite_index.logger bolster.data_sources.nisra.composite_index.NICEI_BASE_URL bolster.data_sources.nisra.composite_index.NICEI_STATS_URL Functions --------- .. autoapisummary:: bolster.data_sources.nisra.composite_index.get_latest_nicei_publication_url bolster.data_sources.nisra.composite_index.parse_nicei_indices bolster.data_sources.nisra.composite_index.parse_nicei_contributions bolster.data_sources.nisra.composite_index.get_latest_nicei bolster.data_sources.nisra.composite_index.get_latest_nicei_contributions bolster.data_sources.nisra.composite_index.get_nicei_by_year bolster.data_sources.nisra.composite_index.get_nicei_by_quarter bolster.data_sources.nisra.composite_index.validate_composite_index_data Module Contents --------------- .. py:data:: logger .. py:data:: NICEI_BASE_URL :value: 'https://www.nisra.gov.uk' .. py:data:: NICEI_STATS_URL :value: 'https://www.nisra.gov.uk/statistics/economic-output/ni-composite-economic-index' .. py:function:: get_latest_nicei_publication_url() Get the URL of the latest NICEI publication. Scrapes the NISRA NICEI statistics page to find the most recent quarterly publication. :returns: Tuple of (excel_url, year, quarter_str) :raises NISRADataNotFoundError: If unable to find the latest publication .. rubric:: Example >>> url, year, quarter = get_latest_nicei_publication_url() >>> url.startswith('https://') True .. py:function:: parse_nicei_indices(file_path) Parse NICEI Table 1: Index values by quarter. Extracts the main NICEI time series including overall index and sectoral breakdowns. :param file_path: Path to the NICEI Excel file :returns: - year: int - quarter: int (1-4) - nicei: float (composite economic index) - private_sector: float - public_sector: float - services: float - production: float - construction: float - agriculture: float :rtype: DataFrame with columns .. rubric:: Example >>> url, _, _ = get_latest_nicei_publication_url() >>> path = download_file(url, cache_ttl_hours=90*24) >>> df = parse_nicei_indices(path) >>> 'nicei' in df.columns True .. py:function:: parse_nicei_contributions(file_path) Parse NICEI Table 11: Sector contributions to quarterly change. Extracts how much each sector contributed to the quarterly change in NICEI. :param file_path: Path to the NICEI Excel file :returns: - year: int - quarter: int (1-4) - nicei: float (index value) - nicei_quarterly_change: float (percentage point change from previous quarter) - public_sector_contribution: float - services_contribution: float - production_contribution: float - construction_contribution: float - agriculture_contribution: float :rtype: DataFrame with columns .. rubric:: Example >>> url, _, _ = get_latest_nicei_publication_url() >>> path = download_file(url, cache_ttl_hours=90*24) >>> df = parse_nicei_contributions(path) >>> 'nicei' in df.columns True .. py:function:: get_latest_nicei(force_refresh = False) Get the latest NICEI index data. Downloads and parses the most recent NICEI publication. Results are cached for 90 days unless force_refresh=True. :param force_refresh: If True, bypass cache and download fresh data :returns: DataFrame with quarterly NICEI index values and sectoral breakdowns .. rubric:: Example >>> df = get_latest_nicei() >>> 'nicei' in df.columns True .. py:function:: get_latest_nicei_contributions(force_refresh = False) Get the latest NICEI sector contribution data. Downloads and parses sector contributions to quarterly change from the most recent NICEI publication. Results are cached for 90 days unless force_refresh=True. :param force_refresh: If True, bypass cache and download fresh data :returns: DataFrame with quarterly sector contributions to NICEI change .. rubric:: Example >>> df = get_latest_nicei_contributions() >>> 'services_contribution' in df.columns True .. py:function:: get_nicei_by_year(df, year) Filter NICEI data for a specific year. :param df: DataFrame from get_latest_nicei() or parse_nicei_indices() :param year: Year to filter for :returns: Filtered DataFrame containing only the specified year .. rubric:: Example >>> df = get_latest_nicei() >>> df_2024 = get_nicei_by_year(df, 2024) >>> len(df_2024) <= 4 True .. py:function:: get_nicei_by_quarter(df, year, quarter) Filter NICEI data for a specific quarter. :param df: DataFrame from get_latest_nicei() or parse_nicei_indices() :param year: Year to filter for :param quarter: Quarter (1-4) to filter for :returns: Filtered DataFrame containing only the specified quarter (usually 1 row) .. rubric:: Example >>> df = get_latest_nicei() >>> q2_2024 = get_nicei_by_quarter(df, 2024, 2) >>> len(q2_2024) <= 1 True .. py:function:: validate_composite_index_data(df) Validate composite index data integrity. :param df: DataFrame from composite index functions :returns: True if validation passes, False otherwise