`bw2io`#

Subpackages#

Submodules#

Package Contents#

Classes#

`BW2Package`	This is a format for saving objects which implement the datastore API.
`CSVImporter`	Generic CSV importer
`CSVLCIAImporter`	Generic CSV LCIA importer.
`ChemIDPlus`	Use the ChemIDPlus API to lookup synonyms for chemicals, including pesticides.
`DatabaseSelectionToGEXF`	Export a Gephi graph for a selection of activities from a database.
`DatabaseToGEXF`	Export a Gephi graph for a database.
`Ecospold1LCIAImporter`	Importer for Ecospold1 LCIA format.
`ExcelImporter`	Generic Excel importer.
`ExcelLCIAImporter`	Generic Excel LCIA importer.
`Exiobase3MonetaryImporter`
`Migration`	A migration is a set of data that can be used to modify a database.
`MultiOutputEcospold1Importer`	Import and process multi-output datasets in the ecospold 1 format.
`SimaProCSVImporter`
`SimaProLCIACSVImporter`	Importer for SimaPro CSV LCIA data format.
`SingleOutputEcospold1Importer`	Import and process single-output datasets in the ecospold 1 format.
`SingleOutputEcospold2Importer`	Class for importing single-output ecospold2 format LCI databases.
`UnlinkedData`

Functions#

`activity_hash`(data[, fields, case_insensitive])	Hash an activity dataset.
`backup_data_directory`()	Backup data directory to a `.tar.gz` (compressed tar archive) in the user's home directory.
`backup_project_directory`(project)	Backup project data directory to a `.tar.gz` (compressed tar archive) in the user's home directory.
`bw2setup`()
`create_core_migrations`()	Add pre-defined core migrations data files.
`create_default_biosphere3`([overwrite])
`create_default_lcia_methods`([overwrite, ...])
`es2_activity_hash`(activity, flow)	Generate unique ID for ecoinvent3 dataset.
`exiobase_monetary`([version, year, products, name, ...])
`lci_matrices_to_excel`(database_name[, include_descendants])	Export LCI matrices to Excel.
`lci_matrices_to_matlab`(database_name)	Export LCI matrices to Matlab format.
`load_json_data_file`(filename)
`restore_project_directory`(fp)	Restore a backed up project data directory from a `.tar.gz` (compressed tar archive) in the user's home directory.
`useeio11`([name, collapse_products, prune])

Attributes#

`migrations`
`normalize_units`
`unlinked_data`

class bw2io.BW2Package[source]#

Bases: object

This is a format for saving objects which implement the datastore API.

Data is stored as a BZip2-compressed file of JSON data.

This archive format is compatible across Python versions, and is, at least in theory, programming-language agnostic.

Validation is done with bw2data.validate.bw2package_validator. The data format is:

{
    'metadata': {},                                     # Dictionary of metadata to be written to metadata-store.
    'name': basestring,                                 # Name of object
    'class': {                                          # Data on the underlying class. A new class is instantiated
                                                        # based on these strings. See _create_class.
        'module': basestring,                           # e.g. "bw2data.database"
        'name': basestring                              # e.g. "Database"
    },
    'unrolled_dict': bool,                              # Flag indicating if dictionary keys needed to
                                                        # be modified for JSON (as JSON keys can't be tuples)
    'data': object                                      # Object data, e.g. LCIA method or LCI database
}

Warning

Perfect roundtrips between machines are not guaranteed:

All lists are converted to tuples (because JSON does not distinguish between lists and tuples).
Absolute filepaths in metadata would be specific to a certain computer and user.

Notes

This class does not need to be instantiated, as all its methods are classmethods, i.e. do BW2Package.import_obj("foo") instead of BW2Package().import_obj("foo")

APPROVED#

classmethod _create_class(metadata, apply_whitelist=True)#

classmethod _create_obj(data)#

classmethod _get_class_metadata(obj)#

classmethod _is_valid_package(data)#

classmethod _is_whitelisted(metadata)#

