Metadata-Version: 2.4
Name: hestia_earth_converters
Version: 0.1.0
Summary: HESTIA's set of file converters
Home-page: https://gitlab.com/hestia-earth/hestia-convert-base
Author: @ToffeeLabs
Author-email: community@hestia.earth
License: MIT
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Werkzeug
Requires-Dist: pydantic==2.*
Requires-Dist: pydantic_core==2.*
Requires-Dist: hestia-earth-schema>=38.3.1
Requires-Dist: hestia-earth-utils>=0.17.25
Requires-Dist: python-dateutil
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: setuptools
Provides-Extra: simapro
Requires-Dist: hestia-earth-schema>=38.3.1; extra == "simapro"
Requires-Dist: hestia-earth-utils>=0.17.25; extra == "simapro"
Requires-Dist: hestia-earth-flowmaps>=0.1.7; extra == "simapro"
Requires-Dist: bw_simapro_csv==0.4.2; extra == "simapro"
Requires-Dist: pydantic==2.*; extra == "simapro"
Requires-Dist: pydantic[email]; extra == "simapro"
Requires-Dist: requests; extra == "simapro"
Requires-Dist: unidecode; extra == "simapro"
Provides-Extra: coolfarm
Requires-Dist: hestia-earth-schema>=38.3.1; extra == "coolfarm"
Requires-Dist: hestia-earth-utils>=0.17.25; extra == "coolfarm"
Requires-Dist: hestia-earth-flowmaps>=0.1.7; extra == "coolfarm"
Requires-Dist: pydantic==2.*; extra == "coolfarm"
Provides-Extra: openlca
Requires-Dist: olca_schema==2.4.0; extra == "openlca"
Requires-Dist: hestia-earth-utils>=0.17.25; extra == "openlca"
Requires-Dist: joblib~=1.5.2; extra == "openlca"
Requires-Dist: email-validator==2.3.0; extra == "openlca"
Requires-Dist: hestia-earth-models>=0.85.0; extra == "openlca"
Requires-Dist: hestia-earth-flowmaps>=0.1.7; extra == "openlca"
Requires-Dist: pydantic-settings; extra == "openlca"
Requires-Dist: filelock; extra == "openlca"
Requires-Dist: unidecode; extra == "openlca"
Provides-Extra: klim
Requires-Dist: hestia-earth-schema>=38.3.1; extra == "klim"
Requires-Dist: hestia-earth-utils>=0.17.25; extra == "klim"
Requires-Dist: hestia-earth-flowmaps>=0.1.7; extra == "klim"
Requires-Dist: pydantic==2.*; extra == "klim"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# HESTIA Converters

> Library to convert from/to HESTIA format.

## Supported Conversions

| Input Format | Output Format | Converter | Install Extra |
|---|---|---|---|
| HESTIA | SimaPro | `hestia_to_simapro` | `pip install "hestia-earth-converters[SimaPro]"` |
| HESTIA | OpenLCA | `hestia_to_openlca` | `pip install "hestia-earth-converters[OpenLCA]"` |
| OpenLCA | HESTIA | `openlca_to_hestia` | `pip install "hestia-earth-converters[OpenLCA]"` |
| OpenLCA | LSRS | `openlca_to_lsrs` | `pip install "hestia-earth-converters[OpenLCA]"` |
| CoolFarm | HESTIA | `coolfarm_to_hestia` | `pip install "hestia-earth-converters[CoolFarm]"` |

## Installation

1. Install the base library:
```
pip install hestia-earth-converters
```
2. Install the converter(s) you need:
```
pip install "hestia-earth-converters[SimaPro]"
```

## Quick Start

Convert an HESTIA ImpactAssessment to SimaPro format:
```
hestia-convert --output-folder samples --input-format HESTIA --output-format SimaPro --hestia-impact-id cocoaSeedWhole-ghana-2010-2025-20250916
```

Convert from OpenLCA to HESTIA:
```
hestia-convert --input-file my_openlca_export.zip --output-folder output --input-format OpenLCA --output-format HESTIA
```

Convert from OpenLCA to the LSRS reporting spreadsheet (writes the intermediate
HESTIA ImpactAssessments plus one combined `lsrs.xlsx` with one row per IA):
```
hestia-convert --input-file my_openlca_export.zip --output-folder output --input-format OpenLCA --output-format LSRS
```

Use `hestia-convert --help` to see all available formats and options.

## CLI Options

### General Options

