hestia-earth-models 0.61.1__tar.gz → 0.75.11__tar.gz

hestia_earth_models-0.75.11/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019-2025 Harmonised Environmental Storage and Tracking of the Impacts of Agriculture (HESTIA) Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hestia_earth_models-0.75.11/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include hestia_earth/models/mocking/*.json
+include hestia_earth/models/config/*.json

hestia_earth_models-0.75.11/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: hestia_earth_models
+Version: 0.75.11
+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<36.0.0,>=35.0.1
+Requires-Dist: hestia-earth-utils>=0.16.7
+Requires-Dist: CurrencyConverter==0.16.8
+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_data = {"@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).
+
+#### Using the ecoinventV3 model
+
+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.

hestia_earth_models-0.75.11/README.md

@@ -0,0 +1,69 @@
+# 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_data = {"@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).
+
+#### Using the ecoinventV3 model
+
+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.

hestia_earth_models-0.75.11/hestia_earth/models/agribalyse2016/__init__.py

@@ -0,0 +1,14 @@
+from os.path import dirname, abspath
+import sys
+from importlib import import_module
+
+from hestia_earth.models.utils.blank_node import run_if_required
+
+CURRENT_DIR = dirname(abspath(__file__)) + "/"
+sys.path.append(CURRENT_DIR)
+MODEL = "agribalyse2016"
+PKG = ".".join(["hestia_earth", "models", MODEL])
+
+
+def run(model: str, data):
+    return run_if_required(MODEL, model, data, import_module(f".{model}", package=PKG))

hestia_earth_models-0.75.11/hestia_earth/models/agribalyse2016/fuelElectricity.py

@@ -0,0 +1,151 @@
+from hestia_earth.schema import TermTermType
+from hestia_earth.utils.model import filter_list_term_type
+from hestia_earth.utils.tools import flatten, list_sum, non_empty_list
+
+from hestia_earth.models.log import (
+    debugValues,
+    logRequirements,
+    logShouldRun,
+    log_as_table,
+)
+
+from hestia_earth.models.utils.group_nodes import group_nodes_by, group_nodes_by_term_id
+from hestia_earth.models.utils.term import get_lookup_value
+from hestia_earth.models.utils.input import _new_input
+from . import MODEL
+
+REQUIREMENTS = {
+    "Cycle": {
+        "completeness.electricityFuel": "False",
+        "practices": [
+            {"@type": "Practice", "term.termType": "operation", "value": "> 0"}
+        ],
+    }
+}
+LOOKUPS = {"operation": "fuelUse"}
+RETURNS = {"Input": [{"term.termType": "fuel", "value": "", "operation": ""}]}
+MODEL_KEY = "fuelElectricity"
+
+
+def _input(term_id: str, value: float, operation: dict):
+    input = _new_input(term=term_id, model=MODEL, value=value)
+    input["operation"] = operation
+    return input
+
+
+def _operation_input(operation: dict):
+    input = operation.get("input", {})
+    return _input(
+        input.get("id"),
+        input.get("value") * operation.get("value"),
+        operation.get("term", {}),
+    )
+
+
+def _run_operation(cycle: dict):
+    def exec(operations: list):
+        input_term_id = operations[0].get("input").get("id")
+        values_logs = log_as_table(
+            [
+                {
+                    "id": p.get("term").get("@id"),
+                    "value": p.get("value"),
+                    "coefficient": p.get("input").get("value"),
+                }
+                for p in operations
+            ]
+        )
+
+        debugValues(cycle, model=MODEL, term=input_term_id, values=values_logs)
+
+        logShouldRun(cycle, MODEL, input_term_id, True, model_key=MODEL_KEY)
+
+        return list(map(_operation_input, operations))
+
+    return exec
+
+
+def _operation_data(practice: dict):
+    term = practice.get("term", {})
+    values = practice.get("value", [])
+    value = (
+        list_sum(values) if all([not isinstance(v, str) for v in values]) else None
+    )  # str allowed for Practice
+
+    coeffs = get_lookup_value(
+        term, LOOKUPS["operation"], model=MODEL, model_key=MODEL_KEY
+    )
+    values = non_empty_list(coeffs.split(";")) if coeffs else []
+    inputs = [{"id": c.split(":")[0], "value": float(c.split(":")[1])} for c in values]
+
+    return [
+        {
+            "term": term,
+            "value": value,
+            "input": input,
+            "dates": ";".join(practice.get("dates", [])),
+        }
+        for input in inputs
+    ]
+
+
+def _should_run(cycle: dict):
+    is_incomplete = not cycle.get("completeness", {}).get("electricityFuel", False)
+    operations = filter_list_term_type(
+        cycle.get("practices", []), TermTermType.OPERATION
+    )
+
+    operations = flatten(map(_operation_data, operations))
+    term_ids = list(
+        set(non_empty_list(map(lambda v: v.get("term", {}).get("@id"), operations)))
+    )
+
+    valid_operations = [v for v in operations if (v.get("value") or 0) > 0]
+    has_operations = len(valid_operations) > 0
+
+    # group operations by term to show in logs
+    grouped_operations = group_nodes_by_term_id(operations, sort=False)
+
+    for term_id, operations in grouped_operations.items():
+        logs = [
+            {
+                "value": operation.get("value"),
+                "dates": operation.get("dates"),
+                "input-id": operation.get("input", {}).get("@id"),
+            }
+            for operation in operations
+        ]
+        logRequirements(
+            cycle,
+            model=MODEL,
+            term=term_id,
+            model_key=MODEL_KEY,
+            details=log_as_table(logs),
+        )
+
+        should_run = any([(v.get("value") or 0) > 0 for v in operations])
+        logShouldRun(cycle, MODEL, term_id, should_run, model_key=MODEL_KEY)
+
+    logRequirements(
+        cycle,
+        model=MODEL,
+        model_key=MODEL_KEY,
+        is_term_type_electricityFuel_incomplete=is_incomplete,
+        has_operations=has_operations,
+        operations=";".join(term_ids),
+    )
+
+    should_run = all([is_incomplete, has_operations])
+    logShouldRun(cycle, MODEL, None, should_run, model_key=MODEL_KEY)
+    return should_run, valid_operations
+
+
+def run(cycle: dict):
+    should_run, operations = _should_run(cycle)
+    # group operations by input to show logs as table
+    grouped_operations = group_nodes_by(operations, "input.id", sort=False)
+    return (
+        flatten(map(_run_operation(cycle), grouped_operations.values()))
+        if should_run
+        else []
+    )

hestia_earth_models-0.75.11/hestia_earth/models/agribalyse2016/machineryInfrastructureDepreciatedAmountPerCycle.py

@@ -0,0 +1,88 @@
+from hestia_earth.utils.tools import list_sum, flatten
+
+from hestia_earth.models.log import (
+    logRequirements,
+    logShouldRun,
+    debugValues,
+    log_as_table,
+)
+from hestia_earth.models.utils.productivity import get_productivity, PRODUCTIVITY
+from hestia_earth.models.utils.input import _new_input
+from hestia_earth.models.utils.completeness import _is_term_type_incomplete
+from hestia_earth.models.utils.term import get_liquid_fuel_terms
+from . import MODEL
+
+REQUIREMENTS = {
+    "Cycle": {
+        "inputs": [{"@type": "Input", "term.termType": "fuel", "value": ""}],
+        "completeness.material": "False",
+        "site": {"@type": "Site", "country": {"@type": "Term", "termType": "region"}},
+    }
+}
+LOOKUPS = {"region": "HDI"}
+RETURNS = {"Input": [{"value": ""}]}
+TERM_ID = "machineryInfrastructureDepreciatedAmountPerCycle"
+
+
+def _get_input_value_from_term(inputs: list, term_id: str):
+    values = flatten(
+        [
+            input.get("value", [])
+            for input in inputs
+            if input.get("term", {}).get("@id") == term_id
+        ]
+    )
+    return list_sum(values, 0) if len(values) > 0 else None
+
+
+def get_value(country: dict, cycle: dict):
+    liquid_fuels = get_liquid_fuel_terms()
+    productivity_key = get_productivity(country)
+    machinery_usage = 11.5 if productivity_key == PRODUCTIVITY.HIGH else 23
+    values = [
+        (term_id, _get_input_value_from_term(cycle.get("inputs", []), term_id))
+        for term_id in liquid_fuels
+    ]
+    value_logs = log_as_table(
+        [{"id": term_id, "value": value} for term_id, value in values]
+    )
+    values = [value for term_id, value in values if value is not None]
+    fuel_use = list_sum(values, 0)
+    debugValues(
+        cycle,
+        model=MODEL,
+        term=TERM_ID,
+        productivity_key=productivity_key.value,
+        fuel_use_details=value_logs,
+        fuel_use=fuel_use,
+    )
+    return fuel_use / machinery_usage if fuel_use > 0 else None
+
+
+def _run(cycle: dict):
+    country = cycle.get("site", {}).get("country", {})
+    value = get_value(country, cycle)
+    return (
+        [_new_input(term=TERM_ID, model=MODEL, value=value)]
+        if value is not None
+        else []
+    )
+
+
+def _should_run(cycle: dict):
+    term_type_incomplete = _is_term_type_incomplete(cycle, TERM_ID)
+
+    logRequirements(
+        cycle,
+        model=MODEL,
+        term=TERM_ID,
+        term_type_material_incomplete=term_type_incomplete,
+    )
+
+    should_run = all([term_type_incomplete])
+    logShouldRun(cycle, MODEL, TERM_ID, should_run)
+    return should_run
+
+
+def run(cycle: dict):
+    return _run(cycle) if _should_run(cycle) else []

hestia_earth_models-0.75.11/hestia_earth/models/akagiEtAl2011/__init__.py

@@ -0,0 +1,14 @@
+from os.path import dirname, abspath
+import sys
+from importlib import import_module
+
+from hestia_earth.models.utils.blank_node import run_if_required
+
+CURRENT_DIR = dirname(abspath(__file__)) + "/"
+sys.path.append(CURRENT_DIR)
+MODEL = "akagiEtAl2011"
+PKG = ".".join(["hestia_earth", "models", MODEL])
+
+
+def run(model: str, data):
+    return run_if_required(MODEL, model, data, import_module(f".{model}", package=PKG))

hestia_earth_models-0.75.11/hestia_earth/models/akagiEtAl2011/ch4ToAirCropResidueBurning.py

@@ -0,0 +1,35 @@
+from hestia_earth.schema import EmissionMethodTier
+
+from .utils import run_emission
+
+REQUIREMENTS = {
+    "Cycle": {
+        "or": {
+            "products": [
+                {
+                    "@type": "Product",
+                    "term.@id": ["aboveGroundCropResidueBurnt", "discardedCropBurnt"],
+                    "value": "",
+                }
+            ],
+            "completeness.cropResidue": "True",
+        }
+    }
+}
+RETURNS = {
+    "Emission": [
+        {"value": "", "sd": "", "methodTier": "tier 1", "statsDefinition": "modelled"}
+    ]
+}
+LOOKUPS = {
+    "emission": [
+        "akagiEtAl2011CropResidueBurningFactor",
+        "akagiEtAl2011CropResidueBurningFactor-sd",
+    ]
+}
+TERM_ID = "ch4ToAirCropResidueBurning"
+TIER = EmissionMethodTier.TIER_1.value
+
+
+def run(cycle: dict):
+    return run_emission(TERM_ID, cycle)

hestia_earth_models-0.75.11/hestia_earth/models/akagiEtAl2011/nh3ToAirCropResidueBurning.py

@@ -0,0 +1,35 @@
+from hestia_earth.schema import EmissionMethodTier
+
+from .utils import run_emission
+
+REQUIREMENTS = {
+    "Cycle": {
+        "or": {
+            "products": [
+                {
+                    "@type": "Product",
+                    "term.@id": ["aboveGroundCropResidueBurnt", "discardedCropBurnt"],
+                    "value": "",
+                }
+            ],
+            "completeness.cropResidue": "True",
+        }
+    }
+}
+RETURNS = {
+    "Emission": [
+        {"value": "", "sd": "", "methodTier": "tier 1", "statsDefinition": "modelled"}
+    ]
+}
+LOOKUPS = {
+    "emission": [
+        "akagiEtAl2011CropResidueBurningFactor",
+        "akagiEtAl2011CropResidueBurningFactor-sd",
+    ]
+}
+TERM_ID = "nh3ToAirCropResidueBurning"
+TIER = EmissionMethodTier.TIER_1.value
+
+
+def run(cycle: dict):
+    return run_emission(TERM_ID, cycle)

hestia_earth_models-0.75.11/hestia_earth/models/akagiEtAl2011/noxToAirCropResidueBurning.py

@@ -0,0 +1,35 @@
+from hestia_earth.schema import EmissionMethodTier
+
+from .utils import run_emission
+
+REQUIREMENTS = {
+    "Cycle": {
+        "or": {
+            "products": [
+                {
+                    "@type": "Product",
+                    "term.@id": ["aboveGroundCropResidueBurnt", "discardedCropBurnt"],
+                    "value": "",
+                }
+            ],
+            "completeness.cropResidue": "True",
+        }
+    }
+}
+RETURNS = {
+    "Emission": [
+        {"value": "", "sd": "", "methodTier": "tier 1", "statsDefinition": "modelled"}
+    ]
+}
+LOOKUPS = {
+    "emission": [
+        "akagiEtAl2011CropResidueBurningFactor",
+        "akagiEtAl2011CropResidueBurningFactor-sd",
+    ]
+}
+TERM_ID = "noxToAirCropResidueBurning"
+TIER = EmissionMethodTier.TIER_1.value
+
+
+def run(cycle: dict):
+    return run_emission(TERM_ID, cycle)

hestia_earth_models-0.75.11/hestia_earth/models/akagiEtAl2011/pm25ToAirCropResidueBurning.py

@@ -0,0 +1,35 @@
+from hestia_earth.schema import EmissionMethodTier
+
+from .utils import run_emission
+
+REQUIREMENTS = {
+    "Cycle": {
+        "or": {
+            "products": [
+                {
+                    "@type": "Product",
+                    "term.@id": ["aboveGroundCropResidueBurnt", "discardedCropBurnt"],
+                    "value": "",
+                }
+            ],
+            "completeness.cropResidue": "True",
+        }
+    }
+}
+RETURNS = {
+    "Emission": [
+        {"value": "", "sd": "", "methodTier": "tier 1", "statsDefinition": "modelled"}
+    ]
+}
+LOOKUPS = {
+    "emission": [
+        "akagiEtAl2011CropResidueBurningFactor",
+        "akagiEtAl2011CropResidueBurningFactor-sd",
+    ]
+}
+TERM_ID = "pm25ToAirCropResidueBurning"
+TIER = EmissionMethodTier.TIER_1.value
+
+
+def run(cycle: dict):
+    return run_emission(TERM_ID, cycle)

hestia_earth_models-0.75.11/hestia_earth/models/akagiEtAl2011/so2ToAirCropResidueBurning.py

@@ -0,0 +1,35 @@
+from hestia_earth.schema import EmissionMethodTier
+
+from .utils import run_emission
+
+REQUIREMENTS = {
+    "Cycle": {
+        "or": {
+            "products": [
+                {
+                    "@type": "Product",
+                    "term.@id": ["aboveGroundCropResidueBurnt", "discardedCropBurnt"],
+                    "value": "",
+                }
+            ],
+            "completeness.cropResidue": "True",
+        }
+    }
+}
+RETURNS = {
+    "Emission": [
+        {"value": "", "sd": "", "methodTier": "tier 1", "statsDefinition": "modelled"}
+    ]
+}
+LOOKUPS = {
+    "emission": [
+        "akagiEtAl2011CropResidueBurningFactor",
+        "akagiEtAl2011CropResidueBurningFactor-sd",
+    ]
+}
+TERM_ID = "so2ToAirCropResidueBurning"
+TIER = EmissionMethodTier.TIER_1.value
+
+
+def run(cycle: dict):
+    return run_emission(TERM_ID, cycle)