bolster.data_sources.nisra.drug_related_deaths
==============================================

.. py:module:: bolster.data_sources.nisra.drug_related_deaths

.. autoapi-nested-parse::

   NISRA Drug-Related and Drug Misuse Deaths Data Source.

   Provides access to NISRA's annual statistics on drug-related deaths and deaths
   due to drug misuse in Northern Ireland via the NISRA PxStat API.  Two geographic
   breakdowns are available: HSC Trust and Local Government District.

   NISRA distinguishes two related measures:

   - **Drug-related deaths** (``DRDCOUNT``): All deaths where a drug was implicated,
     including prescription medicines, controlled drugs, and accidental/intentional
     poisonings.
   - **Drug misuse deaths** (``MISUSECOUNT``): A narrower subset where the underlying
     cause is drug abuse/dependence or the death involved a controlled substance.

   Original data source:
       https://www.nisra.gov.uk/statistics/death-statistics/drug-related-and-drug-misuse-deaths

   PxStat matrices used:
       - DTHSDRHSCT — annual deaths by HSC Trust (6 trusts + NI total)
       - DTHSDRLGD  — annual deaths by LGD (11 districts + NI total)

   Update Frequency: Annual (typically May)
   Geographic Coverage: Northern Ireland

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import drug_related_deaths as drd
   >>> df = drd.get_latest_drug_related_deaths()
   >>> {"year", "geography", "statistic", "value"}.issubset(df.columns)
   True
   >>> len(df) > 0
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.drug_related_deaths.logger
   bolster.data_sources.nisra.drug_related_deaths.DimensionType


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.drug_related_deaths.get_latest_drug_related_deaths
   bolster.data_sources.nisra.drug_related_deaths.validate_data


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

.. py:data:: logger

.. py:data:: DimensionType

.. py:function:: get_latest_drug_related_deaths(dimension = 'all', force_refresh = False)

   Download and return the latest NISRA drug-related deaths data.

   Fetches data from the NISRA PxStat API.  Both available geographic
   breakdowns are returned for ``dimension='all'``.

   .. note::

      ``force_refresh`` is accepted for API compatibility but is ignored —
      the PxStat API is called directly with no local cache layer.

   :param dimension: Geographic breakdown to return.  One of:

                     - ``"hsct"`` — 5 HSC Trusts + NI total
                     - ``"lgd"``  — 11 Local Government Districts + NI total
                     - ``"all"``  — dict containing both breakdowns (default)
   :param force_refresh: Ignored.  Retained for API compatibility.

   :returns:

             DataFrame with columns:

                 - ``year``: Registration year (int)
                 - ``geography_code``: geography identifier code
                 - ``geography``: geography name label
                 - ``statistic``: ``"drug_related"`` or ``"drug_misuse"``
                 - ``value``: Count of deaths (int, NaN where suppressed)

             For ``"all"``: ``{"hsct": DataFrame, "lgd": DataFrame}``
   :rtype: For ``"hsct"`` or ``"lgd"``

   :raises ValueError: If ``dimension`` is not a supported value.

   .. rubric:: Example

   >>> df = get_latest_drug_related_deaths("hsct")
   >>> {"year", "geography", "statistic", "value"}.issubset(df.columns)
   True
   >>> data = get_latest_drug_related_deaths("all")
   >>> sorted(data.keys())
   ['hsct', 'lgd']


.. py:function:: validate_data(df)

   Validate a parsed drug-related deaths DataFrame.

   :param df: DataFrame from :func:`get_latest_drug_related_deaths` with a single
              geographic dimension.

   :returns: True if validation passes, False otherwise.

   .. rubric:: Example

   >>> import pandas as pd
   >>> validate_data(pd.DataFrame())
   False