hestia-earth-models 0.74.15__py3-none-any.whl → 0.74.17__py3-none-any.whl

hestia_earth/models/ipcc2019/co2ToAirCarbonStockChange_utils.py

@@ -18,7 +18,10 @@ from hestia_earth.utils.tools import flatten, non_empty_list, safe_parse_date
 from hestia_earth.utils.stats import correlated_normal_2d, gen_seed
 from hestia_earth.utils.descriptive_stats import calc_descriptive_stats
 
-from hestia_earth.models.log import format_bool, format_float, format_int, format_nd_array, log_as_table
+from hestia_earth.models.log import (
+    format_conditional_message, format_bool, format_float, format_int, format_nd_array, log_as_table, logRequirements,
+    logShouldRun
+)
 from hestia_earth.models.utils import pairwise
 from hestia_earth.models.utils.blank_node import (
     _gapfill_datestr, _get_datestr_format, cumulative_nodes_term_match, DatestrGapfillMode, DatestrFormat,
@@ -88,6 +91,11 @@ _SITE_TYPE_SYSTEMS_MAPPING = {
     ]
 }
 
+_MEASUREMENTS_REQUIRED_LOG_MESSAGE = {
+    "on_true": "True - carbon stock measurements are required for this model to run",
+    "on_false": "False - this model can run without carbon stock measurements in specific cases (see documentation)"
+}
+
 
 class _InventoryKey(Enum):
     """
@@ -103,6 +111,7 @@ class _InventoryKey(Enum):
     LAND_USE_CHANGE_EVENT = "luc-event"
     YEARS_SINCE_LUC_EVENT = "years-since-luc-event"
     YEARS_SINCE_INVENTORY_START = "years-since-inventory-start"
+    YEAR_IS_RELEVANT = "year-is-relevant"
 
 
 CarbonStock = NamedTuple("CarbonStock", [
@@ -338,15 +347,18 @@ def _add_carbon_stock_change_emissions(
 
 def create_should_run_function(
     carbon_stock_term_id: str,
+    land_use_change_emission_term_id: str,
+    management_change_emission_term_id: str,
     *,
     depth_upper: Optional[float] = None,
     depth_lower: Optional[float] = None,
-    measurements_mandatory: bool = True,
+    measurements_required: bool = True,
     measurement_method_ranking: list[MeasurementMethodClassification] = DEFAULT_MEASUREMENT_METHOD_RANKING,
     transition_period: float = _TRANSITION_PERIOD_DAYS,
     get_valid_management_nodes_func: Callable[[dict], list[dict]] = lambda *_: [],
     summarise_land_use_func: Callable[[list[dict]], Any] = lambda *_: None,
-    detect_land_use_change_func: Callable[[Any, Any], bool] = lambda *_: False
+    detect_land_use_change_func: Callable[[Any, Any], bool] = lambda *_: False,
+    exclude_from_logs: Optional[list[str]] = None
 ) -> Callable[[dict], tuple[bool, str, dict, dict]]:
     """
     Create a `should_run` function for a carbon stock change model.
