bolster.data_sources.nisra.claimant_count
=========================================

.. py:module:: bolster.data_sources.nisra.claimant_count

.. autoapi-nested-parse::

   NISRA Claimant Count Statistics Module.

   Provides monthly Claimant Count statistics for Northern Ireland via the NISRA
   PxStat API.  The Claimant Count is an experimental statistic measuring the
   number of people claiming benefits principally for the reason of being
   unemployed.  Data is published monthly and covers Northern Ireland with two
   geographic breakdowns: Local Government Districts and Assembly Areas.

   Original data source:
       https://www.nisra.gov.uk/statistics/labour-market-and-social-welfare/claimant-count

   PxStat matrices used:
       - CCMLGD  — monthly count and rate by LGD (11 districts + NI total)
       - CCMAA   — monthly count and rate by Assembly Area (18 areas + NI total)
       - CCMSOA  — monthly count by Super Output Area (~92 k rows, large)

   Update Frequency: Monthly, approximately 2–3 weeks after the reference month.

   Usage:
       >>> from bolster.data_sources.nisra import claimant_count
       >>> df = claimant_count.get_latest_claimant_count("lgd")
       >>> "claimants_total" in df.columns
       True

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import claimant_count
   >>> df = claimant_count.get_latest_claimant_count("lgd")
   >>> df[df["geography"] == "Northern Ireland"]["claimants_total"].iloc[0] > 0
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.claimant_count.logger


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.claimant_count.get_latest_claimant_count
   bolster.data_sources.nisra.claimant_count.validate_claimant_count


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

.. py:data:: logger

.. py:function:: get_latest_claimant_count(breakdown = 'lgd', adjusted = True, force_refresh = False)

   Download and return the latest NISRA claimant count data.

   Fetches data from the NISRA PxStat API for the chosen geographic breakdown.
   Returns the full time series available from the API (from January 2005).

   .. note::

      ``adjusted`` is accepted for API compatibility but is ignored — the
      PxStat API does not distinguish seasonally adjusted from unadjusted
      counts at geographic level.
      
      ``force_refresh`` is accepted for API compatibility but is ignored —
      the PxStat API is called directly with no local cache layer.

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

                     - ``"lgd"`` — 11 Local Government Districts + NI total (default)
                     - ``"aa"``  — 18 Assembly Areas + NI total
                     - ``"soa"`` — Super Output Areas (~92 k rows, large)
   :param adjusted: Ignored.  Retained for API compatibility.
   :param force_refresh: Ignored.  Retained for API compatibility.

   :returns:

             DataFrame with columns:

                 - ``date``: pandas Timestamp (monthly, day=1)
                 - ``geography_code``: geography identifier code
                 - ``geography``: geography name label
                 - ``claimants_total``: claimant count (float)
                 - ``claimant_rate_total_pct``: claimant rate as percentage (float)

             For ``"soa"``: DataFrame with columns:

                 - ``date``: pandas Timestamp (monthly, day=1)
                 - ``soa_code``: Super Output Area code
                 - ``soa_name``: Super Output Area name
                 - ``claimants``: claimant count (float)
   :rtype: For ``"lgd"`` and ``"aa"``

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

   .. rubric:: Example

   >>> df = get_latest_claimant_count("lgd")
   >>> "claimants_total" in df.columns
   True
   >>> df_aa = get_latest_claimant_count("aa")
   >>> "claimants_total" in df_aa.columns
   True


.. py:function:: validate_claimant_count(df, breakdown)

   Validate the integrity of a claimant count DataFrame.

   Checks that required columns are present, values are in plausible ranges,
   and the DataFrame is non-empty.

   :param df: DataFrame returned by :func:`get_latest_claimant_count`.
   :param breakdown: The breakdown type that produced the DataFrame.
                     One of ``"lgd"``, ``"aa"``, or ``"soa"``.

   :returns: ``True`` if validation passes, ``False`` otherwise.

   .. rubric:: Example

   >>> import pandas as pd
   >>> validate_claimant_count(pd.DataFrame(), "lgd")
   False