randonneur 0.0.1

Migrate LCA data. Compatible with the Brightway framework.

randonneur

Keep moving forward.

Randonneur is a library to make broad or specific changes to life cycle inventory databases. You can use it to re-link your data to the latest version of a background database, to update existing databases with new data, or to perform other data changes. Randonneur uses JSON files to describe these changes; contrast this with wurst, which can do these manipulations and more, but describes its manipulations in code.

Although designed to work with Brightway, this library is not Brightway-specific.

Usage

randonneur supports two migration functions, each with their own migration data format.

All input functions take data in the wurst format.

Migrating exchanges

Exchanges are the consumption or production of a good or service. Exchanges link two nodes (two activities, one product and one activity, one activity and one biosphere flow, or even other node types). We support the following types of exchange changes:

• Create
• Replace
• Update
• Delete
• Disaggregate

Generic data format

Exchange migration is specified in a JSON file. This file should include information on the data author and license (following the datapackage conventions), and at least one of the migration types: create, replace, update, delete, and disaggregate. None of the types are required.

Create

Creates a new exchange in all nodes, or in one specific node.

Because we are specifying a new exchange, we need to list all information needed to define an exchange, including the exchange amount. This is different than the other modification types, where relative amounts are given with the key allocation. We can't give relative amounts here because we have no exchange to refer to, and we don't have a surefire way to identify the reference production exchange (and there might not be one in any case).

If you want to add an exchange to all nodes:

{
    "create": [{
        "target": {
            # All fields needed to define an exchange
        }
    }]
}

If you only want to create an exchange in one node:

{
    "create": [{
        "target": {
            # All fields needed to define an exchange
        },
        "node": {
            # All fields needed to identify the node
        }
    }]
}

node must be a dict, not a list; it can only identify one node.

Note that in the wurst format, node use the key reference product while exchanges use the key product; these are two different concepts, so have different keys.

Replace

Replacement substitutes an exchange one-to-one; as such, the new exchange must be completely defined. However, the amount should not be specified; rather, an allocation factor should be given, and the amount of the original exchange will be multiplied by allocation.

If allocation is not given, a default value of 1.0 is used.

Note: randonneur currently does not adjust uncertainty when rescaling.

Aside from the quantitative values, no other data from the original exchange is taken over to the new exchange. If you only want to change a few fields, use an update instead. If you don't want the exchange amount re-scaled, use a combination of delete and create.

The data format for replace type is:

{
    "replace": [{
        "source": {
            # All fields needed to identify the exchange to be replaced
        },
        "target": {
            # All fields needed to define the new exchange
        },
        # `node` is optional
        "node": {
            # All fields needed to identify the node to change
        }
    }]
}

Update

update differs from replace in that it changes attributes of the original exchange instead of creating a new object; otherwise, its behaviour is the same as replace. The data format is:

{
    "update": [{
        "source": {
            # All fields needed to identify the exchange to be modified
        },
        "target": {
            # Some fields which you want to change
        },
        # `node` is optional
        "node": {
            # All fields needed to identify the node to change
        }
    }]
}

Delete

Delete exchanges. Follows the same patterns as replace and update:

{
    "update": [{
        "source": {
            # All fields needed to identify the exchange to be deleted
        },
        # `node` is optional
        "node": {
            # All fields needed to identify the node to change
        }
    }]
}

Disaggregate

Disaggregation is splitting one exchange into many. The allocation field is used to determine how much of the exchange passes to each new exchange.

The new exchanges start as copies of the original exchange, and are updating using the additional data provided. In other words, this functions more like an update than a replace. This is because the most common use case for disaggregation is to split one input or output among several regions, where almost all metadata for the child exchanges would be identical.

allocation fields do not have to sum to one.

The data format includes a list of new exchanges for each matched source:

{
    "disaggregate": [{
        "source": {
            # All fields needed to identify the exchange to be disaggregated
        },
        "target": [{
            # Some fields which you want to change
        }],
        # `node` is optional
        "node": {
            # All fields needed to identify the node to change
        }
    }]
}

Migrating nodes

Contributing

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

License

Distributed under the terms of the BSD 3 Clause license, randonneur is free and open source software.

Issues

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