bolster.data_sources.nisra.homelessness
=======================================

.. py:module:: bolster.data_sources.nisra.homelessness

.. autoapi-nested-parse::

   Northern Ireland Homelessness Bulletin statistics.

   Biannual homelessness statistics from the Department for Communities NI (DfC),
   sourced from Northern Ireland Housing Executive (NIHE) casework records.
   Covers homeless presentations, acceptances, and temporary accommodation
   placements, broken down by Local Government District (LGD).

   Data is published approximately every six months (Apr–Sep and Oct–Mar periods),
   roughly three months after each period ends.

   Note: This data is **not** available in the NISRA PxStat API. It is published
   directly by DfC as Excel workbooks.

   Publisher:
       Department for Communities NI (DfC) / Northern Ireland Housing Executive (NIHE).
       Publication hub: https://www.communities-ni.gov.uk/articles/northern-ireland-homelessness-bulletin

   Coverage:
       Biannual, 2018/19 to present.
       Geography: 11 Local Government Districts (LGDs) + NI total.

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import homelessness
   >>> df = homelessness.get_latest_data(section='presentations')
   >>> 'lgd' in df.columns
   True



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.homelessness.logger


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.homelessness.get_latest_publication_url
   bolster.data_sources.nisra.homelessness.parse_presentations
   bolster.data_sources.nisra.homelessness.parse_acceptances
   bolster.data_sources.nisra.homelessness.get_latest_data
   bolster.data_sources.nisra.homelessness.validate_data


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

.. py:data:: logger

.. py:function:: get_latest_publication_url()

   Scrape the DfC hub page for the latest homelessness bulletin Excel URL.

   Falls back to the hardcoded 2025/26 Oct–Mar edition URL if scraping fails.

   :returns: Absolute URL of the Excel tables file.

   .. rubric:: Example

   >>> url = get_latest_publication_url()
   >>> 'communities-ni.gov.uk' in url
   True


.. py:function:: parse_presentations(file_path)

   Parse the presentations-by-LGD sheet from a homelessness bulletin workbook.

   :param file_path: Path to the downloaded Excel file.

   :returns: year, period, lgd,
             presentations, rate_per_1000.
   :rtype: Long-format DataFrame with columns

   .. rubric:: Example

   >>> df = parse_presentations('/tmp/homelessness.xlsx')
   >>> set(df.columns) >= {'year', 'period', 'lgd', 'presentations'}
   True


.. py:function:: parse_acceptances(file_path)

   Parse the acceptances-by-LGD sheet from a homelessness bulletin workbook.

   :param file_path: Path to the downloaded Excel file.

   :returns: year, period, lgd,
             acceptances, rate_per_1000.
   :rtype: Long-format DataFrame with columns

   .. rubric:: Example

   >>> df = parse_acceptances('/tmp/homelessness.xlsx')
   >>> set(df.columns) >= {'year', 'period', 'lgd', 'acceptances'}
   True


.. py:function:: get_latest_data(section = 'presentations', force_refresh = False)

   Download and return the latest NI homelessness bulletin data.

   :param section: Which section to return:
                   - ``'presentations'`` (default): Households presenting as homeless
                     by LGD and period.
                   - ``'acceptances'``: Households accepted as homeless by LGD and period.
                   - ``'all'``: Both sections combined with a ``'section'`` column.
   :param force_refresh: If ``True``, bypass the local cache and re-download.

   :returns:

             - **year** (str): Reporting year label (e.g. ``'2025/26'``).
             - **period** (str): Six-month period (e.g. ``'Oct-Mar'``, ``'Apr-Sep'``).
             - **lgd** (str): Local Government District name, or ``'Northern Ireland'``
               for the NI-wide total.
             - **presentations** (int): Households presenting as homeless.
             - **rate_per_1000** (float): Presentations per 1,000 population.

             For ``section='acceptances'``, ``'presentations'`` is replaced by
             ``'acceptances'``. For ``section='all'``, both are included with a
             ``'section'`` column (``'presentations'`` or ``'acceptances'``).
   :rtype: Long-format DataFrame. For ``section='presentations'``, columns are

   :raises ValueError: If ``section`` is not one of the accepted values.
   :raises NISRADataNotFoundError: If the source file cannot be downloaded.

   .. rubric:: Example

   >>> df = get_latest_data()
   >>> 'lgd' in df.columns
   True
   >>> 'Northern Ireland' in df['lgd'].values
   True


.. py:function:: validate_data(df, section = 'presentations')

   Validate a homelessness bulletin DataFrame.

   :param df: DataFrame returned by :func:`get_latest_data`.
   :param section: ``'presentations'`` or ``'acceptances'``, used to identify
                   the count column.

   :returns: ``True`` if all checks pass.

   :raises NISRAValidationError: If any check fails.

   .. rubric:: Example

   >>> df = get_latest_data('presentations')
   >>> validate_data(df, 'presentations')
   True