hestia-earth-models 0.64.1__py3-none-any.whl → 0.64.3__py3-none-any.whl

hestia_earth/models/ipcc2019/aboveGroundBiomass_utils.py

@@ -0,0 +1,180 @@
+from enum import Enum
+from numpy import random
+from numpy.typing import NDArray
+from typing import Callable, Optional, Union
+
+from hestia_earth.models.utils.array_builders import repeat_single, truncated_normal_1d
+from hestia_earth.models.utils.ecoClimateZone import EcoClimateZone, get_ecoClimateZone_lookup_grouped_value
+
+
+class BiomassCategory(Enum):
+    """
+    Enum representing biomass categories, sourced from IPCC (2006), IPCC (2019) and European Commission (2010).
+
+    Enum values formatted for logging as table.
+    """
+    ANNUAL_CROPS = "annual-crops"
+    COCONUT = "coconut"                                             # European Commission (2010)
+    FOREST = "forest"                                               # IPCC (2019) recalculated per eco-climate zone
+    GRASSLAND = "grassland"
+    JATROPHA = "jatropha"                                           # European Commission (2010)
+    JOJOBA = "jojoba"                                               # European Commission (2010)
+    NATURAL_FOREST = "natural-forest"                               # IPCC (2019) recalculated per eco-climate zone
+    OIL_PALM = "oil palm"                                           # IPCC (2019)
+    OLIVE = "olive"                                                 # IPCC (2019)
+    ORCHARD = "orchard"                                             # IPCC (2019)
+    OTHER = "other"
+    PLANTATION_FOREST = "plantation-forest"                         # IPCC (2019) recalculated per eco-climate zone
+    RUBBER = "rubber"                                               # IPCC (2019)
+    SHORT_ROTATION_COPPICE = "short-rotation-coppice"               # IPCC (2019)
+    TEA = "tea"                                                     # IPCC (2019)
+    VINE = "vine"                                                   # IPCC (2019)
+    WOODY_PERENNIAL = "woody-perennial"                             # IPCC (2006)
+
+
+BIOMASS_CATEGORY_TO_LAND_COVER_LOOKUP_VALUE = {
+    BiomassCategory.ANNUAL_CROPS: "Annual crops",
+    BiomassCategory.COCONUT: "Coconut",
+    BiomassCategory.FOREST: "Forest",
+    BiomassCategory.GRASSLAND: "Grassland",
+    BiomassCategory.JATROPHA: "Jatropha",
+    BiomassCategory.JOJOBA: "Jojoba",
+    BiomassCategory.NATURAL_FOREST: "Natural forest",
+    BiomassCategory.OIL_PALM: "Oil palm",
+    BiomassCategory.OLIVE: "Olive",
+    BiomassCategory.ORCHARD: "Orchard",
+    BiomassCategory.OTHER: "Other",
+    BiomassCategory.PLANTATION_FOREST: "Plantation forest",
+    BiomassCategory.RUBBER: "Rubber",
+    BiomassCategory.SHORT_ROTATION_COPPICE: "Short rotation coppice",
+    BiomassCategory.TEA: "Tea",
+    BiomassCategory.VINE: "Vine",
+    BiomassCategory.WOODY_PERENNIAL: "Woody perennial"
+}
+
+
+def assign_biomass_category(lookup_value: str) -> BiomassCategory:
+    """
+    Return the `BiomassCategory` enum member associated with the input lookup value. If lookup value is missing or
+    doesn't map to any category, return `None`.
+    """
+    return next(
+        (key for key, value in BIOMASS_CATEGORY_TO_LAND_COVER_LOOKUP_VALUE.items() if value == lookup_value),
+        None
+    )
+
+
+def sample_biomass_equilibrium(
+    iterations: int,
+    biomass_category: BiomassCategory,
+    eco_climate_zone: EcoClimateZone,
+    seed: Union[int, random.Generator, None] = None
+) -> dict:
+    """
+    Sample a biomass equilibrium using the function specified in `KWARGS_TO_SAMPLE_FUNC`.
+
+    Parameters
+    ----------
+    iterations : int
+        The number of samples to take.
+    biomass_category : BiomassCategory
+        The biomass category of the land cover.
+    eco_climate_zone : EcoClimateZone
+        The eco-climate zone of the site.
+    seed : int | Generator | None, optional
+        A seed to initialize the BitGenerator. If passed a Generator, it will be returned unaltered. If `None`, then
+        fresh, unpredictable entropy will be pulled from the OS.
+
+    Returns
+    -------
+    NDArray
+        The sampled parameter as a numpy array with shape `(1, iterations)`.
+    """
+    kwargs = _get_biomass_equilibrium(biomass_category, eco_climate_zone)
+    func = _get_sample_func(kwargs)
+    return func(iterations=iterations, seed=seed, **kwargs)
+
+
+def _get_biomass_equilibrium(biomass_category: BiomassCategory, eco_climate_zone: EcoClimateZone) -> dict:
+    """
+    Retrieve the biomass equilibrium data for a specific combination of biomass category and eco-climate zone.
+
+    Parameters
+    ----------
+    biomass_category : BiomassCategory
+        The biomass category of the land cover.
+    eco_climate_zone : EcoClimateZone
+        The eco-climate zone of the site.
+
+    Returns
+    -------
+    dict
+        The biomass equilibrium data.
+    """
+    return get_ecoClimateZone_lookup_grouped_value(
+        eco_climate_zone.value,
+        _build_col_name(biomass_category),
+        default={"value": 0}
+    )
+
+
+def _build_col_name(biomass_category: BiomassCategory) -> str:
+    """
+    Get the column name for the `ecoClimateZone-lookup.csv` for a specific biomass category equilibrium.
+    """
+    COL_NAME_ROOT = "AG_BIOMASS_EQUILIBRIUM_KG_C_HECTARE_"
+    return (
+        f"{COL_NAME_ROOT}{biomass_category.name}" if isinstance(biomass_category, BiomassCategory)
+        else f"{COL_NAME_ROOT}OTHER"
+    )
+
+
+def _get_sample_func(kwargs: dict) -> Callable:
+    """
+    Select the correct sample function for a parameter based on the distribution data available. All possible
+    parameters for the model should have, at a minimum, a `value`, meaning that no default function needs to be
+    specified.
+
+    This function has been extracted into it's own method to allow for mocking of sample function.
+
+    Keyword Args
+    ------------
+    value : float
+        The distribution mean.
+    sd : float
+        The standard deviation of the distribution.
+    uncertainty : float
+        The +/- uncertainty of the 95% confidence interval expressed as a percentage of the mean.
+    error : float
+        Two standard deviations expressed as a percentage of the mean.
+
+    Returns
+    -------
+    Callable
+        The sample function for the distribution.
+    """
+    return next(
+        sample_func for required_kwargs, sample_func in _KWARGS_TO_SAMPLE_FUNC.items()
+        if all(kwarg in kwargs.keys() for kwarg in required_kwargs)
+    )
+
+
+def sample_plus_minus_error(
+    *, iterations: int, value: float, error: float, seed: Optional[int] = None, **_
+) -> NDArray:
+    """Randomly sample a model parameter with a truncated normal distribution described using plus/minus error."""
+    sd = value * (error / 200)
+    low = value - (value * (error / 100))
+    high = value + (value * (error / 100))
+    return truncated_normal_1d(shape=(1, iterations), mu=value, sigma=sd, low=low, high=high, seed=seed)
+
+
+def sample_constant(*, iterations: int, value: float, **_) -> NDArray:
+    """Sample a constant model parameter."""
+    return repeat_single(shape=(1, iterations), value=value)
+
+
+_KWARGS_TO_SAMPLE_FUNC = {
+    ("value", "error"): sample_plus_minus_error,
+    ("value",): sample_constant
+}

