bolster.data_sources.nisra.child_protection
===========================================

.. py:module:: bolster.data_sources.nisra.child_protection

.. autoapi-nested-parse::

   NISRA Children's Social Care — Child Protection Statistics Module.

   This module provides access to Northern Ireland's annual Children's Social Care
   Statistics, focusing on the child protection chapter (referrals, investigations,
   registrations, and register characteristics).

   Data Coverage:
       - Children on the Child Protection Register (CPR) by age, sex, trust
       - CPR trend data from 31 March 2015 to present (annual snapshots)
       - Child Protection Referrals by trust and by referral source (2013/14–present)
       - Child Protection Investigations by type and trust (2015–present)
       - Category of abuse breakdowns (neglect, physical, sexual, emotional)
       - Registration duration on the CPR

   HSC Trusts:
       - Belfast, Northern, South Eastern, Southern, Western

   Data Source:
       Department of Health Northern Ireland publishes annual Children's Social Care
       Statistics covering the 12 months to 31 March each year. Child protection data
       is drawn from the Children Order Return (CPR series).

       Source: https://www.health-ni.gov.uk/topics/childrens-services-statistics
       Article: https://www.health-ni.gov.uk/articles/child-protection-register

   Update Frequency:
       Annual, typically published in October for the year ending 31 March.

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import child_protection as cp
   >>> df = cp.get_latest_child_protection()
   >>> sorted(df.columns.tolist())
   ['category', 'measure', 'notes', 'subcategory', 'value', 'year']

   >>> # CPR trend data shows registrations back to 2015
   >>> trend = df[df['measure'] == 'cpr_registrations_ni_total']
   >>> 2015 in trend['year'].values
   True

   Publication Details:
       - Frequency: Annual (year ending 31 March)
       - Published by: Department of Health, Community Information Branch
       - Latest: Children's Social Care Statistics for Northern Ireland 2024/25
       - Source: https://www.health-ni.gov.uk/topics/childrens-services-statistics



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.child_protection.logger
   bolster.data_sources.nisra.child_protection.HEALTH_NI_CHILDREN_ARTICLE
   bolster.data_sources.nisra.child_protection.HEALTH_NI_BASE_URL
   bolster.data_sources.nisra.child_protection.REQUIRED_COLUMNS
   bolster.data_sources.nisra.child_protection.HSC_TRUSTS
   bolster.data_sources.nisra.child_protection.MEASURE_CPR_TOTAL
   bolster.data_sources.nisra.child_protection.MEASURE_REFERRALS_TOTAL
   bolster.data_sources.nisra.child_protection.MEASURE_INVESTIGATIONS_TOTAL


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.child_protection.get_child_protection_publication_url
   bolster.data_sources.nisra.child_protection.parse_child_protection_file
   bolster.data_sources.nisra.child_protection.get_latest_child_protection
   bolster.data_sources.nisra.child_protection.validate_child_protection_data


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

.. py:data:: logger

.. py:data:: HEALTH_NI_CHILDREN_ARTICLE
   :value: 'https://www.health-ni.gov.uk/articles/child-protection-register'


.. py:data:: HEALTH_NI_BASE_URL
   :value: 'https://www.health-ni.gov.uk'


.. py:data:: REQUIRED_COLUMNS

.. py:data:: HSC_TRUSTS
   :value: ['Belfast', 'Northern', 'South Eastern', 'Southern', 'Western']


.. py:data:: MEASURE_CPR_TOTAL
   :value: 'cpr_registrations_ni_total'


.. py:data:: MEASURE_REFERRALS_TOTAL
   :value: 'referrals_ni_total'


.. py:data:: MEASURE_INVESTIGATIONS_TOTAL
   :value: 'investigations_ni_total'


.. py:function:: get_child_protection_publication_url()

   Find the latest Children's Social Care Statistics publication URL.

   Scrapes the Department of Health child protection register article page to find
   the most recent annual publication, then extracts the Excel download link.

   :returns: URL string for the latest Excel data file.

   :raises NISRAValidationError: If publication page cannot be fetched or no Excel link found.

   .. rubric:: Example

   >>> url = get_child_protection_publication_url()
   >>> url.startswith("https://")
   True
   >>> url.endswith((".xlsx", ".XLSX", ".xls"))
   True


.. py:function:: parse_child_protection_file(file_path)

   Parse a Children's Social Care Statistics Excel file into long-format DataFrame.

   Extracts child protection data from the following tables:
   - Table 2.1: CPR snapshot (total registrations for latest year)
   - Table 2.2a: CPR registrations by trust, 2015–present
   - Table 2.5a: CPR by category of abuse, 2015–present
   - Table 2.9: Child protection referrals by trust, 2013/14–present
   - Table 2.12: Child protection investigations by trust, 2015–present

   :param file_path: Path to the Excel file.

   :returns: year (int), measure (str), category (str),
             subcategory (str), value (int), notes (str).
   :rtype: DataFrame with columns

   :raises NISRAValidationError: If the file cannot be parsed or contains no data.


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

   Download and parse the latest Children's Social Care Statistics.

   Fetches the most recent annual publication from the Department of Health
   and returns child protection data in long format.

   :param force_refresh: Force re-download even if cached (default: False).

   :returns: year, measure, category, subcategory, value, notes.
   :rtype: DataFrame with columns

   :raises NISRAValidationError: If download or parsing fails.


.. py:function:: validate_child_protection_data(df)

   Validate child protection DataFrame and raise on structural issues.

   Checks for:
   - Non-empty DataFrame
   - Required columns present
   - No negative values

   :param df: DataFrame to validate.

   :returns: The input DataFrame (unchanged) if validation passes.

   :raises NISRAValidationError: If any check fails.