hestia-earth-models 0.74.3__py3-none-any.whl → 0.74.5__py3-none-any.whl

hestia_earth/models/ipcc2019/co2ToAirCarbonStockChange_utils.py

@@ -11,7 +11,7 @@ from numpy.typing import NDArray
 from pydash.objects import merge
 from typing import Any, Callable, NamedTuple, Optional, Union
 from hestia_earth.schema import (
-    EmissionMethodTier, EmissionStatsDefinition, MeasurementMethodClassification
+    CycleFunctionalUnit, EmissionMethodTier, EmissionStatsDefinition, MeasurementMethodClassification, SiteSiteType
 )
 from hestia_earth.utils.date import diff_in_days, YEAR
 from hestia_earth.utils.tools import flatten, non_empty_list, safe_parse_date
@@ -21,8 +21,8 @@ from hestia_earth.utils.descriptive_stats import calc_descriptive_stats
 from hestia_earth.models.log import log_as_table
 from hestia_earth.models.utils import pairwise
 from hestia_earth.models.utils.blank_node import (
-    _gapfill_datestr, _get_datestr_format, DatestrGapfillMode, DatestrFormat, group_nodes_by_year, node_term_match,
-    split_node_by_dates
+    _gapfill_datestr, _get_datestr_format, cumulative_nodes_term_match, 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.emission import min_emission_method_tier
@@ -47,7 +47,7 @@ Carbon stock measurements without an associated `sd` should be assigned a nomina
 the mean).
 """
 _TRANSITION_PERIOD_YEARS = 20
-_TRANSITION_PERIOD_DAYS = 20 * YEAR  # 20 years in days
+_TRANSITION_PERIOD_DAYS = _TRANSITION_PERIOD_YEARS * YEAR  # 20 years in days
 _VALID_DATE_FORMATS = {
     DatestrFormat.YEAR,
     DatestrFormat.YEAR_MONTH,
@@ -81,6 +81,14 @@ Any `MeasurementMethodClassification` not in the mapping should be assigned `DEF
 """
 
 
+_SITE_TYPE_SYSTEMS_MAPPING = {
+    SiteSiteType.GLASS_OR_HIGH_ACCESSIBLE_COVER.value: [
+        "protectedCroppingSystemSoilBased",
+        "protectedCroppingSystemSoilAndSubstrateBased"
+    ]
+}
+
+
 class _InventoryKey(Enum):
     """
     The inner keys of the annualised inventory created by the `_compile_inventory` function.
@@ -329,70 +337,87 @@ def _add_carbon_stock_change_emissions(
 
 
 def create_should_run_function(
-    *,
     carbon_stock_term_id: str,
-    get_valid_management_nodes_func: Callable[[dict], list[dict]],
-    should_compile_inventory_func: Callable[[dict, list[dict], list[dict]], tuple[bool, dict]],
-    summarise_land_use_func: Callable[[list[dict]], Any],
-    detect_land_use_change_func: Callable[[Any, Any], bool],
-    should_run_measurement_func: Callable[[dict], bool] = lambda *_: True,
-    measurement_method_ranking: list[MeasurementMethodClassification] = DEFAULT_MEASUREMENT_METHOD_RANKING
+    *,
+    depth_upper: Optional[float] = None,
+    depth_lower: Optional[float] = None,
+    measurements_mandatory: 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
 ) -> Callable[[dict], tuple[bool, str, dict, dict]]:
     """
-    Create a should run function for an emissions from carbon stock change model.
+    Create a `should_run` function for a 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.
+    This higher-order function constructs a custom decision function that determines:
+    1. Whether a given cycle has sufficient valid carbon stock measurements and land use information
+       to compile an inventory.
+    2. Which measurements are included in the inventory based on depth, method ranking, and other criteria.
 
     Parameters
     ----------
     carbon_stock_term_id : str
         The `term.@id` of the carbon stock measurement (e.g., `aboveGroundBiomass`, `belowGroundBiomass`,
-        `organicCarbonPerHa`, etc.).
+        `organicCarbonPerHa`).
 
-    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.
+    depth_upper : float, optional
+        The upper bound of the measurement depth (e.g., 0 cm). If provided, only measurements matching this bound are
+        included.
 
