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

.. py:module:: bhepop2.sources.base

.. autoapi-nested-parse::

   This module contains the abstract classes describing an enrichment source.



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

Classes
~~~~~~~

.. autoapisummary::

   bhepop2.sources.base.EnrichmentSource
   bhepop2.sources.base.QuantitativeAttributes




Attributes
~~~~~~~~~~

.. autoapisummary::

   bhepop2.sources.base.DEFAULT_SOURCE_NAME


.. py:data:: DEFAULT_SOURCE_NAME
   :value: 'Enrichment source'

   

.. py:class:: EnrichmentSource(data, name: str = None)


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

   EnrichmentSource classes are supposed to provide ways
   to enrich or analyze a population.

   Sources describe a specific feature, for instance *declared income*.

   .. py:property:: feature_values


   .. py:property:: nb_feature_values


   .. py:method:: _evaluate_feature_values()
      :abstractmethod:

      Evaluate the values that can be taken by the described feature.

      The result will be stored in the feature_values property.

      :return: object describing the feature values


   .. py:method:: _validate_data()
      :abstractmethod:

      Validate the source data.

      Raise a ValueError if data is invalid.

      :raises: SourceValidationError


   .. py:method:: usable_with_population(population)

      Validate that this source is compatible with the given population.

      Raise a PopulationValidationError if an incompatibility is found.

      :param population: population DataFrame
      :raises PopulationValidationError:


   .. py:method:: get_value_for_feature(feature_index, rng)
      :abstractmethod:

      Return a feature value for the given feature index.

      Generate a singular value from the feature state
      corresponding to the given index.

      :param feature_index: index of the feature in self.feature_values
      :param rng: Numpy random Generator

      :return: feature value


   .. py:method:: compare_with_populations(populations, feature_name, **kwargs)
      :abstractmethod:

      Compare the source data with populations containing the described feature (enriched or original)

      The class returns an instance of a PopulationAnalysis subclass, which
      can be used to generate different kinds of comparisons between the
      populations and the source data.

      :param populations: dict of populations {population_name: population}
      :param feature_name: population column containing the feature values
      :param kwargs: additional arguments for the analysis instance

      :return: PopulationAnalysis subclass instance.



.. py:class:: QuantitativeAttributes(abs_minimum: int = 0, relative_maximum: float = 1.5, delta_min: int = None)


   Class containing additional arguments used by quantitative sources.

   .. py:method:: _validate_quantitative_parameters()

      Validate quantitative attributes' values.