New Wurst Database

class premise.ecoinvent_modification.NewDatabase(*args: Any, **kwargs: Any)

Database Cleaner

class premise.clean_datasets.DatabaseCleaner(source_db: str, source_type: str, source_file_path: Path | None, version: str)

Clean datasets contained in inventory databases for further processing.

add_location_field_to_exchanges() → None

Add the location key to production and technosphere exchanges.

Raises:

KeyError – If no matching activity can be found for an exchange input.

add_product_field_to_exchanges() → None

Populate the product key on production and technosphere exchanges.

Raises:

KeyError – If no corresponding activity can be found for an exchange input.

correct_biogas_activities() → None

Balance carbon and energy flows for specific biogas activities.

find_location_given_lookup_dict(lookup_dict: Dict[str, str]) → List[str]

Return locations matching the filters in lookup_dict.

Parameters:

lookup_dict (Dict[str, str]) – Field/value pairs used to filter activities.

Returns:

List of location identifiers corresponding to the filters.

Return type:

List[str]

find_product_given_lookup_dict(lookup_dict: Dict[str, str]) → List[str]

Return products matching the filters in lookup_dict.

Parameters:

lookup_dict (Dict[str, str]) – Field/value pairs used to filter activities.

Returns:

List of product names corresponding to the filters.

Return type:

List[str]

fix_biosphere_flow_categories() → None

Ensure biosphere exchanges include category information.

fix_unset_technosphere_and_production_exchange_locations(matching_fields: Tuple[str, str] = ('name', 'unit')) → None

Fill missing locations for production and technosphere exchanges.

Parameters:

matching_fields (Tuple[str, str]) – Fields used to look up potential location matches.

prepare_datasets(keep_uncertainty_data: bool) → List[dict]

Run the standard cleaning pipeline on the loaded database.

Parameters:

keep_uncertainty_data (bool) – Flag indicating whether to preserve uncertainty data.

Returns:

Cleaned database ready for further processing.

Return type:

List[dict]

transform_parameter_field() → None

Transform the parameter field from lists to dictionaries.

Inventory Imports

class premise.inventory_imports.BaseInventoryImport(database: List[dict], version_in: str, version_out: str, path: str | Path, system_model: str, keep_uncertainty_data: bool = False)

Base class for inventories that are to be merged with the wurst database.

Variables:

database – the target database for the import (the ecoinvent database),

unpacked to a list of dicts :ivar version_in: the ecoinvent database version of the inventory to import :ivar version_out: the ecoinvent database version the imported inventories should comply with :ivar path: the filepath of the inventories to import

__init__(database: List[dict], version_in: str, version_out: str, path: str | Path, system_model: str, keep_uncertainty_data: bool = False) → None

Create a BaseInventoryImport instance.

Add links for biosphere exchanges to import_db Modifies the import_db attribute in place.

add_product_field_to_exchanges() → None

Add the product key to the production and technosphere exchanges in import_db. Also add code field if missing. For production exchanges, use the value of the reference_product field. For technosphere exchanges, search the activities in import_db and use the reference product. If none is found, search the Ecoinvent database. Modifies the import_db attribute in place. :raises IndexError: if no corresponding activity (and reference product) can be found.

check_for_already_existing_datasets() → None

Check whether the inventories to be imported are not already in the source database.

check_units() → None

Check that the units of the exchanges are compliant with the ecoinvent database. :returns: Nothing

correct_product_field(exc: tuple) → [<class 'str'>, None]

Find the correct name for the product field of the exchange :param exc: a dataset exchange :return: name of the product field of the exchange

display_unlinked_exchanges()

Display the list of unlinked exchanges using prettytable

fill_data_gaps(exc)

Some datatsets have the exchange amount set to zero because of ecoinvent license restrictions We need to replace the zero value with the correct amount, which we find in the ecoinvent database.

load_inventory() → None

Load an inventory from a specified path. Sets the import_db attribute. :returns: Nothing.

merge_inventory() → List[dict]

Prepare import_db and merge the inventory to the ecoinvent database. Calls prepare_inventory(). Changes the database attribute. :returns: Nothing

prepare_inventory() → None

Prepare the inventory for the merger with Ecoinvent. Modifies import_db in-place. :returns: Nothing

remove_ds_and_modifiy_exchanges(name: str, ex_data: dict) → None

