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

hestia_earth/models/ipcc2019/co2ToAirBelowGroundBiomassStockChangeLandUseChange.py

@@ -0,0 +1,204 @@
+from hestia_earth.schema import CycleFunctionalUnit, EmissionMethodTier, SiteSiteType
+
+from hestia_earth.models.log import logRequirements, logShouldRun
+from hestia_earth.models.utils.blank_node import cumulative_nodes_term_match
+from hestia_earth.models.utils.emission import _new_emission
+
+from .co2ToAirCarbonStockChange_utils import create_run_function, create_should_run_function
+from . import MODEL
+
+REQUIREMENTS = {
+    "Cycle": {
+        "site": {
+            "measurements": [
+                {
+                    "@type": "Measurement",
+                    "value": "",
+                    "dates": "",
+                    "depthUpper": "0",
+                    "depthLower": "30",
+                    "term.@id": " belowGroundBiomass"
+                }
+            ]
+        },
+        "functionalUnit": "1 ha",
+        "endDate": "",
+        "optional": {
+            "startDate": ""
+        }
+    }
+}
+RETURNS = {
+    "Emission": [{
+        "value": "",
+        "sd": "",
+        "min": "",
+        "max": "",
+        "statsDefinition": "simulated",
+        "observations": "",
+        "methodTier": "",
+        "depth": "30"
+    }]
+}
+TERM_ID = 'co2ToAirBelowGroundBiomassStockChangeLandUseChange'
+
+_DEPTH_UPPER = 0
+_DEPTH_LOWER = 30
+
+_CARBON_STOCK_TERM_ID = 'belowGroundBiomass'
+
+_SITE_TYPE_SYSTEMS_MAPPING = {
+    SiteSiteType.GLASS_OR_HIGH_ACCESSIBLE_COVER.value: [
+        "protectedCroppingSystemSoilBased",
+        "protectedCroppingSystemSoilAndSubstrateBased"
+    ]
+}
+
+
+def _emission(
+    *,
+    value: list[float],
+    method_tier: EmissionMethodTier,
+    sd: list[float] = None,
+    min: list[float] = None,
+    max: list[float] = None,
+    statsDefinition: str = None,
+    observations: list[int] = None
+) -> dict:
+    """
+    Create an emission node based on the provided value and method tier.
+
+    See [Emission schema](https://www.hestia.earth/schema/Emission) for more information.
+
+    Parameters
+    ----------
+    value : float
+        The emission value (kg CO2 ha-1).
+    sd : float
+        The standard deviation (kg CO2 ha-1).
+    method_tier : EmissionMethodTier
+        The emission method tier.
+
+    Returns
+    -------
+    dict
+        The emission dictionary with keys 'depth', 'value', and 'methodTier'.
+    """
+    update_dict = {
+        "value": value,
+        "sd": sd,
+        "min": min,
+        "max": max,
+        "statsDefinition": statsDefinition,
+        "observations": observations,
+        "methodTier": method_tier.value,
+        "depth": _DEPTH_LOWER
+    }
+    emission = _new_emission(TERM_ID, MODEL) | {
+        key: value for key, value in update_dict.items() if value
+    }
+    return emission
+
+
+def run(cycle: dict) -> list[dict]:
+    """
+    Run the `ipcc2019.co2ToAirBelowGroundBiomassStockChangeManagementChange`.
+
+    Parameters
+    ----------
+    cycle : dict
+        A HESTIA (Cycle node)[https://www.hestia.earth/schema/Cycle].
+
+    Returns
+    -------
+    list[dict]
+        A list of [Emission nodes](https://www.hestia.earth/schema/Emission) containing model results.
+    """
+    should_run_exec = create_should_run_function(
+        _CARBON_STOCK_TERM_ID,
+        _should_compile_inventory_func,
+        should_run_measurement_func=_should_run_measurement_func
+    )
+
+    run_exec = create_run_function(_emission)
+
+    should_run, cycle_id, inventory, logs = should_run_exec(cycle)
+
+    logRequirements(cycle, model=MODEL, term=TERM_ID, **logs)
+    logShouldRun(cycle, MODEL, TERM_ID, should_run)
+
+    return run_exec(cycle_id, inventory) if should_run else []
+
+
+def _should_run_measurement_func(node: dict) -> bool:
+    """
+    Validate a [Measurement](https://www.hestia.earth/schema/Measurement) to determine whether it is a valid
+    `organicCarbonPerHa` node.
+
+    Parameters
+    ----------
+    node : dict
+        The node to be validated.
+
+    Returns
+    -------
+    bool
+        `True` if the node passes all validation criteria, `False` otherwise.
+    """
+    return all([
+        node.get("depthLower") == _DEPTH_LOWER,
+        node.get("depthUpper") == _DEPTH_UPPER
+    ])
+
+
+def _should_compile_inventory_func(
+    site: dict, cycles: list[dict], carbon_stock_measurements: list[dict]
+) -> tuple[bool, dict]:
+    """
+    Determine whether a site is suitable and has enough data to compile a carbon stock inventory.
+
+    Parameters
+    ----------
+    site : dict
+        A HESTIA (Site node)[https://www.hestia.earth/schema/Site]
+    cycles : list[dict]
+        A list of HESTIA (Cycle nodes)[https://www.hestia.earth/schema/Cycle] that are related to the site.
+    carbon_stock_measurements : list[dict]
+        A list of HESTIA carbon stock (Measurement nodes)[https://www.hestia.earth/schema/Measurement] that are related
+        to the site.
+
+    Returns
+    -------
+    tuple[bool, dict]
+        `(should_run, logs)`.
+    """
+    site_type = site.get("siteType")
+    has_soil = site_type not in _SITE_TYPE_SYSTEMS_MAPPING or all(
+        cumulative_nodes_term_match(
+            cycle.get("practices", []),
+            target_term_ids=_SITE_TYPE_SYSTEMS_MAPPING[site_type],
+            cumulative_threshold=0
+        ) for cycle in cycles
+    )
+
+    has_stock_measurements = len(carbon_stock_measurements) > 0
+    has_cycles = len(cycles) > 0
+    has_functional_unit_1_ha = all(cycle.get('functionalUnit') == CycleFunctionalUnit._1_HA.value for cycle in cycles)
+
+    should_run = all([
+        has_soil,
+        has_stock_measurements,
+        has_cycles,
+        has_functional_unit_1_ha
+    ])
+
+    logs = {
+        "site_type": site_type,
+        "has_soil": has_soil,
+        "carbon_stock_term": _CARBON_STOCK_TERM_ID,
+        "has_stock_measurements": has_stock_measurements,
+        "has_cycles": has_cycles,
+        "has_functional_unit_1_ha": has_functional_unit_1_ha,
+    }
+
+    return should_run, logs

