bolster.data_sources.nisra.cancer_waiting_times =============================================== .. py:module:: bolster.data_sources.nisra.cancer_waiting_times .. autoapi-nested-parse:: NISRA Cancer Waiting Times Module. This module provides access to Northern Ireland's cancer waiting times statistics, measuring performance against key cancer treatment targets. Cancer Waiting Time Targets: - 14-day: Urgent breast cancer referrals seen within 14 days - 31-day: Treatment started within 31 days of decision to treat - 62-day: Treatment started within 62 days of urgent GP referral Data Coverage: - 31-day and 62-day by HSC Trust: April 2008 - Present (monthly) - 31-day and 62-day by Tumour Site: December 2008 - Present (monthly) - 14-day Breast (Historic by Trust): April 2008 - April 2025 - 14-day Breast (Regional): May 2025 - Present (new regional service) - Breast Cancer Referrals: April 2016 - Present (monthly) HSC Trusts: - Belfast, Northern, South Eastern, Southern, Western Tumour Sites: - Brain/Central Nervous System, Breast Cancer, Gynaecological Cancers, - Haematological Cancers, Head/Neck Cancer, Lower Gastrointestinal Cancer, - Lung Cancer, Other, Skin Cancers, Upper Gastrointestinal Cancer, - Urological Cancer Data Source: Department of Health Northern Ireland provides cancer waiting times statistics through their health publications at https://www.health-ni.gov.uk/articles/cancer-waiting-times. The data tracks performance against cancer treatment targets across Health and Social Care Trusts and by tumour site, providing comprehensive monitoring of cancer care pathways in Northern Ireland. Update Frequency: Quarterly publications are released approximately 3 months after the end of each quarter. Cancer waiting times statistics are published by the Department of Health as part of their healthcare performance monitoring, with data updated four times per year to track progress against key cancer treatment targets. .. rubric:: Example >>> from bolster.data_sources.nisra import cancer_waiting_times as cwt >>> # Get latest 31-day waiting times by HSC Trust >>> df = cwt.get_latest_31_day_by_trust() >>> sorted(df.columns.tolist()) ['date', 'month', 'over_target', 'performance_rate', 'total', 'trust', 'within_target', 'year'] >>> # Get 62-day waiting times by tumour site >>> df_tumour = cwt.get_latest_62_day_by_tumour() >>> 'tumour_site' in df_tumour.columns True Publication Details: - Frequency: Quarterly (published ~3 months after quarter end) - Published by: Department of Health / NISRA - Source: https://www.health-ni.gov.uk/articles/cancer-waiting-times Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.cancer_waiting_times.logger bolster.data_sources.nisra.cancer_waiting_times.DOH_CANCER_PAGE bolster.data_sources.nisra.cancer_waiting_times.DOH_BASE_URL bolster.data_sources.nisra.cancer_waiting_times.SHEET_31_DAY_TRUST bolster.data_sources.nisra.cancer_waiting_times.SHEET_31_DAY_TUMOUR bolster.data_sources.nisra.cancer_waiting_times.SHEET_62_DAY_TRUST bolster.data_sources.nisra.cancer_waiting_times.SHEET_62_DAY_TUMOUR bolster.data_sources.nisra.cancer_waiting_times.SHEET_14_DAY_REGIONAL bolster.data_sources.nisra.cancer_waiting_times.SHEET_14_DAY_HISTORIC bolster.data_sources.nisra.cancer_waiting_times.SHEET_14_DAY_LEGACY bolster.data_sources.nisra.cancer_waiting_times.SHEET_BREAST_REFERRALS Functions --------- .. autoapisummary:: bolster.data_sources.nisra.cancer_waiting_times.get_latest_publication_url bolster.data_sources.nisra.cancer_waiting_times.parse_31_day_by_trust bolster.data_sources.nisra.cancer_waiting_times.parse_31_day_by_tumour bolster.data_sources.nisra.cancer_waiting_times.parse_62_day_by_trust bolster.data_sources.nisra.cancer_waiting_times.parse_62_day_by_tumour bolster.data_sources.nisra.cancer_waiting_times.parse_14_day_breast bolster.data_sources.nisra.cancer_waiting_times.parse_breast_referrals bolster.data_sources.nisra.cancer_waiting_times.get_latest_31_day_by_trust bolster.data_sources.nisra.cancer_waiting_times.get_latest_31_day_by_tumour bolster.data_sources.nisra.cancer_waiting_times.get_latest_62_day_by_trust bolster.data_sources.nisra.cancer_waiting_times.get_latest_62_day_by_tumour bolster.data_sources.nisra.cancer_waiting_times.get_latest_14_day_breast bolster.data_sources.nisra.cancer_waiting_times.get_latest_breast_referrals bolster.data_sources.nisra.cancer_waiting_times.get_data_by_year bolster.data_sources.nisra.cancer_waiting_times.get_performance_summary_by_year bolster.data_sources.nisra.cancer_waiting_times.get_ni_wide_performance bolster.data_sources.nisra.cancer_waiting_times.get_performance_trend bolster.data_sources.nisra.cancer_waiting_times.get_tumour_site_ranking bolster.data_sources.nisra.cancer_waiting_times.validate_performance_data Module Contents --------------- .. py:data:: logger .. py:data:: DOH_CANCER_PAGE :value: 'https://www.health-ni.gov.uk/articles/cancer-waiting-times' .. py:data:: DOH_BASE_URL :value: 'https://www.health-ni.gov.uk' .. py:data:: SHEET_31_DAY_TRUST :value: '31 Day Wait by HSC Trust' .. py:data:: SHEET_31_DAY_TUMOUR :value: '31 Day Wait by Tumour Site' .. py:data:: SHEET_62_DAY_TRUST :value: '62 Day Wait by HSC Trust' .. py:data:: SHEET_62_DAY_TUMOUR :value: '62 Day Wait by Tumour Site' .. py:data:: SHEET_14_DAY_REGIONAL :value: '14 d Wait - Breast Regional' .. py:data:: SHEET_14_DAY_HISTORIC :value: '14 d Wait - Breast Historic' .. py:data:: SHEET_14_DAY_LEGACY :value: '14 Day Wait - Breast Cancer' .. py:data:: SHEET_BREAST_REFERRALS :value: 'Breast Cancer Referrals' .. py:function:: get_latest_publication_url() Find the latest cancer waiting times publication URL. Scrapes the Department of Health cancer waiting times page to find the most recent quarterly publication. :returns: Tuple of (excel_file_url, quarter_string) :raises NISRADataNotFoundError: If publication cannot be found .. py:function:: parse_31_day_by_trust(file_path) Parse 31-day waiting times by HSC Trust. Handles both the 5-column format (pre-Q3 2025-26) and the 7-column format (Q3 2025-26+, which added Median and 95th Percentile columns). :param file_path: Path to the Excel file :returns: date, year, month, trust, within_target, over_target, total, performance_rate :rtype: DataFrame with columns .. py:function:: parse_31_day_by_tumour(file_path) Parse 31-day waiting times by Tumour Site. Handles both the 5-column format (pre-Q3 2025-26) and the 7-column format (Q3 2025-26+, which added Median and 95th Percentile columns). :param file_path: Path to the Excel file :returns: date, year, month, tumour_site, within_target, over_target, total, performance_rate :rtype: DataFrame with columns .. py:function:: parse_62_day_by_trust(file_path) Parse 62-day waiting times by HSC Trust. Handles both the 5-column format (pre-Q3 2025-26) and the 7-column format (Q3 2025-26+, which added Median and 95th Percentile columns). :param file_path: Path to the Excel file :returns: date, year, month, trust, within_target, over_target, total, performance_rate :rtype: DataFrame with columns .. note:: 62-day data may contain fractional patient counts due to shared care arrangements between trusts. .. py:function:: parse_62_day_by_tumour(file_path) Parse 62-day waiting times by Tumour Site. Handles both the 5-column format (pre-Q3 2025-26) and the 7-column format (Q3 2025-26+, which added Median and 95th Percentile columns). :param file_path: Path to the Excel file :returns: date, year, month, tumour_site, within_target, over_target, total, performance_rate :rtype: DataFrame with columns .. py:function:: parse_14_day_breast(file_path) Parse 14-day breast cancer waiting times. Handles three publication formats: - Pre-Q4 2024-25: single sheet 'SHEET_14_DAY_LEGACY' (5 cols) - Q4 2024-25 to Q2 2025-26: split into historic (5 cols) + regional (5 cols) - Q3 2025-26+: split into historic (5 cols) + regional (7 cols, + median/95th pct) :param file_path: Path to the Excel file :returns: date, year, month, trust, within_target, over_target, total, performance_rate :rtype: DataFrame with columns .. note:: From May 2025, breast cancer services became regional. Historic data (pre-May 2025) is by individual Trust. Regional data shows NI-wide figures. .. py:function:: parse_breast_referrals(file_path) Parse breast cancer referrals data. Handles two formats: - Pre-Q3 2025-26: 4 columns (referral_month, trust, total_referrals, urgent_referrals) - Q3 2025-26+: 5 columns (referral_month, trust, routine_referrals, urgent_referrals, total_referrals) :param file_path: Path to the Excel file :returns: date, year, month, trust, total_referrals, urgent_referrals, urgent_rate :rtype: DataFrame with columns .. py:function:: get_latest_31_day_by_trust(force_refresh = False) Get latest 31-day waiting times by HSC Trust. :param force_refresh: Force re-download even if cached :returns: DataFrame with 31-day performance by Trust .. py:function:: get_latest_31_day_by_tumour(force_refresh = False) Get latest 31-day waiting times by Tumour Site. :param force_refresh: Force re-download even if cached :returns: DataFrame with 31-day performance by tumour site .. py:function:: get_latest_62_day_by_trust(force_refresh = False) Get latest 62-day waiting times by HSC Trust. :param force_refresh: Force re-download even if cached :returns: DataFrame with 62-day performance by Trust .. py:function:: get_latest_62_day_by_tumour(force_refresh = False) Get latest 62-day waiting times by Tumour Site. :param force_refresh: Force re-download even if cached :returns: DataFrame with 62-day performance by tumour site .. py:function:: get_latest_14_day_breast(force_refresh = False) Get latest 14-day breast cancer waiting times. :param force_refresh: Force re-download even if cached :returns: DataFrame with 14-day breast cancer performance .. py:function:: get_latest_breast_referrals(force_refresh = False) Get latest breast cancer referrals data. :param force_refresh: Force re-download even if cached :returns: DataFrame with breast cancer referrals .. py:function:: get_data_by_year(df, year) Filter data for a specific year. :param df: DataFrame with 'year' column :param year: Year to filter for :returns: Filtered DataFrame .. py:function:: get_performance_summary_by_year(df, group_col = 'trust') Calculate annual performance summary. :param df: DataFrame with performance data :param group_col: Column to group by ('trust' or 'tumour_site') :returns: DataFrame with annual summary statistics .. py:function:: get_ni_wide_performance(df) Calculate NI-wide performance (aggregated across all trusts/sites). :param df: DataFrame with performance data :returns: DataFrame with NI-wide monthly performance .. py:function:: get_performance_trend(df, window = 12) Calculate rolling performance trend. :param df: DataFrame with NI-wide performance data :param window: Rolling window size in months (default: 12) :returns: DataFrame with rolling average performance .. py:function:: get_tumour_site_ranking(df, year = None) Rank tumour sites by performance. :param df: DataFrame with tumour site data :param year: Optional year to filter (default: all years) :returns: DataFrame ranked by performance (worst to best) .. py:function:: validate_performance_data(df) Validate that performance data is internally consistent. :param df: DataFrame with performance columns :returns: True if validation passes :raises ValueError: If validation fails .. note:: Rows with NaN values (e.g., due to encompass system rollout) or zero totals are excluded from validation checks.