bolster.data_sources.nisra.emergency_care_waiting_times
=======================================================

.. py:module:: bolster.data_sources.nisra.emergency_care_waiting_times

.. autoapi-nested-parse::

   NISRA Emergency Care Waiting Times Module.

   Provides access to Northern Ireland's emergency care (A&E) waiting times
   statistics, measuring performance against the 4-hour target across HSC Trusts
   and hospital departments.

   The 4-hour target requires that 95% of emergency care attendances are seen,
   treated, admitted or discharged within 4 hours of arrival.

   Data Coverage:
       - April 2008 to present (monthly, by hospital department)
       - 5 HSC Trusts: Belfast, Northern, South Eastern, Southern, Western
       - Attendance types: Type 1 (major A&E), Type 2 (single specialty), Type 3 (MIU/UTC)

   Data Source:
       Department of Health Northern Ireland publishes emergency care waiting times
       through quarterly HTML interactive data publications at
       https://www.health-ni.gov.uk/articles/emergency-care-waiting-times.

   Update Frequency:
       Quarterly, approximately 3 months after the end of each quarter.

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import emergency_care_waiting_times as ecwt
   >>> df = ecwt.get_latest_data()
   >>> 'pct_within_4hrs' in df.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/emergency-care-waiting-times



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.emergency_care_waiting_times.logger
   bolster.data_sources.nisra.emergency_care_waiting_times.DOH_LANDING_PAGE
   bolster.data_sources.nisra.emergency_care_waiting_times.DOH_BASE_URL
   bolster.data_sources.nisra.emergency_care_waiting_times.EXPECTED_TRUSTS


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.emergency_care_waiting_times.get_latest_url
   bolster.data_sources.nisra.emergency_care_waiting_times.parse_data
   bolster.data_sources.nisra.emergency_care_waiting_times.get_latest_data
   bolster.data_sources.nisra.emergency_care_waiting_times.validate_data


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

.. py:data:: logger

.. py:data:: DOH_LANDING_PAGE
   :value: 'https://www.health-ni.gov.uk/articles/emergency-care-waiting-times'


.. py:data:: DOH_BASE_URL
   :value: 'https://www.health-ni.gov.uk'


.. py:data:: EXPECTED_TRUSTS

.. py:function:: get_latest_url()

   Return the URL of the most recent interactive data HTML from datavis.nisra.gov.uk.

   Scrapes the Department of Health landing page to find the most recent quarterly
   publication, then follows to the publication page to extract the data HTML link.

   :returns: URL of the HTML page containing the embedded DataTables widget.

   :raises NISRADataNotFoundError: If no publication or data link can be found.


.. py:function:: parse_data(payload)

   Convert a raw DT widget payload into a clean emergency care DataFrame.

   :param payload: The ``x`` sub-dict from the DT widget, as returned by
                   :func:`~bolster.utils.datatables.fetch_datatables_json`.

   :returns: date, year, month, trust, dept, attendance_type,
             under_4hrs, btw_4_12hrs, over_12hrs, total, pct_within_4hrs.

             ``pct_within_4hrs`` is always in the range [0.0, 1.0].
   :rtype: DataFrame with columns

   :raises NISRAValidationError: If expected columns are missing from the payload.


.. py:function:: get_latest_data(force_refresh = False)

   Fetch and return the latest emergency care waiting times data.

   Downloads the most recent quarterly interactive data HTML, extracts the
   embedded DataTables widget, and returns a clean DataFrame.

   :param force_refresh: Ignored (HTML pages are always re-fetched; use for API
                         consistency with other NISRA modules).

   :returns:     - date (datetime): First of the month for the reporting period
                 - year (int): Calendar year
                 - month (str): Month name, e.g. "April"
                 - trust (str): HSC Trust name
                 - dept (str): Hospital department / site name
                 - attendance_type (str): Type 1, Type 2, or Type 3
                 - under_4hrs (int): Attendances seen within 4 hours
                 - btw_4_12hrs (int): Attendances between 4 and 12 hours
                 - over_12hrs (int): Attendances waiting over 12 hours
                 - total (int): Total attendances
                 - pct_within_4hrs (float): Proportion seen within 4 hours (0.0–1.0)
   :rtype: DataFrame with columns

   :raises NISRADataNotFoundError: If the data page cannot be located or fetched.
   :raises NISRAValidationError: If the downloaded data fails schema validation.


.. py:function:: validate_data(df)

   Validate that the emergency care DataFrame is internally consistent.

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

   :returns: True if validation passes.

   :raises NISRAValidationError: If validation fails.