hestia_earth/models/ipcc2019/co2ToAirCarbonStockChange_utils.py

@@ -10,28 +10,36 @@ from itertools import product
 from numpy import array, random, mean
 from numpy.typing import NDArray
 from pydash.objects import merge
-from typing import NamedTuple, Optional, Union
+from typing import Callable, NamedTuple, Optional, Union
 
-from hestia_earth.schema import EmissionMethodTier, MeasurementMethodClassification
+from hestia_earth.schema import (
+    EmissionMethodTier, EmissionStatsDefinition, MeasurementMethodClassification
+)
 from hestia_earth.utils.date import diff_in_days, YEAR
 from hestia_earth.utils.tools import flatten, non_empty_list, safe_parse_date
 
 from hestia_earth.models.log import log_as_table
 from hestia_earth.models.utils import pairwise
-from hestia_earth.models.utils.array_builders import correlated_normal_2d
+from hestia_earth.models.utils.array_builders import correlated_normal_2d, gen_seed
 from hestia_earth.models.utils.blank_node import (
-    _gapfill_datestr, DatestrGapfillMode, group_nodes_by_year, split_node_by_dates
+    _gapfill_datestr, _get_datestr_format, DatestrGapfillMode, DatestrFormat, group_nodes_by_year, node_term_match,
+    split_node_by_dates
 )
 from hestia_earth.models.utils.constant import Units, get_atomic_conversion
+from hestia_earth.models.utils.descriptive_stats import calc_descriptive_stats
 from hestia_earth.models.utils.emission import min_emission_method_tier
 from hestia_earth.models.utils.measurement import (
     group_measurements_by_method_classification, min_measurement_method_classification,
     to_measurement_method_classification
 )
+from hestia_earth.models.utils.site import related_cycles
 from hestia_earth.models.utils.time_series import (
     calc_tau, compute_time_series_correlation_matrix, exponential_decay
 )
 
+from .utils import check_consecutive
+
+_ITERATIONS = 10000
 _MAX_CORRELATION = 1
 _MIN_CORRELATION = 0.5
 _NOMINAL_ERROR = 75
