mescal.esm ========== .. py:module:: mescal.esm Classes ------- .. autoapisummary:: mescal.esm.ESM mescal.esm.PathwayESM Functions --------- .. autoapisummary:: mescal.esm.has_construction mescal.esm.has_decommission mescal.esm.is_process_activity mescal.esm.is_transport Module Contents --------------- .. py:class:: ESM(mapping: pandas.DataFrame, model: pandas.DataFrame, unit_conversion: pandas.DataFrame, mapping_esm_flows_to_CPC_cat: pandas.DataFrame, main_database: mescal.database.Database, esm_db_name: str, main_database_name: str = None, biosphere_db_name: str = 'biosphere3', technology_compositions: pandas.DataFrame = None, results_path_file: str = 'results/', tech_specifics: pandas.DataFrame = None, regionalize_foregrounds: str or list[str] = None, accepted_locations: list[str] = None, esm_location: str = 'GLO', locations_ranking: list[str] = None, spatialized_biosphere_db: mescal.database.Database = None, efficiency: pandas.DataFrame = None, lifetime: pandas.DataFrame = None, max_depth_double_counting_search: int = 10, stop_background_search_when_first_flow_found: bool = False, esm_end_use_demands: list[str] = None, remove_double_counting_to: list[str] = None, extract_eol_from_construction: bool = False) Class that represents the ESM database, that can be modified with double-counting removal, regionalization, efficiency differences correction, and lifetime differences correction. LCA indicators can then be computed from it. And results from the ESM can be added back to the LCI database. Initialize the ESM database creation :param mapping: mapping between the ESM resources, technologies (operation and construction) and flows, and the LCI database activities :param model: dataframe containing the inputs and outputs of each technology in the ESM :param unit_conversion: dataframe containing unit conversion factors for all ESM technologies, resources and flows :param tech_specifics: dataframe containing the specific requirements (if any) of the ESM technologies :param technology_compositions: dataframe containing (if any) the compositions of technologies :param mapping_esm_flows_to_CPC_cat: mapping between ESM flows and CPC categories :param main_database: main LCI database, e.g., ecoinvent or premise database (with CPC categories) :param esm_db_name: name of the ESM database to be written in Brightway :param main_database_name: name of the main database (e.g., 'ecoinvent-3.9.1-cutoff') if main_database is an aggregation of the main database and complementary databases :param biosphere_db_name: name of the (not spatialized) biosphere database. Default is 'biosphere3'. :param results_path_file: path to your result folder. Default is 'results/'. :param regionalize_foregrounds: list of types of LCI datasets that will be subject to the foreground regionalization process. Can be 'Operation', 'Construction', 'Decommission', 'Resource', or a list of these. Set to 'all' to regionalize all types of datasets. Default is None (no regionalization). :param accepted_locations: list of ecoinvent locations to keep without modification in case of regionalization. Default is None (only the esm_location is accepted). :param esm_location: ecoinvent location corresponding to the geographical scope of the ESM :param locations_ranking: ranking of the preferred ecoinvent locations in case of regionalization :param spatialized_biosphere_db: spatialized biosphere database :param efficiency: dataframe containing the ESM technologies to correct regarding efficiency differences between the ESM and LCI database :param lifetime: dataframe containing the lifetime of the ESM technologies :param max_depth_double_counting_search: maximum recursion depth of the double-counting background search algorithm. Default is 10. :param stop_background_search_when_first_flow_found: if True, the background search for double-counting removal (only applied to 'Background search' technologies in tech_specifics) stops once a flow of the targeted category is found. If False, the background search continues until all flows of the targeted category are found within the given number of background layers to explore. :param esm_end_use_demands: list of end-use demand categories for the ESM, needed for double-counting removal on construction and resource datasets :param remove_double_counting_to: list of phases to apply double-counting removal to, can be 'Operation', 'Construction', 'Decommission', and/or 'Resource'. Default is ['Operation']. :param extract_eol_from_construction: if True, the end-of-life flows are set to zero in the construction dataset, and they are used to build the decommission dataset of the technology. .. py:method:: _add_activities_to_database(act_type: str) -> None Add new activities to the main database :param act_type: the type of activity, it can be 'Construction', 'Decommission', 'Operation', or 'Resource' :return: None .. py:method:: _add_technology_specifics(mapping_op: pandas.DataFrame) -> pandas.DataFrame Add technology-specific inputs to the model file :param mapping_op: operation activities, mapping file merged with the model file :return: the updated mapping file .. py:method:: _create_new_activity(name: str, act_type: str, current_code: str, new_code: str, database_name: str, db_as_dict_code: dict) -> dict Create a new LCI dataset for the ESM technology or resource :param name: name of the technology or resource in the ESM :param act_type: the type of activity, it can be 'Construction', 'Decommission', 'Operation', or 'Resource' :param current_code: code of the activity in the original LCI database :param new_code: code of the new activity in the new LCI database :param database_name: name of the original LCI database :param db_as_dict_code: dictionary of the original LCI database with (database, code) as key :return: the new LCI dataset for the technology or resource .. py:method:: _get_activity_name_or_code(tech: str, return_type: str, phase: str = 'Operation') -> str Returns the name of code of the activity :param tech: name of the ESM technology :param return_type: type of return, can be 'name' or 'code' :param phase: phase of the technology, can be 'Operation', 'Construction', 'Decommission' or 'Resource' :return: name or code .. py:method:: _get_new_code() -> None Creates the New_code column in the mapping DataFrame, which contains the new code from the ESM database. :return: None (updates the mapping DataFrame) .. py:method:: _get_new_code_iteration(row: pandas.Series, esm_db_as_dict_name: dict) -> str Function to iterate over the rows of the mapping DataFrame and get the new code for each activity. :param row: row of the mapping DataFrame :param esm_db_as_dict_name: dictionary of the ESM database with (name, product, location, database) as key :return: code of the activity in the ESM database .. py:method:: _get_new_code_previous_years(row: pandas.Series, esm_db_as_dict_name: dict) -> str Function to iterate over the rows of the mapping DataFrame and get the new code for each activity, considering the year of the activity. This is used when operation metrics for all time steps are required. :param row: row of the mapping DataFrame :param esm_db_as_dict_name: dictionary of the ESM database with (name, product, location, database) as key :return: code of the activity in the ESM database .. py:method:: _get_original_code() -> None Creates the Current_code column in the mapping DataFrame, which contains the original code from the main database. :return: None (updates the mapping DataFrame) .. py:method:: _modify_written_activities(db: mescal.database.Database, db_type: str = 'esm') -> None Modify the written database according to the tech_specifics.csv file and using functions from modify_inventory.py :param db: LCI database :param db_type: type of LCI database can be 'esm', 'esm results' or 'main' :return: None (activities are modified in the brightway project) .. py:method:: check_inputs() -> None Check if the inputs are consistent and send feedback to the user :return: None .. py:method:: clean_inputs() -> None Based on the content of the mapping and model files, other input dataframes are cleaned to keep only the relevant rows. :return: None .. py:method:: create_esm_database(return_database: bool = False, write_database: bool = True, write_double_counting_removal_reports: bool = True) -> mescal.database.Database | None Create the ESM database after double counting removal. Three csv files summarizing the double-counting removal process are automatically saved in the results folder: double_counting_removal.csv (amount of removed flows and number of flows set to zero), removed_flows_list.csv (specific activities in which the flows were removed), and validation_double_counting.csv (comparing amounts of removed flows in LCI datasets with amounts present in the ESM). :param return_database: if True, return the ESM database as a mescal.Database object :param write_database: if True, write the ESM database to Brightway :param write_double_counting_removal_reports: if True, write the double-counting removal reports in the results folder :return: the ESM database if return_database is True, None otherwise .. py:attribute:: accepted_locations .. py:property:: activities_background_search .. py:attribute:: added_decom_to_input_data :value: False .. py:property:: background_search_act .. py:attribute:: best_loc_in_ranking .. py:attribute:: biosphere_db_name :value: 'biosphere3' .. py:attribute:: df_activities_subject_to_double_counting :value: None .. py:attribute:: df_flows_set_to_zero :value: None .. py:attribute:: double_counting_removal_amount :value: None .. py:attribute:: efficiency :value: None .. py:attribute:: efficiency_differences_report :value: None .. py:attribute:: esm_db :value: None .. py:attribute:: esm_db_name .. py:attribute:: esm_end_use_demands .. py:attribute:: esm_location :value: 'GLO' .. py:attribute:: esm_results_db_name .. py:attribute:: extract_eol_from_construction :value: False .. py:property:: import_export_list .. py:attribute:: lifetime :value: None .. py:attribute:: list_of_years :value: [None] .. py:attribute:: locations_list .. py:attribute:: locations_ranking :value: None .. py:attribute:: logger .. py:attribute:: main_database .. py:attribute:: main_database_name .. py:attribute:: mapping .. py:property:: mapping_constr .. py:property:: mapping_decom .. py:attribute:: mapping_esm_flows_to_CPC_cat .. py:property:: mapping_infra .. py:property:: mapping_op .. py:property:: mapping_res .. py:property:: mapping_tech .. py:attribute:: max_depth_double_counting_search :value: 10 .. py:attribute:: model .. py:property:: no_background_search_list .. py:property:: no_construction_list .. py:property:: no_decommission_list .. py:property:: no_double_counting_removal_list .. py:attribute:: operation_metrics_for_all_time_steps :value: False .. py:attribute:: pathway :value: False .. py:attribute:: products_without_a_cpc_category .. py:attribute:: regionalize_foregrounds :value: [] .. py:attribute:: remove_double_counting_to .. py:attribute:: resources_without_unit_conversion_factor .. py:attribute:: results_path_file :value: 'results/' .. py:attribute:: spatialized_biosphere_db :value: None .. py:attribute:: spatialized_database :value: True .. py:attribute:: stop_background_search_when_first_flow_found :value: False .. py:attribute:: tech_specifics .. py:attribute:: tech_to_remove_layers :value: None .. py:attribute:: technology_compositions .. py:attribute:: unit_conversion .. py:attribute:: year :value: None .. py:class:: PathwayESM(time_steps: list[dict], operation_metrics_for_all_time_steps: bool = False, *args, **kwargs) Bases: :py:obj:`ESM` The PathwayESM class inherits from the ESM class and is used to create the ESM databases, impact score dataframes, .dat files, etc. corresponding to all time steps of a pathway ESM. Initialize the PathwayESM class. See ESM.__init__ for full argument documentation. :param time_steps: List of dictionaries, each containing parameters for a time step in the pathway ESM. A time step should contain at least the 'year' and 'main_database' keys, and optionally 'main_database_name', 'model' and 'lifetime'. :param operation_metrics_for_all_time_steps: if True, the operation metrics for technologies that were installed in previous time steps (i.e., with a different efficiency that the one of the current year) are added to each yearly database. .. py:method:: _add_operation_metrics_for_previous_time_steps(all_esm_databases: mescal.database.Database, write_database: bool) -> mescal.database.Database .. py:method:: change_location_mapping_file() -> None .. py:method:: compute_impact_scores(esm_db_name: str = None, *args, **kwargs) -> tuple[pandas.DataFrame, pandas.DataFrame | None, pandas.DataFrame | None] .. py:method:: connect_esm_results_to_database(esm_results_db_name: str = None, specific_db_name: str = None, *args, **kwargs) -> None .. py:method:: create_esm_database(return_database: bool = False, write_database: bool = True, *args, **kwargs) -> mescal.database.Database | None Create the ESM database after double counting removal. Three csv files summarizing the double-counting removal process are automatically saved in the results folder: double_counting_removal.csv (amount of removed flows and number of flows set to zero), removed_flows_list.csv (specific activities in which the flows were removed), and validation_double_counting.csv (comparing amounts of removed flows in LCI datasets with amounts present in the ESM). :param return_database: if True, return the ESM database as a mescal.Database object :param write_database: if True, write the ESM database to Brightway :param write_double_counting_removal_reports: if True, write the double-counting removal reports in the results folder :return: the ESM database if return_database is True, None otherwise .. py:method:: create_new_database_with_esm_results(esm_results: pandas.DataFrame, esm_results_db_name: str = None, return_database: bool = False, *args, **kwargs) -> mescal.database.Database | None .. py:attribute:: list_of_years .. py:attribute:: mapping .. py:attribute:: operation_metrics_for_all_time_steps :value: False .. py:attribute:: pathway :value: True .. py:attribute:: time_steps .. py:attribute:: year :value: None .. py:function:: has_construction(row: pandas.Series, no_construction_list: list[str]) -> int Add a construction input to technologies that have a construction phase :param row: row of the model file :param no_construction_list: list of technologies for which the construction phase is not considered :return: 0 if no construction phase, -1 otherwise .. py:function:: has_decommission(row: pandas.Series, no_decommission_list: list[str]) -> int Add a decommissioning input to technologies that have a decommissioning phase outside their construction phase :param row: row of the model file :param no_decommission_list: list of technologies for which the decommissioning phase is not considered :return: -1 if decommissioning phase, 0 otherwise .. py:function:: is_process_activity(row: pandas.Series, process_list: list[str]) -> int Add a fuel input to process activities that could have a mismatch :param row: row of the model file :param process_list: list of process activities :return: -1 if process activity, 0 otherwise .. py:function:: is_transport(row: pandas.Series, mobility_list: list[str]) -> int Add a fuel input to mobility technologies (due to possible mismatch) :param row: row of the model file :param mobility_list: list of mobility technologies :return: -1 if mobility technology, 0 otherwise