mescal.double_counting
======================

.. py:module:: mescal.double_counting


Functions
---------

.. autoapisummary::

   mescal.double_counting._background_search
   mescal.double_counting._double_counting_removal
   mescal.double_counting.background_double_counting_removal
   mescal.double_counting.validation_double_counting


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

.. py:function:: _background_search(self, act: dict, k: int, k_lim: int, amount: float, explore_type: str, ESM_inputs: list[str] or str, perform_d_c: list[list], db_dict_code: dict, db_dict_name: dict, db_as_list: list[dict], db_type: str = 'esm') -> tuple[list[list], dict, dict, list[dict]]

   Explores the tree of the market activity with a recursive approach and write the activities to actually check for
   double-counting in the list perform_d_c.

   :param act: LCI dataset
   :param k: tree depth of act with respect to starting activity
   :param k_lim: maximum allowed tree depth (i.e., maximum recursion depth)
   :param amount: product of amounts when going down in the tree
   :param explore_type: can be 'market' or 'background_removal_' + ds_type (where ds_type can be 'op', 'constr',
       'decom' or 'res')
   :param ESM_inputs: list of the ESM flows to perform double counting removal on
   :param perform_d_c: list of activities to check for double counting
   :param db_dict_code: LCI database as dictionary of activities with (database, code) as key
   :param db_dict_name: LCI database as dictionary of activities with (name, reference product, location, database) as key
   :param db_as_list: LCI database as list of activities
   :param db_type: type of database to use, either 'esm', 'esm results' or 'esm results wo dcr'
   :return: list of activities to check for double counting,
       dictionary of activities with code as key,
       dictionary of activities with name as key,
       list of activities


.. py:function:: _double_counting_removal(self, df: pandas.DataFrame, N: int, ESM_inputs: list[str] or str = 'all', db_type: str = 'esm', ds_type: str = 'Operation') -> tuple[list[list], dict, list[list]]

   Remove double counting in the ESM database and write it in the Brightway project

   :param df: mapping file with input flows of each technology or resource
   :param N: number of columns of the original mapping file
   :param ESM_inputs: list of the ESM flows to perform double counting removal on
   :param db_type: type of database to use, either 'esm', 'esm results' or 'esm results wo dcr'
   :param ds_type: type of LCI dataset to consider, can be 'Operation', 'Construction', 'Decommission' or 'Resource'
   :return: list of removed flows, dictionary of removed quantities, list of activities subject to double counting


.. py:function:: background_double_counting_removal(self, new_db_name: str = None, write_database: bool = True) -> None

   Performs double-counting removal in the background inventory. Concretely, flows included in the ESM end-use demands
   (e.g., energy flows in the ESM geographical scope) are removed from the technosphere matrix. This step is needed if
   the ESM end-use demands include the production and operation of new infrastructures.

   :param new_db_name: name of the new database to write, if None, a default name is used
       (<original_db_name>_adjusted_for_double_counting)
   :param write_database: if True, writes the new database in Brightway
   :return: None


.. py:function:: validation_double_counting(self, esm_results: pandas.DataFrame = None, return_validation_report: bool = True, save_validation_report: bool = False) -> None or pd.DataFrame

   Generate a validation report for the double-counting removal process: comparison of quantities removed in LCI
   datasets vs quantities in ESM flows. LCI datasets quantities are converted in ESM units (both in terms of inputs
   and outputs, i.e., quantities of input fuels per functional unit). If an ESM results dataframe is provided, the
   input flows are aggregated to compare the system's primary energy use.

   :param return_validation_report: if True, returns a DataFrame with the validation report (double-counting removal
       or primary energy use, depending on whether esm_results is provided).
   :param esm_results: dataframe containing the annual production of each technology in the ESM. It must contain the
       columns 'Name' and 'Production', and it can possibly contain the 'Run' and 'Year' columns too. If provided, the
       system's primary energy use will be compared.
   :param save_validation_report: if True, saves the validation report as a CSV file in self.results_path_file.
   :return: None or DataFrame with the validation report if return_validation_report is True