mescal.esm

Classes

ESM

Class that represents the ESM database, that can be modified with double-counting removal, regionalization,

PathwayESM

The PathwayESM class inherits from the ESM class and is used to create the ESM databases, impact score

Functions

is_transport(→ int)

Add a fuel input to mobility technologies (due to possible mismatch)

Module Contents

class mescal.esm.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)[source]

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

Parameters:

  • mapping (pandas.DataFrame) – mapping between the ESM resources, technologies (operation and construction) and flows, and the LCI database activities

  • model (pandas.DataFrame) – dataframe containing the inputs and outputs of each technology in the ESM

  • unit_conversion (pandas.DataFrame) – dataframe containing unit conversion factors for all ESM technologies, resources and flows

  • tech_specifics (pandas.DataFrame) – dataframe containing the specific requirements (if any) of the ESM technologies

  • technology_compositions (pandas.DataFrame) – dataframe containing (if any) the compositions of technologies

  • mapping_esm_flows_to_CPC_cat (pandas.DataFrame) – mapping between ESM flows and CPC categories

  • main_database (mescal.database.Database) – main LCI database, e.g., ecoinvent or premise database (with CPC categories)

  • esm_db_name (str) – name of the ESM database to be written in Brightway

  • main_database_name (str) – 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

  • biosphere_db_name (str) – name of the (not spatialized) biosphere database. Default is ‘biosphere3’.

  • results_path_file (str) – path to your result folder. Default is ‘results/’.

  • regionalize_foregrounds (str or list[str]) – 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).

  • accepted_locations (list[str]) – list of ecoinvent locations to keep without modification in case of regionalization. Default is None (only the esm_location is accepted).

  • esm_location (str) – ecoinvent location corresponding to the geographical scope of the ESM

  • locations_ranking (list[str]) – ranking of the preferred ecoinvent locations in case of regionalization

  • spatialized_biosphere_db (mescal.database.Database) – spatialized biosphere database

  • efficiency (pandas.DataFrame) – dataframe containing the ESM technologies to correct regarding efficiency differences between the ESM and LCI database

  • lifetime (pandas.DataFrame) – dataframe containing the lifetime of the ESM technologies

  • max_depth_double_counting_search (int) – maximum recursion depth of the double-counting background search algorithm. Default is 10.

  • stop_background_search_when_first_flow_found (bool) – 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.

  • esm_end_use_demands (list[str]) – list of end-use demand categories for the ESM, needed for double-counting removal on construction and resource datasets

  • remove_double_counting_to (list[str]) – list of phases to apply double-counting removal to, can be ‘Operation’, ‘Construction’, ‘Decommission’, and/or ‘Resource’. Default is [‘Operation’].

  • extract_eol_from_construction (bool) – 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.

_add_activities_to_database(act_type: str) → None[source]

Add new activities to the main database

Parameters:

act_type (str) – the type of activity, it can be ‘Construction’, ‘Decommission’, ‘Operation’, or ‘Resource’

Returns:

None

Return type:

None

_add_technology_specifics(mapping_op: pandas.DataFrame) → pandas.DataFrame[source]

Add technology-specific inputs to the model file

Parameters:

mapping_op (pandas.DataFrame) – operation activities, mapping file merged with the model file

Returns:

the updated mapping file

Return type:

pandas.DataFrame

_create_new_activity(name: str, act_type: str, current_code: str, new_code: str, database_name: str, db_as_dict_code: dict) → dict[source]

Create a new LCI dataset for the ESM technology or resource

Parameters:

  • name (str) – name of the technology or resource in the ESM

  • act_type (str) – the type of activity, it can be ‘Construction’, ‘Decommission’, ‘Operation’, or ‘Resource’

  • current_code (str) – code of the activity in the original LCI database

  • new_code (str) – code of the new activity in the new LCI database

  • database_name (str) – name of the original LCI database

  • db_as_dict_code (dict) – dictionary of the original LCI database with (database, code) as key

Returns:

the new LCI dataset for the technology or resource

Return type:

dict

_get_activity_name_or_code(tech: str, return_type: str, phase: str = 'Operation') → str[source]

Returns the name of code of the activity

Parameters:

  • tech (str) – name of the ESM technology

  • return_type (str) – type of return, can be ‘name’ or ‘code’

  • phase (str) – phase of the technology, can be ‘Operation’, ‘Construction’, ‘Decommission’ or ‘Resource’

Returns:

name or code

Return type:

str

_get_new_code() → None[source]

Creates the New_code column in the mapping DataFrame, which contains the new code from the ESM database.

Returns:

None (updates the mapping DataFrame)

Return type:

None

_get_new_code_iteration(row: pandas.Series, esm_db_as_dict_name: dict) → str[source]

Function to iterate over the rows of the mapping DataFrame and get the new code for each activity.

Parameters:

  • row (pandas.Series) – row of the mapping DataFrame

  • esm_db_as_dict_name (dict) – dictionary of the ESM database with (name, product, location, database) as key

Returns:

code of the activity in the ESM database

Return type:

str

_get_new_code_previous_years(row: pandas.Series, esm_db_as_dict_name: dict) → str[source]

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.

Parameters:

  • row (pandas.Series) – row of the mapping DataFrame

  • esm_db_as_dict_name (dict) – dictionary of the ESM database with (name, product, location, database) as key

Returns:

code of the activity in the ESM database

