bolster.data_sources.nisra.elective_waiting_times ================================================= .. py:module:: bolster.data_sources.nisra.elective_waiting_times .. autoapi-nested-parse:: NISRA Elective/Outpatient Waiting Times Module. Provides access to Northern Ireland's elective and outpatient waiting times statistics, covering inpatient/day case and outpatient referrals waiting by weeks-waited band, specialty, and HSC Trust. Data is published quarterly by the Department of Health NI and covers two separate series: - **Inpatient/Day Case Waiting Times** — patients waiting by management type (Day Case or Inpatient), weeks-waited band, specialty, and HSC Trust. Data from Q1 2007-08 (quarter ending June 2007) to present. - **Outpatient Waiting Times** — referrals waiting by weeks-waited band, specialty, and HSC Trust. Data from Q1 2008-09 (quarter ending June 2008) to present. Both series contain two sheets reflecting a system change: - **Pre-encompass**: Legacy PAS data up to March 2025 (inpatient) / March 2025 (outpatient). Inpatient pre-encompass includes additional derived aggregate columns (e.g. "> 26 weeks") that are excluded from the long-format output. - **encompass**: Data from the new electronic patient record system, starting from South Eastern Trust in December 2023. Not directly comparable with pre-encompass data due to the system transition. Waiting Bands (Inpatient/Day Case — weeks): 0 - 6, >6 - 13, >13 - 21, >21 - 26, >26 - 52, >52 - 65, >65 - 78, >78 - 91, >91 - 104, >104 Waiting Bands (Outpatient — weeks): 0 - 6, >6 - 9, >9 - 13 / >9 - 12*, >12 - 15, >15 - 18, >18 - 26, >26 - 39, >39 - 52, >52 - 65, >65 - 78, >78 - 91, >91 - 104, >104 (*The >9-13 / >9-12 split is a historical artefact; both columns appear but only one is populated per row.) HSC Trusts: Belfast, Northern, South Eastern, Southern, Western (DPC = Domiciliary/Primary Care, included in source data but typically excluded from trust-level analyses) Data Sources: - Inpatient/Day Case: https://www.health-ni.gov.uk/articles/inpatient-waiting-times - Outpatient: https://www.health-ni.gov.uk/articles/outpatient-waiting-times Update Frequency: Quarterly, published approximately 3-6 months after the quarter end. .. rubric:: Example >>> from bolster.data_sources.nisra import elective_waiting_times as ewt >>> df = ewt.get_latest_elective_waiting_times() >>> sorted(df.columns.tolist()) ['date', 'patients_waiting', 'programme_of_care', 'quarter_ending', 'specialty', 'trust', 'waiting_type', 'weeks_waited_band', 'year'] >>> ewt.validate_elective_waiting_times(df) True Publication Details: - Frequency: Quarterly (published ~3-6 months after quarter end) - Published by: Department of Health NI - Sources: https://www.health-ni.gov.uk/articles/inpatient-waiting-times https://www.health-ni.gov.uk/articles/outpatient-waiting-times Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.elective_waiting_times.logger bolster.data_sources.nisra.elective_waiting_times.DOH_BASE_URL bolster.data_sources.nisra.elective_waiting_times.DOH_INPATIENT_PAGE bolster.data_sources.nisra.elective_waiting_times.DOH_OUTPATIENT_PAGE bolster.data_sources.nisra.elective_waiting_times.SHEET_PRE_ENCOMPASS bolster.data_sources.nisra.elective_waiting_times.SHEET_ENCOMPASS bolster.data_sources.nisra.elective_waiting_times.EXPECTED_TRUSTS bolster.data_sources.nisra.elective_waiting_times.IP_ID_COLS bolster.data_sources.nisra.elective_waiting_times.IP_BAND_COLS bolster.data_sources.nisra.elective_waiting_times.OP_ID_COLS bolster.data_sources.nisra.elective_waiting_times.OP_BAND_COLS bolster.data_sources.nisra.elective_waiting_times.REQUIRED_COLUMNS Functions --------- .. autoapisummary:: bolster.data_sources.nisra.elective_waiting_times.get_elective_waiting_times_url bolster.data_sources.nisra.elective_waiting_times.parse_elective_waiting_times_file bolster.data_sources.nisra.elective_waiting_times.get_latest_elective_waiting_times bolster.data_sources.nisra.elective_waiting_times.validate_elective_waiting_times Module Contents --------------- .. py:data:: logger .. py:data:: DOH_BASE_URL :value: 'https://www.health-ni.gov.uk' .. py:data:: DOH_INPATIENT_PAGE :value: 'https://www.health-ni.gov.uk/articles/inpatient-waiting-times' .. py:data:: DOH_OUTPATIENT_PAGE :value: 'https://www.health-ni.gov.uk/articles/outpatient-waiting-times' .. py:data:: SHEET_PRE_ENCOMPASS :value: 'Pre-encompass' .. py:data:: SHEET_ENCOMPASS :value: 'encompass' .. py:data:: EXPECTED_TRUSTS .. py:data:: IP_ID_COLS :value: ['Management', 'Quarter Ending', 'HSC Trust', 'Specialty', 'Programme Of Care'] .. py:data:: IP_BAND_COLS :value: ['0 - 6 weeks', '> 6 - 13 weeks', '> 13 - 21 weeks', '> 21 - 26 weeks', '> 26-52 weeks', '> 52 -... .. py:data:: OP_ID_COLS :value: ['Quarter Ending', 'HSC Trust', 'Specialty', 'Programme of Care'] .. py:data:: OP_BAND_COLS :value: ['0 - 6 Wks', '>6 - 9 Wks', '>9 - 13 Wks', '>9 - 12 Wks', '>12 - 15 Wks', '>15 - 18 Wks', '>18 -... .. py:data:: REQUIRED_COLUMNS .. py:function:: get_elective_waiting_times_url() Scrape the Department of Health pages to find the latest Excel file URLs. :returns: Dictionary with keys ``"inpatient"`` and ``"outpatient"``, each mapping to the absolute URL of the most recent quarterly Excel file. :raises NISRADataNotFoundError: If either URL cannot be located. .. py:function:: parse_elective_waiting_times_file(file_path) Parse a combined elective waiting times Excel file (inpatient or outpatient). Reads both ``Pre-encompass`` and ``encompass`` sheets from the file, melts the weekly waiting-band columns into long format, and returns a unified DataFrame. The parser auto-detects the file type (inpatient vs outpatient) by checking whether a ``Management`` column (present only in inpatient files) exists in the first data sheet. :param file_path: Path to an Excel file downloaded from the Department of Health inpatient or outpatient waiting times publication pages. :returns: - ``date`` (datetime): Quarter-end date (e.g. 2025-12-31) - ``year`` (int): Calendar year of the quarter end - ``quarter_ending`` (datetime): Same as ``date`` - ``trust`` (str): HSC Trust name - ``specialty`` (str): Medical specialty - ``programme_of_care`` (str): Programme of care grouping - ``weeks_waited_band`` (str): Waiting band label (e.g. "0 - 6 weeks") - ``patients_waiting`` (float): Number of patients/referrals in that band - ``waiting_type`` (str): ``"inpatient_day_case"`` or ``"outpatient"`` For inpatient files, ``management`` (``"Day Case"`` or ``"Inpatient"``) is also present. :rtype: Long-format DataFrame with columns :raises NISRAValidationError: If neither expected sheet is found in the file. .. py:function:: get_latest_elective_waiting_times(force_refresh = False) Download and return the latest elective waiting times data (both series). Fetches the most recent quarterly publication for both the inpatient/day case and outpatient series, parses each into long format, and returns a combined DataFrame. :param force_refresh: If ``True``, bypass the on-disk cache and re-download the Excel files. :returns: Combined long-format DataFrame covering both inpatient/day case and outpatient waiting times. See :func:`parse_elective_waiting_times_file` for the column schema. :raises NISRADataNotFoundError: If either publication page or Excel file cannot be located. :raises NISRAValidationError: If the downloaded data fails schema validation. .. py:function:: validate_elective_waiting_times(df) Validate that an elective waiting times DataFrame meets quality requirements. Checks that the DataFrame is non-empty, contains all required columns, and has no negative patient counts. :param df: DataFrame as returned by :func:`get_latest_elective_waiting_times` or :func:`parse_elective_waiting_times_file`. :returns: ``True`` if all checks pass. :raises NISRAValidationError: If the DataFrame is empty, missing required columns, or contains negative ``patients_waiting`` values.