Metadata-Version: 2.4
Name: hestia_earth_utils
Version: 0.17.10
Summary: HESTIA's utils library
Home-page: https://gitlab.com/hestia-earth/hestia-utils
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
Requires-Dist: hestia-earth-schema>=35.0.1
Requires-Dist: requests>=2.24.0
Requires-Dist: urllib3~=1.26.0
Requires-Dist: python-dateutil>=2.8.1
Requires-Dist: pandas<3,>=2
Requires-Dist: flatten_json
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# HESTIA Utils

## Install

1. Install the module:
```bash
pip install hestia_earth.utils
```
2. Add this to your environment variables:
```
API_URL=https://api.hestia.earth
WEB_URL=https://www.hestia.earth
```

## Usage

1. To download a file from the HESTIA API:
```python
from hestia_earth.schema import SchemaType
from hestia_earth.utils.api import download_hestia

cycle = download_hestia('cycleId', SchemaType.CYCLE)
sandContent = download_hestia('sandContent', SchemaType.TERM)
```

2. To search for a specific Node on HESTIA:
```python
from hestia_earth.schema import SchemaType
from hestia_earth.utils.api import find_node_exact

source = find_node_exact(SchemaType.SOURCE, {'bibliography.title': 'My Bibliography'})
```

3. To get a lookup table from local file system:
```python
from hestia_earth.schema import SchemaType
from hestia_earth.utils.lookup import load_lookup

df = load_lookup('path/to/my/lookup.csv')
```

4. To get a lookup table from HESTIA:
```python
from hestia_earth.schema import SchemaType
from hestia_earth.utils.lookup import download_lookup

df = download_lookup('crop.csv')
```

## LSRS Format

You can use this library to convert HESTIA data into the LSRS format.

For example, this will let you download all verified aggregation on HESTIA:
1. Add the env variable `API_ACCESS_TOKEN` and use the API Key from [your account](https://www.hestia.earth/profile).
2. Create a file to store the search query:
```json
{
  "bool": {
    "must": [
      { "match": { "@type": "ImpactAssessment" } },
      { "match": { "aggregatedDataValidated": true } }
    ]
  }
}
```
3. Run `python3 convert_to_lsrs.py --query-path test.json --data-state recalculated`

This will create 2 files:
- `query-results-lsrs.json`: contains the raw JSON data needed to generate the Excel file
- `query-results-lsrs.xlsx`: cotains the LSRS data in Excel format.

Note: if you make some changes to the Excel generation, you can run this to use the `json` data and re-generate the Excel file quicker: `python3 render_lsrs.py --filepath query-results-lsrs.json`

### Converting multiple files and rendering into a single Excel

You can use the convert script to create all the JSON files containing the raw data, then render everything together at once:
1. Run all your conversion, using `--skip-rendering` parameter:
```
python3 convert_to_lsrs.py --query-path test1.json --data-state recalculated --skip-rendering
python3 convert_to_lsrs.py --query-path test1.json --data-state recalculated --skip-rendering
```
2. This will write multiple JSON files in the `samples` folder. Once done, render all together: `python3 render_lsrs.py --folder samples`. This will create the final `samples.xlsx` file.