Return type:

str

_get_original_code() → None[source]

Creates the Current_code column in the mapping DataFrame, which contains the original code from the main database.

Returns:

None (updates the mapping DataFrame)

Return type:

None

_modify_written_activities(db: mescal.database.Database, db_type: str = 'esm') → None[source]

Modify the written database according to the tech_specifics.csv file and using functions from modify_inventory.py

Parameters:

  • db (mescal.database.Database) – LCI database

  • db_type (str) – type of LCI database can be ‘esm’, ‘esm results’ or ‘main’

Returns:

None (activities are modified in the brightway project)

Return type:

None

check_inputs() → None[source]

Check if the inputs are consistent and send feedback to the user

Returns:

None

Return type:

None

clean_inputs() → None[source]

Based on the content of the mapping and model files, other input dataframes are cleaned to keep only the relevant rows.

Returns:

None

Return type:

None

create_esm_database(return_database: bool = False, write_database: bool = True, write_double_counting_removal_reports: bool = True) → mescal.database.Database | None[source]

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).

Parameters:

  • return_database (bool) – if True, return the ESM database as a mescal.Database object

  • write_database (bool) – if True, write the ESM database to Brightway

  • write_double_counting_removal_reports (bool) – if True, write the double-counting removal reports in the results folder

Returns:

the ESM database if return_database is True, None otherwise

Return type:

mescal.database.Database | None

accepted_locations[source]
added_decom_to_input_data = False[source]
property background_search_act[source]
best_loc_in_ranking[source]
biosphere_db_name = 'biosphere3'[source]
df_activities_subject_to_double_counting = None[source]
df_flows_set_to_zero = None[source]
double_counting_removal_amount = None[source]
efficiency = None[source]
efficiency_differences_report = None[source]
esm_db = None[source]
esm_db_name[source]
esm_end_use_demands[source]
esm_location = 'GLO'[source]
esm_results_db_name[source]
extract_eol_from_construction = False[source]
property import_export_list[source]
lifetime = None[source]
list_of_years = [None][source]
locations_list[source]
locations_ranking = None[source]
logger[source]
main_database[source]
main_database_name[source]
mapping[source]
property mapping_constr[source]
property mapping_decom[source]
mapping_esm_flows_to_CPC_cat[source]
property mapping_infra[source]
property mapping_op[source]
property mapping_res[source]
property mapping_tech[source]
missing_construction_flow = None[source]
missing_input_flow_dict = None[source]
model[source]
property no_background_search_list[source]
property no_construction_list[source]
property no_decommission_list[source]
property no_double_counting_removal_list[source]
operation_metrics_for_all_time_steps = False[source]
pathway = False[source]
products_without_a_cpc_category[source]
regionalize_foregrounds = [][source]
remove_double_counting_to[source]
resources_without_unit_conversion_factor[source]
results_path_file = 'results/'[source]
spatialized_biosphere_db = None[source]
spatialized_database = True[source]
stop_background_search_when_first_flow_found = False[source]
tech_specifics[source]
tech_to_remove_layers = None[source]
technology_compositions[source]
unit_conversion[source]
year = None[source]
class mescal.esm.PathwayESM(time_steps: list[dict], operation_metrics_for_all_time_steps: bool = False, *args, **kwargs)[source]

Bases: 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.

Parameters:

  • time_steps (list[dict]) – 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’.

  • operation_metrics_for_all_time_steps (bool) – 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.

_add_operation_metrics_for_previous_time_steps(all_esm_databases: mescal.database.Database, write_database: bool) → mescal.database.Database[source]
Parameters:
Return type:

mescal.database.Database

change_location_mapping_file() → None[source]
Return type:

None

compute_impact_scores(esm_db_name: str = None, *args, **kwargs) → tuple[pandas.DataFrame, pandas.DataFrame | None, pandas.DataFrame | None][source]
Parameters:

esm_db_name (str)

Return type:

tuple[pandas.DataFrame, pandas.DataFrame | None, pandas.DataFrame | None]

connect_esm_results_to_database(esm_results_db_name: str = None, specific_db_name: str = None, *args, **kwargs) → None[source]
Parameters:

  • esm_results_db_name (str)

  • specific_db_name (str)

Return type:

None

create_esm_database(return_database: bool = False, write_database: bool = True, *args, **kwargs) → mescal.database.Database | None[source]

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).

Parameters:

  • return_database (bool) – if True, return the ESM database as a mescal.Database object

  • write_database (bool) – if True, write the ESM database to Brightway

  • write_double_counting_removal_reports – if True, write the double-counting removal reports in the results folder

Returns:

the ESM database if return_database is True, None otherwise

Return type:

mescal.database.Database | None

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[source]
Parameters:

  • esm_results (pandas.DataFrame)

  • esm_results_db_name (str)

  • return_database (bool)

Return type:

mescal.database.Database | None

list_of_years[source]
mapping[source]
operation_metrics_for_all_time_steps = False[source]
pathway = True[source]
time_steps[source]
year = None[source]
mescal.esm.is_transport(row: pandas.Series, mobility_list: list[str]) → int[source]

Add a fuel input to mobility technologies (due to possible mismatch)

Parameters:

  • row (pandas.Series) – row of the model file

  • mobility_list (list[str]) – list of mobility technologies

Returns:

-1 if mobility technology, 0 otherwise

Return type:

int