bolster.data_sources.nisra.cancer_waiting_times =============================================== .. py:module:: bolster.data_sources.nisra.cancer_waiting_times .. autoapi-nested-parse:: NISRA Cancer Waiting Times 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 by HSC Trust: April 2008 - Present (monthly) - 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, Sarcomas, Skin Cancers, Upper Gastrointestinal Cancer, - Urological Cancer Original data source: https://www.health-ni.gov.uk/articles/cancer-waiting-times Data is fetched from the NISRA PxStat API using the following matrices: - CWT31HSCT: 31-day waiting times by HSC Trust - CWT62HSCT: 62-day waiting times by HSC Trust - CWTBCHSCT: 14-day breast cancer waiting times by HSC Trust - BCREFHSCT: Breast cancer referrals by HSC Trust - CWT31TUMOUR: 31-day waiting times by tumour site - CWT62TUMOUR: 62-day waiting times by tumour site .. rubric:: Example >>> from bolster.data_sources.nisra import cancer_waiting_times as cwt >>> df = cwt.get_latest_31_day_by_trust() >>> sorted(df.columns.tolist()) ['date', 'month', 'over_target', 'performance_rate', 'total', 'trust', 'within_target', 'year'] >>> df_tumour = cwt.get_latest_62_day_by_tumour() >>> 'tumour_site' in df_tumour.columns True Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.cancer_waiting_times.logger Functions --------- .. autoapisummary:: 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_latest_cancer_waiting_times 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:function:: get_latest_31_day_by_trust(force_refresh = False) Get 31-day waiting times by HSC Trust. :param force_refresh: Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching. :returns: date, year, month, trust, within_target, over_target, total, performance_rate. :rtype: DataFrame with columns .. py:function:: get_latest_31_day_by_tumour(force_refresh = False) Get 31-day waiting times by Tumour Site. :param force_refresh: Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching. :returns: date, year, month, tumour_site, within_target, over_target, total, performance_rate. :rtype: DataFrame with columns .. py:function:: get_latest_62_day_by_trust(force_refresh = False) Get 62-day waiting times by HSC Trust. :param force_refresh: Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching. :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:: get_latest_62_day_by_tumour(force_refresh = False) Get 62-day waiting times by Tumour Site. :param force_refresh: Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching. :returns: date, year, month, tumour_site, within_target, over_target, total, performance_rate. :rtype: DataFrame with columns .. py:function:: get_latest_14_day_breast(force_refresh = False) Get 14-day breast cancer waiting times by HSC Trust. :param force_refresh: Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching. :returns: date, year, month, trust, within_target, over_target, total, performance_rate. :rtype: DataFrame with columns .. py:function:: get_latest_breast_referrals(force_refresh = False) Get breast cancer referrals by HSC Trust. :param force_refresh: Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching. :returns: date, year, month, trust, total_referrals, urgent_referrals, urgent_rate. :rtype: DataFrame with columns .. py:function:: get_latest_cancer_waiting_times(target = '31-day', dimension = 'trust', year = None, summary = False, force_refresh = False) Get cancer waiting times data for a given target and dimension. :param target: Waiting time target — '31-day', '62-day', or '14-day'. :param dimension: Breakdown dimension — 'trust' or 'tumour' (tumour not available for 14-day). :param year: Optional year filter. If None all years are returned. :param summary: If True return an annual performance summary aggregated across all groups instead of the full monthly series. :param force_refresh: Accepted for API compatibility but ignored; the PxStat API always returns the latest data without caching. :returns: DataFrame with wait-time performance data. :raises ValueError: If an unsupported target / dimension combination is given. .. 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 or zero totals are excluded from validation checks.