@@ -40,7 +48,14 @@ carbon stock measurements without an associated `sd` should be assigned a nomina
 the mean).
 """
 _TRANSITION_PERIOD = 20 * YEAR  # 20 years in days
-_VALID_MEASUREMENT_METHOD_CLASSIFICATIONS = [
+_VALID_DATE_FORMATS = {
+    DatestrFormat.YEAR,
+    DatestrFormat.YEAR_MONTH,
+    DatestrFormat.YEAR_MONTH_DAY,
+    DatestrFormat.YEAR_MONTH_DAY_HOUR_MINUTE_SECOND
+}
+
+DEFAULT_MEASUREMENT_METHOD_RANKING = [
     MeasurementMethodClassification.ON_SITE_PHYSICAL_MEASUREMENT,
     MeasurementMethodClassification.MODELLED_USING_OTHER_MEASUREMENTS,
     MeasurementMethodClassification.TIER_3_MODEL,
@@ -52,6 +67,19 @@ The list of `MeasurementMethodClassification`s that can be used to calculate car
 order from strongest to weakest.
 """
 
+_DEFAULT_EMISSION_METHOD_TIER = EmissionMethodTier.TIER_1
+_MEASUREMENT_METHOD_CLASSIFICATION_TO_EMISSION_METHOD_TIER = {
+    MeasurementMethodClassification.TIER_2_MODEL: EmissionMethodTier.TIER_2,
+    MeasurementMethodClassification.TIER_3_MODEL: EmissionMethodTier.TIER_3,
+    MeasurementMethodClassification.MODELLED_USING_OTHER_MEASUREMENTS: EmissionMethodTier.MEASURED,
+    MeasurementMethodClassification.ON_SITE_PHYSICAL_MEASUREMENT: EmissionMethodTier.MEASURED,
+}
+"""
+A mapping between `MeasurementMethodClassification`s and `EmissionMethodTier`s. As carbon stock measurements can be
+measured/estimated through a variety of methods, the emission model needs be able to assign an emission tier for each.
+Any `MeasurementMethodClassification` not in the mapping should be assigned `DEFAULT_EMISSION_METHOD_TIER`.
+"""
+
 
 class _InventoryKey(Enum):
     """
@@ -132,7 +160,7 @@ method: MeasurementMethodClassification
 """
 
 
-def lerp_carbon_stocks(start: CarbonStock, end: CarbonStock, target_date: str) -> CarbonStock:
+def _lerp_carbon_stocks(start: CarbonStock, end: CarbonStock, target_date: str) -> CarbonStock:
     """
     Estimate, using linear interpolation, a carbon stock for a specific date based on the carbon stocks of two other
     dates.
@@ -158,7 +186,7 @@ def lerp_carbon_stocks(start: CarbonStock, end: CarbonStock, target_date: str) -
     return CarbonStock(value, target_date, method)
 
 
-def calc_carbon_stock_change(start: CarbonStock, end: CarbonStock) -> CarbonStockChange:
+def _calc_carbon_stock_change(start: CarbonStock, end: CarbonStock) -> CarbonStockChange:
     """
     Calculate the change in a carbon stock between two different dates.
 
@@ -181,7 +209,7 @@ def calc_carbon_stock_change(start: CarbonStock, end: CarbonStock) -> CarbonStoc
     return CarbonStockChange(value, start.date, end.date, method)
 
 
-def calc_carbon_stock_change_emission(carbon_stock_change: CarbonStockChange) -> CarbonStockChangeEmission:
+def _calc_carbon_stock_change_emission(carbon_stock_change: CarbonStockChange) -> CarbonStockChangeEmission:
     """
     Convert a `CarbonStockChange` into a `CarbonStockChangeEmission`.
 
@@ -222,20 +250,6 @@ def _convert_mmc_to_emt(
     )
 
 
-_DEFAULT_EMISSION_METHOD_TIER = EmissionMethodTier.TIER_1
-_MEASUREMENT_METHOD_CLASSIFICATION_TO_EMISSION_METHOD_TIER = {
-    MeasurementMethodClassification.TIER_2_MODEL: EmissionMethodTier.TIER_2,
-    MeasurementMethodClassification.TIER_3_MODEL: EmissionMethodTier.TIER_3,
-    MeasurementMethodClassification.MODELLED_USING_OTHER_MEASUREMENTS: EmissionMethodTier.MEASURED,
-    MeasurementMethodClassification.ON_SITE_PHYSICAL_MEASUREMENT: EmissionMethodTier.MEASURED,
-}
-"""
-A mapping between `MeasurementMethodClassification`s and `EmissionMethodTier`s. As carbon stock measurements can be
-measured/estimated through a variety of methods, the emission model needs be able to assign an emission tier for each.
-Any `MeasurementMethodClassification` not in the mapping should be assigned `DEFAULT_EMISSION_METHOD_TIER`.
-"""
-
-
 def _convert_c_to_co2(kg_c: float) -> float:
     """
     Convert mass of carbon (C) to carbon dioxide (CO2) using the atomic conversion ratio.
