bw2io

Subpackages

• bw2io.export
• bw2io.extractors
• bw2io.importers
• bw2io.strategies

Submodules

• bw2io.backup
• bw2io.compatibility
• bw2io.download_utils
• bw2io.errors
• bw2io.migrations
• bw2io.modified_database
• bw2io.package
• bw2io.remote
• bw2io.units
• bw2io.unlinked_data
• bw2io.utils

Attributes

activity_hash
migrations
normalize_units
unlinked_data

Classes

BW2Package	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.
CSVImporter	Generic CSV importer
CSVLCIAImporter	Generic CSV LCIA importer
DatabaseSelectionToGEXF	Export a Gephi graph for a selection of activities from a database.
DatabaseToGEXF	Export a Gephi graph for a database.
Ecospold1LCIAImporter
ExcelImporter	Generic Excel importer.
ExcelLCIAImporter	Generic Excel LCIA importer.
Migration
MultiOutputEcospold1Importer	Import and process mutli-output datasets in the ecospold 1 format.
SimaProCSVImporter
SimaProLCIACSVImporter
SingleOutputEcospold1Importer	Import and process single-output datasets in the ecospold 1 format.
SingleOutputEcospold2Importer	Base class for format-specific importers.
UnlinkedData

Functions

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.
install_project(project_key[, project_name, ...])	Install an existing Brightway project archive.
lci_matrices_to_excel(database_name[, include_descendants])	Fake docstring
lci_matrices_to_matlab(database_name)
load_json_data_file(filename)
restore_project_directory(fp[, project_name, ...])	Restore a backed up project data directory from a .tar.gz (compressed tar archive) in the user's home directory.

Package Contents

class bw2io.BW2Package

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
}

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.

Note

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

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 to export.

• filename (*) – Name of file to create. Default is obj.name.

• folder (*) – Folder to create file in. Default is export.

• backwards_compatible (*) – Create package compatible with bw2data version 1.

Returns:

Filepath of created file.

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

Export a list of objects. Can have heterogeneous types.

Parameters:

• objs (*) – List of objects to export.

• filename (*) – Name of file to create.

• folder (*) – Folder to create file in. Default is export.

• backwards_compatible (*) – Create package compatible with bw2data version 1.

Returns:

Filepath of created file.

classmethod import_file(filepath, whitelist=True)

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

Parameters:

• filepath (*) – Path of file to import

• whitelist (*) – Apply whitelist to allowed types. Default is True.

Returns:

Created object or list of created objects.

classmethod load_file(filepath, whitelist=True)

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

Parameters:

• filepath (*) – Path of file to import

• whitelist (*) – Apply whitelist of approved classes to allowed types. Default is True.

Returns the loaded data in the bw2package dict data format, with the following changes:

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

APPROVED

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

extractor

format = 'CSV'

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 (*) – Database name.

• keys (*) – The activity keys to export.

data

database

filepath

id_mapping

unfiltered_data

class bw2io.DatabaseToGEXF(database, include_descendants=False)

Bases: object

Export a Gephi graph for a database.

Call .export() to export the file after class instantiation.

Parameters:

• database (*) – Database name.

• include_descendants (*) – Include databases which are linked from database.

Warning

include_descendants is not yet implemented.

export()

Export the Gephi XML file. Returns the filepath of the created file.

get_data(E)

Get Gephi nodes and edges.

data

database

descendants

filename

filepath

id_mapping

class bw2io.Ecospold1LCIAImporter(filepath, biosphere=None)

Bases: bw2io.importers.base_lcia.LCIAImporter

data

format = 'Ecospold1 LCIA'

start

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.

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.

data

extractor

format = 'Excel'

start

strategies

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

Bases: bw2io.importers.base_lcia.LCIAImporter

Generic Excel LCIA importer.

See the documentation.

data

extractor

format = 'Excel'

strategies

class bw2io.Migration(*args, **kwargs)

Bases: bw2data.data_store.DataStore

load()

validate(*args, **kwargs)

write(data, description)

Write migration data. Requires a description.

_intermediate_dir

_metadata

property description

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

Bases: SingleOutputEcospold1Importer

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

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

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

Bases: bw2io.importers.base_lci.LCIImporter

get_db_name()

match_ecoinvent2(db_name)

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

format = 'SimaPro CSV'

start

strategies

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

Bases: bw2io.importers.base_lcia.LCIAImporter

data

format = 'SimaPro CSV LCIA'

start

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.

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

Parameters:

• filepath (*) – Either a file or directory.

• db_name (*) – Name of database to create.

db_name

format = 'Ecospold1'

start

strategies

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

Bases: bw2io.importers.base_lci.LCIImporter

Base class for format-specific importers.

Defines workflow for applying strategies.

Takes a database name (string) as initialization parameter.

Initializes the SingleOutputEcospold2Importer class instance.

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.

• reparametrize_lognormals (bool) – Flag to indicate if lognormal distributions for exchanges should be reparametrized such that the mean value of the resulting distribution meets the amount defined for the exchange.

db_name

dirpath

format = 'Ecospold2'

signal

start

strategies

class bw2io.UnlinkedData

Bases: bw2data.data_store.DataStore

validate(*args, **kwargs)

_intermediate_dir = 'unlinked'

_metadata

bw2io.backup_data_directory()

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: str)

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.

See also

bw2io.backup.restore_project_directory

To restore a project directory from a backup.

bw2io.bw2setup()

bw2io.create_core_migrations()

Add pre-defined core migrations data files

bw2io.create_default_biosphere3(overwrite=False)

bw2io.create_default_lcia_methods(overwrite=False, rationalize_method_names=False, shortcut=True)

bw2io.es2_activity_hash(activity, flow)

Generate unique ID for ecoinvent3 dataset.

Despite using a million UUIDs, there is actually no unique ID in an ecospold2 dataset. Datasets are uniquely identified by the combination of activity and flow UUIDs.

bw2io.install_project(project_key: str, project_name: str | None = None, projects_config: dict | None = get_projects(), url: str | None = 'https://files.brightway.dev/', overwrite_existing: bool | None = False, __recursive: bool | None = False)

Install an existing Brightway project archive.

By default uses https://files.brightway.dev/ as the file repository, but you can run your own.

Parameters:

• project_key (str) – A string uniquely identifying a project, e.g. ecoinvent-3.8-biosphere.

• project_name (str, optional) – The name of the new project to create. If not provided will be taken from the archive file.

• projects_config (dict, optional) – A dictionary that maps project_key values to filenames at the repository

• url (str, optional) – The URL, with trailing slash /, where the file can be found.

• overwrite_existing (bool, optional) – Allow overwriting an existing project

• __recursive (bool) – Internal flag used to determine if this function has errored out already

Returns:

The name of the created project.

Return type:

str

bw2io.lci_matrices_to_excel(database_name, include_descendants=True)

Fake docstring

bw2io.lci_matrices_to_matlab(database_name)

bw2io.load_json_data_file(filename)

bw2io.restore_project_directory(fp: str, project_name: str | None = None, overwrite_existing: bool | None = False)

Restore a backed up project data directory from a .tar.gz (compressed tar archive) in the user’s home directory.

Parameters:

• fp (str) – File path of the project to restore.

• project_name (str, optional) – Name of new project to create

• overwrite_existing (bool, optional)

Returns:

project_name – Name of the project that was restored.

Return type:

str

Raises:

ValueError – If the project does not exist.

See also

bw2io.backup.backup_project_directory

To restore a project directory from a backup.

bw2io.activity_hash

bw2io.migrations

bw2io.normalize_units

bw2io.unlinked_data