bblocks.import_tools.unaids
===========================

.. py:module:: bblocks.import_tools.unaids

.. autoapi-nested-parse::

   Tools to retrieve data from UNAIDS



Attributes
----------

.. autoapisummary::

   bblocks.import_tools.unaids.URL
   bblocks.import_tools.unaids.AREA_CODES
   bblocks.import_tools.unaids.AVAILABLE_INDICATORS


Classes
-------

.. autoapisummary::

   bblocks.import_tools.unaids.Aids


Functions
---------

.. autoapisummary::

   bblocks.import_tools.unaids.get_response
   bblocks.import_tools.unaids.parse_data_table
   bblocks.import_tools.unaids.parse_global_data
   bblocks.import_tools.unaids.clean_data
   bblocks.import_tools.unaids.get_category
   bblocks.import_tools.unaids.check_response
   bblocks.import_tools.unaids.get_dimensions
   bblocks.import_tools.unaids.get_years
   bblocks.import_tools.unaids.response_params
   bblocks.import_tools.unaids.response_to_df
   bblocks.import_tools.unaids.extract_data
   bblocks.import_tools.unaids.check_if_not_downloaded
   bblocks.import_tools.unaids.check_area_grouping


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

.. py:data:: URL
   :type:  str
   :value: 'https://aidsinfo.unaids.org/datasheetdatarequest'


.. py:data:: AREA_CODES
   :type:  dict

.. py:data:: AVAILABLE_INDICATORS

.. py:function:: get_response(url: str, indicator: str, category: str, area_name: str, area_code: str) -> dict

   returns a json response from UNAIDS


.. py:function:: parse_data_table(response: dict, dimensions: list, years: list) -> pandas.DataFrame

   parses data table in json response and returns a formatted dataframe


.. py:function:: parse_global_data(response: dict, dimensions: list, years: list) -> pandas.DataFrame

   parses global data in json response and returns a formatted dataframe


.. py:function:: clean_data(df: pandas.DataFrame, indicator: str) -> pandas.DataFrame

   cleans dataframe and returns a formatted dataframe


.. py:function:: get_category(indicator: str) -> str

   returns the category for an indicator


.. py:function:: check_response(response: dict) -> None

   checks if response has data


.. py:function:: get_dimensions(response: dict) -> list

   returns the dimensions for an indicator


.. py:function:: get_years(response: dict) -> list

   returns the years for an indicator


.. py:function:: response_params(group: str, indicator: str)

   Returns a list of parameters to be used in the response


.. py:function:: response_to_df(grouping: str, response: dict, indicator: str) -> pandas.DataFrame

   Convert response to dataframe


.. py:function:: extract_data(indicator: str, grouping: str)

   pipeline to extract data


.. py:function:: check_if_not_downloaded(indicator: str, area_grouping: str) -> bool

   Checks if data is already downloaded for an indicator and area grouping

   :returns: True if data is not downloaded, False if data is downloaded


.. py:function:: check_area_grouping(area_grouping: str) -> list

   Checks if area grouping is valid and returns a list of area codes


.. py:class:: Aids

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


   An object to extract data from UNAIDS.

   To use, create an instance of the class.
   The load indicators using the load_indicators method. This can be done multiple times.
   To return a dataframe of all available indicators to load, use the available_indicators class attribute.
   If the data for an indicator has never been downloaded, it will be downloaded.
   If it has been downloaded, it will be loaded from disk. If update_data is set to true,
   the data will be downloaded each time an indicator is loaded.
   You can force an update by calling 'update', and all indicators will be reloaded into the object.
   You can get a dataframe by calling 'get_data' and passing the indicator name(s)
   (or None and this will return all indicators) and passing the area grouping(s) ('all' by default)


   .. py:property:: available_indicators
      :type: pandas.DataFrame


      Returns a dataframe of available indicators


   .. py:method:: load_data(indicator: str, area_grouping: str = 'all') -> bblocks.import_tools.common.ImportData

      Load an indicator to the object

      indicator (str): The name of the indicator to load. To see a DataFrame of available
          indicators, use the available_indicators method.
      area_grouping (str): The grouping to use. Choose from ["country", "region", "all"].

      :returns: The same object to allow chaining



   .. py:method:: update_data(reload_data: bool)

      Update all loaded indicators saved on the disk

      When called, it will go through each loaded indicator/area grouping combination
      and update the data saved on disk.

      :returns: The same object to allow chaining



   .. py:method:: get_data(indicators: Optional[str | list] = None, area_grouping: str = 'all') -> pandas.DataFrame

      Get the data as a Pandas DataFrame

      :param indicators: By default, all indicators are returned in a single DataFrame.
                         If a list of indicators is passed, only those indicators will be returned.
                         A single indicator can be passed as a string as well.
      :param area_grouping: The area grouping to use. Choose from ["country", "region", "all"].
                            Default is "all".
      :type area_grouping: str

      :returns: A Pandas DataFrame with the requested indicator data