hestia-earth-models 0.61.7__py3-none-any.whl → 0.62.0__py3-none-any.whl

hestia_earth/models/ipcc2019/organicCarbonPerHa_utils.py

@@ -0,0 +1,324 @@
+from enum import Enum
+from functools import lru_cache
+from numpy.typing import NDArray
+from typing import NamedTuple, Optional
+
+from hestia_earth.schema import MeasurementStatsDefinition, SiteSiteType
+
+from hestia_earth.models.utils.array_builders import (
+    repeat_single, plus_minus_uncertainty_to_normal_1d, truncated_normal_1d
+)
+from hestia_earth.models.utils.blank_node import cumulative_nodes_term_match
+from hestia_earth.models.utils.term import (
+    get_cover_crop_property_terms, get_crop_residue_incorporated_or_left_on_field_terms, get_irrigated_terms,
+    get_residue_removed_or_burnt_terms, get_upland_rice_crop_terms, get_upland_rice_land_cover_terms
+)
+
+STATS_DEFINITION = MeasurementStatsDefinition.SIMULATED.value
+DEPTH_UPPER = 0
+DEPTH_LOWER = 30
+
+MIN_AREA_THRESHOLD = 30  # 30% as per IPCC guidelines
+SUPER_MAJORITY_AREA_THRESHOLD = 100 - MIN_AREA_THRESHOLD
+MIN_YIELD_THRESHOLD = 1
+
+
+def get_cover_crop_property_terms_with_cache():
+    return lru_cache()(get_cover_crop_property_terms)()
+
+
+def get_crop_residue_inc_or_left_terms_with_cache():
+    return lru_cache()(get_crop_residue_incorporated_or_left_on_field_terms)()
+
+
+def get_irrigated_terms_with_cache():
+    return lru_cache()(get_irrigated_terms)()
+
+
+def get_residue_removed_or_burnt_terms_with_cache():
+    return lru_cache()(get_residue_removed_or_burnt_terms)()
+
+
+def get_upland_rice_crop_terms_with_cache():
+    return lru_cache()(get_upland_rice_crop_terms)()
+
+
+def get_upland_rice_land_cover_terms_with_cache():
+    return lru_cache()(get_upland_rice_land_cover_terms)()
+
+
+class EcoClimateZone(Enum):
+    """
+    Enum representing eco-climate zones. The value of each member of the Enum correctly corresponds with the values of
+    `ecoClimateZone` term and the `ecoClimateZone-lookup.csv`.
+    """
+    WARM_TEMPERATE_MOIST = 1
+    WARM_TEMPERATE_DRY = 2
+    COOL_TEMPERATE_MOIST = 3
+    COOL_TEMPERATE_DRY = 4
+    POLAR_MOIST = 5
+    POLAR_DRY = 6
+    BOREAL_MOIST = 7
+    BOREAL_DRY = 8
+    TROPICAL_MONTANE = 9
+    TROPICAL_WET = 10
+    TROPICAL_MOIST = 11
+    TROPICAL_DRY = 12
+
+
+class IpccSoilCategory(Enum):
+    """
+    Enum representing IPCC Soil Categories.
+
+    See [IPCC (2019) Vol 4, Ch. 2 and 3](https://www.ipcc-nggip.iges.or.jp/public/2019rf/vol4.html) for more
+    information.
+    """
+    ORGANIC_SOILS = "organic soils"
+    SANDY_SOILS = "sandy soils"
+    WETLAND_SOILS = "wetland soils"
+    VOLCANIC_SOILS = "volcanic soils"
+    SPODIC_SOILS = "spodic soils"
+    HIGH_ACTIVITY_CLAY_SOILS = "high-activity clay soils"
+    LOW_ACTIVITY_CLAY_SOILS = "low-activity clay soils"
+
+
+IPCC_SOIL_CATEGORY_TO_SOIL_TYPE_LOOKUP_VALUE = {
+    IpccSoilCategory.ORGANIC_SOILS: "Organic soils",
+    IpccSoilCategory.SANDY_SOILS: "Sandy soils",
+    IpccSoilCategory.WETLAND_SOILS: "Wetland soils",
+    IpccSoilCategory.VOLCANIC_SOILS: "Volcanic soils",
+    IpccSoilCategory.SPODIC_SOILS: "Spodic soils",
+    IpccSoilCategory.HIGH_ACTIVITY_CLAY_SOILS: "High-activity clay soils",
+    IpccSoilCategory.LOW_ACTIVITY_CLAY_SOILS: "Low-activity clay soils",
+}
+"""
+A dictionary mapping IPCC soil categories to corresponding soil type and USDA soil type lookup values in the
+`"IPCC_SOIL_CATEGORY"` column.
+"""
+
+
+class IpccLandUseCategory(Enum):
+    """
+    Enum representing IPCC Land Use Categories.
+
+    See [IPCC (2019) Vol 4](https://www.ipcc-nggip.iges.or.jp/public/2019rf/vol4.html) for more information.
+    """
+    GRASSLAND = "grassland"
+    PERENNIAL_CROPS = "perennial crops"
+    PADDY_RICE_CULTIVATION = "paddy rice cultivation"
+    ANNUAL_CROPS_WET = "annual crops (wet)"
+    ANNUAL_CROPS = "annual crops"
+    SET_ASIDE = "set aside"
+    FOREST = "forest"
+    NATIVE = "native"
+    OTHER = "other"
+
+
+SITE_TYPE_TO_IPCC_LAND_USE_CATEGORY = {
+    SiteSiteType.PERMANENT_PASTURE.value: IpccLandUseCategory.GRASSLAND,
+    SiteSiteType.FOREST.value: IpccLandUseCategory.FOREST,
+    SiteSiteType.OTHER_NATURAL_VEGETATION.value: IpccLandUseCategory.NATIVE
+}
+"""
+A dictionary mapping site types to corresponding IPCC land use categories.
+"""
+
+IPCC_LAND_USE_CATEGORY_TO_LAND_COVER_LOOKUP_VALUE = {
+    IpccLandUseCategory.GRASSLAND: "Grassland",
+    IpccLandUseCategory.PERENNIAL_CROPS: "Perennial crops",
+    IpccLandUseCategory.PADDY_RICE_CULTIVATION: "Paddy rice cultivation",
+    IpccLandUseCategory.ANNUAL_CROPS_WET: "Annual crops",
+    IpccLandUseCategory.ANNUAL_CROPS: "Annual crops",
+    IpccLandUseCategory.SET_ASIDE: [
+        "Annual crops", "Paddy rice cultivation", "Perennial crops", "Set aside"
+    ],
+    IpccLandUseCategory.FOREST: "Forest",
+    IpccLandUseCategory.NATIVE: "Native"
+}
+"""
+A dictionary mapping IPCC land use categories to corresponding land cover lookup values in the
+`"IPCC_LAND_USE_CATEGORY"` column.
+"""
+
+
+class IpccManagementCategory(Enum):
+    """
+    Enum representing IPCC Management Categories for grasslands and annual croplands.
+
+    See [IPCC (2019) Vol. 4, Ch. 5 and 6](https://www.ipcc-nggip.iges.or.jp/public/2019rf/vol4.html) for more
+    information.
+    """
+    SEVERELY_DEGRADED = "severely degraded"
+    IMPROVED_GRASSLAND = "improved grassland"
+    HIGH_INTENSITY_GRAZING = "high-intensity grazing"
+    NOMINALLY_MANAGED = "nominally managed"
+    FULL_TILLAGE = "full tillage"
+    REDUCED_TILLAGE = "reduced tillage"
+    NO_TILLAGE = "no tillage"
+    OTHER = "other"
+
+
+IPCC_MANAGEMENT_CATEGORY_TO_GRASSLAND_MANAGEMENT_TERM_ID = {
+    IpccManagementCategory.SEVERELY_DEGRADED: "severelyDegradedPasture",
+    IpccManagementCategory.IMPROVED_GRASSLAND: "improvedPasture",
+    IpccManagementCategory.HIGH_INTENSITY_GRAZING: "highIntensityGrazingPasture",
+    IpccManagementCategory.NOMINALLY_MANAGED: "nominallyManagedPasture",
+    IpccManagementCategory.OTHER: "nativePasture"
+}
+"""
+A dictionary mapping IPCC management categories to corresponding grassland management term IDs from the land cover
+glossary.
+"""
+
+
+IPCC_MANAGEMENT_CATEGORY_TO_TILLAGE_MANAGEMENT_LOOKUP_VALUE = {
+    IpccManagementCategory.FULL_TILLAGE: "Full tillage",
+    IpccManagementCategory.REDUCED_TILLAGE: "Reduced tillage",
+    IpccManagementCategory.NO_TILLAGE: "No tillage"
+}
+"""
+A dictionary mapping IPCC management categories to corresponding tillage lookup values in the
+`"IPCC_TILLAGE_MANAGEMENT_CATEGORY" column`.
+"""
+
+
+class IpccCarbonInputCategory(Enum):
+    """
+    Enum representing IPCC Carbon Input Categories for improved grasslands and annual croplands.
+
+    See [IPCC (2019) Vol. 4, Ch. 4, 5 and 6](https://www.ipcc-nggip.iges.or.jp/public/2019rf/vol4.html) for more
+    information.
+    """
+    GRASSLAND_HIGH = "grassland high"
+    GRASSLAND_MEDIUM = "grassland medium"
+    CROPLAND_HIGH_WITH_MANURE = "cropland high (with manure)"
+    CROPLAND_HIGH_WITHOUT_MANURE = "cropland high (without manure)"
+    CROPLAND_MEDIUM = "cropland medium"
+    CROPLAND_LOW = "cropland low"
+    OTHER = "other"
+
+
+CarbonSource = NamedTuple(
+    "CarbonSource",
+    [
+        ("mass", float),
+        ("carbon_content", float),
+        ("nitrogen_content", float),
+        ("lignin_content", float),
+    ]
+)
+"""
+A single carbon source (e.g. crop residues or organic amendment).
+
+Attributes
+-----------
+mass : float
+    The dry-matter mass of the carbon source, kg ha-1
+carbon_content : float
+    The carbon content of the carbon source, decimal proportion, kg C (kg d.m.)-1.
+nitrogen_content : float
+    The nitrogen content of the carbon source, decimal_proportion, kg N (kg d.m.)-1.
+lignin_content : float
+    The lignin content of the carbon source, decimal_proportion, kg lignin (kg d.m.)-1.
+"""
+
+
+def check_consecutive(ints: list[int]) -> bool:
+    """
+    Checks whether a list of integers are consecutive.
+
+    Used to determine whether annualised data is complete from every year from beggining to end.
+
+    Parameters
+    ----------
+    ints : list[int]
+        A list of integer values.
+
+    Returns
+    -------
+    bool
+        Whether or not the list of integers is consecutive.
+    """
+    range_list = list(range(min(ints), max(ints)+1)) if ints else []
+    return all(a == b for a, b in zip(ints, range_list))
+
+
+def check_irrigation(water_regime_nodes: list[dict]) -> bool:
+    """
+    Check if irrigation is present in the water regime nodes.
+
+    Parameters
+    ----------
+    water_regime_nodes : list[dict]
+        List of water regime nodes to be checked.
+
+    Returns
+    -------
+    bool
+        `True` if irrigation is present, `False` otherwise.
+    """
+    return cumulative_nodes_term_match(
+        water_regime_nodes,
+        target_term_ids=get_irrigated_terms_with_cache(),
+        cumulative_threshold=MIN_AREA_THRESHOLD
+    )
+
+
+def sample_truncated_normal(
+    *, iterations: int, value: float, sd: float, min: float, max: float, seed: Optional[int] = None, **_
+) -> NDArray:
+    """Randomly sample a model parameter with a truncated normal distribution."""
+    return truncated_normal_1d(shape=(1, iterations), mu=value, sigma=sd, low=min, high=max, seed=seed)
+
+
+def sample_plus_minus_uncertainty(
+    *, iterations: int, value: float, uncertainty: float, seed: Optional[int] = None, **_
+) -> NDArray:
+    """Randomly sample a model parameter with a plus/minus uncertainty distribution."""
+    return plus_minus_uncertainty_to_normal_1d(shape=(1, iterations), value=value, uncertainty=uncertainty, seed=seed)
+
+
+def sample_plus_minus_error(
+    *, iterations: int, value: float, error: float, seed: Optional[int] = None, **_
+) -> NDArray:
+    """Randomly sample a model parameter with a truncated normal distribution described using plus/minus error."""
+    sd = value * (error / 200)
+    low = value - (value * (error / 100))
+    high = value + (value * (error / 100))
+    return truncated_normal_1d(shape=(1, iterations), mu=value, sigma=sd, low=low, high=high, seed=seed)
+
+
+def sample_constant(*, iterations: int, value: float, **_) -> NDArray:
+    """Sample a constant model parameter."""
+    return repeat_single(shape=(1, iterations), value=value)
+
+
+def format_bool(value: Optional[bool]) -> str:
+    """Format a bool for logging in a table."""
+    return str(bool(value))
+
+
+def format_number(value: Optional[float]) -> str:
+    """Format a float for logging in a table."""
+    return f"{value:.1f}" if isinstance(value, (float, int)) else "None"
+
+
+def format_enum(value: Optional[Enum]) -> str:
+    """Format an enum for logging in a table."""
+    return value.value if isinstance(value, Enum) else "None"
+
+
+def format_bool_list(values: Optional[list[bool]]) -> str:
+    """Format a list of bools for logging in a table."""
+    return (
+        " ".join(format_bool(value) for value in values) or "None" if isinstance(values, list)
+        else "None"
+    )
+
+
+def format_number_list(values: Optional[list[float]]) -> str:
+    """Format a list of floats for logging in a table."""
+    return (
+        " ".join(format_number(value) for value in values) or "None"if isinstance(values, list)
+        else "None"
+    )