@@ -362,6 +374,12 @@ def create_should_run_function(
         The `term.@id` of the carbon stock measurement (e.g., `aboveGroundBiomass`, `belowGroundBiomass`,
         `organicCarbonPerHa`).
 
+    land_use_change_emission_term_id : str
+        The term id for emissions allocated to land use changes.
+
+    management_change_emission_term_id : str
+        The term id for emissions allocated to management changes.
+
     depth_upper : float, optional
         The upper bound of the measurement depth (e.g., 0 cm). If provided, only measurements matching this bound are
         included.
@@ -370,7 +388,7 @@ def create_should_run_function(
         The lower bound of the measurement depth (e.g., 30 cm). If provided, only measurements matching this bound are
         included.
 
-    measurements_mandatory : bool, default=True
+    measurements_required : bool, default=True
         If `True`, at least two valid measurement must be present for the cycle to be included in the inventory. If
         `False`, the function may allow an inventory to be generated without direct measurements.
 
@@ -407,6 +425,10 @@ def create_should_run_function(
 
         Detects whether a land use change event has occurred between two summaries.
 
+    exclude_from_logs : list[str], optional
+
+        A list of log keys to exclude from the model logs.
+
     Returns
     -------
     should_run_func : Callable[[dict], tuple[bool, str, dict, dict]]
@@ -471,7 +493,7 @@ def create_should_run_function(
             has_soil
             and has_cycles
             and has_functional_unit_1_ha
-            and (has_stock_measurements or not measurements_mandatory)
+            and (has_stock_measurements or not measurements_required)
         )
 
         compile_inventory_func = _create_compile_inventory_function(
@@ -485,13 +507,21 @@ def create_should_run_function(
 
         inventory, inventory_logs = (
             compile_inventory_func(
+                cycle_id,
                 cycles,
                 carbon_stock_measurements,
                 land_cover_nodes
             ) if should_compile_inventory else ({}, {})
         )
 
-        has_valid_inventory = len(inventory) > 0
+        assigned_emissions = _assign_emissions(
+            cycle_id,
+            inventory,
+            land_use_change_emission_term_id,
+            management_change_emission_term_id
+        )
+
+        has_valid_inventory = bool(assigned_emissions) > 0
         has_consecutive_years = check_consecutive(inventory.keys())
 
         should_run_ = all([has_valid_inventory, has_consecutive_years])
@@ -506,10 +536,28 @@ def create_should_run_function(
             "has_valid_inventory": has_valid_inventory,
             "has_consecutive_years": has_consecutive_years,
             "has_stock_measurements": has_stock_measurements,
-            "measurements_mandatory": measurements_mandatory
+            "measurements_required": format_conditional_message(
+                measurements_required,
+                **_MEASUREMENTS_REQUIRED_LOG_MESSAGE
+            )
         }
 
-        return should_run_, cycle_id, inventory, logs
+        final_logs = _filter_logs(logs, exclude_from_logs) if isinstance(exclude_from_logs, list) else logs
+
+        for term_id in [land_use_change_emission_term_id, management_change_emission_term_id]:
+
+            assigned_emission = assigned_emissions.get(term_id)
+            tier = (
+                _get_emission_method(assigned_emission).value if assigned_emission
+                else _DEFAULT_EMISSION_METHOD_TIER.value
+            )
+
+            should_run_term = should_run_ and bool(assigned_emission)
+
+            logRequirements(cycle, model=MODEL, term=term_id, **final_logs)
+            logShouldRun(cycle, MODEL, term_id, should_run_term, methodTier=tier)
+
+        return should_run_, assigned_emissions
 
     return should_run
 
@@ -589,6 +637,7 @@ def _create_compile_inventory_function(
         A function that compiles an annual inventory given cycles, carbon stock measurements, and land cover nodes.
     """
     def compile_inventory(
+        cycle_id: str,
         cycles: list[dict],
         carbon_stock_measurements: list[dict],
         land_cover_nodes: list[dict]
@@ -612,6 +661,9 @@ def _create_compile_inventory_function(
 
         Parameters
         ----------
+        cycle_id : str
+            The `@id` of the cycle the model is running on.
+
         cycles : list[dict]
             A list of [Cycle](https://www.hestia.earth/schema/Cycles) nodes related to the site.
 
@@ -645,7 +697,7 @@ def _create_compile_inventory_function(
         logs : dict
             Diagnostic logs describing intermediate steps and validation decisions.
         """
-        cycle_inventory = _compile_cycle_inventory(cycles)
+        cycle_inventory = _compile_cycle_inventory(cycle_id, cycles)
         carbon_stock_inventory = _compile_carbon_stock_inventory(
             carbon_stock_measurements, transition_period=transition_period, iterations=iterations, seed=seed
         )
@@ -667,7 +719,7 @@ def _create_compile_inventory_function(
     return compile_inventory
 
 
-def _compile_cycle_inventory(cycles: list[dict]) -> dict:
+def _compile_cycle_inventory(cycle_id: str, cycles: list[dict]) -> dict:
     """
     Compile the share of emissions for each cycle, grouped by inventory year.
 
@@ -690,6 +742,9 @@ def _compile_cycle_inventory(cycles: list[dict]) -> dict:
 
     Parameters
     ----------
+    cycle_id : str
+        The `@id` of the cycle the model is running on.
+
     cycles : list[dict]
         List of [Cycle](https://www.hestia.earth/schema/Cycle) nodes.
 
@@ -713,8 +768,10 @@ def _compile_cycle_inventory(cycles: list[dict]) -> dict:
         }
 
     return {
-        year: {_InventoryKey.SHARE_OF_EMISSION: calculate_emissions(cycles_in_year)}
-        for year, cycles_in_year in grouped_cycles.items()
+        year: {
+            _InventoryKey.SHARE_OF_EMISSION: calculate_emissions(cycles_in_year),
+            _InventoryKey.YEAR_IS_RELEVANT: cycle_id in (cycle.get("@id") for cycle in cycles_in_year)
+        } for year, cycles_in_year in grouped_cycles.items()
     }
 
 
@@ -1373,11 +1430,12 @@ def _format_cycle_inventory(cycle_inventory: dict) -> str:
     Format the cycle inventory for logging as a table. Rows represent inventory years, columns represent the share of
     emission for each cycle present in the inventory. If the inventory is invalid, return `"None"` as a string.
     """
-    KEY = _InventoryKey.SHARE_OF_EMISSION
+    RELEVANT_KEY = _InventoryKey.YEAR_IS_RELEVANT
+    SHARE_KEY = _InventoryKey.SHARE_OF_EMISSION
 
     unique_cycles = sorted(
-        set(non_empty_list(flatten(list(group[KEY]) for group in cycle_inventory.values()))),
-        key=lambda id: next((year, id) for year in cycle_inventory if id in cycle_inventory[year][KEY])
+        set(non_empty_list(flatten(list(group[SHARE_KEY]) for group in cycle_inventory.values()))),
+        key=lambda id: next((year, id) for year in cycle_inventory if id in cycle_inventory[year][SHARE_KEY])
     )
 
     should_run = cycle_inventory and len(unique_cycles) > 0
@@ -1385,8 +1443,9 @@ def _format_cycle_inventory(cycle_inventory: dict) -> str:
     return log_as_table(
         {
             "year": year,
+            RELEVANT_KEY.value: format_bool(group.get(RELEVANT_KEY, False)),
             **{
-                id: format_float(group.get(KEY, {}).get(id, 0)) for id in unique_cycles
+                id: format_float(group.get(SHARE_KEY, {}).get(id, 0)) for id in unique_cycles
             }
         } for year, group in cycle_inventory.items()
     ) if should_run else "None"
@@ -1474,6 +1533,10 @@ def _format_named_tuple(value: Optional[Union[CarbonStock, CarbonStockChange, Ca
     )
 
 
+def _filter_logs(logs: dict[str, Any], exclude_keys: list[str]):
+    return {k: v for k, v in logs.items() if k not in exclude_keys}
+
+
 _LAND_USE_INVENTORY_KEY_TO_FORMAT_FUNC = {
     _InventoryKey.LAND_USE_CHANGE_EVENT: format_bool,
     _InventoryKey.YEARS_SINCE_LUC_EVENT: format_int,
@@ -1485,32 +1548,14 @@ the `dict` keys.
 """
 
 
-def create_run_function(
-    new_emission_func: Callable[[EmissionMethodTier, dict], dict],
+def _assign_emissions(
+    cycle_id: str,
+    inventory,
     land_use_change_emission_term_id: str,
     management_change_emission_term_id: str
-) -> Callable[[str, dict], list[dict]]:
-    """
-    Create a run function for an emissions from carbon stock change model.
-
-    A model-specific `new_emission_func` should be passed as a parameter to this higher-order function to control how
-    model ouputs are formatted into HESTIA emission nodes.
+):
 
-    Parameters
-    ----------
-    new_emission_func : Callable[[EmissionMethodTier, tuple], dict]
-        A function, with the signature `(method_tier: dict, **kwargs: dict) -> (emission_node: dict)`.
-    land_use_change_emission_term_id : str
-        The term id for emissions allocated to land use changes.
-    management_change_emission_term_id : str
-        The term id for emissions allocated to management changes.
-
-    Returns
-    -------
-    Callable[[str, dict], list[dict]]
-        The customised `run` function with the signature `(cycle_id: str, inventory: dict) -> emissions: list[dict]`.
-    """
-    def reduce_emissions(result: dict, year: int, cycle_id: str, inventory: dict):
+    def assign(result: dict, year: int, cycle_id: str, inventory: dict):
         """
         Assign emissions to either the land use or management change term ids and sum together.
         """
@@ -1560,7 +1605,36 @@ def create_run_function(
 
         return result | emission_dict | zero_emission_dict
 
-    def run(cycle_id: str, inventory: dict) -> list[dict]:
+    def should_run_year(year: int) -> bool:
+        return cycle_id in inventory.get(year, {}).get(_InventoryKey.SHARE_OF_EMISSION, {}).keys()
+
+    return reduce(
+        lambda result, year: assign(result, year, cycle_id, inventory),
+        (year for year in inventory.keys() if should_run_year(year)),
+        {}
+    )
+
+
+def create_run_function(
+    new_emission_func: Callable[[EmissionMethodTier, dict], dict]
+) -> Callable[[str, dict], list[dict]]:
+    """
+    Create a run function for an emissions from carbon stock change model.
+
+    A model-specific `new_emission_func` should be passed as a parameter to this higher-order function to control how
+    model ouputs are formatted into HESTIA emission nodes.
+
+    Parameters
+    ----------
+    new_emission_func : Callable[[EmissionMethodTier, tuple], dict]
+        A function, with the signature `(method_tier: dict, **kwargs: dict) -> (emission_node: dict)`.
+
+    Returns
+    -------
+    Callable[[str, dict], list[dict]]
+        The customised `run` function with the signature `(cycle_id: str, inventory: dict) -> emissions: list[dict]`.
+    """
+    def run(assigned_emissions: dict) -> list[dict]:
         """
         Calculate emissions for a specific cycle using from a carbon stock change using pre-compiled inventory data.
 
@@ -1579,27 +1653,17 @@ def create_run_function(
         list[dict]
             A list of [Emission](https://www.hestia.earth/schema/Emission) nodes containing model results.
         """
-
-        def should_run_year(year: int) -> bool:
-            return cycle_id in inventory.get(year, {}).get(_InventoryKey.SHARE_OF_EMISSION, {}).keys()
-
-        assigned_emissions = reduce(
-            lambda result, year: reduce_emissions(result, year, cycle_id, inventory),
-            (year for year in inventory.keys() if should_run_year(year)),
-            {}
-        )
-
         return [
             new_emission_func(
                 term_id=emission_term_id,
-                method_tier=_get_emission_method(total_emission),
+                method_tier=_get_emission_method(stock_change_emission),
                 **calc_descriptive_stats(
-                    total_emission.value,
+                    stock_change_emission.value,
                     EmissionStatsDefinition.SIMULATED,
                     decimals=6
                 )
-            ) for emission_term_id, total_emission in assigned_emissions.items()
-            if isinstance(total_emission, CarbonStockChangeEmission)
+            ) for emission_term_id, stock_change_emission in assigned_emissions.items()
+            if isinstance(stock_change_emission, CarbonStockChangeEmission)
         ]
 
     return run
@@ -1616,7 +1680,7 @@ def get_zero_emission(year):
 
 def _get_emission_method(emission: CarbonStockChangeEmission):
     method = emission.method
-    return method if isinstance(method, EmissionMethodTier) else EmissionMethodTier.TIER_1
+    return method if isinstance(method, EmissionMethodTier) else _DEFAULT_EMISSION_METHOD_TIER
 
 
 def is_soil_based_system(cycles, site_type):

hestia_earth/models/ipcc2019/co2ToAirSoilOrganicCarbonStockChange.py

@@ -1,6 +1,5 @@
 from hestia_earth.schema import EmissionMethodTier
 
-from hestia_earth.models.log import logRequirements, logShouldRun
 from hestia_earth.models.utils.emission import _new_emission
 
 from .organicCarbonPerHa_tier_1 import _assign_ipcc_land_use_category, get_valid_management_nodes
@@ -43,8 +42,10 @@ RETURNS = {
 }
 TERM_ID = 'co2ToAirSoilOrganicCarbonStockChangeLandUseChange,co2ToAirSoilOrganicCarbonStockChangeManagementChange'
 
-_LU_EMISSION_TERM_ID = "co2ToAirSoilOrganicCarbonStockChangeLandUseChange"
-_MG_EMISSION_TERM_ID = "co2ToAirSoilOrganicCarbonStockChangeManagementChange"
+_TERM_IDS = TERM_ID.split(",")
+
+_LU_EMISSION_TERM_ID = _TERM_IDS[0]
+_MG_EMISSION_TERM_ID = _TERM_IDS[1]
 
 _DEPTH_UPPER = 0
 _DEPTH_LOWER = 30
@@ -115,24 +116,18 @@ def run(cycle: dict) -> list[dict]:
     """
     should_run_exec = create_should_run_function(
         _CARBON_STOCK_TERM_ID,
+        _LU_EMISSION_TERM_ID,
+        _MG_EMISSION_TERM_ID,
         depth_upper=_DEPTH_UPPER,
         depth_lower=_DEPTH_LOWER,
-        measurements_mandatory=False,  # Model can allocate zero emissions to LUC with enough landCover data
+        measurements_required=False,  # Model can allocate zero emissions to LUC with enough landCover data
         get_valid_management_nodes_func=get_valid_management_nodes,
         summarise_land_use_func=lambda nodes: _assign_ipcc_land_use_category(nodes, None),
         detect_land_use_change_func=lambda a, b: a != b
     )
 
-    run_exec = create_run_function(
-        new_emission_func=_emission,
-        land_use_change_emission_term_id=_LU_EMISSION_TERM_ID,
-        management_change_emission_term_id=_MG_EMISSION_TERM_ID
-    )
-
-    should_run, cycle_id, inventory, logs = should_run_exec(cycle)
+    run_exec = create_run_function(new_emission_func=_emission)
 
-    for term_id in [_LU_EMISSION_TERM_ID, _MG_EMISSION_TERM_ID]:
-        logRequirements(cycle, model=MODEL, term=term_id, **logs)
-        logShouldRun(cycle, MODEL, term_id, should_run)
+    should_run, assigned_emissions = should_run_exec(cycle)
 
-    return run_exec(cycle_id, inventory) if should_run else []
+    return run_exec(assigned_emissions) if should_run else []