bolster.data_sources.nisra.quarterly_employment_survey ====================================================== .. py:module:: bolster.data_sources.nisra.quarterly_employment_survey .. autoapi-nested-parse:: NISRA Quarterly Employment Survey (QES) for Northern Ireland. Provides quarterly employee job estimates for Northern Ireland by broad industry sector, both seasonally adjusted and unadjusted. The QES is used by the ONS as the primary source for NI estimates within UK-wide quarterly workforce statistics. Sectors covered: - Manufacturing - Construction - Services - Other Industries - All Industries (total) Data Source: **Statistics page**: https://www.nisra.gov.uk/statistics/work-pay-and-benefits/quarterly-employment-survey The module scrapes this page to find the latest quarterly supplementary tables, then downloads the Excel file. Update Frequency: Quarterly (published ~2 weeks after reference quarter) Geographic Coverage: Northern Ireland Time Series: Q1 2005 to present (seasonally adjusted); Q1 2005 unadjusted .. rubric:: Example >>> from bolster.data_sources.nisra import quarterly_employment_survey as qes >>> df = qes.get_latest_qes() >>> 'total_jobs' in df.columns True >>> growth = qes.get_qes_growth(df) >>> 'total_yoy' in growth.columns True Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.quarterly_employment_survey.logger bolster.data_sources.nisra.quarterly_employment_survey.QES_STATS_URL bolster.data_sources.nisra.quarterly_employment_survey.QES_BASE_URL Functions --------- .. autoapisummary:: bolster.data_sources.nisra.quarterly_employment_survey.get_latest_qes_publication_url bolster.data_sources.nisra.quarterly_employment_survey.parse_qes_file bolster.data_sources.nisra.quarterly_employment_survey.get_latest_qes bolster.data_sources.nisra.quarterly_employment_survey.validate_qes_data bolster.data_sources.nisra.quarterly_employment_survey.get_qes_by_year bolster.data_sources.nisra.quarterly_employment_survey.get_qes_growth bolster.data_sources.nisra.quarterly_employment_survey.get_sector_shares Module Contents --------------- .. py:data:: logger .. py:data:: QES_STATS_URL :value: 'https://www.nisra.gov.uk/statistics/work-pay-and-benefits/quarterly-employment-survey' .. py:data:: QES_BASE_URL :value: 'https://www.nisra.gov.uk' .. py:function:: get_latest_qes_publication_url() Scrape the QES statistics page to find the latest supplementary tables Excel. :returns: URL of the latest QES supplementary tables Excel file :raises NISRADataNotFoundError: If publication cannot be found .. py:function:: parse_qes_file(file_path, adjusted = True) Parse QES supplementary tables Excel file into long-format DataFrame. Reads Table 5.2 (seasonally adjusted) or Table 5.3 (unadjusted), which contain quarterly employee job counts by broad industry sector. :param file_path: Path to downloaded QES supplementary tables Excel file :param adjusted: If True, read Table 5.2 (seasonally adjusted). If False, read Table 5.3 (unadjusted). :returns: - date: Timestamp (first day of quarter) - year: int - quarter: int (1-4) - quarter_label: str (e.g. "Q1 2025") - manufacturing_jobs: int - construction_jobs: int - services_jobs: int - other_jobs: int - total_jobs: int - adjusted: bool (True if seasonally adjusted) :rtype: DataFrame with columns :raises NISRAValidationError: If file structure is unexpected .. py:function:: get_latest_qes(force_refresh = False, adjusted = True) Get the latest NI Quarterly Employment Survey data. :param force_refresh: If True, bypass cache and download fresh data :param adjusted: If True (default), return seasonally adjusted series (Table 5.2). If False, return unadjusted series (Table 5.3). :returns: date, year, quarter, quarter_label, manufacturing_jobs, construction_jobs, services_jobs, other_jobs, total_jobs, adjusted :rtype: DataFrame with columns :raises NISRADataNotFoundError: If latest publication cannot be found :raises NISRAValidationError: If file structure is unexpected .. rubric:: Example >>> df = get_latest_qes() >>> 'total_jobs' in df.columns True .. py:function:: validate_qes_data(df) Validate QES DataFrame for basic integrity. :param df: DataFrame from get_latest_qes() :returns: True if validation passes :raises NISRAValidationError: If validation fails .. py:function:: get_qes_by_year(df, year) Filter QES data to a specific year. :param df: DataFrame from get_latest_qes() :param year: Year to filter :returns: Filtered DataFrame (up to 4 quarters) .. rubric:: Example >>> df = get_latest_qes() >>> df_2024 = get_qes_by_year(df, 2024) >>> len(df_2024) <= 4 True .. py:function:: get_qes_growth(df) Calculate quarter-on-quarter and year-on-year growth for total employee jobs. :param df: DataFrame from get_latest_qes() :returns: - total_qoq: Total jobs quarter-on-quarter change (absolute) - total_yoy: Total jobs year-on-year % change - services_yoy: Services jobs year-on-year % change - manufacturing_yoy: Manufacturing jobs year-on-year % change :rtype: DataFrame with additional columns .. rubric:: Example >>> df = get_latest_qes() >>> growth = get_qes_growth(df) >>> 'total_yoy' in growth.columns True .. py:function:: get_sector_shares(df) Calculate each sector's share of total employee jobs. :param df: DataFrame from get_latest_qes() :returns: - manufacturing_share: Manufacturing % of total - construction_share: Construction % of total - services_share: Services % of total - other_share: Other industries % of total :rtype: DataFrame with additional columns .. rubric:: Example >>> df = get_latest_qes() >>> shares = get_sector_shares(df) >>> 'services_share' in shares.columns True