| Flag | Description |
|---|---|
| `--input-file` | Path to input file |
| `--output-folder` | Output files folder (required) |
| `--input-format` | Input format: `HESTIA`, `CoolFarm`, or `OpenLCA` (required) |
| `--output-format` | Output format: `HESTIA`, `SimaPro`, `OpenLCA`, or `LSRS` (required) |
| `--mapping-files-directory` | Folder containing mapping files in `.csv` format (default: `hestia-flowmaps`) |
| `--skip-existing` | Do not overwrite existing converted files |
| `--verbose` | Enable verbose mode |
| `--debug-file` | Output conversion logs to a debug file |
| `--filter-by-name` | Optional list of names to filter results on (must be in quotes) |

### HESTIA Options

| Flag | Description |
|---|---|
| `--hestia-impact-id` | One or more HESTIA ImpactAssessment IDs to download and convert |

### SimaPro Options

| Flag | Default | Description |
|---|---|---|
| `--simapro-output-process-type` | `System` | Type of SimaPro process to generate: `System` or `Unit process` |
| `--simapro-preferred-simapro-libraries` | — | Ordered list of SimaPro library names for replacing HESTIA terms with SimaPro processes |
| `--simapro-map-water-use-to-irrigation-processes` | `False` | Replace HESTIA water terms with SimaPro irrigation processes when the cycle used irrigation |
| `--simapro-override-default-emission-compartment` | `False` | Rewrite all "Emissions to air/(unspecified)" to "Emissions to air/low. pop." |
| `--simapro-naming-convention` | `default` | Naming convention for process names: `default` or `INRAE` |
| `--simapro-create-dummy-processes` | `True` | When using `Unit process`, turn unmapped inputs into "Dummy" processes |
| `--simapro-guess-country-for-certain-inputs` | `False` | Regionalise certain inputs (e.g. irrigation, electricity) if country info is missing |
| `--simapro-convert-linked-impact-assessment` | `False` | Also download and convert HESTIA impact assessments referenced in cycle inputs |

### OpenLCA Options

| Flag | Default | Description |
|---|---|---|
| `--openlca-rescale-impact-assessment-to-amount` | `1` | Rescale all values for a new Product value amount |

## How the HESTIA → SimaPro Conversion Works

The https://www.hestia.earth/explorer platform contains [Cycles](https://www.hestia.earth/schema/Cycle), and [ImpactAssessments](https://www.hestia.earth/schema/ImpactAssessment) data that can be imported into [SimaPro Craft](https://simapro.com/craft/).

The Hestia-To-SimaPro converter lets you convert HESTIA data to the "SimaPro CSV format" that can then be imported into SimaPro Craft.

