bolster.data_sources.health_ni.diagnostic_waiting_times
=======================================================

.. py:module:: bolster.data_sources.health_ni.diagnostic_waiting_times

.. autoapi-nested-parse::

   NISRA Diagnostic Waiting Times Module.

   Provides access to Northern Ireland's diagnostic waiting times statistics,
   covering patients waiting for diagnostic tests across HSC Trusts, diagnostic
   services, and categories of test.

   Waiting Time Bands:
       - Total: All patients waiting (any duration)
       - 0–9 weeks: Patients waiting 0–9 weeks
       - >9 weeks: Patients waiting more than 9 weeks
       - >26 weeks: Patients waiting more than 26 weeks

   Data Coverage:
       - Q4 2007/08 (quarter ending March 2008) to present
       - Quarterly frequency
       - 5 HSC Trusts: Belfast, Northern, South Eastern, Southern, Western
       - Categories: Imaging, Endoscopy, Physiological measurements (and 'All')
       - Individual diagnostic services (endoscopy, radiology, physiological, etc.)

   HSC Trusts:
       Belfast, Northern, South Eastern, Southern, Western

   Original data source:
       https://www.health-ni.gov.uk/articles/diagnostic-waiting-times

   Data is fetched from the NISRA PxStat API using matrix ``DWT``.

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import diagnostic_waiting_times as dwt
   >>> df = dwt.get_latest_diagnostic_waiting_times()
   >>> sorted(df.columns.tolist())
   ['category', 'date', 'over_26_weeks', 'over_9_weeks', 'performance_rate', 'quarter', 'total_waiting', 'trust', 'within_9_weeks', 'year']



Attributes
----------

.. autoapisummary::

   bolster.data_sources.health_ni.diagnostic_waiting_times.logger
   bolster.data_sources.health_ni.diagnostic_waiting_times.EXPECTED_TRUSTS


Functions
---------

.. autoapisummary::

   bolster.data_sources.health_ni.diagnostic_waiting_times.get_latest_diagnostic_waiting_times
   bolster.data_sources.health_ni.diagnostic_waiting_times.validate_diagnostic_waiting_times


Module Contents
---------------

.. py:data:: logger

.. py:data:: EXPECTED_TRUSTS

.. py:function:: get_latest_diagnostic_waiting_times(trust = None, year = None, force_refresh = False)

   Get diagnostic waiting times by HSC Trust and category of test.

   Returns aggregate-level data (all diagnostic services combined) pivoted
   so that each row represents one trust/quarter with waiting band columns.

   :param trust: Optional HSC Trust name to filter (e.g. ``"Belfast"``).  If
                 ``None`` all trusts are returned (NI-wide aggregate excluded).
   :param year: Optional calendar year filter.  If ``None`` all years returned.
   :param force_refresh: Accepted for API compatibility but ignored; the PxStat
                         API always returns the latest data without caching.

   :returns:

             - ``date``: Timestamp (quarter end date)
             - ``quarter``: Quarter label (e.g. ``"2023/24Q1"``)
             - ``year``: Calendar year of the quarter end
             - ``trust``: HSC Trust name
             - ``category``: Category of test (``"All categories of test"`` for
               this aggregate view)
             - ``total_waiting``: Total patients waiting (any duration)
             - ``within_9_weeks``: Patients waiting 0–9 weeks
             - ``over_9_weeks``: Patients waiting >9 weeks
             - ``over_26_weeks``: Patients waiting >26 weeks
   :rtype: DataFrame with columns

   .. rubric:: Example

   >>> df = get_latest_diagnostic_waiting_times()
   >>> "Belfast" in df["trust"].values
   True
   >>> "total_waiting" in df.columns
   True


.. py:function:: validate_diagnostic_waiting_times(df)

   Validate that diagnostic waiting times data is internally consistent.

   Checks that required columns are present, values are non-negative,
   performance rates are within 0–1, and there is sufficient data.

   :param df: DataFrame as returned by :func:`get_latest_diagnostic_waiting_times`.

   :returns: ``True`` if all validation checks pass.

   :raises ValueError: If any validation check fails.