-    get_valid_management_nodes_func : Callable[[dict], list[dict]]
-        A function, with the signature... `(site: dict) -> management_nodes: list[dict]` to extract valid management
-        nodes from the site for building the land use inventory.
+    depth_lower : float, optional
+        The lower bound of the measurement depth (e.g., 30 cm). If provided, only measurements matching this bound are
+        included.
 
-    summarise_land_use_func: Callable[[list[dict]], Any]
-        A function with the signature `(nodes: list[dict]) -> Any`, to reduce a list of `landCover`
-        [Management](https://www.hestia.earth/schema/Management) nodes into a land use summary that can be compared
-        with other summaries to determine whether land use change events have occured.
-
-    detect_land_use_change_func: Callable[[Any, Any], bool]
-        A function with the signature `(summary_a: Any, summary_b: Any) -> bool`, to determine whether a land use
-        change event has occured.
-
-    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.
+    measurements_mandatory : 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.
 
     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:
+        The priority order for selecting among multiple measurement methods. Defaults to:
         ```
-        MeasurementMethodClassification.ON_SITE_PHYSICAL_MEASUREMENT,
-        MeasurementMethodClassification.MODELLED_USING_OTHER_MEASUREMENTS,
-        MeasurementMethodClassification.TIER_3_MODEL,
-        MeasurementMethodClassification.TIER_2_MODEL,
-        MeasurementMethodClassification.TIER_1_MODEL
+        [
+            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.
+        Measurements using methods not in this ranking are excluded.
+
+    transition_period : float, default=_TRANSITION_PERIOD_DAYS
+        The transition period (in days) over which management changes are assumed to take effect. Used to generate a
+        correlation matrix for multivariate sampling of carbon stock values.
+
+    get_valid_management_nodes_func : Callable[[dict], list[dict]], optional
+        Function with signature `(site: dict) -> list[dict]`.
+
+        Extracts valid management nodes from the site for building the land use inventory.
+
+    summarise_land_use_func : Callable[[list[dict]], Any], optional
+        Function with signature `(nodes: list[dict]) -> Any`.
+
+        Summarises a list of `landCover` [Management](https://www.hestia.earth/schema/Management) nodes into a
+        comparable representation for detecting land use changes.
+
+    detect_land_use_change_func : Callable[[Any, Any], bool], optional
+        Function with signature `(summary_a: Any, summary_b: Any) -> bool`.
+
+        Detects whether a land use change event has occurred between two summaries.
 
     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)`.
+    should_run_func : Callable[[dict], tuple[bool, str, dict, dict]]
+        A function with the signature:
+        `(cycle: dict) -> (should_run: bool, cycle_id: str, inventory: dict, logs: dict)`
+
+        - `should_run` : Whether the model should run for the cycle.
+        - `cycle_id`   : Identifier of the cycle.
+        - `inventory`  : The constructed carbon stock inventory for the cycle.
+        - `logs`       : Diagnostic logs describing validation and filtering decisions.
     """
-
     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
@@ -410,21 +435,24 @@ def create_should_run_function(
             `(should_run, cycle_id, inventory, logs)`
         """
         cycle_id = cycle.get("@id")
-        cycle_start_date = cycle.get("startDate")
-        cycle_end_date = cycle.get("endDate")
 
-        site = _get_site(cycle)
+        site = cycle.get("site", {})
+        site_type = site.get("siteType")
+
         cycles = related_cycles(site, cycles_mapping={cycle_id: cycle})
 
         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)
-            ])
+            if (
+                node_term_match(node, carbon_stock_term_id)
+                and all([
+                    _has_valid_array_fields(node),
+                    _has_valid_dates(node),
+                    node.get("methodClassification") in (m.value for m in measurement_method_ranking),
+                    depth_upper is None or node.get("depthUpper") == depth_upper,
+                    depth_lower is None or node.get("depthLower") == depth_lower
+                ])
+            )
         ]
 
         land_cover_nodes = get_valid_management_nodes_func(site)