classmethod _load_obj(data, whitelist=True)#

classmethod _prepare_obj(obj, backwards_compatible=False)#

classmethod _write_file(filepath, data)#

classmethod export_obj(obj, filename=None, folder='export', backwards_compatible=False)#

Export an object.

Parameters

obj (object) – Object to export.
filename (str, optional) – Name of file to create. Default is obj.name.
folder (str, optional) – Folder to create file in. Default is export.
backwards_compatible (bool, optional) – Create package compatible with bw2data version 1.

Returns

Filepath of created file.

Return type

str

classmethod export_objs(objs, filename, folder='export', backwards_compatible=False)#

Export a list of objects. Can have heterogeneous types.

Parameters

objs (list) – List of objects to export.
filename (str) – Name of file to create.
folder (str, optional) – Folder to create file in. Default is export.
backwards_compatible (bool, optional) – Create package compatible with bw2data version 1.

Returns

Filepath of created file.

Return type

str

classmethod import_file(filepath, whitelist=True)#

Import bw2package file, and create the loaded objects, including registering, writing, and processing the created objects.

Parameters

filepath (str) – Path of file to import
whitelist (bool) – Apply whitelist to allowed types. Default is True.

Returns

Created object or list of created objects.

Return type

object or list of objects

classmethod load_file(filepath, whitelist=True)#

Load a bw2package file with one or more objects. Does not create new objects.

Parameters

filepath (str) – Path of file to import
whitelist (bool) – Apply whitelist of approved classes to allowed types. Default is True.

Returns

"class" is an actual Python class object (but not instantiated).

Return type

The loaded data in the bw2package dict data format, with the following changes

class bw2io.CSVImporter(filepath)#

Bases: ExcelImporter

Generic CSV importer

extractor#

format = 'CSV'#

class bw2io.CSVLCIAImporter(filepath, name, description, unit, **metadata)#

Bases: ExcelLCIAImporter

Generic CSV LCIA importer.

format#

The file format.

Type: str

extractor#

The file extractor class.

Type: class

Initializes the ExcelLCIAImporter object.

Parameters

filepath (str) – The path to the Excel file.
name (tuple) – The name of the LCIA method.
description (str) – The description of the LCIA method.
unit (str) – The unit of the LCIA method.
**metadata – The metadata associated with the LCIA method.

extractor#

format = 'CSV'#

class bw2io.ChemIDPlus[source]#

Use the ChemIDPlus API to lookup synonyms for chemicals, including pesticides.

Always used to match against a master list. Seeded with names from ecoinvent.

api_cache#

Dictionary with raw data from API, key is canonical name.

Type: dict

master_mapping#

Dictionary from synonyms, including canonical names, to master flows.

Type: dict

forbidden_keys#

Identifiers that aren’t unique in the ChemIDPlus system.

Type: set

match(synonym, search=True)#: Match a synonym to a master flow.

match_cas(number)#: Match a CAS number to a master flow.

process_request(request)#: Process a request to the ChemIDPlus API.

load_cache()#: Load the cache of API results.

save_cache()#: Save the cache of API results.

CAS_TEMPLATE = 'https://chem.nlm.nih.gov/api/data/search?data=complete&exp=rn%2Feq%2F{cas}'#

NAME_TEMPLATE = 'https://chem.nlm.nih.gov/api/data/search?data=complete&exp=na%2Feq%2F{name}'#

add_master_term(term, CAS)#

load_cache()#

match(synonym, search=True)#

match_cas(number)#

process_request(response)#

save_cache()#

class bw2io.DatabaseSelectionToGEXF(database, keys)#

Bases: DatabaseToGEXF

Export a Gephi graph for a selection of activities from a database.

Also includes all inputs for the filtered activities.

Parameters

database (str) – Database name.
keys (str) – The activity keys to export.

Examples

>>> dstg = DatabaseSelectionToGEXF(database='example_db', keys=['foo', 'bar'])

class bw2io.DatabaseToGEXF(database, include_descendants=False)#

Bases: object