Each HESTIA cycle, aggregated cycle, and impact assessment has a "HESTIA ID".
You can find this ID in the Summary section of the cycle / aggregated cycle page.
For example [Oil palm, fruit - Malaysia - 2010-2025](https://www.hestia.earth/cycle/oilPalmFruit-malaysia-2010-2025-20250916) has ID `oilPalmFruit-malaysia-2010-2025-20250916` both in the Summary and the page url.

When using the Hestia-To-SimaPro converter, you typically specify the ImpactAssessment ID, and the converter will download it from the HESTIA platform and output a SimaPro CSV file.

Hestia-To-SimaPro converter is capable of creating both ["System processes" or "Unit processes"](https://support.simapro.com/s/article/What-are-unit-and-system-processes).
If you use the `--simapro-output-process-type` option, [Cycle Inputs](https://www.hestia.earth/schema/Cycle#inputs) and their related [Cycle Emissions](https://www.hestia.earth/schema/Cycle#emissions) will be turned into stand alone "Dummy" unit processes that link back to the main process.

Some cycle Inputs come from a cycle on the HESTIA platform and contain [a link to an Impact Assessment of that input product](https://www.hestia.earth/schema/Input#impactAssessment). In this case, the Impact Assessment will also be downloaded and saved as a separate SimaPro CSV file in a new folder called "referenced_processes" in the output folder. These new referenced processes should be imported to SimaPro first, as they are "upstream" from the main converted process.

#### Warning

When converting multiple Hestia cycles, some may contain [links](https://www.hestia.earth/schema/Input#impactAssessment) to different versions of the same Impact assessment.
Therefore, both versions of that Impact Assessment will be saved to the "referenced_processes" folder.
When importing into SimaPro, care must be taken to only import the version of this Impact Assessment you want to use, as SimaPro will not import a process if an old version already exists in the database and will not update existing processes.

### Ecoinvent Data

The created SimaPro CSV files often refer to processes from the "Ecoinvent" libraries. To import these files, you will need to have the SimaPro ecoinvent library installed, and this, in most cases requires an Ecoinvent license.

Most cycles on the HESTIA platform include some use of [Electricity terms](https://www.hestia.earth/glossary?termType=electricity).
In SimaPro, these are typically represented as links to electricity producing processes.
Currently, the Hestia-To-SimaPro converter only converts these electricity terms into equivalent "TechExchange" "links" to the ecoinvent electricity processes included by default in SimaPro Craft.

If you are converting HESTIA data into unit processes, some inputs will be converted to the equivalent "TechExchange" "links" to ecoinvent processes known to produce these inputs.
The HESTIA terms that contain both a [ecoinventReferenceProductId](https://www.hestia.earth/schema/Term#ecoinventReferenceProductId) and a "ecoinventMapping" lookup listed on their ["https://www.hestia.earth/term/ TERM NAME"](https://www.hestia.earth/term/diesel) page will be converted to the equivalent Ecoinvent process in the SimaPro library 'Ecoinvent 3 - allocation, cut-off by classification - unit'.
On rare occasions, other libraries may be used, such as:
- "AGRIBALYSE - unit"
- "ecoinvent 3.11 (APOS)"

You can customise what ecoinvent processes, if any, are used by providing the converter a custom "flowmap" file. See [Flowmaps](#flowmaps).

### Flowmaps

The converter relies on "flowmap" mapping files in order to translate from [HESTIA glossary terms](https://www.hestia.earth/glossary) to [SimaPro glossary terms](https://github.com/PRe-Sustainability/GLAD-ElementaryFlowResources/blob/0e4b60b62afb1aafb5ed2e7b42589f1c8b0764e2/Original%20Flowlists/20250804_CurrentSimaProSubstanceList_GLAD.xlsx), also known as "Substances" or "Elementary flows."
If you do not provide your own flowmaps, the converter will automatically download the latest flowmaps from the [hestia-convert-flowmaps](https://gitlab.com/hestia-earth/hestia-convert-flowmaps) repository.
If you find any errors or omissions in these flowmaps, please open a GitLab issue [HERE](https://gitlab.com/hestia-earth/hestia-convert-flowmaps/-/issues/new?description_template=bug).

If you wish for the converter to use different SimaPro substances or different library processes during the conversion, you can create your own flowmaps and use the `--mapping-files-directory` option to specify their location.

These flowmap files must be compatible with the "[GLAD](https://github.com/UNEP-Economy-Division/GLAD-ElementaryFlowResources/blob/master/Formats/FlowMapping.md)" format. Please see [hestia-convert-flowmaps/README.MD](https://gitlab.com/hestia-earth/hestia-convert-flowmaps/-/blob/main/README.MD) for details on creating your own mappings.

## Known Limitations

- Most of the converted data comes from HESTIA [Cycles](https://www.hestia.earth/schema/Cycle). Only a limited amount of data is taken from [ImpactAssessments](https://www.hestia.earth/schema/ImpactAssessment). No data is currently taken from [Sites](https://www.hestia.earth/schema/Site).
- If the converter does not know how to translate a given HESTIA term to a SimaPro term, it will output an error message and omit that data in the conversion. This can cause large gaps in the data. These error messages can be saved to a ".log" text file to help debug these errors. Please use the `--debug-file` flag to save logs to a file.
- If the converter does not know how to translate a "regionalised" term, (a HESTIA [Input](https://www.hestia.earth/schema/Input#country), [Emission](https://www.hestia.earth/schema/Emission#country), or [Indicator](https://www.hestia.earth/schema/Indicator#country) containing country information) to a "regionalised" [SimaPro glossary term](https://github.com/PRe-Sustainability/GLAD-ElementaryFlowResources/blob/0e4b60b62afb1aafb5ed2e7b42589f1c8b0764e2/Original%20Flowlists/20250804_CurrentSimaProSubstanceList_GLAD.xlsx) then the converter will attempt to fallback on equivalent "non regionalised" SimaPro Substances / Elementary flows. This can cause characterisation methods to use default characterisation factors instead of regionalised factors and can skew results.
- The converter currently only maps [HESTIA Electricity terms](https://www.hestia.earth/glossary?termType=electricity) to ecoinvent electricity processes. Other free open source libraries for electricity are actively being sought.
- Some of the data on the HESTIA platform is confidential and cannot be downloaded. For some cycles, you may be required to use your [HESTIA API KEY](https://www.hestia.earth/docs/#hestia-api) to download certain nodes. To do this, please create an Account. Go to https://www.hestia.earth/profile. Scroll down to "API Access". Copy the "API Key". And set the `API_ACCESS_TOKEN=<API Key>` [environment variable](https://docs.python.org/3/using/windows.html#excursus-setting-environment-variables).