hestia_earth/models/ipcc2019/pastureGrass.py

@@ -1,15 +1,18 @@
 """
-Full Grass Consumption
+Cycle Pasture Grass
 
 This model estimates the energetic requirements of ruminants and can be used to estimate the amount of grass they graze.
 Source:
 [IPCC 2019, Vol.4, Chapter 10](https://www.ipcc-nggip.iges.or.jp/public/2019rf/pdf/4_Volume4/19R_V4_Ch10_Livestock.pdf).
+
+This version of the model will run at the Cycle level, if at least one Cycle Input is given as feed
+(see https://www.hestia.earth/schema/Input#isAnimalFeed).
 """
 from hestia_earth.schema import TermTermType
 from hestia_earth.utils.model import filter_list_term_type
 from hestia_earth.utils.tools import list_sum
 
-from hestia_earth.models.log import logRequirements, logShouldRun
+from hestia_earth.models.log import logRequirements, logShouldRun, debugValues
 from hestia_earth.models.utils.input import _new_input
 from hestia_earth.models.utils.term import get_wool_terms
 from hestia_earth.models.utils.completeness import _is_term_type_complete, _is_term_type_incomplete
@@ -30,7 +33,7 @@ from .pastureGrass_utils import (
 REQUIREMENTS = {
     "Cycle": {
         "completeness.animalFeed": "True",
-        "completeness.animalPopulation": "False",
+        "completeness.animalPopulation": "True",
         "completeness.freshForage": "False",
         "site": {
             "@type": "Site",
@@ -45,6 +48,19 @@ REQUIREMENTS = {
                 "term.termType": "landCover"
             }
         }],
+        "inputs": [{
+            "@type": "Input",
+            "term.units": "kg",
+            "value": "> 0",
+            "isAnimalFeed": "True",
+            "optional": {
+                "properties": [{
+                    "@type": "Property",
+                    "value": "",
+                    "term.@id": ["neutralDetergentFibreContent", "energyContentHigherHeatingValue"]
+                }]
+            }
+        }],
         "animals": [{
             "@type": "Animal",
             "value": "> 0",
@@ -93,19 +109,6 @@ REQUIREMENTS = {
             }
         }],
         "optional": {
-            "inputs": [{
-                "@type": "Input",
-                "term.units": "kg",
-                "value": "> 0",
-                "isAnimalFeed": "True",
-                "optional": {
-                    "properties": [{
-                        "@type": "Property",
-                        "value": "",
-                        "term.@id": ["neutralDetergentFibreContent", "energyContentHigherHeatingValue"]
-                    }]
-                }
-            }],
             "products": [{
                 "@type": "Product",
                 "value": "",
@@ -169,6 +172,17 @@ def _calculate_GE(
     NEwork = _sum_values(values, 3)
     NEp = _sum_values(values, 4)
     NEg = _sum_values(values, 5)
+
+    debugValues(cycle, model=MODEL, term=MODEL_KEY, model_key=MODEL_KEY,
+                NEm=NEm,
+                NEa=NEa,
+                NEl=NEl,
+                NEwork=NEwork,
+                NEp=NEp,
+                NEg=NEg,
+                NEm_feed=NEm_feed,
+                NEg_feed=NEg_feed)
+
     return (NEm + NEa + NEl + NEwork + NEp - NEm_feed)/REM + (NEg + NEwool - NEg_feed)/REG
 
 
@@ -207,17 +221,20 @@ def _run_practice(cycle: dict, meanDE: float, meanECHHV: float, system: dict):
 def _should_run(cycle: dict, practices: dict):
     systems = filter_list_term_type(cycle.get('practices', []), TermTermType.SYSTEM)
     animalFeed_complete = _is_term_type_complete(cycle, 'animalFeed')
-    animalPopulation_incomplete = _is_term_type_incomplete(cycle, 'animalPopulation')
+    animalPopulation_complete = _is_term_type_complete(cycle, 'animalPopulation')
     freshForage_incomplete = _is_term_type_incomplete(cycle, 'freshForage')
     all_animals_have_value = all([a.get('value', 0) > 0 for a in cycle.get('animals', [])])
 
+    has_cycle_inputs_feed = any([i.get('isAnimalFeed', False) for i in cycle.get('inputs', [])])
+
     meanDE = calculate_meanDE(practices)
     meanECHHV = calculate_meanECHHV(practices)
 
     should_run = all([
         animalFeed_complete,
-        animalPopulation_incomplete,
+        animalPopulation_complete,
         freshForage_incomplete,
+        has_cycle_inputs_feed,
         all_animals_have_value,
         len(systems) > 0,
         len(practices) > 0,
@@ -228,8 +245,9 @@ def _should_run(cycle: dict, practices: dict):
     for term_id in [MODEL_KEY] + [practice_input_id(p) for p in practices]:
         logRequirements(cycle, model=MODEL, term=term_id, model_key=MODEL_KEY,
                         term_type_animalFeed_complete=animalFeed_complete,
-                        term_type_animalPopulation_incomplete=animalPopulation_incomplete,
+                        term_type_animalPopulation_complete=animalPopulation_complete,
                         term_type_freshForage_incomplete=freshForage_incomplete,
+                        has_cycle_inputs_feed=has_cycle_inputs_feed,
                         all_animals_have_value=all_animals_have_value,
                         meanDE=meanDE,
                         meanECHHV=meanECHHV)

hestia_earth/models/ipcc2019/pastureGrass_utils.py

@@ -3,7 +3,7 @@ from hestia_earth.utils.api import download_hestia
 from hestia_earth.utils.lookup import download_lookup, get_table_value, column_name, extract_grouped_data
 from hestia_earth.utils.tools import list_sum, safe_parse_float
 
-from hestia_earth.models.log import debugValues, logRequirements, logShouldRun
+from hestia_earth.models.log import debugValues
 from hestia_earth.models.utils.input import get_feed_inputs
 from hestia_earth.models.utils.term import get_lookup_value
 from hestia_earth.models.utils.property import get_node_property, get_node_property_value, node_property_lookup_value
@@ -98,7 +98,7 @@ _NEa_BY_GROUPING = {
 
 def _calculate_NEa(cycle: dict, animal: dict, system: dict, NEm: float) -> float:
     grouping = _get_grouping(animal)
-    return _NEa_BY_GROUPING.get(grouping, lambda *args: None)(cycle, animal, system, NEm)
+    return _NEa_BY_GROUPING.get(grouping, lambda *args: 0)(cycle, animal, system, NEm)
 
 
 def _calculate_NEl_cattleAndBuffalo(cycle: dict, animal: dict) -> float:
@@ -156,7 +156,7 @@ _NEl_BY_GROUPING = {
 
 def _calculate_NEl(cycle: dict, animal: dict) -> float:
     grouping = _get_grouping(animal)
-    return _NEl_BY_GROUPING.get(grouping, lambda *args: None)(cycle, animal)
+    return _NEl_BY_GROUPING.get(grouping, lambda *args: 0)(cycle, animal)
 
 
 def _calculate_NEwork(cycle: dict, animal: dict, NEm: float) -> float:
@@ -347,8 +347,6 @@ def calculate_NEfeed(node: dict) -> tuple:
 
 
 def get_animal_values(cycle: dict, animal: dict, system: dict):
-    term_id = animal.get('term', {}).get('@id')
-
     NEm = _calculate_NEm(cycle, animal)
     NEa = _calculate_NEa(cycle, animal, system, NEm)
     NEl = _calculate_NEl(cycle, animal)
@@ -356,14 +354,6 @@ def get_animal_values(cycle: dict, animal: dict, system: dict):
     NEp = _calculate_NEp(cycle, animal, NEm)
     NEg = _calculate_NEg(cycle, animal)
 
-    logRequirements(cycle, model=MODEL, term=term_id, model_key=MODEL_KEY,
-                    NEm=NEm,
-                    NEa=NEa,
-                    NEl=NEl,
-                    NEwork=NEwork,
-                    NEp=NEp,
-                    NEg=NEg)
-
     return (NEm, NEa, NEl, NEwork, NEp, NEg)
 
 
@@ -394,14 +384,7 @@ def should_run_practice(cycle: dict):
         term_id = practice.get('term', {}).get('@id')
         key_term_type = practice.get('key', {}).get('termType')
         value = practice.get('value', [])
-
-        logRequirements(cycle, model=MODEL, term=term_id,
-                        practice_value=list_sum(value),
-                        practice_key_term_type=key_term_type)
-
-        should_run = all([len(value) > 0, term_id == MODEL_KEY, key_term_type in KEY_TERM_TYPES])
-        logShouldRun(cycle, MODEL, term_id, should_run)
-        return should_run
+        return all([len(value) > 0, term_id == MODEL_KEY, key_term_type in KEY_TERM_TYPES])
 
     return should_run