bolster.data_sources.nisra.deprivation
======================================

.. py:module:: bolster.data_sources.nisra.deprivation

.. autoapi-nested-parse::

   NISRA Multiple Deprivation Measure (NIMDM 2017) Module.

   Provides access to the Northern Ireland Multiple Deprivation Measure 2017,
   which ranks all 890 Super Output Areas (SOAs) on overall deprivation and
   seven domain ranks. Rank 1 is the most deprived SOA in each domain.

   Domains:
       - Income
       - Employment
       - Health Deprivation and Disability
       - Education, Skills and Training
       - Access to Services
       - Living Environment
       - Crime and Disorder

   Data Source:
       Publication page: https://www.nisra.gov.uk/publications/nimdm17-soa-level-results
       Direct file: https://www.nisra.gov.uk/files/nisra/publications/NIMDM17_SOAresults.xls

   Update Frequency:
       Infrequent. NIMDM2017 is the current release; NIMDM2021 is pending
       Census 2021 data integration. The download URL is stable and has no
       year in the path, so it will need to be updated when NIMDM2021 publishes.

   .. rubric:: Example

   >>> from bolster.data_sources.nisra import deprivation
   >>> df = deprivation.get_latest_data()
   >>> 'mdm_rank' in df.columns
   True
   >>> df['soa_code'].nunique()
   890



Attributes
----------

.. autoapisummary::

   bolster.data_sources.nisra.deprivation.logger
   bolster.data_sources.nisra.deprivation.NIMDM_SOA_URL


Functions
---------

.. autoapisummary::

   bolster.data_sources.nisra.deprivation.get_latest_data
   bolster.data_sources.nisra.deprivation.validate_data


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

.. py:data:: logger

.. py:data:: NIMDM_SOA_URL
   :value: 'https://www.nisra.gov.uk/files/nisra/publications/NIMDM17_SOAresults.xls'


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

   Get the latest NIMDM SOA-level deprivation ranks.

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

   :returns: lgd, urban_rural, soa_code, soa_name,
             mdm_rank, income_rank, employment_rank, health_disability_rank,
             education_rank, access_to_services_rank, living_environment_rank,
             crime_disorder_rank. Rank 1 is the most deprived SOA.
   :rtype: DataFrame with columns

   :raises NISRADataError: If the data file cannot be downloaded or parsed.

   .. rubric:: Example

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


.. py:function:: validate_data(df)

   Validate the NIMDM DataFrame for internal consistency.

   :param df: DataFrame as returned by :func:`get_latest_data`.

   :returns: True if all checks pass.

   :raises NISRAValidationError: Describing the first failing check.

   .. rubric:: Example

   >>> import pandas as pd
   >>> df = pd.DataFrame({
   ...     "soa_code": ["95AA01S1"], "soa_name": ["Aldergrove_1"],
   ...     "lgd": ["Antrim and Newtownabbey"], "urban_rural": ["Rural"],
   ...     "mdm_rank": [516], "income_rank": [790],
   ...     "employment_rank": [888], "health_disability_rank": [890],
   ...     "education_rank": [254], "access_to_services_rank": [17],
   ...     "living_environment_rank": [75], "crime_disorder_rank": [874],
   ... })
   >>> validate_data(df)
   True