@@ -255,7 +269,7 @@ def _convert_c_to_co2(kg_c: float) -> float:
     return kg_c * get_atomic_conversion(Units.KG_CO2, Units.TO_C)
 
 
-def rescale_carbon_stock_change_emission(
+def _rescale_carbon_stock_change_emission(
     emission: CarbonStockChangeEmission, factor: float
 ) -> CarbonStockChangeEmission:
     """
@@ -278,7 +292,7 @@ def rescale_carbon_stock_change_emission(
     return CarbonStockChangeEmission(value, emission.start_date, emission.end_date, emission.method)
 
 
-def add_carbon_stock_change_emissions(
+def _add_carbon_stock_change_emissions(
     emission_1: CarbonStockChangeEmission, emission_2: CarbonStockChangeEmission
 ) -> CarbonStockChangeEmission:
     """
@@ -304,12 +318,157 @@ def add_carbon_stock_change_emissions(
     return CarbonStockChangeEmission(value, start_date, end_date, method)
 
 
-def compile_inventory(
+def create_should_run_function(
+    carbon_stock_term_id: str,
+    should_compile_inventory_func: Callable[[dict, list[dict], list[dict]], tuple[bool, dict]],
+    should_run_measurement_func: Callable[[dict], bool] = lambda _: True,
+    measurement_method_ranking: list[MeasurementMethodClassification] = DEFAULT_MEASUREMENT_METHOD_RANKING
+) -> Callable[[dict], tuple[bool, str, dict, dict]]:
+    """
+    Create a should run function for an emissions from carbon stock change model.
+
+    Model-specific validation functions should be passed as parameters to this higher order function to determine which
+    carbon stock measurements are included in the inventory and whether there is enough data to compile an annual
+    inventory of carbon stock change data.
+
+    Parameters
+    ----------
+    carbon_stock_term_id : str
+        The `term.@id` of the carbon stock measurement (e.g., `aboveGroundBiomass`, `belowGroundBiomass`,
+        `organicCarbonPerHa`, etc.).
+
+    should_compile_inventory_func : Callable[[dict, list[dict], list[dict]], tuple[bool, dict]]
+        A function, with the signature
+        `(site: dict, cycles: list[dict], carbon_stock_measurements: list[dict]) -> (should_run: bool, logs: dict)`, to
+        determine whether there is enough site and cycles data available to compile the carbon stock change inventory.
+
+    should_run_measurement_func : Callable[[dict], bool], optional.
+        An optional measurement validation function, with the signature `(measurement: dict) -> bool`, that can be used
+        to add in additional criteria (`depthUpper`, `depthLower`, etc.) for the inclusion of a measurement in the
+        inventory.
+
+    measurement_method_ranking : list[MeasurementMethodClassification], optional
+        The order in which to prioritise `MeasurementMethodClassification`s when reducing the inventory down to a
+        single method per year. Defaults to:
+        ```
+        MeasurementMethodClassification.ON_SITE_PHYSICAL_MEASUREMENT,
+        MeasurementMethodClassification.MODELLED_USING_OTHER_MEASUREMENTS,
+        MeasurementMethodClassification.TIER_3_MODEL,
+        MeasurementMethodClassification.TIER_2_MODEL,
+        MeasurementMethodClassification.TIER_1_MODEL
+        ```
+        n.b., measurements with methods not included in the ranking will not be included in the inventory.
+
+    Returns
+    -------
+    Callable[[dict], tuple[bool, str, dict, dict]]
+        The customised `should_run` function with the signature
+        `(cycle: dict) -> (should_run_: bool, cycle_id: str, inventory: dict, logs: dict)`.
+    """
+
+    def should_run(cycle: dict) -> tuple[bool, str, dict, dict]:
+        """
+        Determine if calculations should run for a given [Cycle](https://www.hestia.earth/schema/Cycle) based on
+        available carbon stock data. If data availability is sufficient, return an inventory of pre-processed input
+        data for the model and log data.
+
+        Parameters
+        ----------
+        cycle : dict
+            The cycle dictionary for which the calculations will be evaluated.
+
+        Returns
+        -------
+        tuple[bool, str, dict, dict]
+            `(should_run, cycle_id, inventory, logs)`
+        """
+        cycle_id = cycle.get("@id")
+        site = _get_site(cycle)
+        cycles = related_cycles(site)
+
+        carbon_stock_measurements = [
+            node for node in site.get("measurements", []) if all([
+                node_term_match(node, carbon_stock_term_id),
+                _has_valid_array_fields(node),
+                _has_valid_dates(node),
+                node.get("methodClassification") in (m.value for m in measurement_method_ranking),
+                should_run_measurement_func(node)
+            ])
+        ]
+
+        seed = gen_seed(site)  # All cycles linked to the same site should be consistent
+        rng = random.default_rng(seed)
+
+        should_compile_inventory, should_compile_logs = should_compile_inventory_func(
+            site, cycles, carbon_stock_measurements
+        )
+
+        inventory, inventory_logs = (
+            _compile_inventory(
+                cycle_id,
+                cycles,
+                carbon_stock_measurements,
+                iterations=_ITERATIONS,
+                seed=rng,
+                measurement_method_ranking=measurement_method_ranking
+            ) if should_compile_inventory else ({}, {})
+        )
+
+        has_valid_inventory = len(inventory) > 0
+        has_consecutive_years = check_consecutive(inventory.keys())
+
+        should_run_ = all([has_valid_inventory, has_consecutive_years])
+
+        logs = should_compile_logs | inventory_logs | {
+            "seed": seed,
+            "has_valid_inventory": has_valid_inventory,
+            "has_consecutive_years": has_consecutive_years
+        }
+
+        return should_run_, cycle_id, inventory, logs
+
+    return should_run
+
+
+def _has_valid_array_fields(node: dict) -> bool:
+    """Validate that the array-type fields of a node (`value`, `dates`, `sd`) have data and matching lengths."""
+    value = node.get("value", [])
+    sd = node.get("sd", [])
+    dates = node.get("dates", [])
+    return all([
+        len(value) > 0,
+        len(value) == len(dates),
+        len(sd) == 0 or len(sd) == len(value)
+    ])
+
+
+def _has_valid_dates(node: dict) -> bool:
+    """Validate that all dates in a node's `dates` field have a valid format."""
+    return all(_get_datestr_format(datestr) in _VALID_DATE_FORMATS for datestr in node.get("dates", []))
+
+
+def _get_site(cycle: dict) -> dict:
+    """
+    Get the [Site](https://www.hestia.earth/schema/Site) data from a [Cycle](https://www.hestia.earth/schema/Cycle).
+
+    Parameters
+    ----------
+    cycle : dict
+
+    Returns
+    -------
+    str
+    """
+    return cycle.get("site", {})
+
+
+def _compile_inventory(
     cycle_id: str,
     cycles: list[dict],
     carbon_stock_measurements: list[dict],
     iterations: int = 10000,
-    seed: Union[int, random.Generator, None] = None
+    seed: Union[int, random.Generator, None] = None,
+    measurement_method_ranking: list[MeasurementMethodClassification] = DEFAULT_MEASUREMENT_METHOD_RANKING
 ) -> tuple[dict, dict]:
     """
     Compile an annual inventory of carbon stocks, changes in carbon stocks, carbon stock change emissions, and the share
@@ -354,17 +513,16 @@ def compile_inventory(
     tuple[dict, dict]
         `(inventory, logs)`
     """
-    # Process cycles and carbon stock measurements independently
     cycle_inventory = _compile_cycle_inventory(cycles)
     carbon_stock_inventory = _compile_carbon_stock_inventory(
         carbon_stock_measurements, iterations=iterations, seed=seed
     )
 
-    # Generate logs without side-effects
     logs = _generate_logs(cycle_inventory, carbon_stock_inventory)
 
-    # Combine the inventories functionally
-    inventory = _squash_inventory(cycle_id, cycle_inventory, carbon_stock_inventory)
+    inventory = _squash_inventory(
+        cycle_id, cycle_inventory, carbon_stock_inventory, measurement_method_ranking=measurement_method_ranking
+    )
 
     return inventory, logs
 
@@ -623,7 +781,7 @@ def _interpolate_carbon_stocks(carbon_stocks: list[CarbonStock]) -> dict:
         )
 
         update = {
-            year: {_InventoryKey.CARBON_STOCK: lerp_carbon_stocks(
+            year: {_InventoryKey.CARBON_STOCK: _lerp_carbon_stocks(
                 start,
                 end,
                 f"{year}-12-31T23:59:59"
@@ -654,7 +812,7 @@ def _calculate_stock_changes(carbon_stocks_by_year: dict) -> dict:
     """
     return {
         year: {
-            _InventoryKey.CARBON_STOCK_CHANGE: calc_carbon_stock_change(
+            _InventoryKey.CARBON_STOCK_CHANGE: _calc_carbon_stock_change(
                 start_group[_InventoryKey.CARBON_STOCK],
                 end_group[_InventoryKey.CARBON_STOCK]
             )
@@ -681,7 +839,7 @@ def _calculate_co2_emissions(carbon_stock_changes_by_year: dict) -> dict:
     """
     return {
         year: {
-            _InventoryKey.CO2_EMISSION: calc_carbon_stock_change_emission(
+            _InventoryKey.CO2_EMISSION: _calc_carbon_stock_change_emission(
                 group[_InventoryKey.CARBON_STOCK_CHANGE]
             )
         } for year, group in carbon_stock_changes_by_year.items()
@@ -711,7 +869,12 @@ def _sorted_merge(*sources: Union[dict, list[dict]]) -> dict:
     return dict(sorted(merged.items()))
 
 
-def _squash_inventory(cycle_id: str, cycle_inventory: dict, carbon_stock_inventory: dict) -> dict:
+def _squash_inventory(
+    cycle_id: str,
+    cycle_inventory: dict,
+    carbon_stock_inventory: dict,
+    measurement_method_ranking: list[MeasurementMethodClassification] = DEFAULT_MEASUREMENT_METHOD_RANKING
+) -> dict:
     """
     Combine the `cycle_inventory` and `carbon_stock_inventory` into a single inventory by merging data for each year
     using the strongest available `MeasurementMethodClassification`. Any years not relevant to the cycle identified
@@ -789,7 +952,7 @@ def _squash_inventory(cycle_id: str, cycle_inventory: dict, carbon_stock_invento
         update_dict = next(
             (
                 {year: reduce(merge, [carbon_stock_inventory[method][year], cycle_inventory[year]], dict())}
-                for method in _VALID_MEASUREMENT_METHOD_CLASSIFICATIONS if should_run_group(method, year)
+                for method in measurement_method_ranking if should_run_group(method, year)
             ),
             {}
         )
@@ -902,3 +1065,60 @@ def _format_named_tuple(value: Optional[Union[CarbonStock, CarbonStockChange, Ca
         if isinstance(value, (CarbonStock, CarbonStockChange, CarbonStockChangeEmission))
         else "None"
     )
+
+
+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(cycle_id: str, inventory: dict) -> list[dict]:
+        """
+        Calculate emissions for a specific cycle using from a carbon stock change using pre-compiled inventory data.
+
+        The emission method tier is based on the minimum measurement method tier of the carbon stock measures used to
+        calculate the emission.
+
+        Parameters
+        ----------
+        cycle_id : str
+            The "@id" field of the [Cycle node](https://www.hestia.earth/schema/Cycle).
+        grouped_data : dict
+            A dictionary containing grouped carbon stock change and share of emissions data.
+
+        Returns
+        -------
+        list[dict]
+            A list of [Emission nodes](https://www.hestia.earth/schema/Emission) containing model results.
+        """
+        rescaled_emissions = [
+            _rescale_carbon_stock_change_emission(
+                group[_InventoryKey.CO2_EMISSION], group[_InventoryKey.SHARE_OF_EMISSION][cycle_id]
+            ) for group in inventory.values()
+        ]
+        total_emission = reduce(_add_carbon_stock_change_emissions, rescaled_emissions)
+
+        descriptive_stats = calc_descriptive_stats(
+            total_emission.value,
+            EmissionStatsDefinition.SIMULATED,
+            decimals=6
+        )
+
+        method_tier = total_emission.method
+        return [new_emission_func(method_tier=method_tier, **descriptive_stats)]
+
+    return run