Skip to content

Latest commit

 

History

History
135 lines (90 loc) · 6.93 KB

README.md

File metadata and controls

135 lines (90 loc) · 6.93 KB

bw_simapro_csv

PyPI Status Python Version License

Read the documentation at https://bw_simapro_csv.readthedocs.io/ Tests Codecov

pre-commit Black

Installation

You can install bw_simapro_csv via from PyPI:

$ pip install bw_simapro_csv

Or using conda/mamba from the channel cmutel:

$ mamba install -c conda-forge -c cmutel bw_simapro_csv

To install with the compatible Brightway libraries via pip:

$ pip install "bw_simapro_csv[brightway]""

Or via conda/mamba:

$ mamba install -c conda-forge -c cmutel bw_simapro_csv brightway25

On MacOS with ARM chips, run instead:

$ mamba install -c conda-forge -c cmutel bw_simapro_csv brightway25_nosolver

See the Brightway docs for more on ARM CPUs and sparse solvers.

Usage

bw_simapro_csv extracts a single SimaPro separated value export file to a series of blocks. Files can be CSV, TSV, or some other separator. Basic usage:

from pathlib import Path
from bw_simapro_csv import SimaProCSV
sp = SimaProCSV(Path("my SimaPro file.csv"))

The file object must be an instance of pathlib.Path or io.StringIO. The SimaProCSV will do the following:

  • Determine the file type. There are three kinds of SimaPro export files: "processes", "methods", and "product stages". This library does not yet work with product stages.
  • Read the header, and build SimaProCSV.header. The header is a dictionary of metadata. We do our best to convert the values to their python equivalents, such as datetimes or booleans.
  • Using the metadata, read the rest of the file, and convert it into a series of blocks. Each block has its own data schema, though they are mostly similar.
  • While reading the file, some common data mistakes are cleaned up. For example, impossible uncertainty distributions are switch to UnkownUncertainty. We also do our best to create valid and reasonable unicode text.
  • Many numeric values can be defined by formulae. In order to parse these formulae in python, we need to substitute some operators for their python equivalents (e.g. ** instead of ^). As python is case-sensitive, we switch all variable names to upper case, and add the prefix SP_, so my_variable would become SP_MY_VARIABLE. We then evaluate all formulas (including for allocation), and store their numeric results in the amount field.

The end result is SimaProCSV.blocks, a list of SimaProCSVBlock instances with parsed and cleaned data.

Products versus processes

Despite the presence of a Products block in processes, SimaPro doesn't really differentiate between between the two. Therefore, all process datasets should be considered as ProcessWithReferenceProduct. Consider this quote from the tutorial:

Process name in SimaPro
Under the Documentation tab, you can enter the process name. Please note that this is only for
your own reference and this name is not used anywhere. Processes are identified by the name
defined under the Input/Output tab in the product section. Therefore, if you want to search for a
certain process, you should use the product name defined in the Input/Output as the keyword.

Waste modelling

The intersection of ecoinvent waste models (negative values means things labelled as inputs are outputs, and vice-versa) and SimaPro Waste treatment versus Waste to treatment make life interesting. The SimaPro model is:

  • Waste treatment are inputs, and indicate that the given process is a waste treatment process, i.e. it does not have a Products block, and has the category_type waste treatment.
  • Waste to treatment are outputs, and indicate that waste is being produced which needs to be treated. Negative amounts in Waste to treatment indicate that these wastes are inputs, and that this process is a waste treatment process.

We label edges in both Products and Waste treatment as functional when exporting to Brightway.

Logging

bw_simapro_csv uses the loguru library for controlling logs. By default, logs are printed to stderr, and two log files are created: warning.log for important errors or information messages, and debug.log, for a detailed log of operations and resolved data issues.

Log are created in a directory path drawn from the platformdirs library; you can copy them to a more convenient place with SimaProCSV.copy_log_dir(some_dir), where some_dir is a pathlib.Path directory instance.

Exporting to Brightway

Process datasets can be exported to a format usable by bw2io with SimaProCSV.to_brightway(). This returns a Python dictionary, but you can also write this data to a file on disk by passing a pathlib.Path instance, i.e.:

from pathlib import Path
from bw_simapro_csv import SimaProCSV
sp = SimaProCSV(Path("my SimaPro file.csv"))
sp.to_brightway(Path("my-export.json"))

Blocks

Contributing

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

License

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

Issues

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