:py:mod:`bhepop2.tools`
=======================

.. py:module:: bhepop2.tools

.. autoapi-nested-parse::

   Utility functions



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


Functions
~~~~~~~~~

.. autoapisummary::

   bhepop2.tools.add_household_size_attribute
   bhepop2.tools.add_household_type_attribute
   bhepop2.tools.read_filosofi
   bhepop2.tools.read_filosofi_attributes
   bhepop2.tools.read_distributions_from_filosofi



Attributes
~~~~~~~~~~

.. autoapisummary::

   bhepop2.tools.filosofi_attributes


.. py:function:: add_household_size_attribute(population: pandas.DataFrame, values_map: callable = lambda x: str(x) + '_pers' if x < 5 else '5_pers_or_more', person_id: str = 'person_id', household_id: str = 'household_id', column_name: str = 'size')

   Add a size attribute to the given synthetic population.

   Even though we add the attribute at a person's level,
   its value is related to the household (we add household size).

   :param population: synthetic population df
   :param values_map: mapping function applied to household count
   :param person_id: name of the column containing persons' ids
   :param household_id: name of the column containing households' ids
   :param column_name: name of the added column

   :return: population with new 'column_name' column containing household size


.. py:function:: add_household_type_attribute(population, person_id: str = 'person_id', household_id: str = 'household_id', column_name='family_comp')

   Add a type attribute to the given synthetic population.

   The following attributes are needed on the population:
       - household_size: number of person's in the household
       - sex: person's sex
       - age: person's age
       - couple: boolean indicating if the person is in couple in the household

   The household type can take the following values:
       - Single_man
       - Single_wom
       - Couple_without_child
       - Couple_with_child
       - Single_parent
       - complex_hh

   Even though we add the attribute at a person's level,
   its value is related to the household (we add household type).

   :param population: synthetic population df
   :param person_id: name of the column containing persons' ids
   :param household_id: name of the column containing households' ids
   :param column_name: name of the added column

   :return: population with new 'column_name' column containing household size


.. py:data:: filosofi_attributes

   

.. py:function:: read_filosofi(filepath: str, year: str, attributes: list, communes=None)

   Fetch income distributions by attribute (age, sex, ...) and commune from Filosofi file

   :param filepath: path to Filosofi excel file (DISP_COM)
   :param year: Filosofi data year
   :param attributes: list of attributes and their modalities, with data required for extraction
   :param communes: optional list of communes to filter

   :return: distributions DataFrame


.. py:function:: read_filosofi_attributes(filosofi_sheets, year, attributes: list, communes=None)

   Read distributions from list of attributes and their modalities in filosofi sheets.

   :param filosofi_sheets: Filosofi excel as DataFrame indexed by sheet
   :param year: Filosofi data year
   :param attributes: list of attributes and their modalities, with data required for extraction
   :param communes: optional list of communes to filter

   :return: distributions DataFrame


.. py:function:: read_distributions_from_filosofi(filosofi_sheets, year: str, sheet: str, col_pattern: str, attribute: str, modality: str, communes=None)

   :param filosofi_sheets: Filosofi excel as DataFrame indexed by sheet
   :param year: Filosofi data year
   :param sheet: sheet name
   :param col_pattern: column pattern
   :param attribute: attribute name
   :param modality: modality name
   :param communes: optional list of communes to filter

   :return: distributions DataFrame