bw-matchbox

bw_matchbox

bw_matchbox is a web app for matching two Brightway. It allows you to do complicated matches, such as:

• Link process a to processes b and c, with allocation factors
• Link process a to a proxy for process b, changing the exchange values in b proxy to match those in process a where desired
• Link process a to a proxy for process b, removing some exchanges from b and adding some from a
• Link process a to a proxy for process b, expanding and inlining some exchanges from b to "flatten" its supply chain

Installation

You can install bw_matchbox via [pip] from [PyPI]:

pip install bw_matchbox

It's possible to install the library itself for development purposes (in the cloned project):

pip install -e .

This library depends on:

• Brightway 2.5 (brightway25)
• docopt-ng
• flask and flask_httpauth
• tomli
• werkzeug

Usage

This is a flask application. Flask has a debug server suitable for development, but it should not be used for production!

To use bw_matchbox, you need to do the following:

Create a configuration file

Configuration is done via a toml file. See config_example.toml for the structure of this file. Here is an example:

[users]
jane = "deer"
john = "doe"

[roles]
editors = ["jane"]
reviewers = ["john"]

[configs]
my_config = { project = "something", source = "database A", target = "database B", proxy = "database C"}

[files]
output_dir = "/Path/to/some/directory"

The config.toml file needs to provide the following:

• [users] section: Authentication, via a set of usernames and passwords
• [roles] section: The exact role labels must be used. Editors can make changes, reviewers can only comment.
• [configs] section: A combination of Brightway project and the source, target and proxy databases.
• [files] section: Currently only uses the output_dir key.

The easiest way to set this up is with:

matchbox setup

This will create stub configuration and changes files in your current working directory - note that you should change the configuration and username/password in config.toml.

Running the development server

Just run:

matchbox webapp config.toml

Running in production

You will need to configure the Flask app using configure_app, or re-implement its functionality. Here is an example using waitress:

from bw_matchbox import matchbox_app, configure_app
config_filepath = "/path/to/config.toml"
app = configure_app(config_filepath, matchbox_app)

from waitress import serve
serve(app, port=8080)

Starting the app

Once the app is running and configured locally or remotely, connect to the correct address and port. If you are running locally, this is probably either http://localhost:5000 or http://127.0.0.1:5000.

In the first screen, choose the Brightway project you want to work on. This is matchbox-example if you ran matchbox example_project.

On the next screen, choose one database as the source, and a different database as the target. Currently you need to specify a new proxy database by typing a new database name into the Create a new database input box.

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, bw_matchbox is free and open source software.

Issues

If you encounter any problems, please [file an issue] along with a detailed description.