Technical Reference¶

Searching¶

wurst.searching.equals(field, value)¶: Return function where input field value is equal to value

wurst.searching.contains(field, value)¶

wurst.searching.startswith(field, value)¶

wurst.searching.either(*funcs)¶: Return True is any of the function evaluate true

wurst.searching.exclude(func)¶: Return the opposite of func (i.e. False instead of True)

wurst.searching.doesnt_contain_any(field, values)¶: Exclude all dataset whose field contains any of values

wurst.searching.get_many(data, *funcs)¶: Apply all filter functions funcs to data

wurst.searching.get_one(data, *funcs)¶

Apply filter functions funcs to data, and return exactly one result.

Raises wurst.errors.NoResults or wurst.errors.MultipleResults if zero or multiple results are returned.

Exchange iterators¶

wurst.searching.technosphere(ds, *funcs)¶: Get all technosphere exchanges in ds that pass filtering functions funcs

wurst.searching.biosphere(ds, *funcs)¶: Get all biosphere exchanges in ds that pass filtering functions funcs

wurst.searching.production(ds, *funcs)¶: Get all production exchanges in ds that pass filtering functions funcs

wurst.searching.reference_product(ds)¶

Get single reference product exchange from a dataset.

Raises wurst.errors.NoResults or wurst.errors.MultipleResults if zero or multiple results are returned.

Geo functions¶

wurst.transformations.geo.copy_to_new_location(ds, location)¶

Copy dataset and substitute new location.

Doesn’t change exchange locations, except for production exchanges.

Returns the new dataset.

wurst.transformations.geo.relink_technosphere_exchanges(ds, data, exclusive=True, drop_invalid=False, biggest_first=False, contained=True)¶

Find new technosphere providers based on the location of the dataset.

Designed to be used when the dataset’s location changes, or when new datasets are added.

Uses the name, reference product, and unit of the exchange to filter possible inputs. These must match exactly. Searches in the list of datasets data.

Will only search for providers contained within the location of ds, unless contained is set to False, all providers whose location intersects the location of ds will be used.

A RoW provider will be added if there is a single topological face in the location of ds which isn’t covered by the location of any providing activity.

If no providers can be found, relink_technosphere_exchanes will try to add a RoW or GLO providers, in that order, if available. If there are still no valid providers, a InvalidLink exception is raised, unless drop_invalid is True, in which case the exchange will be deleted.

Allocation between providers is done using allocate_inputs; results seem strange if contained=False, as production volumes for large regions would be used as allocation factors.

Input arguments:

ds: The dataset whose technosphere exchanges will be modified.

data: The list of datasets to search for technosphere product providers.

exclusive: Bool, default is True. Don’t allow overlapping locations in input providers.

drop_invalid: Bool, default is False. Delete exchanges for which no valid provider is available.

biggest_first: Bool, default is False. Determines search order when selecting provider locations. Only relevant is exclusive is True.

contained: Bool, default is True. If ture, only use providers whose location is completely within the ds location; otherwise use all intersecting locations.

Modifies the dataset in place; returns the modified dataset.

wurst.transformations.geo.allocate_inputs(exc, lst)¶

Allocate the input exchanges in lst to exc, using production volumes where possible, and equal splitting otherwise.

Always uses equal splitting if RoW is present.

wurst.transformations.default_global_location(database)¶

Set missing locations to `GLO` for datasets in database.

Changes location if location is missing or None. Will add key location if missing.

Linking¶

wurst.linking.link_internal(data, fields=('name', 'product', 'location', 'unit'))¶: Link internal exchanges by fields. Creates input field in newly-linked exchanges.

wurst.linking.check_internal_linking(data)¶: Check that each internal link is to an actual activity

wurst.linking.change_db_name(data, name)¶

Change the database of all datasets in data to name.

Raises errors if each dataset does not have exactly one reference production exchange.

wurst.linking.check_duplicate_codes(data)¶: Check that there won’t be duplicate codes when activities are merged to new, common database

Transformations¶

wurst.transformations.activity.change_exchanges_by_constant_factor(ds, value, technosphere_filters=None, biosphere_filters=None)¶

Change some or all inputs and biosphere flows by a constant factor.

ds is a dataset document.
value is a number. Existing exchange amounts will be multiplied by this number.
technosphere_filters is an iterable of filter functions. Optional.
biosphere_filters is an iterable of filter functions. Optional.

Returns the altered dataset. The dataset is also modified in place, so the return value can be ignored.

Example: Changing coal dataset to reflect increased fuel efficiency

import wurst as w

apct_products = w.either(
    w.equals('name', 'market for NOx retained'),
    w.equals('name', 'market for SOx retained'),
)

generation_filters = [
    w.either(w.contains('name', 'coal'), w.contains('name', 'lignite')),
    w.contains('name', 'electricity'),
    w.equals('unit', 'kilowatt hour'),
    w.doesnt_contain_any('name', [
        'market', 'aluminium industry',
        'coal, carbon capture and storage'
    ])
]

fuel_independent = w.doesnt_contain_any('name', (
    'Methane, fossil', 'Sulfur dioxide', 'Carbon monoxide, fossil',
    'Nitrogen oxides', 'Dinitrogen monoxide', 'Particulates'
))

for ds in w.get_many(data, generation_filters):
    change_exchanges_by_constant_factor(
        ds,
        0.8,  # Or whatever from input data
        [w.exclude(apct_products)],
        [fuel_independent]
    )

wurst.transformations.delete_zero_amount_exchanges(data, drop_types=None)¶

Drop all zero value exchanges from a list of datasets.

drop_types is an optional list of strings, giving the type of exchanges to drop; default is to drop all types.

Returns the modified data.

wurst.transformations.rescale_exchange(exc, value, remove_uncertainty=True)¶

Dummy function to rescale exchange amount and uncertainty.

This depends on some code being separated from Ocelot, which will take a bit of time.

exc is an exchange dataset.
value is a number, to be multiplied by the existing amount.
remove_uncertainty: Remove (unscaled) uncertainty data, default is True.

Returns the modified exchange.

wurst.transformations.empty_market_dataset(ds, exclude=None)¶

Remove input exchanges from a market dataset, in preparation for input exchanges defined by an external data source.

Removes all exchanges which have the same flow as the reference product of the exchange. exclude is an iterable of activity names to exclude.

Brightway IO¶

wurst.brightway.extract_database.extract_brightway2_databases(database_names, add_properties=False, add_identifiers=False)¶

Extract a Brightway2 SQLiteBackend database to the Wurst internal format.

database_names is a list of database names. You should already be in the correct project.

Returns a list of dataset documents.

wurst.brightway.write_database.write_brightway2_database(data, name)¶

Write a new database as a new Brightway2 database named name.

You should be in the correct project already.

This function will do the following:

Change the database name for all activities and internal exchanges to name. All activities will have the new database name, even if the original data came from multiple databases.
Relink exchanges using the default fields: ('name', 'product', 'location', 'unit').
Check that all internal links resolve to actual activities, If the input value is ('name', 'bar'), there must be an activity with the code bar.
Check to make sure that all activity codes are unique
Write the data to a new Brightway2 SQLite database

Will raise an assertion error is name already exists.

Doesn’t return anything.