hestia-earth-models 0.64.8__py3-none-any.whl → 0.64.10__py3-none-any.whl

hestia_earth/models/ipcc2019/aboveGroundBiomass.py

@@ -1,9 +1,8 @@
 from enum import Enum
 from functools import reduce
-from math import isclose
 from numpy import average, copy, random, vstack
 from numpy.typing import NDArray
-from typing import Callable, Optional, Union
+from typing import Optional, Union
 
 from hestia_earth.schema import (
     MeasurementMethodClassification,
@@ -12,7 +11,6 @@ from hestia_earth.schema import (
     TermTermType
 )
 
-from hestia_earth.utils.blank_node import get_node_value
 from hestia_earth.utils.model import filter_list_term_type
 from hestia_earth.utils.tools import non_empty_list
 
@@ -23,15 +21,16 @@ from hestia_earth.models.utils.blank_node import group_nodes_by_year
 from hestia_earth.models.utils.descriptive_stats import calc_descriptive_stats
 from hestia_earth.models.utils.ecoClimateZone import EcoClimateZone, get_eco_climate_zone_value
 from hestia_earth.models.utils.measurement import _new_measurement
-from hestia_earth.models.utils.term import get_lookup_value
 
 from . import MODEL
-from .aboveGroundBiomass_utils import assign_biomass_category, BiomassCategory, sample_biomass_equilibrium
+from .biomass_utils import (
+    BiomassCategory, detect_land_cover_change, group_by_biomass_category, group_by_term_id, sample_biomass_equilibrium,
+    summarise_land_cover_nodes
+)
 
 
 REQUIREMENTS = {
     "Site": {
-        "siteType": ["cropland", "permanent pasture", "forest", "other natural vegetation"],
         "management": [
             {
                 "@type": "Management",
@@ -49,7 +48,10 @@ REQUIREMENTS = {
                 "value": ["1", "2", "3", "4", "7", "8", "9", "10", "11", "12"],
                 "term.@id": "ecoClimateZone"
             }
-        ]
+        ],
+        "none": {
+            "siteType": ["glass or high accessible cover"]
+        }
     }
 }
 LOOKUPS = {
@@ -93,28 +95,13 @@ _METHOD_CLASSIFICATION = MeasurementMethodClassification.TIER_1_MODEL.value
 _STATS_DEFINITION = MeasurementStatsDefinition.SIMULATED.value
 
 _LAND_COVER_TERM_TYPE = TermTermType.LANDCOVER
-_TARGET_LAND_COVER = 100
 
 _EQUILIBRIUM_TRANSITION_PERIOD = 20
 _EXCLUDED_ECO_CLIMATE_ZONES = {EcoClimateZone.POLAR_MOIST, EcoClimateZone.POLAR_DRY}
-_VALID_SITE_TYPES = {
-    SiteSiteType.CROPLAND.value,
-    SiteSiteType.FOREST.value,
-    SiteSiteType.OTHER_NATURAL_VEGETATION.value,
-    SiteSiteType.PERMANENT_PASTURE.value
+_EXCLUDED_SITE_TYPES = {
+    SiteSiteType.GLASS_OR_HIGH_ACCESSIBLE_COVER.value
 }
 
-_GROUP_LAND_COVER_BY_BIOMASS_CATEGORY = [
-    BiomassCategory.ANNUAL_CROPS,
-    BiomassCategory.GRASSLAND,
-    BiomassCategory.OTHER,
-    BiomassCategory.SHORT_ROTATION_COPPICE
-]
-"""
-Terms associated with these biomass categories can be grouped together when summarising land cover coverage in
-`_group_by_term_id`.
-"""
-
 
 class _InventoryKey(Enum):
     """
@@ -171,7 +158,7 @@ def _should_run(site: dict) -> tuple[bool, dict, dict]:
 
     land_cover = filter_list_term_type(site.get("management", []), _LAND_COVER_TERM_TYPE)
 
-    has_valid_site_type = site_type in _VALID_SITE_TYPES
+    has_valid_site_type = site_type not in _EXCLUDED_SITE_TYPES
     has_valid_eco_climate_zone = all([
         eco_climate_zone,
         eco_climate_zone not in _EXCLUDED_ECO_CLIMATE_ZONES
@@ -267,12 +254,12 @@ def _compile_inventory(land_cover_nodes: list[dict]) -> dict:
         prev_year, current_year = year_pair
         land_cover_nodes = land_cover_grouped.get(current_year, {})
 
-        biomass_category_summary = _summarise_land_cover_nodes(land_cover_nodes, _group_by_biomass_category)
-        land_cover_summary = _summarise_land_cover_nodes(land_cover_nodes, _group_by_term_id)
+        biomass_category_summary = summarise_land_cover_nodes(land_cover_nodes, group_by_biomass_category)
+        land_cover_summary = summarise_land_cover_nodes(land_cover_nodes, group_by_term_id)
 
         prev_land_cover_summary = inventory.get(prev_year, {}).get(_InventoryKey.LAND_COVER_SUMMARY, {})
 
-        is_lcc_event = _is_lcc_event(land_cover_summary, prev_land_cover_summary)
+        is_lcc_event = detect_land_cover_change(land_cover_summary, prev_land_cover_summary)
 
         time_delta = current_year - prev_year
         prev_years_since_lcc_event = inventory.get(prev_year, {}).get(_InventoryKey.YEARS_SINCE_LCC_EVENT, 0)
@@ -295,11 +282,11 @@ def _compile_inventory(land_cover_nodes: list[dict]) -> dict:
 
     initial = {
         start_year: {
-            _InventoryKey.BIOMASS_CATEGORY_SUMMARY: _summarise_land_cover_nodes(
-                initial_land_cover_nodes, _group_by_biomass_category
+            _InventoryKey.BIOMASS_CATEGORY_SUMMARY: summarise_land_cover_nodes(
+                initial_land_cover_nodes, group_by_biomass_category
             ),
-            _InventoryKey.LAND_COVER_SUMMARY: _summarise_land_cover_nodes(
-                initial_land_cover_nodes, _group_by_term_id
+            _InventoryKey.LAND_COVER_SUMMARY: summarise_land_cover_nodes(
+                initial_land_cover_nodes, group_by_term_id
             ),
             _InventoryKey.LAND_COVER_CHANGE_EVENT: False,
             _InventoryKey.YEARS_SINCE_LCC_EVENT: _EQUILIBRIUM_TRANSITION_PERIOD,
@@ -314,216 +301,6 @@ def _compile_inventory(land_cover_nodes: list[dict]) -> dict:
     )
 
 
-def _group_by_biomass_category(result: dict[BiomassCategory, float], node: dict) -> dict[BiomassCategory, float]:
-    """
-    Reducer function for `_group_land_cover_nodes_by` that groups and sums node value by their associated
-    `BiomassCategory`.
-
-    Parameters
-    ----------
-    result : dict
-        A dict with the shape `{category (BiomassCategory): sum_value (float), ...categories}`.
-    node : dict
-        A HESTIA `Management` node with `term.termType` = `landCover`.
-
-    Returns
-    -------
-    result : dict
-        A dict with the shape `{category (BiomassCategory): sum_value (float), ...categories}`.
-    """
-    biomass_category = _retrieve_biomass_category(node)
-    value = get_node_value(node)
-
-    update_dict = {biomass_category: result.get(biomass_category, 0) + value}
-
-    should_run = biomass_category and value
-    return result | update_dict if should_run else result
-
-
-def _group_by_term_id(
-    result: dict[Union[str, BiomassCategory], float], node: dict
-) -> dict[Union[str, BiomassCategory], float]:
-    """
-    Reducer function for `_group_land_cover_nodes_by` that groups and sums node value by their `term.@id` if a the land
-    cover is a woody plant, else by their associated `BiomassCategory`
-
-    Land cover events can be triggered by changes in land cover within the same `BiomassCategory` (e.g., `peachTree` to
-    `appleTree`) due to the requirement to clear the previous woody biomass to establish the new land cover.
-
-    Some land covers (e.g., land covers associated with the `BiomassCategory` = `Annual crops`, `Grassland`, `Other` or
-    `Short rotation coppice`) are exempt from this rule due to the Tier 1 assumptions that biomass does not accumulate
-    within the category or the maturity cycle of the land cover is significantly shorter than the amortisation period of
-    20 years.
-
-    Parameters
-    ----------
-    result : dict
-        A dict with the shape `{category (str | BiomassCategory): sum_value (float), ...categories}`.
-    node : dict
-        A HESTIA `Management` node with `term.termType` = `landCover`.
-
-    Returns
-    -------
-    result : dict
-        A dict with the shape `{category (str | BiomassCategory): sum_value (float), ...categories}`.
-    """
-    term_id = node.get("term", {}).get("@id")
-    biomass_category = _retrieve_biomass_category(node)
-    value = get_node_value(node)
-
-    key = biomass_category if biomass_category in _GROUP_LAND_COVER_BY_BIOMASS_CATEGORY else term_id
-
-    update_dict = {key: result.get(key, 0) + value}
-
-    should_run = biomass_category and value
-    return result | update_dict if should_run else result
-
-
-def _retrieve_biomass_category(node: dict) -> Optional[BiomassCategory]:
-    """
-    Retrieve the `BiomassCategory` associated with a land cover using the `BIOMASS_CATEGORY` lookup.
-
-    If lookup value is missing, return `None`.
-
-    Parameters
-    ----------
-    node : dict
-        A valid `Management` node with `term.termType` = `landCover`.
-
-    Returns
-    -------
-    BiomassCategory | None
-        The associated `BiomassCategory` or `None`
-    """
-    LOOKUP = LOOKUPS["landCover"]
-    term = node.get("term", {})
-    lookup_value = get_lookup_value(term, LOOKUP)
-
-    return assign_biomass_category(lookup_value) if lookup_value else None
-
-
-def _summarise_land_cover_nodes(
-    land_cover_nodes: list[dict],
-    group_by_func: Callable[[dict, dict], dict] = _group_by_biomass_category
-) -> dict[Union[str, BiomassCategory], float]:
-    """
-    Group land cover nodes using `group_by_func`.
-
-    Parameters
-    ----------
-    land_cover_nodes : list[dict]
-        A list of HESTIA `Management` nodes with `term.termType` = `landCover`.
-
-    Returns
-    -------
-    result : dict
-        A dict with the shape `{category (str | BiomassCategory): sum_value (float), ...categories}`.
-    """
-    category_cover = reduce(group_by_func, land_cover_nodes, dict())
-    return _rescale_category_cover(category_cover)
-
-
-def _rescale_category_cover(
-    category_cover: dict[Union[BiomassCategory, str], float]
-) -> dict[Union[BiomassCategory, str], float]:
-    """
-    Enforce a land cover coverage of 100%.
-
-    If input coverage is less than 100%, fill the remainder with `BiomassCategory.OTHER`. If the input coverage is
-    greater than 100%, proportionally downscale all categories.
-
-    Parameters
-    ----------
-    category_cover : dict[BiomassCategory | str, float]
-        The input category cover dict.
-
-    Returns
-    -------
-    result : dict[BiomassCategory | str, float]
-        The rescaled category cover dict.
-    """
-    total_cover = sum(category_cover.values())
-    return (
-        _fill_category_cover(category_cover) if total_cover < _TARGET_LAND_COVER
-        else _squash_category_cover(category_cover) if total_cover > _TARGET_LAND_COVER
-        else category_cover
-    )
-
-
-def _fill_category_cover(
-    category_cover:  dict[Union[BiomassCategory, str], float]
-) -> dict[Union[BiomassCategory, str], float]:
-    """
-    Fill the land cover coverage with `BiomassCategory.OTHER` to enforce a total coverage of 100%.
-
-    Parameters
-    ----------
-    category_cover : dict[BiomassCategory | str, float]
-        The input category cover dict.
-
-    Returns
-    -------
-    result : dict[BiomassCategory | str, float]
-        The rescaled category cover dict.
-    """
-    total_cover = sum(category_cover.values())
-    update_dict = {
-        BiomassCategory.OTHER: category_cover.get(BiomassCategory.OTHER, 0) + (_TARGET_LAND_COVER - total_cover)
-    }
-    return category_cover | update_dict
-
-
-def _squash_category_cover(
-    category_cover: dict[Union[BiomassCategory, str], float]
-) -> dict[Union[BiomassCategory, str], float]:
-    """
-    Proportionally shrink all land cover categories to enforce a total coverage of 100%.
-
-    Parameters
-    ----------
-    category_cover : dict[BiomassCategory | str, float]
-        The input category cover dict.
-
-    Returns
-    -------
-    result : dict[BiomassCategory | str, float]
-        The rescaled category cover dict.
-    """
-    total_cover = sum(category_cover.values())
-    return {
-        category: (cover / total_cover) * _TARGET_LAND_COVER
-        for category, cover in category_cover.items()
-    }
-
-
-def _is_lcc_event(
-    a: dict[Union[BiomassCategory, str], float],
-    b: dict[Union[BiomassCategory, str], float]
-) -> bool:
-    """
-    Land cover values (% area) are compared with an absolute tolerance of 0.0001, which is equivalent to 1 m2 per
-    hectare.
-
-    Parameters
-    ----------
-    a : dict[BiomassCategory | str, float]
-        The first land-cover summary dict.
-    b : dict[BiomassCategory | str, float]
-        The second land-cover summary dict.
-
-    Returns
-    -------
-    bool
-        Whether a land-cover change event has occured.
-    """
-    keys_match = sorted(str(key) for key in b.keys()) == sorted(str(key) for key in a.keys())
-    values_close = all(
-        isclose(b.get(key), a.get(key, -999), abs_tol=0.0001) for key in b.keys()
-    )
-
-    return not all([keys_match, values_close])
-
-
 def _format_inventory(inventory: dict) -> str:
     """
     Format the SOC inventory for logging as a table. Rows represent inventory years, columns represent soc stock change
@@ -665,7 +442,7 @@ def _run(
     timestamps = list(inventory.keys())
 
     factor_cache = {
-        category: sample_biomass_equilibrium(iterations, category, eco_climate_zone, rng)
+        category: sample_biomass_equilibrium(iterations, category, eco_climate_zone, _build_col_name, seed=rng)
         for category in unique_biomass_categories
     }
 
@@ -710,6 +487,17 @@ def _run(
     return [_measurement(timestamps, **descriptive_stats)]
 
 
+def _build_col_name(biomass_category: BiomassCategory) -> str:
+    """
+    Get the column name for the `ecoClimateZone-lookup.csv` for a specific biomass category equilibrium.
+    """
+    COL_NAME_ROOT = "AG_BIOMASS_EQUILIBRIUM_KG_C_HECTARE_"
+    return (
+        f"{COL_NAME_ROOT}{biomass_category.name}" if isinstance(biomass_category, BiomassCategory)
+        else f"{COL_NAME_ROOT}OTHER"
+    )
+
+
 def _measurement(
     timestamps: list[int],
     value: list[float],

hestia_earth/models/ipcc2019/animal/fatContent.py

@@ -0,0 +1,38 @@
+from .utils import should_run_by_productivity_lookup, run_animal_by_productivity
+
+REQUIREMENTS = {
+    "Cycle": {
+        "site": {
+            "@type": "Site",
+            "country": {"@type": "Term", "termType": "region"}
+        },
+        "animals": [{
+            "@type": "Animal",
+            "term.termType": "liveAnimal",
+            "practices": {
+                "@type": "Practice",
+                "term.termType": "animalManagement"
+            }
+        }]
+    }
+}
+LOOKUPS = {
+    "region-liveAnimal-milkFatContent": "fat content",
+    "liveAnimal": "milkYieldPracticeTermIds"
+}
+RETURNS = {
+    "Animal": [{
+        "practices": [{
+            "@type": "Practice",
+            "value": ""
+        }]
+    }]
+}
+TERM_ID = 'fatContent'
+
+
+def run(cycle: dict):
+    animals = should_run_by_productivity_lookup(
+        TERM_ID, cycle, list(LOOKUPS.keys())[0], practice_id=LOOKUPS['liveAnimal']
+    )
+    return list(map(run_animal_by_productivity(TERM_ID, include_practice=True), animals))

hestia_earth/models/ipcc2019/animal/liveweightGain.py

@@ -1,11 +1,4 @@
-from hestia_earth.schema import TermTermType
-from hestia_earth.utils.model import filter_list_term_type
-
-from hestia_earth.models.log import logRequirements, logShouldRun
-from hestia_earth.models.utils.blank_node import merge_blank_nodes
-from hestia_earth.models.utils.property import _new_property, node_has_no_property
-from .utils import productivity_lookup_value
-from .. import MODEL
+from .utils import should_run_by_productivity_lookup, run_animal_by_productivity
 
 REQUIREMENTS = {
     "Cycle": {
@@ -40,50 +33,6 @@ RETURNS = {
 TERM_ID = 'liveweightGain'
 
 
-def _property(value: float):
-    prop = _new_property(TERM_ID, MODEL)
-    prop['value'] = value
-    return prop
-
-
-def _run_animal(data: dict):
-    animal = data.get('animal')
-    value = data.get('value')
-    return animal | {
-        'properties': merge_blank_nodes(animal.get('properties', []), [_property(value)])
-    }
-
-
-def _should_run(cycle: dict):
-    country = cycle.get('site', {}).get('country', {})
-    country_id = country.get('@id')
-    live_animals = filter_list_term_type(cycle.get('animals', []), TermTermType.LIVEANIMAL)
-    live_animals = list(filter(node_has_no_property(TERM_ID), live_animals))
-    live_animals_with_value = [{
-        'animal': animal,
-        'value': productivity_lookup_value(TERM_ID, list(LOOKUPS.keys())[0], country, animal)
-    } for animal in live_animals]
-
-    def _should_run_animal(value: dict):
-        animal = value.get('animal')
-        lookup_value = value.get('value')
-        term_id = animal.get('term').get('@id')
-
-        logRequirements(cycle, model=MODEL, term=term_id, property=TERM_ID,
-                        country_id=country_id,
-                        liveweightGain=lookup_value)
-
-        should_run = all([
-            country_id,
-            lookup_value is not None
-        ])
-        logShouldRun(cycle, MODEL, term_id, should_run, property=TERM_ID)
-
-        return should_run
-
-    return list(filter(_should_run_animal, live_animals_with_value))
-
-
 def run(cycle: dict):
-    animals = _should_run(cycle)
-    return list(map(_run_animal, animals))
+    animals = should_run_by_productivity_lookup(TERM_ID, cycle, list(LOOKUPS.keys())[0])
+    return list(map(run_animal_by_productivity(TERM_ID), animals))

hestia_earth/models/ipcc2019/animal/liveweightPerHead.py

@@ -1,11 +1,4 @@
-from hestia_earth.schema import TermTermType
-from hestia_earth.utils.model import filter_list_term_type
-
-from hestia_earth.models.log import logRequirements, logShouldRun
-from hestia_earth.models.utils.blank_node import merge_blank_nodes
-from hestia_earth.models.utils.property import _new_property, node_has_no_property
-from .utils import productivity_lookup_value
-from .. import MODEL
+from .utils import should_run_by_productivity_lookup, run_animal_by_productivity
 
 REQUIREMENTS = {
     "Cycle": {
@@ -40,50 +33,6 @@ RETURNS = {
 TERM_ID = 'liveweightPerHead'
 
 
-def _property(value: float):
-    prop = _new_property(TERM_ID, MODEL)
-    prop['value'] = value
-    return prop
-
-
-def _run_animal(data: dict):
-    animal = data.get('animal')
-    value = data.get('value')
-    return animal | {
-        'properties': merge_blank_nodes(animal.get('properties', []), [_property(value)])
-    }
-
-
-def _should_run(cycle: dict):
-    country = cycle.get('site', {}).get('country', {})
-    country_id = country.get('@id')
-    live_animals = filter_list_term_type(cycle.get('animals', []), TermTermType.LIVEANIMAL)
-    live_animals = list(filter(node_has_no_property(TERM_ID), live_animals))
-    live_animals_with_value = [{
-        'animal': animal,
-        'value': productivity_lookup_value(TERM_ID, list(LOOKUPS.keys())[0], country, animal)
-    } for animal in live_animals]
-
-    def _should_run_animal(value: dict):
-        animal = value.get('animal')
-        lookup_value = value.get('value')
-        term_id = animal.get('term').get('@id')
-
-        logRequirements(cycle, model=MODEL, term=term_id, property=TERM_ID,
-                        country_id=country_id,
-                        liveweightPerHead=lookup_value)
-
-        should_run = all([
-            country_id,
-            lookup_value is not None
-        ])
-        logShouldRun(cycle, MODEL, term_id, should_run, property=TERM_ID)
-
-        return should_run
-
-    return list(filter(_should_run_animal, live_animals_with_value))
-
-
 def run(cycle: dict):
-    animals = _should_run(cycle)
-    return list(map(_run_animal, animals))
+    animals = should_run_by_productivity_lookup(TERM_ID, cycle, list(LOOKUPS.keys())[0])
+    return list(map(run_animal_by_productivity(TERM_ID), animals))

hestia_earth/models/ipcc2019/animal/pregnancyRateTotal.py

@@ -0,0 +1,38 @@
+from .utils import should_run_by_productivity_lookup, run_animal_by_productivity
+
+REQUIREMENTS = {
+    "Cycle": {
+        "site": {
+            "@type": "Site",
+            "country": {"@type": "Term", "termType": "region"}
+        },
+        "animals": [{
+            "@type": "Animal",
+            "term.termType": "liveAnimal",
+            "none": {
+                "properties": [{
+                    "@type": "Property",
+                    "value": "",
+                    "term.@id": "pregnancyRateTotal"
+                }]
+            }
+        }]
+    }
+}
+LOOKUPS = {
+    "region-liveAnimal-pregnancyRateTotal": "pregnancy rate"
+}
+RETURNS = {
+    "Animal": [{
+        "properties": [{
+            "@type": "Property",
+            "value": ""
+        }]
+    }]
+}
+TERM_ID = 'pregnancyRateTotal'
+
+
+def run(cycle: dict):
+    animals = should_run_by_productivity_lookup(TERM_ID, cycle, list(LOOKUPS.keys())[0])
+    return list(map(run_animal_by_productivity(TERM_ID), animals))

hestia_earth/models/ipcc2019/animal/trueProteinContent.py

@@ -0,0 +1,38 @@
+from .utils import should_run_by_productivity_lookup, run_animal_by_productivity
+
+REQUIREMENTS = {
+    "Cycle": {
+        "site": {
+            "@type": "Site",
+            "country": {"@type": "Term", "termType": "region"}
+        },
+        "animals": [{
+            "@type": "Animal",
+            "term.termType": "liveAnimal",
+            "practices": {
+                "@type": "Practice",
+                "term.termType": "animalManagement"
+            }
+        }]
+    }
+}
+LOOKUPS = {
+    "region-liveAnimal-milkTrueProteinContent": "protein content",
+    "liveAnimal": "milkYieldPracticeTermIds"
+}
+RETURNS = {
+    "Animal": [{
+        "practices": [{
+            "@type": "Practice",
+            "value": ""
+        }]
+    }]
+}
+TERM_ID = 'trueProteinContent'
+
+
+def run(cycle: dict):
+    animals = should_run_by_productivity_lookup(
+        TERM_ID, cycle, list(LOOKUPS.keys())[0], practice_id=LOOKUPS['liveAnimal']
+    )
+    return list(map(run_animal_by_productivity(TERM_ID, include_practice=True), animals))