bolster.data_sources.nisra.cancer_waiting_times

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

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

logger

Functions

`get_latest_31_day_by_trust`([force_refresh])	Get 31-day waiting times by HSC Trust.
`get_latest_31_day_by_tumour`([force_refresh])	Get 31-day waiting times by Tumour Site.
`get_latest_62_day_by_trust`([force_refresh])	Get 62-day waiting times by HSC Trust.
`get_latest_62_day_by_tumour`([force_refresh])	Get 62-day waiting times by Tumour Site.
`get_latest_14_day_breast`([force_refresh])	Get 14-day breast cancer waiting times by HSC Trust.
`get_latest_breast_referrals`([force_refresh])	Get breast cancer referrals by HSC Trust.
`get_latest_cancer_waiting_times`([target, dimension, ...])	Get cancer waiting times data for a given target and dimension.
`get_data_by_year`(df, year)	Filter data for a specific year.
`get_performance_summary_by_year`(df[, group_col])	Calculate annual performance summary.
`get_ni_wide_performance`(df)	Calculate NI-wide performance (aggregated across all trusts/sites).
`get_performance_trend`(df[, window])	Calculate rolling performance trend.
`get_tumour_site_ranking`(df[, year])	Rank tumour sites by performance.
`validate_performance_data`(df)	Validate that performance data is internally consistent.

Module Contents

bolster.data_sources.nisra.cancer_waiting_times.logger[source]

bolster.data_sources.nisra.cancer_waiting_times.get_latest_31_day_by_trust(force_refresh=False)[source]

Get 31-day waiting times by HSC Trust.

Parameters:: force_refresh (bool) – 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.
Return type:: DataFrame with columns

bolster.data_sources.nisra.cancer_waiting_times.get_latest_31_day_by_tumour(force_refresh=False)[source]

Get 31-day waiting times by Tumour Site.

Parameters:: force_refresh (bool) – 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.
Return type:: DataFrame with columns

bolster.data_sources.nisra.cancer_waiting_times.get_latest_62_day_by_trust(force_refresh=False)[source]

Get 62-day waiting times by HSC Trust.

Parameters:: force_refresh (bool) – 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.
Return type:: DataFrame with columns

Note

62-day data may contain fractional patient counts due to shared care arrangements between trusts.

bolster.data_sources.nisra.cancer_waiting_times.get_latest_62_day_by_tumour(force_refresh=False)[source]

Get 62-day waiting times by Tumour Site.

Parameters:: force_refresh (bool) – 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.
Return type:: DataFrame with columns

bolster.data_sources.nisra.cancer_waiting_times.get_latest_14_day_breast(force_refresh=False)[source]

Get 14-day breast cancer waiting times by HSC Trust.

Parameters:: force_refresh (bool) – 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.
Return type:: DataFrame with columns

bolster.data_sources.nisra.cancer_waiting_times.get_latest_breast_referrals(force_refresh=False)[source]

Get breast cancer referrals by HSC Trust.

Parameters:: force_refresh (bool) – 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.
Return type:: DataFrame with columns

bolster.data_sources.nisra.cancer_waiting_times.get_latest_cancer_waiting_times(target='31-day', dimension='trust', year=None, summary=False, force_refresh=False)[source]

Get cancer waiting times data for a given target and dimension.

Parameters:

target (str) – Waiting time target — ‘31-day’, ‘62-day’, or ‘14-day’.
dimension (str) – Breakdown dimension — ‘trust’ or ‘tumour’ (tumour not available for 14-day).
year (int | None) – Optional year filter. If None all years are returned.
summary (bool) – If True return an annual performance summary aggregated across all groups instead of the full monthly series.
force_refresh (bool) – 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.

Return type:

pandas.DataFrame

bolster.data_sources.nisra.cancer_waiting_times.get_data_by_year(df, year)[source]

Filter data for a specific year.

Parameters:

df (pandas.DataFrame) – DataFrame with ‘year’ column.
year (int) – Year to filter for.

Returns:

Filtered DataFrame.

Return type:

pandas.DataFrame

bolster.data_sources.nisra.cancer_waiting_times.get_performance_summary_by_year(df, group_col='trust')[source]

Calculate annual performance summary.

Parameters:

df (pandas.DataFrame) – DataFrame with performance data.
group_col (str) – Column to group by (‘trust’ or ‘tumour_site’).

Returns:

DataFrame with annual summary statistics.

Return type:

pandas.DataFrame

bolster.data_sources.nisra.cancer_waiting_times.get_ni_wide_performance(df)[source]

Calculate NI-wide performance (aggregated across all trusts/sites).

Parameters:: df (pandas.DataFrame) – DataFrame with performance data.
Returns:: DataFrame with NI-wide monthly performance.
Return type:: pandas.DataFrame

bolster.data_sources.nisra.cancer_waiting_times.get_performance_trend(df, window=12)[source]

Calculate rolling performance trend.

Parameters:

df (pandas.DataFrame) – DataFrame with NI-wide performance data.
window (int) – Rolling window size in months (default: 12).

Returns:

DataFrame with rolling average performance.

Return type:

pandas.DataFrame

bolster.data_sources.nisra.cancer_waiting_times.get_tumour_site_ranking(df, year=None)[source]

Rank tumour sites by performance.

Parameters:

df (pandas.DataFrame) – DataFrame with tumour site data.
year (int) – Optional year to filter (default: all years).

Returns:

DataFrame ranked by performance (worst to best).

Return type:

pandas.DataFrame

bolster.data_sources.nisra.cancer_waiting_times.validate_performance_data(df)[source]

Validate that performance data is internally consistent.

Parameters:: df (pandas.DataFrame) – DataFrame with performance columns.
Returns:: True if validation passes.
Raises:: ValueError – If validation fails.
Return type:: bool

Note

Rows with NaN values or zero totals are excluded from validation checks.