hestia-earth-models 0.74.7__py3-none-any.whl → 0.74.9__py3-none-any.whl

hestia_earth/models/ipcc2019/organicCarbonPerHa_tier_1.py

@@ -19,14 +19,16 @@ from hestia_earth.models.utils.blank_node import (
 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.property import get_node_property
-from hestia_earth.models.utils.term import get_residue_removed_or_burnt_terms, get_upland_rice_land_cover_terms
+from hestia_earth.models.utils.term import (
+    get_lookup_value, get_residue_removed_or_burnt_terms, get_upland_rice_land_cover_terms
+)
 
 from .organicCarbonPerHa_utils import (
-    check_irrigation, DEPTH_LOWER, DEPTH_UPPER, IPCC_SOIL_CATEGORY_TO_SOIL_TYPE_LOOKUP_VALUE,
+    check_irrigation, DEPTH_LOWER, DEPTH_UPPER, format_soil_inventory, IPCC_SOIL_CATEGORY_TO_SOIL_TYPE_LOOKUP_VALUE,
     IPCC_LAND_USE_CATEGORY_TO_LAND_COVER_LOOKUP_VALUE, IPCC_MANAGEMENT_CATEGORY_TO_GRASSLAND_MANAGEMENT_TERM_ID,
     IPCC_MANAGEMENT_CATEGORY_TO_TILLAGE_MANAGEMENT_LOOKUP_VALUE, IpccSoilCategory, IpccCarbonInputCategory,
     IpccLandUseCategory, IpccManagementCategory, is_cover_crop, MIN_AREA_THRESHOLD, sample_constant,
-    sample_plus_minus_error, sample_plus_minus_uncertainty, SITE_TYPE_TO_IPCC_LAND_USE_CATEGORY,
+    sample_plus_minus_error, sample_plus_minus_uncertainty, SITE_TYPE_TO_IPCC_LAND_USE_CATEGORY, SoilData,
     SUPER_MAJORITY_AREA_THRESHOLD, STATS_DEFINITION
 )
 from . import MODEL
@@ -45,7 +47,11 @@ REQUIREMENTS = {
         ],
         "optional": {
             "measurements": [
-                {"@type": "Measurement", "value": "", "term.termType": ["soilType", "usdaSoilType"]}
+                {
+                    "@doc": "This model cannot run on sites with more than 30 percent organic soils (`histols`, `histosol` and their subclasses).",  # noqa: E501
+                    "@type": "Measurement", "value": "",
+                    "term.termType": ["soilType", "usdaSoilType"]
+                }
             ],
             "management": [
                 {
@@ -606,16 +612,19 @@ def should_run(site: dict) -> tuple[bool, dict, dict]:
     measurement_nodes = site.get("measurements", [])
 
     eco_climate_zone = get_eco_climate_zone_value(site, as_enum=True)
-    ipcc_soil_category = _assign_ipcc_soil_category(measurement_nodes)
+    ipcc_soil_category, soil_logs = _assign_ipcc_soil_category(measurement_nodes)
     soc_ref = _get_soc_ref_preview(ipcc_soil_category, eco_climate_zone)
 
+    valid_site_type = site_type in _VALID_SITE_TYPES
+    valid_eco_climate_zone = eco_climate_zone not in _EXCLUDED_ECO_CLIMATE_ZONES
+    valid_soc_ref = isinstance(soc_ref, (float, int)) and soc_ref > 0
     has_management = len(management_nodes) > 0
     has_measurements = len(measurement_nodes) > 0
 
     should_compile_inventory = all([
-        site_type in _VALID_SITE_TYPES,
-        eco_climate_zone not in _EXCLUDED_ECO_CLIMATE_ZONES,
-        soc_ref or -9999 > 0,
+        valid_site_type,
+        valid_eco_climate_zone,
+        valid_soc_ref,
         has_management,
         has_measurements
     ])
@@ -638,9 +647,13 @@ def should_run(site: dict) -> tuple[bool, dict, dict]:
         year for year, group in inventory.items() if group.get(_InventoryKey.SHOULD_RUN)
     )
 
-    logs = inventory_logs | {
+    logs = soil_logs | inventory_logs | {
         "site_type": site_type,
+        "soc_ref_available": valid_soc_ref,
         "soc_ref": soc_ref,
+        "valid_eco_climate_zone": valid_eco_climate_zone,
+        "valid_soil_category": ipcc_soil_category not in [IpccSoilCategory.ORGANIC_SOILS],
+        "valid_site_type": valid_site_type,
         "has_management": has_management,
         "has_measurements": has_measurements,
         "should_compile_inventory_tier_1": should_compile_inventory,
@@ -1034,24 +1047,34 @@ def _assign_ipcc_soil_category(
     soil_types = _get_soil_type_measurements(measurement_nodes, TermTermType.SOILTYPE)
     usda_soil_types = _get_soil_type_measurements(measurement_nodes, TermTermType.USDASOILTYPE)
 
+    soil_data = [_unpack_soil_data(node) for node in soil_types]
+    usda_soil_data = [_unpack_soil_data(node) for node in usda_soil_types]
+
     clay_content = get_node_value(find_term_match(measurement_nodes, _CLAY_CONTENT_TERM_ID))
     sand_content = get_node_value(find_term_match(measurement_nodes, _SAND_CONTENT_TERM_ID))
-
     has_sandy_soil = clay_content < _CLAY_CONTENT_MAX and sand_content > _SAND_CONTENT_MIN
 
-    return next(
+    logs = {
+        "soil_data": format_soil_inventory(soil_data),
+        "usda_soil_data": format_soil_inventory(usda_soil_data),
+        "has_sandy_soil_texture": has_sandy_soil
+    }
+
+    category = next(
         (
             key for key in _SOIL_CATEGORY_DECISION_TREE
-            if _SOIL_CATEGORY_DECISION_TREE[key](
+            if _check_soil_category(
                 key=key,
-                soil_types=soil_types,
-                usda_soil_types=usda_soil_types,
+                soil_data=soil_data,
+                usda_soil_data=usda_soil_data,
                 has_sandy_soil=has_sandy_soil
             )
         ),
         default
     ) if len(soil_types) > 0 or len(usda_soil_types) > 0 else default
 
+    return category, logs
+
 
 def _get_soil_type_measurements(
     nodes: list[dict], term_type: Literal[TermTermType.SOILTYPE, TermTermType.USDASOILTYPE]
@@ -1067,98 +1090,66 @@ def _get_soil_type_measurements(
     )
 
 
-def _check_soil_category(
-    *,
-    key: IpccSoilCategory,
-    soil_types: list[dict],
-    usda_soil_types: list[dict],
-    **_
-) -> bool:
-    """
-    Check if the soil category matches the given key.
-
-    Parameters
-    ----------
-    key : IpccSoilCategory
-        The IPCC soil category to check.
-    soil_types : list[dict]
-        List of soil type measurement nodes.
-    usda_soil_types : list[dict]
-        List of USDA soil type measurement nodes
-
-    Returns
-    -------
-    bool
-        `True` if the soil category matches, `False` otherwise.
-    """
-    SOIL_TYPE_LOOKUP = LOOKUPS["soilType"]
-    USDA_SOIL_TYPE_LOOKUP = LOOKUPS["usdaSoilType"]
+def _unpack_soil_data(node):
+    term = node.get("term", {})
+    term_id = term.get("@id")
+    term_type = term.get("termType")
+    value = get_node_value(node)
 
-    target_lookup_values = IPCC_SOIL_CATEGORY_TO_SOIL_TYPE_LOOKUP_VALUE.get(key, None)
+    lookup_value = get_lookup_value(term, LOOKUPS[term_type]) if term_type else None
+    category = next(key for key, value in IPCC_SOIL_CATEGORY_TO_SOIL_TYPE_LOOKUP_VALUE.items() if value == lookup_value)
 
-    is_soil_type_match = cumulative_nodes_lookup_match(
-        soil_types,
-        lookup=SOIL_TYPE_LOOKUP,
-        target_lookup_values=target_lookup_values,
-        cumulative_threshold=MIN_AREA_THRESHOLD
-    )
+    return SoilData(term_id, value, category)
 
-    is_usda_soil_type_match = cumulative_nodes_lookup_match(
-        usda_soil_types,
-        lookup=USDA_SOIL_TYPE_LOOKUP,
-        target_lookup_values=target_lookup_values,
-        cumulative_threshold=MIN_AREA_THRESHOLD
-    )
 
-    return is_soil_type_match or is_usda_soil_type_match
+_IPCC_SOIL_CATEGORY_TO_OVERRIDE_KWARGS = {
+    IpccSoilCategory.SANDY_SOILS: {"has_sandy_soil"}
+}
+"""
+Keyword arguments that can override the `soilType`/`usdaSoilType` lookup match for an `IpccSoilCategory`.
+"""
 
 
-def _check_sandy_soil_category(
-    *,
-    key: IpccSoilCategory,
-    soil_types: list[dict],
-    usda_soil_types: list[dict],
-    has_sandy_soil: bool,
-    **_
+def _check_soil_category(
+    *, key: IpccSoilCategory, soil_data: list[SoilData], usda_soil_data: list[SoilData], **kwargs
 ) -> bool:
     """
-    Check if the soils are sandy.
-
-    This function is special case of `_check_soil_category`.
+    Check if the soil category matches the given key.
 
     Parameters
     ----------
     key : IpccSoilCategory
         The IPCC soil category to check.
-    soil_types : list[dict]
-        List of soil type measurement nodes.
-    usda_soil_types : list[dict]
-        List of USDA soil type measurement nodes
-    has_sandy_soil : bool
-        True if the soils are sandy, False otherwise.
+    soil_data : list[SoilData]
+        List of `SoilData` NamedEnums generated from `soilType` measurement nodes.
+    usda_soil_data : list[SoilData]
+        List of `SoilData` NamedEnums generated from `usdaSoilType` measurement nodes.
 
     Returns
     -------
     bool
         `True` if the soil category matches, `False` otherwise.
     """
-    return _check_soil_category(key=key, soil_types=soil_types, usda_soil_types=usda_soil_types) or has_sandy_soil
+    override_kwargs = _IPCC_SOIL_CATEGORY_TO_OVERRIDE_KWARGS.get(key, set())
+    valid_override = any(v for k, v in kwargs.items() if k in override_kwargs)
 
+    is_soil_match = sum(data.value for data in soil_data if data.category == key) > MIN_AREA_THRESHOLD
+    is_usda_soil_match = sum(data.value for data in usda_soil_data if data.category == key) > MIN_AREA_THRESHOLD
+
+    return valid_override or is_soil_match or is_usda_soil_match
 
-_SOIL_CATEGORY_DECISION_TREE = {
-    IpccSoilCategory.ORGANIC_SOILS: _check_soil_category,
-    IpccSoilCategory.SANDY_SOILS: _check_sandy_soil_category,
-    IpccSoilCategory.WETLAND_SOILS: _check_soil_category,
-    IpccSoilCategory.VOLCANIC_SOILS: _check_soil_category,
-    IpccSoilCategory.SPODIC_SOILS: _check_soil_category,
-    IpccSoilCategory.HIGH_ACTIVITY_CLAY_SOILS: _check_soil_category,
-    IpccSoilCategory.LOW_ACTIVITY_CLAY_SOILS: _check_soil_category
-}
-"""
-A decision tree mapping IPCC soil categories to corresponding check functions.
 
-Key: IpccSoilCategory
-Value: Corresponding function for checking the match of the given soil category based on soil types.
+_SOIL_CATEGORY_DECISION_TREE = [
+    IpccSoilCategory.ORGANIC_SOILS,
+    IpccSoilCategory.SANDY_SOILS,
+    IpccSoilCategory.WETLAND_SOILS,
+    IpccSoilCategory.VOLCANIC_SOILS,
+    IpccSoilCategory.SPODIC_SOILS,
+    IpccSoilCategory.HIGH_ACTIVITY_CLAY_SOILS,
+    IpccSoilCategory.LOW_ACTIVITY_CLAY_SOILS
+]
+"""
+A decision tree determining the order to check IPCC soil categories.
 """
 
 
@@ -1201,7 +1192,7 @@ def _assign_ipcc_land_use_category(
     return next(
         (
             key for key in DECISION_TREE
-            if DECISION_TREE[key](
+            if _check_ipcc_land_use_category(
                 key=key,
                 land_cover_nodes=land_cover_nodes,
                 has_long_fallow=has_long_fallow,
@@ -1317,23 +1308,19 @@ Keyword arguments that can override the `landCover` lookup match for specific `I
 """
 
 
-_LAND_USE_CATEGORY_DECISION_TREE = {
-    IpccLandUseCategory.GRASSLAND: _check_ipcc_land_use_category,
-    IpccLandUseCategory.SET_ASIDE: _check_ipcc_land_use_category,
-    IpccLandUseCategory.PERENNIAL_CROPS: _check_ipcc_land_use_category,
-    IpccLandUseCategory.PADDY_RICE_CULTIVATION: _check_ipcc_land_use_category,
-    IpccLandUseCategory.ANNUAL_CROPS_WET: _check_ipcc_land_use_category,
-    IpccLandUseCategory.ANNUAL_CROPS: _check_ipcc_land_use_category,
-    IpccLandUseCategory.FOREST: _check_ipcc_land_use_category,
-    IpccLandUseCategory.NATIVE: _check_ipcc_land_use_category,
-    IpccLandUseCategory.OTHER: _check_ipcc_land_use_category
-}
+_LAND_USE_CATEGORY_DECISION_TREE = [
+    IpccLandUseCategory.GRASSLAND,
+    IpccLandUseCategory.SET_ASIDE,
+    IpccLandUseCategory.PERENNIAL_CROPS,
+    IpccLandUseCategory.PADDY_RICE_CULTIVATION,
+    IpccLandUseCategory.ANNUAL_CROPS_WET,
+    IpccLandUseCategory.ANNUAL_CROPS,
+    IpccLandUseCategory.FOREST,
+    IpccLandUseCategory.NATIVE,
+    IpccLandUseCategory.OTHER
+]
 """
-A decision tree mapping IPCC soil categories to corresponding check functions.
-
-Key: IpccLandUseCategory
-Value: Corresponding function for checking the match of the given land use category based on land cover nodes
-and additional kwargs.
+A decision tree determining the order to check IPCC land use categories.
 """
 
 

hestia_earth/models/ipcc2019/organicCarbonPerHa_utils.py

@@ -8,6 +8,7 @@ from hestia_earth.utils.stats import calc_z_critical
 from hestia_earth.utils.stats import (
     repeat_single, truncated_normal_1d
 )
+from hestia_earth.models.log import log_as_table
 from hestia_earth.models.utils.blank_node import cumulative_nodes_term_match, node_term_match
 from hestia_earth.models.utils.term import get_cover_crop_property_terms, get_irrigated_terms
 
@@ -178,6 +179,16 @@ lignin_content : float
 """
 
 
+SoilData = NamedTuple(
+    "SoilData",
+    [
+        ("term_id", str),
+        ("value", float),
+        ("category", IpccSoilCategory)
+    ]
+)
+
+
 def check_consecutive(ints: list[int]) -> bool:
     """
     Checks whether a list of integers are consecutive.
@@ -286,3 +297,13 @@ def format_number_list(values: Optional[list[float]]) -> str:
         " ".join(format_number(value) for value in values) or "None"if isinstance(values, list)
         else "None"
     )
+
+
+def format_soil_inventory(inventory: list[SoilData]) -> str:
+    return log_as_table(
+        {
+            "term-id": data.term_id,
+            "value": format_number(data.value),
+            "category": format_enum(data.category)
+        } for data in inventory
+    ) if inventory else "None"