bolster.data_sources.nisra.business_register
============================================

.. py:module:: bolster.data_sources.nisra.business_register

.. autoapi-nested-parse::

   NISRA NI Business Register (IDBR) Module.

   Provides access to the annual count of VAT and/or PAYE registered businesses
   operating in Northern Ireland, sourced from the Inter-Departmental Business
   Register (IDBR). This is the only structured time-series of NI business stock.

   Data Coverage:
       - By broad industry group: 2010-present
       - By legal status: 2010-present
       - By Local Government District (LGD): 2013-present

   Data Source:
       Publication page (year-specific):
           https://www.nisra.gov.uk/publications/northern-ireland-business-activity-size-location-and-ownership-{year}
       Direct file (year-specific):
           https://www.nisra.gov.uk/system/files/statistics/{year}-06/IDBR-Publication-{year}.xlsx

   Update Frequency:
       Annual, published in June.

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import business_register
   >>> df = business_register.get_latest_data()
   >>> 'businesses' in df.columns
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.business_register.logger
   bolster.data_sources.nisra.business_register.NISRA_BASE_URL
   bolster.data_sources.nisra.business_register.PUBLICATION_PAGE_TEMPLATE
   bolster.data_sources.nisra.business_register.FILE_URL_TEMPLATE


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.business_register.get_idbr_publication_url
   bolster.data_sources.nisra.business_register.get_businesses_by_industry
   bolster.data_sources.nisra.business_register.get_businesses_by_legal_status
   bolster.data_sources.nisra.business_register.get_businesses_by_lgd
   bolster.data_sources.nisra.business_register.get_latest_data
   bolster.data_sources.nisra.business_register.validate_data


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

.. py:data:: logger

.. py:data:: NISRA_BASE_URL
   :value: 'https://www.nisra.gov.uk'


.. py:data:: PUBLICATION_PAGE_TEMPLATE
   :value: 'https://www.nisra.gov.uk/publications/northern-ireland-business-activity-size-location-and-owner...


.. py:data:: FILE_URL_TEMPLATE
   :value: 'https://www.nisra.gov.uk/system/files/statistics/{year}-06/IDBR-Publication-{year}.xlsx'


.. py:function:: get_idbr_publication_url(year = None)

   Find the IDBR publication Excel URL for a given (or latest) year.

   Tries the direct, stable URL pattern first (year is incremented each
   publication). Falls back to scraping the year-specific publication page
   if the direct URL is not reachable.

   :param year: Publication year to look for. Defaults to trying the current
                year, then the previous year.

   :returns: Tuple of (excel_url, year).

   :raises NISRADataNotFoundError: If no publication could be found.

   .. rubric:: Example

   >>> url, year = get_idbr_publication_url()
   >>> url.startswith('https://')
   True


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

   Get annual business counts by broad industry group (Table 1.1).

   :param force_refresh: Force re-download even if cached.

   :returns: year, industry_group, businesses.
   :rtype: DataFrame with columns


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

   Get annual business counts by legal status (Table 2.1).

   :param force_refresh: Force re-download even if cached.

   :returns: year, legal_status, sector, businesses.
   :rtype: DataFrame with columns


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

   Get annual business counts by Local Government District (Table 3.1).

   :param force_refresh: Force re-download even if cached.

   :returns: year, lgd, businesses.
   :rtype: DataFrame with columns


.. py:function:: get_latest_data(force_refresh = False, level = 'industry')

   Get the latest NI Business Register (IDBR) data.

   :param force_refresh: Force re-download even if cached.
   :param level: Breakdown level - 'industry' (default), 'legal_status', or 'lgd'.

   :returns: DataFrame for the requested breakdown level. See
             :func:`get_businesses_by_industry`, :func:`get_businesses_by_legal_status`,
             and :func:`get_businesses_by_lgd` for column details.

   :raises ValueError: If level is not one of 'industry', 'legal_status', or 'lgd'.

   .. rubric:: Example

   >>> df = get_latest_data()
   >>> 'businesses' in df.columns
   True


.. py:function:: validate_data(df, level = 'industry')

   Validate the IDBR DataFrame for internal consistency.

   :param df: DataFrame as returned by :func:`get_latest_data`.
   :param level: Validation mode matching the breakdown level - 'industry'
                 (default), 'legal_status', or '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": [2020, 2021], "industry_group": ["Retail", "Retail"],
   ...     "businesses": [5890.0, 6040.0],
   ... })
   >>> validate_data(df)
   True