Export a Gephi graph for a database.

Parameters

database (str) – Database name.
include_descendants (bool, optional) – Include databases which are linked from database. (default False)

Warning

include_descendants is not yet implemented.

Raises: NotImplemented – If include_descendants is True, as this option is not yet implemented.

export()#: Export the Gephi XML file.

get_data(E)#: Get the nodes and edges for the Gephi XML file.

Examples

>>> dtg = DatabaseToGEXF(database='example_db', include_descendants=False)
>>> dtg.export()
'/path/to/example_db.gexf'

>>> dtg = DatabaseToGEXF(database='example_db', include_descendants=True)
>>> dtg.get_data()
(nodes, edges)

export()#

Export the Gephi XML file.

Parameters: None –
Returns: Filepath of the created file.
Return type: str

Examples

>>> dtg = DatabaseToGEXF(database='example_db', include_descendants=False)
>>> dtg.export()
'/path/to/example_db.gexf'

get_data(E)#

Get Gephi nodes and edges.

Parameters

E (lxml.builder.ElementMaker) – ElementMaker object for GEXF XML

Returns

nodes (lxml.etree._Element) – GEXF nodes
edges (lxml.etree._Element) – GEXF edges

Examples

>>> dtg = DatabaseToGEXF(database='example_db', include_descendants=False)
>>> dtg.get_data(E)
(nodes, edges)

class bw2io.Ecospold1LCIAImporter(filepath, biosphere=None)#

Bases: bw2io.importers.base_lcia.LCIAImporter

Importer for Ecospold1 LCIA format.

Parameters

filepath (str) – Path to the Ecospold1 LCIA file.
biosphere (bw2data.BiosphereDatabase, optional) – Biosphere database to use. If None, the default biosphere database will be used.

format#

The format of the LCIA data, which is “Ecospold1 LCIA”.

Type: str

data#

The LCIA data extracted from the Ecospold1 LCIA file.

Type: dict

Initialize the Ecospold1LCIAImporter instance.

Parameters

filepath (str) – Path to the Ecospold1 LCIA file.
biosphere (bw2data.BiosphereDatabase, optional) – Biosphere database to use. If None, the default biosphere database will be used.

format = 'Ecospold1 LCIA'#

class bw2io.ExcelImporter(filepath)#

Bases: bw2io.importers.base_lci.LCIImporter

Generic Excel importer.

See the generic Excel example spreadsheet.

Excel spreadsheet should follow the following format:

::

Project parameters <variable>, <formula>, <amount>, metadata

Database, <name of database> <database field name>, <database field value>

Parameters <variable>, <formula>, <amount>, metadata

Activity, <name of activity> <database field name>, <database field value> Exchanges <field name>, <field name>, <field name> <value>, <value>, <value> <value>, <value>, <value>

Neither project parameters, parameters, nor exchanges for each activity are required.

An activity is marked as finished with a blank line.

In general, data is imported without modification. However, the following transformations are applied:

Numbers are translated from text into actual numbers.
Tuples, separated in the cell by the :: string, are reconstructed.
True and False are transformed to boolean values.
Fields with the value (Unknown) are dropped.

extractor#

format = 'Excel'#

get_activity(sn, ws)#

get_database(data)#

get_database_parameters(data)#

get_labelled_section(sn, ws, index=0, transform=True)#

Turn a list of rows into a list of dictionaries.

The first line of ws is the column labels. All subsequent rows are the data values. Missing columns are dropped.

transform is a boolean: perform CSV transformation functions like csv_restore_tuples.

get_metadata_section(sn, ws, index=0, transform=True)#

get_project_parameters(data)#

Extract project parameters (variables and formulas).

Project parameters are a section that starts with a line with the string “project parameters” (case-insensitive) in the first cell, and ends with a blank line. There can be multiple project parameter sections.

process_activities(data)#: Take list of (sheet names, raw data) and process it.

write_activity_parameters(data=None, delete_existing=True)#

