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

`has_construction`(→ int)	Add a construction input to technologies that have a construction phase
`has_decommission`(→ int)	Add a decommissioning input to technologies that have a decommissioning phase outside their construction phase
`is_process_activity`(→ int)	Add a fuel input to process activities that could have a mismatch
`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]

property activities_background_search[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]

max_depth_double_counting_search = 10[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:

all_esm_databases (mescal.database.Database)
write_database (bool)

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.has_construction(row: pandas.Series, no_construction_list: list[str]) → int[source]

Add a construction input to technologies that have a construction phase

Parameters:

row (pandas.Series) – row of the model file
no_construction_list (list[str]) – list of technologies for which the construction phase is not considered

Returns:

0 if no construction phase, -1 otherwise

Return type:

int

mescal.esm.has_decommission(row: pandas.Series, no_decommission_list: list[str]) → int[source]

Add a decommissioning input to technologies that have a decommissioning phase outside their construction phase

Parameters:

row (pandas.Series) – row of the model file
no_decommission_list (list[str]) – list of technologies for which the decommissioning phase is not considered

Returns:

-1 if decommissioning phase, 0 otherwise

Return type:

int

mescal.esm.is_process_activity(row: pandas.Series, process_list: list[str]) → int[source]

Add a fuel input to process activities that could have a mismatch

Parameters:

row (pandas.Series) – row of the model file
process_list (list[str]) – list of process activities

Returns:

-1 if process activity, 0 otherwise

Return type:

int

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