hestia_earth/models/ipcc2019/animal/liveweightGain.py

@@ -0,0 +1,88 @@
+from hestia_earth.schema import TermTermType
+from hestia_earth.utils.model import filter_list_term_type
+
+from hestia_earth.models.log import logRequirements, logShouldRun
+from hestia_earth.models.utils.blank_node import merge_blank_nodes
+from hestia_earth.models.utils.property import _new_property, node_has_no_property
+from .utils import productivity_lookup_value
+from .. import MODEL
+
+REQUIREMENTS = {
+    "Cycle": {
+        "site": {
+            "@type": "Site",
+            "country": {"@type": "Term", "termType": "region"}
+        },
+        "animals": [{
+            "@type": "Animal",
+            "term.termType": "liveAnimal",
+            "none": {
+                "properties": [{
+                    "@type": "Property",
+                    "value": "",
+                    "term.@id": "liveweightGain"
+                }]
+            }
+        }]
+    }
+}
+LOOKUPS = {
+    "region-liveAnimal-liveweightGain": "liveweight gain"
+}
+RETURNS = {
+    "Animal": [{
+        "properties": [{
+            "@type": "Property",
+            "value": ""
+        }]
+    }]
+}
+TERM_ID = 'liveweightGain'
+
+
+def _property(value: float):
+    prop = _new_property(TERM_ID, MODEL)
+    prop['value'] = value
+    return prop
+
+
+def _run_animal(data: dict):
+    animal = data.get('animal')
+    value = data.get('value')
+    return animal | {
+        'properties': merge_blank_nodes(animal.get('properties', []), [_property(value)])
+    }
+
+
+def _should_run(cycle: dict):
+    country = cycle.get('site', {}).get('country', {})
+    country_id = country.get('@id')
+    live_animals = filter_list_term_type(cycle.get('animals', []), TermTermType.LIVEANIMAL)
+    live_animals = list(filter(node_has_no_property(TERM_ID), live_animals))
+    live_animals_with_value = [{
+        'animal': animal,
+        'value': productivity_lookup_value(TERM_ID, list(LOOKUPS.keys())[0], country, animal)
+    } for animal in live_animals]
+
+    def _should_run_animal(value: dict):
+        lookup_value = value.get('value')
+        term_id = value.get('animal').get('term').get('@id')
+
+        logRequirements(cycle, model=MODEL, term=term_id,
+                        country_id=country_id,
+                        liveweightGain=lookup_value)
+
+        should_run = all([
+            country_id,
+            lookup_value is not None
+        ])
+        logShouldRun(cycle, MODEL, term_id, should_run)
+
+        return should_run
+
+    return list(filter(_should_run_animal, live_animals_with_value))
+
+
+def run(cycle: dict):
+    animals = _should_run(cycle)
+    return list(map(_run_animal, animals))