Remove an activity dataset from import_db and replace the corresponding technosphere exchanges by what is given as second argument. :param str name: name of activity to be removed :param dict ex_data: data to replace the corresponding exchanges :returns: Nothing

search_missing_exchanges(label: str, value: str) → List[dict]

Return a list of activities for which a given exchange cannot be found :param label: the label of the field to look for :param value: the value of the field to look for :return:

search_missing_field(field: str, scope: str = 'activity') → List[dict]

Find exchanges and activities that do not contain a specific field in imort_db :param str field: label of the field to search for. :param scope: “activity” or “all”. whether to search in the activity or the activity and its exchanges :returns: a list of dictionaries, activities and exchanges :rtype: list

Remind Data Collection

class premise.data_collection.IAMDataCollection(model: str, pathway: str, year: int, filepath_iam_files: Path, key: bytes, external_scenarios: dict | None = None, system_model: str = 'cutoff', system_model_args: dict | None = None, gains_scenario: str = 'CLE', use_absolute_efficiency: bool = False)
Variables:

  • model – name of the IAM model (e.g., “remind”)

  • pathway – name of the IAM scenario (e.g., “SSP2-Base”)

  • year – year to produce the database for

  • system_model – “cutoff” or “consequential”.

fetch_external_data_battery_mobile_scenarios()

Fetch external data on mobile battery scenarios.

fetch_external_data_battery_stationary_scenarios(exclude_chemistries: List[str] | None = None)

Fetch external data on stationary battery scenarios.

fetch_external_data_coal_power_plants()

Fetch data on coal power plants from external sources. Source: Oberschelp, C., Pfister, S., Raptis, C.E. et al. Global emission hotspots of coal power generation. Nat Sustain 2, 113–121 (2019). https://doi.org/10.1038/s41893-019-0221-6

get_external_data(external_scenarios: List[Dict[str, Any]]) → Dict[int, Dict[str, Any]]

Fetch data from external sources.

Parameters

external_scenarioslist of dict
Each dict has keys:

  • “scenario”: str (scenario name to filter the table)

  • “data”: a data package-like object exposing get_resource(name)->resource,

    where resource has .raw_read() (bytes) and optionally .headers

Returns

dict
{i: {

‘production volume’: xarray.DataArray (optional), ‘efficiency’: xarray.DataArray (optional), ‘regions’: list of regions present in the subset (if PV was found), ‘config’: parsed YAML config

}}

get_iam_efficiencies(data: DataArray, efficiency_labels: dict | None = None, production_labels: dict | None = None, energy_labels: dict | None = None, use_absolute_efficiency: bool = False) → [<class 'xarray.core.dataarray.DataArray'>, None]

This method retrieves efficiency values for the specified sector, for a specified year, for each region provided by the IAM.

Parameters:

  • data – The data to process.

  • efficiency_labels – The efficiency labels to use.

  • production_labels – The production labels to use.

  • energy_labels – The energy labels to use.

  • use_absolute_efficiency – If True, the efficiency is considered as absolute.

Returns:

a multidimensional array with sector’s technologies market

share for a given year, for all regions.

Remind to Ecoinvent mapping

class premise.activity_maps.InventorySet(database: List[dict], version: str | None = None, model: str | None = None)

Generate activity mappings between Premise sectors and ecoinvent datasets.

generate_activities_using_metals_map() → Dict[str, List[dict]]

Return mapping of metal-using activities to ecoinvent datasets.

Returns:

Mapping keyed by metal name.

Return type:

ActivityMapping

generate_biomass_map() → Dict[str, List[dict]]

Return mapping of biomass technologies to ecoinvent activities.

Returns:

Mapping keyed by biomass technology name.

Return type:

ActivityMapping

generate_cdr_map(model: str | None = None) → Dict[str, List[dict]]

Return mapping of carbon dioxide removal technologies to activities.

Parameters:

model (Optional[str]) – IAM model identifier used to filter the mapping.

Returns:

Mapping keyed by carbon removal technology.

Return type:

ActivityMapping

generate_cement_fuels_map() → Dict[str, List[dict]]

Return mapping of cement production fuels to ecoinvent activities.

Returns:

Mapping keyed by cement fuel category.

Return type:

ActivityMapping

generate_cement_map() → Dict[str, List[dict]]

Return mapping of cement production routes to activities.

Returns:

Mapping keyed by cement technology name.

Return type:

ActivityMapping

generate_final_energy_map() → Dict[str, List[dict]]

Return mapping of final energy carriers to activities.

Returns:

