hestia-earth-models 0.70.0__py3-none-any.whl → 0.70.2__py3-none-any.whl

hestia_earth/models/ipcc2019/n2OToAirOrganicSoilCultivationDirect.py

@@ -0,0 +1,161 @@
+from hestia_earth.schema import EmissionMethodTier, EmissionStatsDefinition
+
+from hestia_earth.models.log import logRequirements, logShouldRun
+from hestia_earth.models.utils.cycle import land_occupation_per_ha
+from hestia_earth.models.utils.ecoClimateZone import EcoClimateZone, get_eco_climate_zone_value
+from hestia_earth.models.utils.emission import _new_emission
+from hestia_earth.models.utils.measurement import most_relevant_measurement_value
+from hestia_earth.models.utils.site import valid_site_type
+
+from .organicSoilCultivation_utils import (
+    assign_organic_soil_category, calc_emission, get_emission_factor, OrganicSoilCategory, remap_categories,
+    valid_eco_climate_zone
+)
+from . import MODEL
+
+
+REQUIREMENTS = {
+    "Cycle": {
+        "or": [
+            {
+                "cycleDuration": "",
+                "practices": [{"@type": "Practice", "value": "", "term.@id": "longFallowRatio"}]
+            },
+            {
+                "@doc": "for plantations, additional properties are required",
+                "practices": [
+                    {"@type": "Practice", "value": "", "term.@id": "nurseryDensity"},
+                    {"@type": "Practice", "value": "", "term.@id": "nurseryDuration"},
+                    {"@type": "Practice", "value": "", "term.@id": "plantationProductiveLifespan"},
+                    {"@type": "Practice", "value": "", "term.@id": "plantationDensity"},
+                    {"@type": "Practice", "value": "", "term.@id": "plantationLifespan"},
+                    {"@type": "Practice", "value": "", "term.@id": "rotationDuration"}
+                ]
+            }
+        ],
+        "site": {
+            "@type": "Site",
+            "measurements": [
+                {"@type": "Measurement", "value": "", "term.@id": "histosol"},
+                {"@type": "Measurement", "value": "", "term.@id": "ecoClimateZone"}
+            ]
+        },
+        "optional": {
+            "cycleDuration": ""
+        }
+    }
+}
+LOOKUPS = {
+    "crop": [
+        "isPlantation",
+        "IPCC_2013_ORGANIC_SOIL_CULTIVATION_CATEGORY"
+    ],
+    "forage": [
+        "isPlantation",
+        "IPCC_2013_ORGANIC_SOIL_CULTIVATION_CATEGORY"
+    ],
+    "ecoClimateZone": [
+        "IPCC_2013_ORGANIC_SOILS_TONNES_N2O-N_HECTARE_ANNUAL_CROPS",
+        "IPCC_2013_ORGANIC_SOILS_TONNES_N2O-N_HECTARE_PERENNIAL_CROPS",
+        "IPCC_2013_ORGANIC_SOILS_TONNES_N2O-N_HECTARE_ACACIA",
+        "IPCC_2013_ORGANIC_SOILS_TONNES_N2O-N_HECTARE_OIL_PALM",
+        "IPCC_2013_ORGANIC_SOILS_TONNES_N2O-N_HECTARE_SAGO_PALM",
+        "IPCC_2013_ORGANIC_SOILS_TONNES_N2O-N_HECTARE_PADDY_RICE_CULTIVATION",
+        "IPCC_2013_ORGANIC_SOILS_TONNES_N2O-N_HECTARE_GRASSLAND",
+        "IPCC_2013_ORGANIC_SOILS_TONNES_N2O-N_HECTARE_OTHER"
+    ]
+}
+RETURNS = {
+    "Emission": [{
+        "value": "",
+        "sd": "",
+        "statsDefinition": "modelled",
+        "methodTier": "tier 1"
+    }]
+}
+TERM_ID = 'n2OToAirOrganicSoilCultivationDirect'
+TIER = EmissionMethodTier.TIER_1.value
+
+_STATS_DEFINITION = EmissionStatsDefinition.MODELLED.value
+
+_CATEGORY_REMAPPER = {
+    OrganicSoilCategory.ACACIA: OrganicSoilCategory.PERENNIAL_CROPS
+}
+
+
+def _emission(value: float, sd: float):
+    emission = _new_emission(TERM_ID, MODEL)
+    emission['value'] = [value]
+    emission['sd'] = [sd]
+    emission['statsDefinition'] = _STATS_DEFINITION
+    emission['methodTier'] = TIER
+    return emission
+
+
+def sample_emission_factor(
+    eco_climate_zone: EcoClimateZone,
+    organic_soil_category: OrganicSoilCategory,
+) -> tuple[float, float]:
+    category = remap_categories(organic_soil_category, _CATEGORY_REMAPPER)  # fewer categories than CO2 model
+    factor_data = get_emission_factor(TERM_ID, eco_climate_zone, category)
+    mean = factor_data.get("value", 0)
+    sd = factor_data.get("sd", 0)
+    return mean, sd
+
+
+def _should_run(cycle: dict):
+    end_date = cycle.get('endDate')
+    site = cycle.get('site', {})
+    measurements = site.get('measurements', [])
+
+    def _get_measurement_content(term_id: str):
+        return most_relevant_measurement_value(measurements, term_id, end_date)
+
+    histosol = _get_measurement_content('histosol')
+    eco_climate_zone = get_eco_climate_zone_value(cycle, as_enum=True)
+    organic_soil_category = assign_organic_soil_category(cycle, log_id=TERM_ID)
+
+    emission_factor_mean, emission_factor_sd = (
+        sample_emission_factor(eco_climate_zone, organic_soil_category)
+        if eco_climate_zone
+        else (None, None)
+    )
+
+    land_occupation = land_occupation_per_ha(MODEL, TERM_ID, cycle)
+
+    logRequirements(
+        cycle, model=MODEL, term=TERM_ID,
+        eco_climate_zone=eco_climate_zone,
+        organic_soil_category=organic_soil_category,
+        emission_factor=f"{emission_factor_mean} ± {emission_factor_sd}",
+        land_occupation=land_occupation,
+        histosol=histosol
+    )
+
+    should_run = all([
+        valid_site_type(site),
+        valid_eco_climate_zone(eco_climate_zone),
+        all(
+            var is not None for var in [
+                emission_factor_mean,
+                emission_factor_sd,
+                land_occupation,
+                histosol
+            ]
+        )
+    ])
+
+    logShouldRun(cycle, MODEL, TERM_ID, should_run, methodTier=TIER)
+
+    return should_run, emission_factor_mean, emission_factor_sd, histosol, land_occupation
+
+
+def _run(emission_factor_mean: float, emission_factor_sd: float, histosol: float, land_occupation: float):
+    value = calc_emission(TERM_ID, emission_factor_mean, histosol, land_occupation)
+    sd = calc_emission(TERM_ID, emission_factor_sd, histosol, land_occupation)
+    return [_emission(value, sd)]
+
+
+def run(cycle: dict):
+    should_run, emission_factor_mean, emission_factor_sd, histosol, land_occupation = _should_run(cycle)
+    return _run(emission_factor_mean, emission_factor_sd, histosol, land_occupation) if should_run else []

