:py:mod:`bhepop2.enrichment.base`
=================================

.. py:module:: bhepop2.enrichment.base

.. autoapi-nested-parse::

   This module contains base code for synthetic population enrichment classes.



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

Classes
~~~~~~~

.. autoapisummary::

   bhepop2.enrichment.base.SyntheticPopulationEnrichment




.. py:class:: SyntheticPopulationEnrichment(population: pandas.DataFrame, source, feature_name: str = None, seed=None)


   Bases: :py:obj:`abc.ABC`, :py:obj:`bhepop2.utils.Bhepop2Logger`

   This abstract class describes the base attributes and methods of
   synthetic population enrichment classes.

   The class instances work on an original synthetic population,
   which is enriched using a dedicated algorithm.

   This enrichment process is executed in the assign_feature_value_to_pop method.
   Its implementation, and the algorithm used to evaluate the feature values,
   are core to the SyntheticPopulationEnrichment classes.

   .. py:attribute:: _required_source_class

      

   .. py:method:: assign_feature_values()

      Assign feature values to the population individuals.

      This method evaluates and adds feature values to each
      population individual. The name of the added column is
      defined by the feature_name class parameter.

      Returned enriched population is a copy of the original population.
      The original population is not modified.

      :return: enriched population


   .. py:method:: _evaluate_feature_on_population()
      :abstractmethod:

      Evaluate a list of feature values for each individual.

      :return: iterable with same size and order than the population


   .. py:method:: _get_value_for_feature(feature_id)

      Get a feature value for the given feature id.

      This method is a helper that class self.source.get_value_for_feature
      with feature id and self.rng.

      :param feature_id:

      :return: feature value


   .. py:method:: _validate_and_process_inputs()

      Validate and process the provided enrichment inputs.

      Both the population and the enrichment source may need to be validated.

      :raise: ValueError if validation fails


   .. py:method:: compare_with_source(enriched_population_name: str = 'enriched_population', **kwargs)

      Create a PopulationAnalysis instance for the enriched population.

      :param enriched_population_name: display name of the enriched population
      :param kwargs: additional parameters for the PopulationAnalysis instantiation

      :return: PopulationAnalysis for the current enriched population