@@ -432,16 +460,27 @@ def create_should_run_function(
         seed = gen_seed(site, MODEL, carbon_stock_term_id)  # 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
+        has_soil = is_soil_based_system(cycles, site_type)
+        has_cycles = len(cycles) > 0
+        has_functional_unit_1_ha = all(
+            cycle.get('functionalUnit') == CycleFunctionalUnit._1_HA.value for cycle in cycles
+        )
+        has_stock_measurements = bool(carbon_stock_measurements)
+
+        should_compile_inventory = (
+            has_soil
+            and has_cycles
+            and has_functional_unit_1_ha
+            and (has_stock_measurements or not measurements_mandatory)
         )
 
         compile_inventory_func = _create_compile_inventory_function(
+            transition_period=transition_period,
+            seed=rng,
+            iterations=_ITERATIONS,
+            measurement_method_ranking=measurement_method_ranking,
             summarise_land_use_func=summarise_land_use_func,
             detect_land_use_change_func=detect_land_use_change_func,
-            iterations=_ITERATIONS,
-            seed=rng,
-            measurement_method_ranking=measurement_method_ranking
         )
 
         inventory, inventory_logs = (
@@ -457,21 +496,20 @@ def create_should_run_function(
 
         should_run_ = all([has_valid_inventory, has_consecutive_years])
 
-        kwargs = {
-            "cycle_id": cycle_id,
-            "cycle_start_date": cycle_start_date,
-            "cycle_end_date": cycle_end_date,
-            "inventory": inventory
-        }
-
-        logs = should_compile_logs | inventory_logs | {
+        logs = inventory_logs | {
+            "carbon_stock_term": carbon_stock_term_id,
             "seed": seed,
+            "site_type": site_type,
+            "has_soil": has_soil,
+            "has_cycles": has_cycles,
+            "has_functional_unit_1_ha": has_functional_unit_1_ha,
             "has_valid_inventory": has_valid_inventory,
             "has_consecutive_years": has_consecutive_years,
-            "has_stock_measurements": bool(carbon_stock_measurements)
+            "has_stock_measurements": has_stock_measurements,
+            "measurements_mandatory": measurements_mandatory
         }
 
-        return should_run_, kwargs, logs
+        return should_run_, cycle_id, inventory, logs
 
     return should_run
 
@@ -493,69 +531,62 @@ def _has_valid_dates(node: dict) -> bool:
     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 _create_compile_inventory_function(
     *,
-    summarise_land_use_func: Callable[[list[dict]], Any],
-    detect_land_use_change_func: Callable[[Any, Any], bool],
-    iterations: int = 10000,
+    transition_period: float,
     seed: Union[int, random.Generator, None] = None,
-    measurement_method_ranking: list[MeasurementMethodClassification] = DEFAULT_MEASUREMENT_METHOD_RANKING
+    iterations: int = 10000,
+    measurement_method_ranking: list[MeasurementMethodClassification] = DEFAULT_MEASUREMENT_METHOD_RANKING,
+    summarise_land_use_func: Callable[[list[dict]], Any],
+    detect_land_use_change_func: Callable[[Any, Any], bool]
 ) -> Callable:
     """
-    Create a compile inventory function for an emissions from carbon stock change model.
+    Create a `compile_inventory` function for a carbon stock change model.
 
-    Model-specific validation functions should be passed as parameters to this higher order function to determine how
-    land cover data is reduced down to a land use summary and how those land use summaries should be compared to
-    determine when land use change events have occured.
+    This higher-order function produces a callable that generates annual inventories of carbon stock, carbon stock
+    change, emissions, and land-use-related events. It combines data from cycles, measurements, and land cover to build
+    a unified inventory.
 
     Parameters
     ----------
-    summarise_land_use_func: Callable[[list[dict]], Any]
-        A function with the signature `(nodes: list[dict]) -> Any`, to reduce a list of `landCover`
-        [Management](https://www.hestia.earth/schema/Management) nodes into a land use summary that can be compared
-        with other summaries to determine whether land use change events have occured.
-
-    detect_land_use_change_func: Callable[[Any, Any], bool]
-        A function with the signature `(summary_a: Any, summary_b: Any) -> bool`, to determine whether a land use
-        change event has occured.
-
-    iterations : int, optional
-        The number of iterations for stochastic processing (default is 10,000).
+    transition_period : float, default=_TRANSITION_PERIOD_DAYS
+        The transition period (in days) over which management changes are assumed to take effect. Used to generate a
+        correlation matrix for multivariate sampling of carbon stock values.
 
     seed : int, random.Generator, or None, optional
-        Seed for random number generation to ensure reproducibility. Default is None.
+        Seed for random number generation to ensure reproducibility.
+
+    iterations : int, optional, default=`10000`
+        The number of iterations for the Monte Carlo simualation.
 
     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:
+        The priority order for selecting among multiple measurement methods. Defaults to:
         ```
-        MeasurementMethodClassification.ON_SITE_PHYSICAL_MEASUREMENT,
-        MeasurementMethodClassification.MODELLED_USING_OTHER_MEASUREMENTS,
-        MeasurementMethodClassification.TIER_3_MODEL,
-        MeasurementMethodClassification.TIER_2_MODEL,
-        MeasurementMethodClassification.TIER_1_MODEL
+        [
+            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.
+        Measurements using methods not in this ranking are excluded.
+
+    summarise_land_use_func : Callable[[list[dict]], Any], optional
+        Function with signature `(nodes: list[dict]) -> Any`.
+
+        Summarises a list of `landCover` [Management](https://www.hestia.earth/schema/Management) nodes into a
+        comparable representation for detecting land use changes.
+
+    detect_land_use_change_func : Callable[[Any, Any], bool], optional
+        Function with signature `(summary_a: Any, summary_b: Any) -> bool`.
+
+        Detects whether a land use change event has occurred between two summaries.
 
     Returns
     ----------
-    Callable
-        The `compile_inventory` function.
+    compile_inventory : Callable[[list[dict], list[dict], list[dict]], tuple[dict, dict]]
+        A function that compiles an annual inventory given cycles, carbon stock measurements, and land cover nodes.
     """
     def compile_inventory(
         cycles: list[dict],
@@ -563,52 +594,60 @@ def _create_compile_inventory_function(
         land_cover_nodes: list[dict]
     ) -> tuple[dict, dict]:
         """
-        Compile an annual inventory of carbon stocks, changes in carbon stocks, carbon stock change emissions, and the
-        share of emissions of cycles based on the provided cycles and measurement data.
-
-        A separate inventory is compiled for each valid `MeasurementMethodClassification` present in the data, and the
-        strongest available method is chosen for each relevant inventory year. These inventories are then merged into
-        one final result.
-
-        The final inventory structure is:
-        ```
-        {
-            year (int): {
-                _InventoryKey.CARBON_STOCK: value (CarbonStock),
-                _InventoryKey.CARBON_STOCK_CHANGE: value (CarbonStockChange),
-                _InventoryKey.CO2_EMISSION: value (CarbonStockChangeEmission),
-                _InventoryKey.SHARE_OF_EMISSION: {
-                    cycle_id (str): value (float),
-                    ...cycle_ids
-                },
-                _InventoryKey.YEARS_SINCE_LUC_EVENT: value (int)
-            },
-            ...years
-        }
+        Compile an annual inventory of carbon stocks, stock changes, emissions, and land
+        use events.
+
+        The function integrates data from cycles, carbon stock measurements, and land cover management nodes. For each
+        year, the inventory includes:
+          - carbon stock values,
+          - carbon stock changes,
+          - CO₂ emissions,
+          - attribution of emissions to cycles,
+          - and time since land use change (LUC) events.
+
+        A separate inventory is compiled for each valid measurement method present in the data. The best available
+        method per year (according to `measurement_method_ranking`) is chosen, and inventories are merged into the
+        final result.
         ```
 
         Parameters
         ----------
-        cycle_id : str
-            The unique identifier of the cycle being processed.
         cycles : list[dict]
             A list of [Cycle](https://www.hestia.earth/schema/Cycles) nodes related to the site.
+
         carbon_stock_measurements : list[dict]
             A list of [Measurement](https://www.hestia.earth/schema/Measurement) nodes, representing carbon stock
             measurements across time and methods.
+
         land_cover_nodes : list[dict]
-            A list of `landCover `[Management](https://www.hestia.earth/schema/Management) nodes, representing the
+            A list of `landCover` [Management](https://www.hestia.earth/schema/Management) nodes, representing the
             site's land cover over time.
 
 
         Returns
         -------
-        tuple[dict, dict]
-            `(inventory, logs)`
+        inventory : dict
+            Annual inventory of carbon stock, carbon stock change, emissions, and land use
+            change information. Structure:
+            ```
+            {
+                year (int): {
+                    _InventoryKey.CARBON_STOCK: CarbonStock,
+                    _InventoryKey.CARBON_STOCK_CHANGE: CarbonStockChange,
+                    _InventoryKey.CO2_EMISSION: CarbonStockChangeEmission,
+                    _InventoryKey.SHARE_OF_EMISSION: {cycle_id (str): float, ...},
+                    _InventoryKey.YEARS_SINCE_LUC_EVENT: int
+                },
+                ...years
+            }
+            ```
+
+        logs : dict
+            Diagnostic logs describing intermediate steps and validation decisions.
         """
         cycle_inventory = _compile_cycle_inventory(cycles)
         carbon_stock_inventory = _compile_carbon_stock_inventory(
-            carbon_stock_measurements, iterations=iterations, seed=seed
+            carbon_stock_measurements, transition_period=transition_period, iterations=iterations, seed=seed
         )
         land_use_inventory = _compile_land_use_inventory(
             land_cover_nodes, summarise_land_use_func, detect_land_use_change_func
@@ -630,20 +669,19 @@ def _create_compile_inventory_function(
 
 def _compile_cycle_inventory(cycles: list[dict]) -> dict:
     """
-    Calculate grouped share of emissions for cycles based on the amount they contribute the the overall land management
-    of an inventory year.
+    Compile the share of emissions for each cycle, grouped by inventory year.
 
-    This function groups cycles by year, then calculates the share of emissions for each cycle based on the
-    `fraction_of_group_duration` value. The share of emissions is normalized by the sum of cycle occupancies for the
-    entire dataset to ensure the values represent a valid share.
+    Each cycle is assumed to occupy a fraction of its group's duration (given by the `"fraction_of_group_duration"`
+    key). For each year, this function normalizes those fractions so that the shares of emissions across all cycles in
+    that year sum to 1.0.
 
-    The returned inventory has the shape:
+    The returned inventory has the structure:
     ```
     {
         year (int): {
             _InventoryKey.SHARE_OF_EMISSION: {
-                cycle_id (str): value (float),
-                ...cycle_ids
+                cycle_id (str): float,   # share of emissions attributed to this cycle
+                ...more cycle_ids
             }
         },
         ...more years
@@ -653,17 +691,17 @@ def _compile_cycle_inventory(cycles: list[dict]) -> dict:
     Parameters
     ----------
     cycles : list[dict]
-        List of [Cycle nodes](https://www.hestia.earth/schema/Cycle), where each cycle dictionary should contain a
-        "fraction_of_group_duration" key added by the `group_nodes_by_year` function.
-    iterations : int, optional
-        Number of iterations for stochastic sampling when processing carbon stock values (default is 10,000).
-    seed : int, random.Generator, or None, optional
-        Seed for random number generation (default is None).
+        List of [Cycle](https://www.hestia.earth/schema/Cycle) nodes.
+
+        Each cycle dictionary must include:
+        - `@id` : str, unique identifier for the cycle
+        - `fraction_of_group_duration` : float, the fraction of the year this cycle contributes, typically added by
+        `group_nodes_by_year`.
 
     Returns
     -------
     dict
-        A dictionary with grouped share of emissions for each cycle based on the fraction of the year.
+        A dictionary mapping each year to its inventory of emission shares per cycle.
     """
     grouped_cycles = group_nodes_by_year(cycles)
 
@@ -682,27 +720,30 @@ def _compile_cycle_inventory(cycles: list[dict]) -> dict:
 
 def _compile_carbon_stock_inventory(
     carbon_stock_measurements: list[dict],
+    transition_period: float,
     iterations: int = 10000,
     seed: Union[int, random.Generator, None] = None
 ) -> dict:
     """
-    Compile an annual inventory of carbon stock data and pre-computed carbon stock change emissions.
+    Compile an annual inventory of carbon stock, stock change, and associated CO₂ emissions.
 
-    Carbon stock measurements are grouped by the method used (MeasurementMethodClassification). For each method,
-    carbon stocks are processed for each year and changes between years are computed, followed by the calculation of
-    CO2 emissions.
+    Carbon stock measurements are grouped by their measurement method (`MeasurementMethodClassification`). For each
+    method:
+    - Annual carbon stock values are estimated.
+    - Year-to-year changes in carbon stocks are calculated.
+    - CO₂ emissions are derived from the changes.
 
-    The returned inventory has the shape:
+    The returned inventory has the structure:
     ```
     {
         method (MeasurementMethodClassification): {
             year (int): {
-                _InventoryKey.CARBON_STOCK: value (CarbonStock),
-                _InventoryKey.CARBON_STOCK_CHANGE: value (CarbonStockChange),
-                _InventoryKey.CO2_EMISSION: value (CarbonStockChangeEmission)
+                _InventoryKey.CARBON_STOCK: CarbonStock,
+                _InventoryKey.CARBON_STOCK_CHANGE: CarbonStockChange,
+                _InventoryKey.CO2_EMISSION: CarbonStockChangeEmission
             },
             ...more years
-        }
+        },
         ...more methods
     }
     ```
@@ -710,41 +751,60 @@ def _compile_carbon_stock_inventory(
     Parameters
     ----------
     carbon_stock_measurements : list[dict]
-        List of carbon [Measurement nodes](https://www.hestia.earth/schema/Measurement) nodes.
-    iterations : int, optional
-        Number of iterations for stochastic sampling when processing carbon stock values (default is 10,000).
+        List of [Measurement](https://www.hestia.earth/schema/Measurement) nodes representing
+        carbon stock observations. Each measurement should include:
+        - `@id` : str, unique measurement identifier
+        - `measurementMethod` : MeasurementMethodClassification
+        - `value` : float
+        - `timestamp` or `year` : temporal reference
+
+    transition_period : float, default=_TRANSITION_PERIOD_DAYS
+        The transition period (in days) over which management changes are assumed to take effect. Used to generate a
+        correlation matrix for multivariate sampling of carbon stock values.
+
+    iterations : int, default=10000
+        Number of iterations for stochastic sampling when estimating carbon stock values.
+
     seed : int, random.Generator, or None, optional
-        Seed for random number generation (default is None).
+        Seed for random number generation. Default is `None`.
 
     Returns
     -------
     dict
-        The carbon stock inventory grouped by measurement method classification.
+        Nested dictionary of annual inventories, grouped by measurement method classification.
     """
     carbon_stock_measurements_by_method = group_measurements_by_method_classification(carbon_stock_measurements)
 
     return {
-        method: _process_carbon_stock_measurements(measurements, iterations=iterations, seed=seed)
+        method: _process_carbon_stock_measurements(measurements, transition_period, iterations, seed)
         for method, measurements in carbon_stock_measurements_by_method.items()
     }
 
 
 def _process_carbon_stock_measurements(
     carbon_stock_measurements: list[dict],
+    transition_period: float,
     iterations: int = 10000,
     seed: Union[int, random.Generator, None] = None
 ) -> dict:
     """
-    Process carbon stock measurements to compile an annual inventory of carbon stocks, carbon stock changes, and CO2
-    emissions. The inventory is built by interpolating between measured values and calculating changes across years.
+    Process carbon stock measurements to build an annual inventory of carbon stocks,
+    carbon stock changes, and CO₂ emissions.
 
-    The returned inventory has the shape:
+    The function:
+    - Preprocesses measurements (e.g., applies decay/transition dynamics using `transition_period`).
+    - Interpolates carbon stock values across years.
+    - Calculates year-to-year stock changes.
+    - Derives CO₂ emissions from the stock changes.
+    - Merges results into a single annual inventory.
+
+    The returned inventory has the structure:
     ```
     {
         year (int): {
-            _InventoryKey.CARBON_STOCK: value (CarbonStock),
-            _InventoryKey.CARBON_STOCK_CHANGE: value (CarbonStockChange),
-            _InventoryKey.CO2_EMISSION: value (CarbonStockChangeEmission)
+            _InventoryKey.CARBON_STOCK: CarbonStock,
+            _InventoryKey.CARBON_STOCK_CHANGE: CarbonStockChange,
+            _InventoryKey.CO2_EMISSION: CarbonStockChangeEmission,
         },
         ...more years
     }
@@ -753,18 +813,33 @@ def _process_carbon_stock_measurements(
     Parameters
     ----------
     carbon_stock_measurements : list[dict]
-        List of pre-validated carbon stock [Measurement nodes](https://www.hestia.earth/schema/Measurement).
-    iterations : int, optional
-        Number of iterations for stochastic sampling when processing carbon stock values (default is 10,000).
+        List of carbon stock [Measurement](https://www.hestia.earth/schema/Measurement) nodes.
+
+        Each measurement is expected to include:
+        - `@id` : str, unique identifier
+        - `value` : float, the carbon stock estimate
+        - `timestamp` or `year` : temporal reference
+        - `measurementMethod` : MeasurementMethodClassification
+
+    transition_period : float, default=_TRANSITION_PERIOD_DAYS
+        The transition period (in days) over which management changes are assumed to take effect. Used to generate a
+        correlation matrix for multivariate sampling of carbon stock values.
+
+    iterations : int, default=10000
+        Number of iterations for stochastic sampling when estimating carbon stock values.
+
     seed : int, random.Generator, or None, optional
-        Seed for random number generation (default is None).
+        Seed for random number generation to ensure reproducibility. Default is `None`.
 
     Returns
     -------
     dict
-        The annual inventory.
+        Annual inventory mapping years to:
+        - `_InventoryKey.CARBON_STOCK` : CarbonStock
+        - `_InventoryKey.CARBON_STOCK_CHANGE` : CarbonStockChange
+        - `_InventoryKey.CO2_EMISSION` : CarbonStockChangeEmission
     """
-    carbon_stocks = _preprocess_carbon_stocks(carbon_stock_measurements, iterations, seed)
+    carbon_stocks = _preprocess_carbon_stocks(carbon_stock_measurements, transition_period, iterations, seed)
 
     carbon_stocks_by_year = _interpolate_carbon_stocks(carbon_stocks)
     carbon_stock_changes_by_year = _calculate_stock_changes(carbon_stocks_by_year)
@@ -775,29 +850,47 @@ def _process_carbon_stock_measurements(
 
 def _preprocess_carbon_stocks(
     carbon_stock_measurements: list[dict],
+    half_life: float,
     iterations: int = 10000,
     seed: Union[int, random.Generator, None] = None
 ) -> list[CarbonStock]:
     """
-    Pre-process a list of carbon stock measurements by normalizing and sorting them by date. The measurements are used
-    to create correlated samples using stochastic sampling methods.
+    Preprocess a list of carbon stock measurements by normalizing, filling missing values, and generating correlated
+    stochastic samples.
 
-    The carbon stock measurements are processed to fill in any gaps in data (e.g., missing standard deviations), and
-    correlated samples are drawn to handle measurement uncertainty.
+    Steps:
+    - Measurements are expanded and sorted by date.
+    - Missing uncertainty values (e.g., standard deviations) are filled if necessary.
+    - A correlation matrix across time is built using an exponential decay function parameterized by `half_life`.
+    - Correlated random samples are drawn to represent measurement uncertainty over time.
+    - The results are returned as a list of `CarbonStock` objects.
 
     Parameters
     ----------
     carbon_stock_measurements : list[dict]
-        List of pre-validated carbon stock [Measurement nodes](https://www.hestia.earth/schema/Measurement).
-    iterations : int, optional
-        Number of iterations for stochastic sampling when processing carbon stock values (default is 10,000).
+        List of carbon stock [Measurement](https://www.hestia.earth/schema/Measurement) nodes.
+        Each measurement is expected to include:
+        - `@id` : str, unique identifier
+        - `value` : float, measured carbon stock
+        - `timestamp` or `year` : temporal reference
+        - `standardDeviation` : float, optional measurement uncertainty
+        - `measurementMethod` : MeasurementMethodClassification
+
+    half_life : float
+        Transition period (in days) used to parameterize the exponential decay function for building the correlation
+        matrix across time.
+
+    iterations : int, default=10000
+        Number of stochastic samples to draw for each measurement.
+
     seed : int, random.Generator, or None, optional
-        Seed for random number generation (default is None).
+        Seed for random number generation, to ensure reproducibility.
 
     Returns
     -------
     list[CarbonStock]
-        A list of carbon stocks sorted by date.
+        A list of `CarbonStock` objects, one per measurement date and method, each containing simulated sample values
+        and associated metadata.
     """
     dates, values, sds, methods = _extract_node_data(
         flatten([split_node_by_dates(m) for m in carbon_stock_measurements])
@@ -807,7 +900,7 @@ def _preprocess_carbon_stocks(
         dates,
         decay_fn=lambda dt: exponential_decay(
             dt,
-            tau=calc_tau(_TRANSITION_PERIOD_DAYS),
+            tau=calc_tau(half_life),
             initial_value=_MAX_CORRELATION,
             final_value=_MIN_CORRELATION
         )
@@ -982,13 +1075,17 @@ def _compile_land_use_inventory(
     ----------
     land_cover_nodes : list[dict]
         A list of `landCover` Management nodes, representing the site's land cover over time.
-    summarise_land_use_func: Callable[[list[dict]], Any]
-        A function with the signature `(nodes: list[dict]) -> Any`, to reduce a list of `landCover` Management nodes
-        into a land use summary that can be compared with other summaries to determine whether land use change events
-        have occured.
-    detect_land_use_change_func: Callable[[Any, Any], bool]
-        A function with the signature `(summary_a: Any, summary_b: Any) -> bool`, to determine whether a land use
-        change event has occured.
+
+    summarise_land_use_func : Callable[[list[dict]], Any]
+        Function with signature `(nodes: list[dict]) -> Any`.
+
+        Summarises a list of `landCover` [Management](https://www.hestia.earth/schema/Management) nodes into a
+        comparable representation for detecting land use changes.
+
+    detect_land_use_change_func : Callable[[Any, Any], bool]
+        Function with signature `(summary_a: Any, summary_b: Any) -> bool`.
+
+        Detects whether a land use change event has occurred between two summaries.
 
     Returns
     -------
@@ -1086,13 +1183,14 @@ def _squash_inventory(
     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
-    by `cycle_id` are excluded.
+    Combine the `cycle_inventory`, `carbon_stock_inventory`, and `land_use_inventory` into a single inventory.
+
+    For each year, the function selects the strongest available `MeasurementMethodClassification` (based on the
+    ranking) to provide carbon stock and emissions data, and merges it with cycle-level emissions shares and land use
+    change information.
 
     Parameters
     ----------
-
     cycle_inventory : dict
         A dictionary representing the share of emissions for each cycle, grouped by year.
         Format:
@@ -1133,15 +1231,16 @@ def _squash_inventory(
             year (int): {
                 _InventoryKey.LAND_USE_SUMMARY: value (Any),
                 _InventoryKey.LAND_USE_CHANGE_EVENT: value (bool),
-                _InventoryKey.YEARS_SINCE_LUC_EVENT: value (int)
+                _InventoryKey.YEARS_SINCE_LUC_EVENT: value (int),
+                _InventoryKey.YEARS_SINCE_INVENTORY_START: value (int)
             },
             ...years
         }
         ```
 
     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:
+        The order in which to prioritise `MeasurementMethodClassification`s when reducing the inventory to a single
+        method per year. Defaults to:
         ```
         MeasurementMethodClassification.ON_SITE_PHYSICAL_MEASUREMENT,
         MeasurementMethodClassification.MODELLED_USING_OTHER_MEASUREMENTS,
@@ -1149,13 +1248,12 @@ def _squash_inventory(
         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.
+        Note: measurements with methods not included in the ranking are ignored.
 
     Returns
     -------
     dict
-        A combined inventory that merges cycle and carbon stock inventories for relevant years and cycles.
-        The resulting structure is:
+        A combined inventory with one entry per year containing:
         ```
         {
             year (int): {
@@ -1165,7 +1263,11 @@ def _squash_inventory(
                 _InventoryKey.SHARE_OF_EMISSION: {
                     cycle_id (str): value (float),
                     ...other cycle_ids
-                }
+                },
+                _InventoryKey.LAND_USE_SUMMARY: value (Any),
+                _InventoryKey.LAND_USE_CHANGE_EVENT: value (bool),
+                _InventoryKey.YEARS_SINCE_LUC_EVENT: value (int),
+                _InventoryKey.YEARS_SINCE_INVENTORY_START: value (int)
             },
             ...more years
         }
@@ -1473,7 +1575,7 @@ def create_run_function(
 
         return result | emission_dict | zero_emission_dict
 
-    def run(cycle_id: str, cycle_start_date: str, cycle_end_date: str, inventory: dict) -> 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.
 
@@ -1530,3 +1632,13 @@ def get_zero_emission(year):
 def _get_emission_method(emission: CarbonStockChangeEmission):
     method = emission.method
     return method if isinstance(method, EmissionMethodTier) else EmissionMethodTier.TIER_1
+
+
+def is_soil_based_system(cycles, site_type):
+    return 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
+    )