hestia_earth/models/ipcc2019/nonCo2EmissionsToAirNaturalVegetationBurning.py

@@ -156,8 +156,6 @@ _Inventory = dict[int, _InventoryYear]
 {year (int): data (_InventoryYear)}
 """
 
-_EmissionInventory = dict[_EmissionTermId, npt.NDArray]
-
 
 _BIOMASS_CATEGORY_TO_FUEL_CATEGORY = {
     BiomassCategory.FOREST: {
@@ -518,9 +516,9 @@ def _sum_cycle_emissions(term_id: _EmissionTermId, cycle_id: str, inventory: _In
     return reduce(add_cycle_emissions, inventory.keys(), np.array(0))
 
 
-def _compile_run_data(
+def _compile_inventory(
     cycle: dict, site: dict, land_cover_nodes: list[dict], eco_climate_zone: EcoClimateZone
-) -> tuple[_EmissionInventory, _Inventory, dict]:
+):
     """
     Compile the run data for the model, collating data from `site.management` and related cycles. An annualised
     inventory of land cover change and natural vegetation burning events is constructed. Emissions from burning events
@@ -539,18 +537,12 @@ def _compile_run_data(
 
     Returns
     -------
-    emission_inventory : _EmissionInventory
-        A dictionary of emissions relevant to the cycle the model is run on, in the format:
-        ```
-        {
-            emission_term_id (str): value (NDArray),
-            ...
-        }
-        ```
+    should_run : bool
+        Whether the model should be run.
     inventory : _Inventory
-        An inventory of model data
+        An inventory of model data.
     logs : dict
-        Data from the compilation process that should be logged.
+        Data about the inventory compilation to be logged.
     """
     cycle_id = cycle.get("@id")
     related_cycles_ = related_cycles(site, cycles_mapping={cycle_id: cycle})
@@ -586,9 +578,15 @@ def _compile_run_data(
         Returns
         -------
         inventory : dict
-            An inventory of model data, updated to include the new model year.
+            An inventory of model data, updated to include the input year.
         """
-        land_cover_nodes = next((nodes for year_, nodes in land_cover_grouped.items() if year_ >= year), [])  # Backfill
+        land_cover_nodes = land_cover_grouped.get(
+            next(
+                (k for k in sorted(land_cover_grouped) if k >= year),  # backfill if possible
+                min(land_cover_grouped, key=lambda k: abs(k - year))   # else forward-fill
+            ),
+            []
+        )
 
         biomass_category_summary = summarise_land_cover_nodes(land_cover_nodes)
         prev_biomass_category_summary = inventory.get(year-1, {}).get("biomass_category_summary", {})
@@ -656,17 +654,17 @@ def _compile_run_data(
 
     inventory = reduce(build_inventory_year, range(min_year, max_year+1), dict())
 
-    emission_inventory = {
-        term_id: value for term_id in EMISSION_TERM_IDS
-        if np.all((value := _sum_cycle_emissions(term_id, cycle_id, inventory)) > 0)
-    }
+    n_land_cover_years = len(land_cover_grouped)
 
     logs = {
+        "n_land_cover_years": n_land_cover_years,
         "percent_burned": percent_burned,
         "seed": seed,
     }
 
-    return emission_inventory, inventory, logs
+    should_run = bool(inventory and n_land_cover_years > 1)
+
+    return should_run, inventory, logs
 
 
 def _format_bool(value: Optional[bool]) -> str:
@@ -831,23 +829,16 @@ def _format_inventory(term_id: _EmissionTermId, cycle_id: str, inventory: dict)
     ) if inventory else "None"
 
 
-def _should_run_emission(
-    term_id: _EmissionTermId, cycle: dict, emission_inventory: _EmissionInventory, inventory: dict, logs: dict
-):
+def _log_emission_data(should_run: bool, term_id: _EmissionTermId, cycle: dict, inventory: dict, logs: dict):
     """
-    Determine, based on the compiled data, whether the model should run for a specifc emission term id. Format and log
-    the model logs and inventory.
+    Format and log the model logs and inventory.
     """
-    should_run = term_id in emission_inventory
-
     formatted_logs = _format_logs(logs)
     formatted_inventory = _format_inventory(term_id, cycle.get("@id"), inventory)
 
     logRequirements(cycle, model=MODEL, term=term_id, **formatted_logs, inventory=formatted_inventory)
     logShouldRun(cycle, MODEL, term_id, should_run)
 
-    return should_run
-
 
 def _should_run(cycle: dict):
     """
@@ -861,8 +852,8 @@ def _should_run(cycle: dict):
 
     Returns
     -------
-    tuple[bool, dict]
-        should_run, emission_inventory
+    tuple[bool, _Inventory]
+        should_run, inventory
     """
     site = _get_site(cycle)
 
@@ -873,7 +864,7 @@ def _should_run(cycle: dict):
 
     has_valid_site_type = all([site_type, site_type not in _EXCLUDED_SITE_TYPES])
     has_valid_eco_climate_zone = all([eco_climate_zone, eco_climate_zone not in _EXCLUDED_ECO_CLIMATE_ZONES])
-    has_land_cover_nodes = len(land_cover_nodes) > 0
+    has_land_cover_nodes = len(land_cover_nodes) > 1
 
     should_compile_inventory = all([
         has_valid_site_type,
@@ -881,9 +872,9 @@ def _should_run(cycle: dict):
         has_land_cover_nodes
     ])
 
-    emission_inventory, inventory, compilation_logs = (
-        _compile_run_data(cycle, site, land_cover_nodes, eco_climate_zone)
-        if should_compile_inventory else ({}, {}, {})
+    should_run, inventory, compilation_logs = (
+        _compile_inventory(cycle, site, land_cover_nodes, eco_climate_zone)
+        if should_compile_inventory else (False, {}, {})
     )
 
     logs = {
@@ -897,21 +888,18 @@ def _should_run(cycle: dict):
         **compilation_logs
     }
 
-    should_run = all([
-        any([
-            _should_run_emission(term_id, cycle, emission_inventory, inventory, logs) for term_id in EMISSION_TERM_IDS
-        ])
-    ])
+    for term_id in EMISSION_TERM_IDS:
+        _log_emission_data(should_run, term_id, cycle, inventory, logs)
 
-    return should_run, emission_inventory
+    return should_run, inventory
 
 
-def _run_emission(term_id: _EmissionTermId, emissions: dict[_EmissionTermId, npt.NDArray]) -> list[dict]:
+def _run_emission(term_id: _EmissionTermId, cycle_id: str, inventory: _Inventory) -> list[dict]:
     """
-    Retrieve the pre-computed emissions and format them as a HESTIA
+    Retrieve the sum relevant emissions and format them as a HESTIA
     [Emission node](https://www.hestia.earth/schema/Emission).
     """
-    emission = emissions[term_id]
+    emission = _sum_cycle_emissions(term_id, cycle_id, inventory)
     descriptive_stats = calc_descriptive_stats(emission, STATS_DEFINITION, decimals=3)
     return _emission(term_id, **descriptive_stats)
 
@@ -932,5 +920,5 @@ def run(cycle: dict):
         `ch4ToAirNaturalVegetationBurning` **OR** `coToAirNaturalVegetationBurning` **OR**
         `n2OToAirNaturalVegetationBurningDirect` **OR** `noxToAirNaturalVegetationBurning`.
     """
-    should_run, emission_inventory = _should_run(cycle)
-    return [_run_emission(term_id, emission_inventory) for term_id in emission_inventory] if should_run else []
+    should_run, inventory = _should_run(cycle)
+    return [_run_emission(term_id, cycle.get("@id"), inventory) for term_id in EMISSION_TERM_IDS] if should_run else []

hestia_earth/models/ipcc2019/organicCarbonPerHa_tier_1.py

@@ -31,6 +31,77 @@ from .organicCarbonPerHa_utils import (
 )
 from . import MODEL
 
+REQUIREMENTS = {
+    "Site": {
+        "management": [
+            {"@type": "Management", "value": "", "term.termType": "landCover"}
+        ],
+        "measurements": [
+            {
+                "@type": "Measurement",
+                "value": ["1", "2", "3", "4", "7", "8", "9", "10", "11", "12"],
+                "term.@id": "ecoClimateZone"
+            }
+        ],
+        "optional": {
+            "measurements": [
+                {"@type": "Measurement", "value": "", "term.termType": ["soilType", "usdaSoilType"]}
+            ],
+            "management": [
+                {
+                    "@type": "Management",
+                    "value": "",
+                    "startDate": "",
+                    "endDate": "",
+                    "term.termType": "cropResidueManagement",
+                    "name": ["burnt", "removed"]
+                },
+                {
+                    "@type": "Management",
+                    "value": "",
+                    "startDate": "",
+                    "endDate": "",
+                    "term.termType": "landUseManagement"
+                },
+                {"@type": "Management", "value": "", "startDate": "", "endDate": "", "term.termType": "tillage"},
+                {
+                    "@type": "Management",
+                    "value": "",
+                    "startDate": "",
+                    "endDate": "",
+                    "term.termType": "waterRegime",
+                    "name": ["deep water", "irrigated"]
+                },
+                {
+                    "@type": "Management",
+                    "value": "",
+                    "startDate": "",
+                    "endDate": "",
+                    "term.@id": "amendmentIncreasingSoilCarbonUsed"
+                },
+                {"@type": "Management", "value": "", "startDate": "", "endDate": "", "term.@id": "animalManureUsed"},
+                {
+                    "@type": "Management",
+                    "value": "",
+                    "startDate": "",
+                    "endDate": "",
+                    "term.@id": "inorganicNitrogenFertiliserUsed"
+                },
+                {
+                    "@type": "Management",
+                    "value": "",
+                    "startDate": "",
+                    "endDate": "",
+                    "term.@id": "organicFertiliserUsed"
+                },
+                {"@type": "Management", "value": "", "startDate": "", "endDate": "", "term.@id": "shortBareFallow"}
+            ]
+        },
+        "none": {
+            "siteType": ["glass or high accessible cover"]
+        }
+    }
+}
 LOOKUPS = {
     "crop": "IPCC_LAND_USE_CATEGORY",
     "landCover": [
@@ -43,6 +114,20 @@ LOOKUPS = {
     "tillage": "IPCC_TILLAGE_MANAGEMENT_CATEGORY",
     "usdaSoilType": "IPCC_SOIL_CATEGORY"
 }
+RETURNS = {
+    "Measurement": [{
+        "value": "",
+        "sd": "",
+        "min": "",
+        "max": "",
+        "statsDefinition": "simulated",
+        "observations": "",
+        "dates": "",
+        "depthUpper": "0",
+        "depthLower": "30",
+        "methodClassification": "tier 1 model"
+    }]
+}
 
 TERM_ID = 'organicCarbonPerHa'
 _METHOD_CLASSIFICATION = MeasurementMethodClassification.TIER_1_MODEL.value
@@ -108,7 +193,7 @@ def _measurement(
     dict
         A valid HESTIA `Measurement` node, see: https://www.hestia.earth/schema/Measurement.
     """
-    measurement = _new_measurement(TERM_ID) | descriptive_stats_dict
+    measurement = _new_measurement(TERM_ID, MODEL) | descriptive_stats_dict
     measurement["dates"] = [f"{year}-12-31" for year in timestamps]
     measurement["depthUpper"] = DEPTH_UPPER
     measurement["depthLower"] = DEPTH_LOWER

hestia_earth/models/ipcc2019/organicCarbonPerHa_tier_2.py

@@ -33,11 +33,137 @@ from .organicCarbonPerHa_utils import (
 )
 from . import MODEL
 
+REQUIREMENTS = {
+    "Site": {
+        "siteType": "cropland",
+        "measurements": [
+            {
+                "@type": "Measurement",
+                "term.@id": "sandContent",
+                "value": "",
+                "depthUpper": "0",
+                "depthLower": "30",
+                "optional": {
+                    "dates": ""
+                }
+            },
+            {
+                "@type": "Measurement",
+                "term.@id": "temperatureMonthly",
+                "value": "",
+                "dates": ""
+            },
+            {
+                "@type": "Measurement",
+                "term.@id": "precipitationMonthly",
+                "value": "",
+                "dates": ""
+            },
+            {
+                "@type": "Measurement",
+                "term.@id": "potentialEvapotranspirationMonthly",
+                "value": "",
+                "dates": ""
+            }
+        ],
+        "related": {
+            "Cycle": [{
+                "endDate": "",
+                "products": [
+                    {
+                        "@type": "Product",
+                        "term.@id": [
+                            "aboveGroundCropResidueLeftOnField",
+                            "aboveGroundCropResidueIncorporated",
+                            "belowGroundCropResidue",
+                            "discardedCropLeftOnField",
+                            "discardedCropIncorporated"
+                        ],
+                        "value": "",
+                        "properties": [
+                            {
+                                "@type": "Property",
+                                "term.@id": "carbonContent",
+                                "value": ""
+                            },
+                            {
+                                "@type": "Property",
+                                "term.@id": "nitrogenContent",
+                                "value": ""
+                            },
+                            {
+                                "@type": "Property",
+                                "term.@id": "ligninContent",
+                                "value": ""
+                            }
+                        ]
+                    }
+                ],
+                "inputs": [
+                    {
+                        "@type": "Input",
+                        "term.termType": ["organicFertiliser", "soilAmendment"],
+                        "value": "",
+                        "properties": [
+                            {
+                                "@type": "Property",
+                                "term.@id": "carbonContent",
+                                "value": ""
+                            },
+                            {
+                                "@type": "Property",
+                                "term.@id": "nitrogenContent",
+                                "value": ""
+                            },
+                            {
+                                "@type": "Property",
+                                "term.@id": "ligninContent",
+                                "value": ""
+                            }
+                        ]
+                    }
+                ],
+                "practices": [
+                    {
+                        "@type": "Practice",
+                        "term.termType": "tillage",
+                        "value": ""
+                    },
+                    {
+                        "@type": "Practice",
+                        "term.termType": "waterRegime",
+                        "name": "irrigated",
+                        "value": "",
+                        "startDate": "",
+                        "endDate": ""
+                    }
+                ],
+                "optional": {
+                    "startDate": ""
+                }
+            }]
+        }
+    }
+}
 LOOKUPS = {
     "crop": "IPCC_LAND_USE_CATEGORY",
     "landCover": "IPCC_LAND_USE_CATEGORY",
     "tillage": "IPCC_TILLAGE_MANAGEMENT_CATEGORY"
 }
+RETURNS = {
+    "Measurement": [{
+        "value": "",
+        "sd": "",
+        "min": "",
+        "max": "",
+        "statsDefinition": "simulated",
+        "observations": "",
+        "dates": "",
+        "depthUpper": "0",
+        "depthLower": "30",
+        "methodClassification": "tier 2 model"
+    }]
+}
 
 TERM_ID = 'organicCarbonPerHa'
 _METHOD_CLASSIFICATION = MeasurementMethodClassification.TIER_2_MODEL.value
@@ -124,7 +250,7 @@ def _measurement(
     dict
         A valid HESTIA `Measurement` node, see: https://www.hestia.earth/schema/Measurement.
     """
-    measurement = _new_measurement(TERM_ID) | descriptive_stats_dict
+    measurement = _new_measurement(TERM_ID, MODEL) | descriptive_stats_dict
     measurement["dates"] = [f"{year}-12-31" for year in timestamps]
     measurement["depthUpper"] = DEPTH_UPPER
     measurement["depthLower"] = DEPTH_LOWER

hestia_earth/models/ipcc2019/organicCarbonPerHa_utils.py

@@ -1,13 +1,15 @@
 from enum import Enum
+from numpy import inf
 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
+    repeat_single, truncated_normal_1d
 )
 from hestia_earth.models.utils.blank_node import cumulative_nodes_term_match, node_term_match
+from hestia_earth.models.utils.stats import calc_z_critical
 from hestia_earth.models.utils.term import get_cover_crop_property_terms, get_irrigated_terms
 
 STATS_DEFINITION = MeasurementStatsDefinition.SIMULATED.value
@@ -238,7 +240,9 @@ 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)
+    n_sds = calc_z_critical(95)
+    sigma = (value * (uncertainty / 100)) / n_sds
+    return truncated_normal_1d(shape=(1, iterations), mu=value, sigma=sigma, low=0, high=inf, seed=seed)
 
 
 def sample_plus_minus_error(
@@ -246,9 +250,7 @@ def sample_plus_minus_error(
 ) -> 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)
+    return truncated_normal_1d(shape=(1, iterations), mu=value, sigma=sd, low=0, high=inf, seed=seed)
 
 
 def sample_constant(*, iterations: int, value: float, **_) -> NDArray: