Metadata-Version: 2.4
Name: hestia_earth_models
Version: 0.79.4
Summary: HESTIA's set of modules for filling gaps in the activity data using external datasets (e.g. populating soil properties with a geospatial dataset using provided coordinates) and internal lookups (e.g. populating machinery use from fuel use). Includes rules for when gaps should be filled versus not (e.g. never gap fill yield, gap fill crop residue if yield provided etc.).
Home-page: https://gitlab.com/hestia-earth/hestia-engine-models
Author: HESTIA Team
Author-email: guillaumeroyer.mail@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hestia-earth-schema<37.0.0,>=36.0.0
Requires-Dist: hestia-earth-utils>=0.17.2
Requires-Dist: CurrencyConverter==0.17.0
Requires-Dist: haversine>=2.7.0
Requires-Dist: pydash
Requires-Dist: area
Provides-Extra: spatial
Requires-Dist: hestia-earth-earth-engine>=0.6.0; extra == "spatial"
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 Engine Models

[![Pipeline Status](https://gitlab.com/hestia-earth/hestia-engine-models/badges/master/pipeline.svg)](https://gitlab.com/hestia-earth/hestia-engine-models/commits/master)
[![Coverage Report](https://gitlab.com/hestia-earth/hestia-engine-models/badges/master/coverage.svg)](https://gitlab.com/hestia-earth/hestia-engine-models/commits/master)

HESTIA's set of models for running calculations or retrieving data using external datasets and internal lookups.

## Documentation

Documentation for every model can be found in the [HESTIA Guide](https://hestia.earth/guide/models).

## Install

1. Install python `3.12` minimum
2. Install the module:
```bash
pip install hestia_earth.models
```

### Usage

```python
from hestia_earth.models.pooreNemecek2018 import run

cycle_data = {"@type": "Cycle", ...}
# cycle is a JSONLD node Cycle
result = run('no3ToGroundwaterSoilFlux', cycle_data)
print(result)
```

This will display only the result of the `no3ToGroundwaterSoilFlux` model (Emission).

Additionally, to reduce the number of queries to the HESTIA API and run the models faster, prefetching can be enabled:
```python
from hestia_earth.models.preload_requests import enable_preload

enable_preload()
```

#### Using the orchestrator

The models come with an "orchestrator", which allows you to run a pre-configured set of models instead of a single one.

The configuration for each Node (Cycle, Site or ImpactAssessment) can be found in the [config](./config) folder.

Usage:
```python
from hestia_earth.orchestrator import run
from hestia_earth.models.config import load_config

cycle = {"@type": "Cycle", ...}
result = run(cycle, load_config(cycle))
print(result)
```

This will display the Cycle recalculated with all HESTIA default models running.

#### Using Spatial Models

We have models that can gap-fill geographical information on a `Site`. If you want to use these models:
1. Install the library: `pip install hestia-earth-earth-engine`
2. Follow the [Getting Started instructions](https://gitlab.com/hestia-earth/hestia-earth-engine#getting-started).

### Collecting logs in JSON format

:info: This is an experimental feature and is not yet integrated in all the HESTIA tools.

To collect logs in JSON format:
1. Set the env variable `LOG_JSON_ENABLED` to `true`
1. Use the following code to collect contribution logs:
```python
from hestia_earth.orchestrator import run
from hestia_earth.models.config import load_config
from hestia_earth.models.log_utils import reset_collected_logs, get_collected_logs

# make sure the logs are reset before each run
reset_collected_logs()

# run the models as usual
impact = {"@type": "ImpactAssessment", ...}
result = run(impact, load_config(impact))
print(result)

# write the logs to a JSON file
logs = get_collected_logs()
with open("logs.json", "w") as f:
    f.write(to_string(logs, indent=2))
```

### Collecting contribution data

:info: This is an experimental feature and is not yet integrated in all the HESTIA tools.

To collect contribution data of impacts/endpoints on ImpactAssessment:
1. Set the env variable `LOG_CONTRIBUTION_ENABLED` to `true`
1. Use the following code to collect contribution logs:
```python
from hestia_earth.orchestrator import run
from hestia_earth.models.config import load_config
from hestia_earth.models.log_contribution import reset_contributions, get_contributions

# make sure the contributions are reset before each run
reset_contributions()

# run the models as usual
impact = {"@type": "ImpactAssessment", ...}
result = run(impact, load_config(impact))
print(result)

# write the contributions to a JSON file
contributions = get_contributions()
with open("contributions.json", "w") as f:
    f.write(to_string(contributions, indent=2))
```

The contribution data will store the factors used for each `emissionsResourceUse` that contributes to specific `impacts`, and likewise `impacts` that contribute to `endpoints`. The index in the data represents the index of the blank node in the list of contributing blank nodes.

#### Using the ecoinventV3 model

:warning: This model has been deprecated and no further support will be provided.

ecoinvent is a consistent, transparent, and well validated life cycle inventory database.
We use ecoinvent data to ascertain the environmental impacts of activities that occur outside of our system boundary, for example data on the environmental impacts of extracting oil and producing diesel, or the impacts of manufacturing plastics.

The `ecoinventV3` model requires a valid [license](https://ecoinvent.org/offerings/licences/) to run. We are currently working on a way to enable users of this code with a valid ecoinvent licence to run these models themselves, but for now, these models are only available on the public platform.