Mapping keyed by energy carrier name.

Return type:

ActivityMapping

generate_fuel_map(model: str | None = None) → Dict[str, List[dict]]

Return mapping of fuel supply chains to activities.

Parameters:

model (Optional[str]) – IAM model identifier used to filter the mapping.

Returns:

Mapping keyed by fuel name.

Return type:

ActivityMapping

generate_gains_mapping() → Dict[str, List[dict]]

Return mapping between GAINS variables and ecoinvent datasets.

Returns:

Mapping keyed by GAINS variable name.

Return type:

ActivityMapping

generate_heat_map(model: str | None) → Dict[str, List[dict]]

Return mapping of heat production technologies to activities.

Parameters:

model (Optional[str]) – IAM model identifier used to filter the mapping.

Returns:

Mapping keyed by heat technology name.

Return type:

ActivityMapping

generate_map(filters: Dict[str, dict]) → Dict[str, List[dict]]

Generate an activity mapping using the provided filter definitions.

Parameters:

filters (Dict[str, dict]) – Mapping specifications used to query the database.

Returns:

Dictionary with technology keys and matching datasets.

Return type:

ActivityMapping

generate_metals_activities_map() → Dict[str, List[dict]]

Return mapping of metal-related activities to datasets.

Returns:

Mapping keyed by material name.

Return type:

ActivityMapping

generate_mining_waste_map() → Dict[str, List[dict]]

Return mapping of mining waste management activities.

Returns:

Mapping keyed by mining waste type.

Return type:

ActivityMapping

generate_powerplant_efficiency_bounds() → Tuple[Dict[str, dict], Dict[str, dict]]

Return minimum and maximum efficiency mappings for power plants.

Returns:

Tuple (min_efficiency, max_efficiency) containing lookup dictionaries.

Return type:

Tuple[Dict[str, dict], Dict[str, dict]]

generate_powerplant_fuels_map() → Dict[str, List[dict]]

Return mapping of power plant fuel supply chains to activities.

Returns:

Mapping keyed by fuel technology.

Return type:

ActivityMapping

generate_powerplant_map() → Dict[str, List[dict]]

Return mapping of power plant technologies to activities.

Returns:

Mapping keyed by electricity production technology.

Return type:

ActivityMapping

generate_sets_from_filters(filtr: Dict[str, Dict[str, str | List[str] | Dict[str, str | List[str]]]], database: List[dict] | None = None) → Dict[str, List[dict]]

Generate activity mappings using Wurst filter specifications.

Parameters:

  • filtr (Dict[str, Dict[str, FilterType]]) – Filter configuration mapping technology names to filter definitions.

  • database (Optional[List[dict]]) – Optional database subset to apply the filters on.

Returns:

Mapping keyed by technology name with matching activities as values.

Return type:

ActivityMapping

generate_steel_map() → Dict[str, List[dict]]

Return mapping of steel production routes to activities.

Returns:

Mapping keyed by steel technology name.

Return type:

ActivityMapping

generate_transport_map(transport_type: str) → Dict[str, List[dict]]

Return mapping of transport technologies to activities.

Parameters:

transport_type (str) – Transport mode to retrieve (e.g. "car").

Returns:

Mapping keyed by transport technology.

Return type:

ActivityMapping

generate_vehicle_fuel_map(transport_type: str) → Dict[str, List[dict]]

Return mapping of transport fuel supply chains to activities.

Parameters:

transport_type (str) – Transport mode to retrieve fuel mappings for.

Returns:

Mapping keyed by transport fuel type.

Return type:

ActivityMapping

Electricity markets modelling

class premise.electricity.Electricity(database: List[dict], iam_data: IAMDataCollection, model: str, pathway: str, year: int, version: str, system_model: str, use_absolute_efficiency: bool = False, cache: dict | None = None, index: dict | None = None)

Class that modifies electricity markets in the database based on IAM output data. Inherits from transformation.BaseTransformation.

Variables:

  • database (list) – wurst database, which is a list of dictionaries

  • iam_data (xarray.DataArray) – IAM data

  • model (str) – name of the IAM model (e.g., “remind”, “image”)

  • year (int) – year of the pathway (e.g., 2030)

adjust_aluminium_electricity_markets() → None