hestia_earth/models/ipcc2019/animal/liveweightPerHead.py

@@ -0,0 +1,88 @@
+from hestia_earth.schema import TermTermType
+from hestia_earth.utils.model import filter_list_term_type
+
+from hestia_earth.models.log import logRequirements, logShouldRun
+from hestia_earth.models.utils.blank_node import merge_blank_nodes
+from hestia_earth.models.utils.property import _new_property, node_has_no_property
+from .utils import productivity_lookup_value
+from .. import MODEL
+
+REQUIREMENTS = {
+    "Cycle": {
+        "site": {
+            "@type": "Site",
+            "country": {"@type": "Term", "termType": "region"}
+        },
+        "animals": [{
+            "@type": "Animal",
+            "term.termType": "liveAnimal",
+            "none": {
+                "properties": [{
+                    "@type": "Property",
+                    "value": "",
+                    "term.@id": "liveweightPerHead"
+                }]
+            }
+        }]
+    }
+}
+LOOKUPS = {
+    "region-liveAnimal-liveweightPerHead": "liveweight per head"
+}
+RETURNS = {
+    "Animal": [{
+        "properties": [{
+            "@type": "Property",
+            "value": ""
+        }]
+    }]
+}
+TERM_ID = 'liveweightPerHead'
+
+
+def _property(value: float):
+    prop = _new_property(TERM_ID, MODEL)
+    prop['value'] = value
+    return prop
+
+
+def _run_animal(data: dict):
+    animal = data.get('animal')
+    value = data.get('value')
+    return animal | {
+        'properties': merge_blank_nodes(animal.get('properties', []), [_property(value)])
+    }
+
+
+def _should_run(cycle: dict):
+    country = cycle.get('site', {}).get('country', {})
+    country_id = country.get('@id')
+    live_animals = filter_list_term_type(cycle.get('animals', []), TermTermType.LIVEANIMAL)
+    live_animals = list(filter(node_has_no_property(TERM_ID), live_animals))
+    live_animals_with_value = [{
+        'animal': animal,
+        'value': productivity_lookup_value(TERM_ID, list(LOOKUPS.keys())[0], country, animal)
+    } for animal in live_animals]
+
+    def _should_run_animal(value: dict):
+        lookup_value = value.get('value')
+        term_id = value.get('animal').get('term').get('@id')
+
+        logRequirements(cycle, model=MODEL, term=term_id,
+                        country_id=country_id,
+                        liveweightPerHead=lookup_value)
+
+        should_run = all([
+            country_id,
+            lookup_value is not None
+        ])
+        logShouldRun(cycle, MODEL, term_id, should_run)
+
+        return should_run
+
+    return list(filter(_should_run_animal, live_animals_with_value))
+
+
+def run(cycle: dict):
+    animals = _should_run(cycle)
+    return list(map(_run_animal, animals))

