bblocks.import_tools.hdr
========================

.. py:module:: bblocks.import_tools.hdr

.. autoapi-nested-parse::

   Tools to import UNDP Human Development Report data.

   `get_hdr_data` returns a dataframe with all HDR data.
   Use the `HDR` object to extract and interact with the data



Attributes
----------

.. autoapisummary::

   bblocks.import_tools.hdr.BASE_URL
   bblocks.import_tools.hdr.HDR_INDICATORS


Classes
-------

.. autoapisummary::

   bblocks.import_tools.hdr.HDR


Functions
---------

.. autoapisummary::

   bblocks.import_tools.hdr._parse_html
   bblocks.import_tools.hdr.get_data_links
   bblocks.import_tools.hdr.read_data
   bblocks.import_tools.hdr.create_code_dict
   bblocks.import_tools.hdr.format_data
   bblocks.import_tools.hdr.get_hdr_data
   bblocks.import_tools.hdr.available_indicators
   bblocks.import_tools.hdr.available_composite_indices


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

.. py:data:: BASE_URL
   :type:  str
   :value: 'https://hdr.undp.org/data-center/documentation-and-downloads'


.. py:data:: HDR_INDICATORS
   :type:  dict[str, list]

.. py:function:: _parse_html(soup: bs4.BeautifulSoup) -> tuple[str, str]

   Parses html for data and metadata links


.. py:function:: get_data_links() -> dict[str, str]

   returns links for data and metadata


.. py:function:: read_data(response: requests.Response) -> pandas.DataFrame

   Read UNDP Human Development Report data from a URL.

   Returns a dataframe with either the data or metadata. The function checks
   the content type of the response and returns the appropriate dataframe.

   :param response: Response object from a request to a UNDP HDR data URL.


.. py:function:: create_code_dict(metadata_df: pandas.DataFrame) -> dict[str, str]

   Create a dictionary of variable codes and names.

   This function takes the metadata dataframe and returns a dictionary
   to be used to map variable codes to variable names.

   :param metadata_df: Metadata dataframe.
   :type metadata_df: pd.DataFrame


.. py:function:: format_data(data_df: pandas.DataFrame, code_dict: dict[str, str]) -> pandas.DataFrame

   Format HDR data.

   This function takes the raw dataframe and:
   - melts the data to long format
   - creates a year columnand new variable column by splitting on the last underscore
       (variables contain year such as "hdi_rank_2019")
   - creates a variable_name column by mapping the variable to the code_dict

   :param data_df: Raw dataframe to be formatted.
   :type data_df: pd.DataFrame
   :param code_dict: Dictionary of variable codes and names.
   :type code_dict: dict


.. py:function:: get_hdr_data() -> pandas.DataFrame

   Get UNDP Human Development Report data.

   This function returns the formatted HDR data as a dataframe.


.. py:function:: available_indicators(composite_index: str = 'all') -> list[str]

   See available indicators

   :param composite_index: Composite index to see available indicators for. If None, all
   :type composite_index: str


.. py:function:: available_composite_indices() -> list[str]

   See available composite indices


.. py:class:: HDR

   Bases: :py:obj:`bblocks.import_tools.common.ImportData`


   An object to help download and use UNDP Human Development Report data
   To use, create an instance of the class. Call `load_data` to load the data for
   desired indicators. If the data is not already downloaded, it will be downloaded,
   then the selected indicators will be loaded to the object.
   To see available indicators, call the function `available_indicators`. To see available composite
   indices, call the function `available_composite_indices`.
   To get the data as a dataframe, call `get_data` method. You can force an update by calling `update_data`


   .. py:method:: load_data(indicators: str | list = 'all') -> bblocks.import_tools.common.ImportData

      Load data to the object

      When called this method checks if the data has been downloaded, if not it downloads it.
      It then loads the data into the object for selected indicators and returns the object.

      :param indicators: Indicator(s) to load. If "all", load all indicators.

      :returns: same object with loaded indicators to allow chaining



   .. py:method:: update_data(reload_data: bool = True) -> bblocks.import_tools.common.ImportData

      Update the data

      When called it will update the data used to load indicators.

      :param reload_data: If True, reload the indicators after updating the data. Default is True.

      :returns: same object with updated data to allow chaining