write_database(**kwargs)#: Same as base write_database method, but activate_parameters is True by default.

write_database_parameters(activate_parameters=True, delete_existing=True)#: Same as base write_database_parameters method, but activate_parameters is True by default.

class bw2io.ExcelLCIAImporter(filepath, name, description, unit, **metadata)#

Bases: bw2io.importers.base_lcia.LCIAImporter

Generic Excel LCIA importer.

See the documentation.

format#

The file format. The default format is CSV.

Type: str

extractor#

The file extractor class.

Type: class

Initializes the ExcelLCIAImporter object.

Parameters

filepath (str) – The path to the Excel file.
name (tuple) – The name of the LCIA method.
description (str) – The description of the LCIA method.
unit (str) – The unit of the LCIA method.
**metadata – The metadata associated with the LCIA method.

extractor#

format = 'Excel'#

class bw2io.Exiobase3MonetaryImporter(dirpath, db_name, ignore_small_balancing_corrections=True)#

Bases: bw2io.importers.base_lci.LCIImporter

format = 'Exiobase 3'#

add_unlinked_flows_to_new_biosphere_database(biosphere_name=None)#

apply_strategies(biosphere=None)#

abstract apply_strategy(*args, **kwargs)#

patch_lcia_methods(new_biosphere)#

write_activities_as_database()#

write_database(biosphere=None)#

class bw2io.Migration(*args, **kwargs)[source]#

Bases: bw2data.data_store.DataStore

A migration is a set of data that can be used to modify a database.

Migrations are stored in the migrations directory of the project. They are stored as JSON files, and are registered in the migrations.json file.

write(data, description)#: Write migration data. Requires a description.

load()#: Load migration data.

validate()#: Validate migration data.

property description#

_metadata#

load()#

validate(*args, **kwargs)#

write(data, description)#

Write migration data. Requires a description.

Parameters

data (dict) – Migration data.
description (str) – Description of the migration.

class bw2io.MultiOutputEcospold1Importer(*args, **kwargs)#

Bases: SingleOutputEcospold1Importer

Import and process multi-output datasets in the ecospold 1 format.

Works the same as the single-output importer, but first allocates multioutput datasets.

strategies#

A list of strategies that the importer applies to process the dataset.

Type: list

Returns

None
Initialize MultiOutputEcospold1Importer.
param *args: Variable length argument list.
type *args: tuple
param **kwargs: Arbitrary keyword arguments.
type **kwargs: dict
rtype: None

class bw2io.SimaProCSVImporter(filepath, name=None, delimiter=';', encoding='latin-1', normalize_biosphere=True, biosphere_db=None, extractor=SimaProCSVExtractor)#

Bases: bw2io.importers.base_lci.LCIImporter

format = 'SimaPro CSV'#

get_db_name()#

match_ecoinvent2(db_name)#

write_database(data=None, name=None, *args, **kwargs)#

class bw2io.SimaProLCIACSVImporter(filepath, biosphere=None, delimiter=';', encoding='latin-1', normalize_biosphere=True)#

Bases: bw2io.importers.base_lcia.LCIAImporter

Importer for SimaPro CSV LCIA data format.

Parameters

filepath (str) – Path to the SimaPro CSV LCIA file.
biosphere (str, optional) – Name of the biosphere database to use. Default is None, which uses the current project’s default biosphere.
delimiter (str, optional) – Delimiter used in the CSV file. Default is ‘;’.
encoding (str, optional) – Character encoding used in the CSV file. Default is ‘latin-1’.
normalize_biosphere (bool, optional) – Whether to normalize biosphere flows using the included strategies. Default is True.

Notes

This importer extracts SimaPro CSV LCIA data.

If normalize_biosphere=True, the following strategies are applied:

normalize_units
set_biosphere_type
normalize_simapro_biosphere_categories
normalize_simapro_biosphere_names

format = 'SimaPro CSV LCIA'#

class bw2io.SingleOutputEcospold1Importer(filepath, db_name, use_mp=True, extractor=Ecospold1DataExtractor)#