hestia_earth/models/ipcc2019/animal/pastureGrass.py

@@ -10,10 +10,10 @@ This version of the model will run at the Animal Blank Node level, if none of th
 """
 from hestia_earth.schema import TermTermType
 from hestia_earth.utils.model import filter_list_term_type
-from hestia_earth.utils.tools import list_sum
+from hestia_earth.utils.tools import list_sum, non_empty_list
 
 from hestia_earth.models.log import logRequirements, logShouldRun, debugValues, log_as_table
-from hestia_earth.models.utils.blank_node import lookups_logs, properties_logs
+from hestia_earth.models.utils.blank_node import lookups_logs, properties_logs, merge_blank_nodes
 from hestia_earth.models.utils.input import _new_input
 from hestia_earth.models.utils.term import get_wool_terms, get_lookup_value
 from hestia_earth.models.utils.completeness import _is_term_type_complete, _is_term_type_incomplete
@@ -42,15 +42,22 @@ REQUIREMENTS = {
             "@type": "Site",
             "siteType": "permanent pasture"
         },
-        "practices": [{
-            "@type": "Practice",
-            "value": "",
-            "term.@id": "pastureGrass",
-            "key": {
-                "@type": "Term",
-                "term.termType": "landCover"
+        "practices": [
+            {
+                "@type": "Practice",
+                "value": "",
+                "term.termType": "system"
+            },
+            {
+                "@type": "Practice",
+                "value": "",
+                "term.@id": "pastureGrass",
+                "key": {
+                    "@type": "Term",
+                    "term.termType": "landCover"
+                }
             }
-        }],
+        ],
         "animals": [{
             "@type": "Animal",
             "value": "> 0",
@@ -140,7 +147,8 @@ RETURNS = {
         "inputs": [{
             "@type": "Input",
             "term.termType": ["crop", "forage"],
-            "value": ""
+            "value": "",
+            "isAnimalFeed": "True"
         }]
     }]
 }
@@ -150,6 +158,7 @@ MODEL_KEY = 'pastureGrass'
 def _input(term_id: str, value: float):
     node = _new_input(term_id, MODEL)
     node['value'] = [value]
+    node['isAnimalFeed'] = True
     return node
 
 
@@ -187,10 +196,9 @@ def calculate_NEwool(cycle: dict, animal: dict, products: list, total_weight: fl
     return total_energy * animal_weight/total_weight
 
 
-def _run_practice(
-    animal: dict, values: dict, meanDE: float, meanECHHV: float, REM: float, REG: float,
-    NEwool: float, NEm_feed: float, NEg_feed: float
-):
+def _run_practice(animal: dict, values: dict, meanDE: float, meanECHHV: float, REM: float, REG: float, NEwool: float):
+    NEm_feed, NEg_feed, log_feed = calculate_NEfeed(animal)
+
     def run(practice: dict):
         key = practice.get('key', {})
         key_id = key.get('@id')
@@ -202,18 +210,15 @@ def _run_practice(
 
         value = (GE / meanECHHV) * (list_sum(practice.get('value', [0])) / 100)
 
-        logs = log_as_table(values | {
-            'animalId': animal.get('term', {}).get('@id'),
-            'practiceKeyId': key_id,
-            'GE': GE,
-            'NEmFeed': NEm_feed,
-            'NEgFeed': NEg_feed,
-            'REM': REM,
-            'REG': REG,
+        logs = log_as_table([{
+            'id': animal.get('term', {}).get('@id')
+        } | values | {
             'NEwool': NEwool,
-            'meanECHHV': meanECHHV,
-            'meanDE': meanDE
-        })
+            'total-feed-NEm': NEm_feed,
+            'total-feed-NEg': NEg_feed,
+            'practiceKeyId': key_id,
+            'GE': GE
+        }])
         animal_lookups = lookups_logs(MODEL, [animal], LOOKUPS, model_key=MODEL_KEY, term=input_term_id)
         animal_properties = properties_logs([animal], properties=[
             'liveweightPerHead',
@@ -226,23 +231,24 @@ def _run_practice(
             'weightAtOneYear',
             'weightAtSlaughter'
         ])
+        has_positive_feed_values = all([NEm_feed > 0, NEg_feed > 0])
 
         logRequirements(animal, model=MODEL, term=input_term_id, model_key=MODEL_KEY,
+                        feed_logs=log_as_table(log_feed),
+                        has_positive_feed_values=has_positive_feed_values,
                         animal_logs=logs,
                         animal_lookups=animal_lookups,
                         animal_properties=animal_properties)
 
-        logShouldRun(animal, MODEL, input_term_id, True, model_key=MODEL_KEY)
+        should_run = all([has_positive_feed_values])
+        logShouldRun(animal, MODEL, input_term_id, should_run, model_key=MODEL_KEY)
 
-        return _input(input_term_id, value)
+        return _input(input_term_id, value) if should_run else None
 
     return run
 
 
-def _run_animal(cycle: dict, meanDE: float, meanECHHV: float, system: dict, practices: list):
-    REM = calculate_REM(meanDE)
-    REG = calculate_REG(meanDE)
-
+def _run_animal(cycle: dict, meanDE: float, meanECHHV: float, REM: float, REG: float, systems: list, practices: list):
     wool_term_ids = get_wool_terms()
     # list of animal product
     wool_products = [p for p in cycle.get('products', []) if p.get('term', {}).get('@id') in wool_term_ids]
@@ -253,15 +259,14 @@ def _run_animal(cycle: dict, meanDE: float, meanECHHV: float, system: dict, prac
         NEwool = calculate_NEwool(cycle, animal, wool_products, total_liveWeightPerHead) if (
             total_liveWeightPerHead > 0
         ) else 0
-        NEm_feed, NEg_feed = calculate_NEfeed(animal)
-        animal_values = get_animal_values(cycle, animal, system)
+        animal_values = get_animal_values(cycle, animal, systems)
 
-        inputs = list(map(
-            _run_practice(animal, animal_values, meanDE, meanECHHV, REM, REG, NEwool, NEm_feed, NEg_feed),
+        inputs = non_empty_list(map(
+            _run_practice(animal, animal_values, meanDE, meanECHHV, REM, REG, NEwool),
             practices
         ))
         return animal | {
-            'inputs': animal.get('inputs', []) + inputs
+            'inputs': merge_blank_nodes(animal.get('inputs', []), inputs)
         }
 
     return run
@@ -278,6 +283,8 @@ def _should_run(cycle: dict, animals: list, practices: dict):
 
     meanDE = calculate_meanDE(practices)
     meanECHHV = calculate_meanECHHV(practices)
+    REM = calculate_REM(meanDE)
+    REG = calculate_REG(meanDE)
 
     should_run = all([
         animalFeed_complete,
@@ -299,16 +306,18 @@ def _should_run(cycle: dict, animals: list, practices: dict):
                             term_type_freshForage_incomplete=freshForage_incomplete,
                             no_cycle_inputs_feed=no_cycle_inputs_feed,
                             all_animals_have_value=all_animals_have_value,
-                            meanDE=calculate_meanDE(practices, term=term_id),
-                            meanECHHV=calculate_meanECHHV(practices, term=term_id))
+                            grass_MeanDE=calculate_meanDE(practices, term=term_id),
+                            grass_MeanECHHV=calculate_meanECHHV(practices, term=term_id),
+                            grass_REM=REM,
+                            grass_REG=REG)
 
             logShouldRun(animal, MODEL, term_id, should_run, model_key=MODEL_KEY)
 
-    return should_run, meanDE, meanECHHV, systems[0] if systems else None
+    return should_run, meanDE, meanECHHV, REM, REG, systems
 
 
 def run(cycle: dict):
     animals = get_animals_by_period(cycle)
     practices = list(filter(should_run_practice(cycle), cycle.get('practices', [])))
-    should_run, meanDE, meanECHHV, system = _should_run(cycle, animals, practices)
-    return list(map(_run_animal(cycle, meanDE, meanECHHV, system, practices), animals)) if should_run else []
+    should_run, meanDE, meanECHHV, REM, REG, systems = _should_run(cycle, animals, practices)
+    return list(map(_run_animal(cycle, meanDE, meanECHHV, REM, REG, systems, practices), animals)) if should_run else []

hestia_earth/models/ipcc2019/animal/utils.py

@@ -0,0 +1,20 @@
+from hestia_earth.utils.lookup import download_lookup, get_table_value, column_name, extract_grouped_data
+from hestia_earth.utils.tools import safe_parse_float
+
+from hestia_earth.models.log import debugMissingLookup
+from hestia_earth.models.utils.productivity import PRODUCTIVITY, get_productivity
+from .. import MODEL
+
+
+def productivity_lookup_value(term_id: str, lookup: str, country: dict, animal: dict):
+    country_id = country.get('@id')
+    productivity_key = get_productivity(country)
+    lookup_name = f"{lookup}.csv"
+    lookup = download_lookup(lookup_name)
+    column = column_name(animal.get('term').get('@id'))
+    value = get_table_value(lookup, 'termid', country_id, column)
+    debugMissingLookup(lookup_name, 'termid', country_id, column, value, model=MODEL, term=term_id)
+    return safe_parse_float(
+        extract_grouped_data(value, productivity_key.value) or
+        extract_grouped_data(value, PRODUCTIVITY.HIGH.value)  # defaults to high if low is not found
+    )

hestia_earth/models/ipcc2019/animal/weightAtMaturity.py

@@ -4,11 +4,11 @@ greater than or equal to `liveweightPerHead` value.
 """
 from hestia_earth.schema import TermTermType
 from hestia_earth.utils.model import filter_list_term_type, find_term_match
