bolster.data_sources.nisra.index_of_services ============================================ .. py:module:: bolster.data_sources.nisra.index_of_services .. autoapi-nested-parse:: 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 .. rubric:: 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 ---------- .. autoapisummary:: bolster.data_sources.nisra.index_of_services.logger bolster.data_sources.nisra.index_of_services.IOS_STATS_URL bolster.data_sources.nisra.index_of_services.IOS_BASE_URL Functions --------- .. autoapisummary:: bolster.data_sources.nisra.index_of_services.get_latest_ios_publication_url bolster.data_sources.nisra.index_of_services.parse_ios_file bolster.data_sources.nisra.index_of_services.get_latest_ios bolster.data_sources.nisra.index_of_services.validate_ios_data bolster.data_sources.nisra.index_of_services.get_ios_by_year bolster.data_sources.nisra.index_of_services.get_ios_by_quarter bolster.data_sources.nisra.index_of_services.get_ios_summary_statistics bolster.data_sources.nisra.index_of_services.get_ios_growth Module Contents --------------- .. py:data:: logger .. py:data:: IOS_STATS_URL :value: 'https://www.nisra.gov.uk/statistics/economic-output/index-services' .. py:data:: IOS_BASE_URL :value: 'https://www.nisra.gov.uk' .. py:function:: get_latest_ios_publication_url() 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 .. py:function:: parse_ios_file(file_path) Parse IOS Excel tables file into long-format DataFrame. Reads Table_1_1 which contains the headline NI and UK services index series. :param file_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) :rtype: DataFrame with columns :raises NISRAValidationError: If file structure is unexpected .. py:function:: get_latest_ios(force_refresh = False) Get the latest NI Index of Services quarterly series. :param force_refresh: If True, bypass cache and download fresh data :returns: date, year, quarter, quarter_label, ni_index, uk_index (base year 2020=100) :rtype: DataFrame with columns :raises NISRADataNotFoundError: If latest publication cannot be found :raises NISRAValidationError: If file structure is unexpected .. rubric:: Example >>> df = get_latest_ios() >>> 'ni_index' in df.columns True .. py:function:: validate_ios_data(df) Validate IOS DataFrame for basic integrity. :param df: DataFrame from get_latest_ios() :returns: True if validation passes :raises NISRAValidationError: If validation fails .. py:function:: get_ios_by_year(df, year) Filter IOS data to a specific year. :param df: DataFrame from get_latest_ios() :param year: Year to filter :returns: Filtered DataFrame (up to 4 quarters) .. rubric:: Example >>> df = get_latest_ios() >>> df_2024 = get_ios_by_year(df, 2024) >>> len(df_2024) <= 4 True .. py:function:: get_ios_by_quarter(df, quarter, year) Filter IOS data to a specific quarter. :param df: DataFrame from get_latest_ios() :param quarter: Quarter number (1-4) :param year: Year :returns: Filtered DataFrame (single row) .. rubric:: Example >>> df = get_latest_ios() >>> q1_2024 = get_ios_by_quarter(df, 1, 2024) >>> len(q1_2024) == 1 True .. py:function:: get_ios_summary_statistics(df, start_year = None, end_year = None) Calculate summary statistics for a period of IOS data. :param df: DataFrame from get_latest_ios() :param start_year: Optional start year filter (inclusive) :param end_year: Optional end year filter (inclusive) :returns: period, ni_mean, ni_min, ni_max, uk_mean, uk_min, uk_max, quarters_count :rtype: Dictionary with keys .. rubric:: Example >>> df = get_latest_ios() >>> stats = get_ios_summary_statistics(df, start_year=2020) >>> 'ni_mean' in stats True .. py:function:: get_ios_growth(df) Calculate quarter-on-quarter and year-on-year growth rates. :param df: 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 :rtype: DataFrame with additional columns .. rubric:: Example >>> df = get_latest_ios() >>> growth = get_ios_growth(df) >>> 'ni_yoy' in growth.columns True