Metadata-Version: 2.4
Name: hestia_earth_aggregation
Version: 0.23.9
Summary: HESTIA's aggregation engine.
Home-page: https://gitlab.com/hestia-earth/hestia-aggregation-engine
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>=39.0.1
Requires-Dist: hestia-earth-utils>=0.17.25
Requires-Dist: hestia-earth-models>=0.87.10
Requires-Dist: requests
Requires-Dist: unidecode
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# HESTIA Aggregation Engine

[![Pipeline Status](https://gitlab.com/hestia-earth/hestia-aggregation-engine/badges/master/pipeline.svg)](https://gitlab.com/hestia-earth/hestia-aggregation-engine/commits/master)
[![Coverage Report](https://gitlab.com/hestia-earth/hestia-aggregation-engine/badges/master/coverage.svg)](https://gitlab.com/hestia-earth/hestia-aggregation-engine/commits/master)
[![Documentation Status](https://readthedocs.org/projects/hestia-aggregation-engine/badge/?version=latest)](https://hestia-aggregation-engine.readthedocs.io/en/latest/?badge=latest)

## Documentation

Official documentation can be found on [Read the Docs](https://hestia-aggregation-engine.readthedocs.io/en/latest/index.html).

Documentation of the aggregation process can be found in the [docs folder](./hestia_earth/aggregation/docs).

## Install

1. Install the module:
```bash
pip install hestia_earth.aggregation
```

### Usage

```python
from hestia_earth.aggregation import aggregate

# `country` and `product` are glossary Terms
country = {'@type': 'Term', '@id': 'GADM-JPN', 'name': 'Japan', 'termType': 'region'}
product = {'@type': 'Term', '@id': 'wheatGrain', 'name': 'Wheat, grain', 'termType': 'crop'}

aggregates = aggregate(country=country, product=product, start_year=2010, end_year=2025)
```

## Generating Covariance matrix

To generate the covariance matrix, some CSV files are generated and stored in a folder.

By default, these files are created in the `/tmp/covariance` directory and removed at the end of the aggregation. Set the `TMP_DIR` env variable to use `$TMP_DIR/covariance` instead.

You can also choose a different storage method with the `AGGREGATION_COVARIANCE_STORAGE` env variable:
- `temporary`: default value, will store the files in `$TMP_DIR/covariance` and delete them at the end;
- `s3#<folder>`: upload the files on the S3 bucket defined by the variable `AWS_BUCKET_UPLOADS`;
- `local#<folder>`: copy the files to a local folder.