Bases: bw2io.importers.base_lci.LCIImporter

Import and process single-output datasets in the ecospold 1 format.

Notes

Applies the following strategies: 1. If only one exchange is a production exchange, that is the reference product. 2. Delete (unreliable) integer codes from extracted data. 3. Drop unspecified subcategories from biosphere flows. 4. Normalize biosphere flow categories to ecoinvent 3.1 standard. 5. Normalize biosphere flow names to ecoinvent 3.1 standard. 6. Remove locations from biosphere exchanges. 7. Create a code from the activity hash of the dataset. 8. Link biosphere exchanges to the default biosphere database. 9. Link internal technosphere exchanges.

Parameters

filepath (str or Path) – File or directory path.
db_name (str) – Name of database to create.
use_mp (bool, optional) – Whether to use multiprocessing. Default is True.
extractor (Type[Ecospold1DataExtractor], optional) – Data extractor to use. Default is Ecospold1DataExtractor.

format = 'Ecospold1'#

class bw2io.SingleOutputEcospold2Importer(dirpath, db_name, extractor=Ecospold2DataExtractor, use_mp=True, signal=None)#

Bases: bw2io.importers.base_lci.LCIImporter

Class for importing single-output ecospold2 format LCI databases.

Parameters

dirpath (str) – Path to the directory containing the ecospold2 file.
db_name (str) – Name of the LCI database.
extractor (class) – Class for extracting data from the ecospold2 file, by default Ecospold2DataExtractor.
use_mp (bool) – Flag to indicate whether to use multiprocessing, by default True.
signal (object) – Object to indicate the status of the import process, by default None.

Raises

MultiprocessingError – If an error occurs during multiprocessing.
Initializes the SingleOutputEcospold2Importer class instance. –
:param dirpath – Path to the directory containing the ecospold2 file.:
:type dirpath – str:
:param db_name – Name of the LCI database.:
:type db_name – str:
:param extractor – Class for extracting data from the ecospold2 file, by default Ecospold2DataExtractor.:
:type extractor – class:
:param use_mp – Flag to indicate whether to use multiprocessing, by default True.:
:type use_mp – bool:
:param signal – Object to indicate the status of the import process, by default None.:
:type signal – object:

format = 'Ecospold2'#

class bw2io.UnlinkedData[source]#

Bases: bw2data.data_store.DataStore

Inheritance diagram of bw2io.UnlinkedData

_intermediate_dir = 'unlinked'#

_metadata#

validate(*args, **kwargs)#

bw2io.activity_hash(data, fields=None, case_insensitive=True)[source]#

Hash an activity dataset.

Used to import data formats like ecospold 1 (ecoinvent v1-2) and SimaPro, where no unique attributes for datasets are given.

This is clearly an imperfect and brittle solution, but there is no other obvious approach at this time.

By default, uses the following, in order: * name * categories * unit * reference product * location

Parameters: data (dict) – The activity dataset data.

fieldslist, optional

Optional list of fields to hash together. Default is ('name', 'categories', 'unit', 'reference product', 'location').

An empty string is used if a field isn’t present. All fields are cast to lower case.

case_insensitivebool, optional

Cast everything to lowercase before computing hash. Default is True.

Returns: A MD5 hash string, hex-encoded.
Return type: str

bw2io.backup_data_directory()[source]#

Backup data directory to a .tar.gz (compressed tar archive) in the user’s home directory. Restoration is done manually.

Examples

>>> bw2io.bw2setup()
>>> bw2io.backup.backup_data_directory()
Creating backup archive - this could take a few minutes...

bw2io.backup_project_directory(project)[source]#

Backup project data directory to a .tar.gz (compressed tar archive) in the user’s home directory.

Parameters: project (str) – Name of the project to backup.
Returns: project_name – Name of the project that was backed up.
Return type: str
Raises: ValueError – If the project does not exist.

bw2io#

Subpackages#

Submodules#

Package Contents#

Classes#

Functions#

Attributes#

`bw2io`#