-from hestia_earth.utils.lookup import download_lookup, get_table_value, column_name
-from hestia_earth.utils.tools import safe_parse_float
 
-from hestia_earth.models.log import logRequirements, logShouldRun, debugMissingLookup
+from hestia_earth.models.log import logRequirements, logShouldRun
+from hestia_earth.models.utils.blank_node import merge_blank_nodes
 from hestia_earth.models.utils.property import _new_property, node_has_no_property
+from .utils import productivity_lookup_value
 from .. import MODEL
 
 REQUIREMENTS = {
@@ -61,24 +61,19 @@ def _run_animal(data: dict):
     animal = data.get('animal')
     value = data.get('value')
     return animal | {
-        'properties': animal.get('properties', []) + [_property(value)]
+        'properties': merge_blank_nodes(animal.get('properties', []), [_property(value)])
     }
 
 
-def _lookup_value(country_id: str, animal: dict):
-    lookup_name = f"{list(LOOKUPS.keys())[0]}.csv"
-    lookup = download_lookup(lookup_name)
-    column = column_name(animal.get('term').get('@id'))
-    value = get_table_value(lookup, 'termid', country_id, column)
-    debugMissingLookup(lookup_name, 'termid', country_id, column, value, model=MODEL, term=TERM_ID)
-    return safe_parse_float(value)
-
-
 def _should_run(cycle: dict):
-    country_id = cycle.get('site', {}).get('country', {}).get('@id')
+    country = cycle.get('site', {}).get('country', {})
+    country_id = country.get('@id')
     live_animals = filter_list_term_type(cycle.get('animals', []), TermTermType.LIVEANIMAL)
     live_animals = list(filter(node_has_no_property(TERM_ID), live_animals))
-    live_animals_with_value = [{'animal': a, 'value': _lookup_value(country_id, a)} for a in live_animals]
+    live_animals_with_value = [{
+        'animal': animal,
+        'value': productivity_lookup_value(TERM_ID, list(LOOKUPS.keys())[0], country, animal)
+    } for animal in live_animals]
 
     def _should_run_animal(value: dict):
         lookup_value = value.get('value')