bolster.data_sources.nisra.disease_prevalence
=============================================

.. py:module:: bolster.data_sources.nisra.disease_prevalence

.. autoapi-nested-parse::

   NISRA Disease Prevalence Module.

   Provides access to Northern Ireland's disease prevalence statistics from
   GP clinical disease registers (Quality & Outcomes Framework, QOF).
   Data are released annually after National Prevalence Day.

   Data Coverage:
       - Financial years 2017/18 to present (extended annually)
       - NI-level: registered patients per disease register and prevalence
         per 1,000 patients
       - By Local Government District (LGD): same metrics per council
       - By HSC Trust: same metrics per Trust

   Disease Registers (17):
       Asthma, Atrial Fibrillation, Cancer, Chronic Kidney Disease,
       Chronic Obstructive Pulmonary Disease, Coronary Heart Disease,
       Dementia, Depression, Diabetes Mellitus, Heart Failure 1,
       Heart Failure 3, Hypertension, Mental Health,
       Non-Diabetic Hyperglycaemia, Osteoporosis, Rheumatoid Arthritis,
       Stroke & TIA

   Original data sources:
       https://www.opendatani.gov.uk/dataset/gp-practice-reference-file
       https://www.health-ni.gov.uk/topics/health-statistics/disease-prevalence

   Data is fetched from the NISRA PxStat API using the following matrices:
       - DISPREVNI: NI-wide annual prevalence by disease
       - DISPREVLGD: Annual prevalence by LGD and disease
       - DISPREVHSCT: Annual prevalence by HSC Trust and disease

   Update Frequency:
       Annual, approximately May of the following calendar year.

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import disease_prevalence as dp
   >>> df = dp.get_latest_disease_prevalence()
   >>> 'registered_patients' in df.columns
   True
   >>> 'prevalence_per_1000' in df.columns
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.disease_prevalence.logger


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.disease_prevalence.get_ni_prevalence
   bolster.data_sources.nisra.disease_prevalence.get_lgd_prevalence
   bolster.data_sources.nisra.disease_prevalence.get_hsct_prevalence
   bolster.data_sources.nisra.disease_prevalence.get_latest_disease_prevalence
   bolster.data_sources.nisra.disease_prevalence.validate_disease_prevalence


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

.. py:data:: logger

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

   Get NI-wide annual disease prevalence (DISPREVNI).

   :param force_refresh: Accepted for API compatibility but ignored; the PxStat
                         API always returns the latest data without caching.

   :returns: financial_year, year, disease,
             registered_patients, prevalence_per_1000.
   :rtype: DataFrame with columns


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

   Get annual disease prevalence by Local Government District (DISPREVLGD).

   :param force_refresh: Accepted for API compatibility but ignored; the PxStat
                         API always returns the latest data without caching.

   :returns: financial_year, year, lgd, disease,
             registered_patients, prevalence_per_1000.
   :rtype: DataFrame with columns


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

   Get annual disease prevalence by HSC Trust (DISPREVHSCT).

   :param force_refresh: Accepted for API compatibility but ignored; the PxStat
                         API always returns the latest data without caching.

   :returns: financial_year, year, trust, disease,
             registered_patients, prevalence_per_1000.
   :rtype: DataFrame with columns


.. py:function:: get_latest_disease_prevalence(force_refresh = False, level = 'ni', lcg = None)

   Get the latest NI disease prevalence data.

   Fetches data from the NISRA PxStat API.  The ``level`` parameter
   controls geographic granularity; ``lcg`` filters to a specific
   Local Government District (when level='lgd').

   :param force_refresh: Accepted for API compatibility but ignored; the PxStat
                         API always returns the latest data without caching.
   :param level: Geographic level — 'ni' for NI-wide (default), 'lgd' for
                 Local Government District breakdown, or 'trust' for HSC Trust.
   :param lcg: Optional LGD name filter (used when level='lgd').  If provided,
               only rows for that LGD are returned.

   :returns: financial_year, year, disease,
             registered_patients, prevalence_per_1000.
             When level='lgd', also includes an 'lgd' column.
             When level='trust', also includes a 'trust' column.
   :rtype: DataFrame with columns

   :raises ValueError: If level is not one of 'ni', 'lgd', or 'trust'.

   .. rubric:: Example

   >>> df = get_latest_disease_prevalence()
   >>> 'registered_patients' in df.columns
   True
   >>> 'prevalence_per_1000' in df.columns
   True


.. py:function:: validate_disease_prevalence(df, level = 'ni')

   Validate the disease prevalence DataFrame for internal consistency.

   :param df: DataFrame as returned by :func:`get_latest_disease_prevalence`.
   :param level: Validation mode — 'ni' (default) or 'lgd'/'trust' for
                 geographic breakdowns.  Validates the 'gp' level alias for
                 backward compatibility (treated same as 'lgd').

   :returns: True if all checks pass.

   :raises NISRAValidationError: Describing the first failing check.
   :raises ValueError: If level is not a recognised value.

   .. rubric:: Example

   >>> import pandas as pd
   >>> df = pd.DataFrame({
   ...     "year": [2017], "financial_year": ["2017/18"],
   ...     "disease": ["Hypertension"],
   ...     "registered_patients": [184824.0],
   ...     "prevalence_per_1000": [102.9],
   ... })
   >>> validate_disease_prevalence(df)
   True