Aluminium production is a major electricity consumer. In Ecoinvent, aluminium producers have their own electricity markets. In the IAM, aluminium production is part of the electricity market. We need to adjust the electricity markets of aluminium producers by linking them to the regional electricity markets. However, some aluminium electricity markets are already deeply decarbonized because some smelters are powered by hydroelectricity. Hence, we choose to link aluminium producers to the regional electricity markets but only those that are not already decarbonized, meaning from those regions:

  • RoW

  • IAI Area, Africa

  • CN

  • IAI Area, South America

  • UN-OCEANIA

  • IAI Area, Asia, without China and GCC

  • IAI Area, Gulf Cooperation Council

while we leave untouched the following regions:

  • IAI Area, Russia & RER w/o EU27 & EFTA

  • CA

  • IAI Area, EU27 & EFTA

adjust_coal_power_plant_emissions() → None

Based on: Fetch data on coal power plants from external sources. Source: Oberschelp, C., Pfister, S., Raptis, C.E. et al. Global emission hotspots of coal power generation. Nat Sustain 2, 113–121 (2019). https://doi.org/10.1038/s41893-019-0221-6

We adjust efficiency and emissions of coal power plants, including coal-fired CHPs.

correct_hydropower_water_emissions() → None

Correct the emissions of water for hydropower plants. In Swiss datasets, water evaporation is too high. We use a new factor from Flury and Frischknecht (2021) to correct this. https://treeze.ch/fileadmin/user_upload/downloads/Publications/Case_Studies/Energy/flury-2012-hydroelectric-power-generation.pdf

create_missing_power_plant_datasets() → None

Create missing power plant datasets. We use proxy datasets, copy them and rename them.

create_new_markets_high_voltage() → None

Create high voltage market groups for electricity, based on electricity mixes given by the IAM scenario. Contribution from solar power is added in low voltage market groups. Does not return anything. Modifies the database in place.

create_new_markets_low_voltage() → None

Create low voltage market groups for electricity, by receiving medium voltage market groups as input and adding transformation and distribution losses. Transformation and distribution losses are taken from ei37. Contribution from solar power is added here as well, as most is delivered at low voltage, although CSP delivers at high voltage. Does not return anything. Modifies the database in place.

create_new_markets_medium_voltage() → None

Create medium voltage market groups for electricity, by receiving high voltage market groups as inputs and adding transformation and distribution losses. Contribution from solar power is added in low voltage market groups. Does not return anything. Modifies the database in place.

create_region_specific_power_plants()

Some power plant inventories are not native to ecoinvent but imported. However, they are defined for a specific location (mostly European), but are used in many electricity markets (non-European). Hence, we create region-specific versions of these datasets, to align inputs providers with the geographical scope of the region.

generate_world_market(dataset: dict, regions: List[str]) → dict

Generate the world market for a given dataset and product variables.

Parameters:

  • dataset – The dataset for which to generate the world market.

  • regions – A dictionary of activity datasets, keyed by region.

This function generates the world market exchanges for a given dataset and set of product variables. It first filters out non-production exchanges from the dataset, and then calculates the total production volume for the world using the given product variables. For each region, it calculates the share of the production volume and adds a technosphere exchange to the dataset with the appropriate share.

get_production_per_tech_dict() → Dict[Tuple[str, str], float]

Create a dictionary with tuples (technology, country) as keys and production volumes as values. :return: technology to production volume dictionary :rtype: dict

get_production_weighted_share(supplier: dict, suppliers: List[dict]) → float

Return the share of production of an electricity-producing dataset in a specific location, relative to the summed production of similar technologies in locations contained in the same IAM region. :param supplier: electricity-producing dataset :type supplier: wurst dataset :param suppliers: list of electricity-producing datasets :type suppliers: list of wurst datasets :return: share of production relative to the total population :rtype: float

update_efficiency_of_solar_pv() → None

Update the efficiency of solar PV modules. We look at how many square meters are needed per kilowatt of installed capacity to obtain the current efficiency. Then we update the surface needed according to the projected efficiency. :return:

update_electricity_efficiency() → None

This method modifies each ecoinvent coal, gas, oil and biomass dataset using data from the IAM scenario. Return a wurst database with modified datasets.

Returns:

a wurst database, with rescaled electricity-producing datasets.

Return type:

list

update_electricity_markets() → None

Delete electricity markets. Create high, medium and low voltage market groups for electricity. Link electricity-consuming datasets to newly created market groups for electricity. Return a wurst database with modified datasets.

Returns:

a wurst database with new market groups for electricity

Return type:

list

write_log(dataset, status='created')

Write log file.