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

hestia_earth/models/pooreNemecek2018/saplings.py

@@ -11,6 +11,7 @@ from .plantationLifespan import TERM_ID as PRACTICE_TERM_ID
 REQUIREMENTS = {
     "Cycle": {
         "completeness.other": "False",
+        "cycleDuration": "> 0",
         "products": [{"@type": "Product", "value": "", "term.termType": "crop"}],
         "practices": [{"@type": "Practice", "value": "", "term.@id": "plantationLifespan"}]
     }
@@ -37,15 +38,16 @@ def _get_value(product: dict):
     return safe_parse_float(get_crop_lookup_value(MODEL, TERM_ID, term_id, LOOKUPS['crop']), None)
 
 
-def _run(product: dict, plantation_duration: float):
+def _run(product: dict, plantation_duration: float, cycleDuration: float):
     value = _get_value(product)
-    return [_input(value / plantation_duration)]
+    return [_input(value / plantation_duration * cycleDuration)]
 
 
 def _should_run_product(product: dict): return _get_value(product) is not None
 
 
 def _should_run(cycle: dict):
+    cycleDuration = cycle.get('cycleDuration')
     term_type_incomplete = _is_term_type_incomplete(cycle, TERM_ID)
     product = next((p for p in cycle.get('products', []) if _should_run_product(p)), None)
     plantation_duration = list_sum(find_term_match(cycle.get('practices', []), PRACTICE_TERM_ID).get('value'), None)
@@ -53,13 +55,14 @@ def _should_run(cycle: dict):
     logRequirements(cycle, model=MODEL, term=TERM_ID,
                     term_type_seed_incomplete=term_type_incomplete,
                     product_id=(product or {}).get('term', {}).get('@id'),
-                    plantation_duration=plantation_duration)
+                    plantation_duration=plantation_duration,
+                    cycleDuration=cycleDuration)
 
-    should_run = all([term_type_incomplete, product, plantation_duration])
+    should_run = all([term_type_incomplete, product, plantation_duration, (cycleDuration or 0) > 0])
     logShouldRun(cycle, MODEL, TERM_ID, should_run)
-    return should_run, product, plantation_duration
+    return should_run, product, plantation_duration, cycleDuration
 
 
 def run(cycle: dict):
-    should_run, product, plantation_duration = _should_run(cycle)
-    return _run(product, plantation_duration) if should_run else []
+    should_run, product, plantation_duration, cycleDuration = _should_run(cycle)
+    return _run(product, plantation_duration, cycleDuration) if should_run else []

hestia_earth/models/site/management.py

@@ -160,16 +160,18 @@ def _get_landCover_term_id(product: dict) -> str:
 
 
 def _get_relevant_items(
-        cycles: list[dict], item_name: str, relevant_terms: list, date_fill: callable = _default_dates
-) -> list:
+    cycles: list[dict], item_name: str, relevant_terms: list, date_fill: callable = _default_dates
+):
     """
     Get items from the list of cycles with any of the relevant terms.
     Also adds dates if missing.
     """
     return [
-        item
+        [
+            item
+            for item in date_fill(cycle=cycle, values=filter_list_term_type(cycle.get(item_name, []), relevant_terms))
+        ]
         for cycle in cycles
-        for item in date_fill(cycle=cycle, values=filter_list_term_type(cycle.get(item_name, []), relevant_terms))
     ]
 
 
@@ -230,18 +232,19 @@ def _has_gap_fill_to_management_set(practices: list) -> list:
 
 
 def _should_run_all_products(cycles: list, site_type: str):
+    products_land_cover = flatten(_get_relevant_items(
+        cycles=cycles,
+        item_name="products",
+        relevant_terms=[TermTermType.LANDCOVER]
+    )) if site_type else []
     products_land_cover = [
         _extract_node_value(
             _include(
                 value=product,
                 keys=["term", "value", "startDate", "endDate", "properties"]
             )
-        ) for product in _get_relevant_items(
-            cycles=cycles,
-            item_name="products",
-            relevant_terms=[TermTermType.LANDCOVER]
-        )
-    ] if site_type else []
+        ) for product in products_land_cover
+    ]
 
     products_crop_forage = _get_relevant_items(
         cycles=cycles,
@@ -255,10 +258,11 @@ def _should_run_all_products(cycles: list, site_type: str):
             keys=["startDate", "endDate", "properties"],
             dest={
                 "term": linked_node(download_hestia(_get_landCover_term_id(product))),
-                "value": 100
+                "value": round(100 / len(_products), 2)
             }
         )
-        for product in list(filter(_get_landCover_term_id, [i for i in products_crop_forage]))
+        for _products in products_crop_forage
+        for product in list(filter(_get_landCover_term_id, _products))
     ] if site_type else []
     dates = sorted(list(set(
         non_empty_list(flatten([[cycle.get('startDate'), cycle.get('endDate')] for cycle in cycles]))
@@ -293,7 +297,7 @@ def _should_run(site: dict):
                 value=practice,
                 keys=["term", "value", "startDate", "endDate"]
             )
-        ) for practice in _get_relevant_items(
+        ) for practice in flatten(_get_relevant_items(
             cycles=cycles,
             item_name="practices",
             relevant_terms=[
@@ -303,7 +307,7 @@ def _should_run(site: dict):
                 TermTermType.LANDUSEMANAGEMENT,
                 TermTermType.SYSTEM
             ]
-        )
+        ))
     ]
     practices = _has_gap_fill_to_management_set(practices)
     practices = condense_nodes(practices)

hestia_earth/models/utils/__init__.py

@@ -1,6 +1,8 @@
 from os.path import dirname, abspath
 from collections.abc import Generator, Iterable
 from itertools import tee
+from decimal import Decimal
+from statistics import mean
 import sys
 import datetime
 from functools import reduce
@@ -10,6 +12,7 @@ from hestia_earth.schema import SchemaType
 from hestia_earth.utils.api import download_hestia
 from hestia_earth.utils.model import linked_node
 from hestia_earth.utils.tools import flatten, non_empty_list
+from hestia_earth.utils.date import is_in_days, is_in_months
 
 from .constant import Units
 
@@ -94,6 +97,23 @@ def multiply_values(values: list):
     return reduce(operator.mul, filtered_values, 1) if len(filtered_values) > 1 else None
 
 
+def _numeric_weighted_average(values: list):
+    total_weight = sum(Decimal(str(weight)) for _v, weight in values) if values else Decimal(0)
+    weighted_values = [Decimal(str(value)) * Decimal(str(weight)) for value, weight in values]
+    average = sum(weighted_values) / (total_weight if total_weight else 1) if weighted_values else None
+    return None if average is None else float(average)
+
+
+def _bool_weighted_average(values: list):
+    return mean(map(int, values)) >= 0.5
+
+
+def weighted_average(weighted_values: list):
+    values = [v for v, _w in weighted_values]
+    all_boolean = all([isinstance(v, bool) for v in values])
+    return _bool_weighted_average(values) if all_boolean else _numeric_weighted_average(weighted_values)
+
+
 def term_id_prefix(term_id: str): return term_id.split('Kg')[0]
 
 
@@ -156,3 +176,21 @@ def pairwise(iterable):
     a, b = tee(iterable)
     next(b, None)
     return zip(a, b)
+
+
+def full_date_str(date_str: str, is_end: bool = False):
+    """
+    Return the date in format YYY-MM-dd, by setting the month and day if they are not provided.
+    """
+    return date_str if is_in_days(date_str) else (
+        f"{date_str}-{14 if is_end else 15}" if is_in_months(date_str)
+        else f"{date_str}-{'12-31' if is_end else '01-01'}"
+    )
+
+
+def days_to_years(days):
+    return days / 365
+
+
+def hectar_to_square_meter(value):
+    return value * 10000

hestia_earth/models/utils/array_builders.py

@@ -3,11 +3,11 @@ Based on code by Cool Farm Tool:
 https://gitlab.com/MethodsCFT/coolfarm-soc/-/blob/main/src/cfasoc/builders.py
 """
 import hashlib
-from numpy import array, concatenate, cumsum, full, hstack, random, mean, prod, vstack
+from numpy import cumsum, dot, full, linalg, hstack, random, mean, vstack
 from numpy.typing import NDArray, DTypeLike
 from typing import Union
 
-from .descriptive_stats import calc_z_critical
+from .stats import calc_z_critical, truncnorm_rvs
 
 
 def repeat_single(shape: tuple, value: float, dtype: DTypeLike = None) -> NDArray:
@@ -31,7 +31,7 @@ def repeat_single(shape: tuple, value: float, dtype: DTypeLike = None) -> NDArra
     return full(shape=shape, fill_value=value, dtype=dtype)
 
 
-def repeat_array_as_columns(n_iterations: int, array: NDArray) -> NDArray:
+def repeat_array_as_columns(n_iterations: int, arr: NDArray) -> NDArray:
     """
     Repeat a numpy array horizontally as columns.
 
@@ -39,7 +39,7 @@ def repeat_array_as_columns(n_iterations: int, array: NDArray) -> NDArray:
     ----------
     n_iterations : int
         Number of times the columns should be repeated.
-    array : NDArray
+    arr : NDArray
         Array to repeat.
 
     Returns
@@ -47,10 +47,10 @@ def repeat_array_as_columns(n_iterations: int, array: NDArray) -> NDArray:
     NDArray
         Repeated array.
     """
-    return hstack([array for _ in range(n_iterations)])
+    return hstack([arr for _ in range(n_iterations)])
 
 
-def repeat_array_as_rows(n_iterations: int, array: NDArray) -> NDArray:
+def repeat_array_as_rows(n_iterations: int, arr: NDArray) -> NDArray:
     """
     Repeat a numpy array vertically as rows.
 
@@ -58,7 +58,7 @@ def repeat_array_as_rows(n_iterations: int, array: NDArray) -> NDArray:
     ----------
     n_iterations : int
         Number of times the rows should be repeated.
-    array : NDArray
+    arr : NDArray
         Array to repeat.
 
     Returns
@@ -66,7 +66,7 @@ def repeat_array_as_rows(n_iterations: int, array: NDArray) -> NDArray:
     NDArray
         Repeated array.
     """
-    return vstack([array for _ in range(n_iterations)])
+    return vstack([arr for _ in range(n_iterations)])
 
 
 def repeat_1d_array_as_columns(n_columns: int, column: NDArray) -> NDArray:
@@ -307,7 +307,7 @@ def truncated_normal_1d(
     n_rows, n_columns = shape
     return repeat_array_as_rows(
         n_rows,
-        _truncnorm_rvs(a=low, b=high, loc=mu, scale=sigma, shape=n_columns, seed=seed)
+        truncnorm_rvs(a=low, b=high, loc=mu, scale=sigma, shape=n_columns, seed=seed)
     )
 
 
@@ -339,49 +339,7 @@ def truncated_normal_2d(
     NDArray
         Array of samples with 2 dimensional variability.
     """
-    return _truncnorm_rvs(a=low, b=high, loc=mu, scale=sigma, shape=shape, seed=seed)
-
-
-def _truncnorm_rvs(
-    a: float,
-    b: float,
-    loc: float,
-    scale: float,
-    shape: Union[int, tuple[int, ...]],
-    seed: Union[int, random.Generator, None] = None
-) -> NDArray:
-    """
-    Generate random samples from a truncated normal distribution. Unlike the `scipy` equivalent, the `a` and `b` values
-    are the abscissae at which we wish to truncate the distribution (as opposed to the number of standard deviations
-    from `loc`).
-
-    Parameters
-    ----------
-    loc : float
-        Mean ("centre") of the distribution.
-    scale : float
-        Standard deviation (spread or "width") of the distribution. Must be non-negative.
-    size : int | tuple[int, ...]
-        Output shape. If the given shape is, e.g., (m, n, k), then m * n * k samples are drawn.
-    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
-        Array of samples.
-    """
-    size = prod(shape)
-    samples = array([])
-    rng = random.default_rng(seed)
-
-    while samples.size < size:
-        samples_temp = rng.normal(loc, scale, (size - samples.size) * 2)
-        valid_samples = samples_temp[(a <= samples_temp) & (samples_temp <= b)]
-        samples = concatenate([samples, valid_samples])
-
-    return samples[:size].reshape(shape)
+    return truncnorm_rvs(a=low, b=high, loc=mu, scale=sigma, shape=shape, seed=seed)
 
 
 def plus_minus_uncertainty_to_normal_1d(
@@ -576,3 +534,56 @@ def gen_seed(node: dict) -> int:
     node_id = node.get("@id", "")
     hashed = hashlib.shake_128(node_id.encode(), usedforsecurity=False).hexdigest(4)
     return abs(int(hashed, 16))
+
+
+def correlated_normal_2d(
+    n_iterations: int,
+    means: NDArray,
+    sds: NDArray,
+    correlation_matrix: NDArray,
+    seed: Union[int, random.Generator, None] = None,
+) -> NDArray:
+    """
+    Generate correlated random samples from a multivariate normal distribution with specified means, standard
+    deviations, and a correlation matrix. Each row represents a different variable (e.g., different years), and each
+    column represents a different iteration (sample).
+
+    Parameters
+    ----------
+    n_iterations : int
+        The number of samples (iterations) to generate for each variable.
+    means : NDArray
+        An array of mean values for each variable (row).
+    sds : NDArray
+        An array of standard deviations for each variable (row).
+    correlation_matrix : NDArray
+        A positive-definite matrix representing the correlations between the variables (rows).
+    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
+        A 2D array of shape (len(means), n_iterations), where each row corresponds to a different variable and each
+        column corresponds to a sample iteration. The values in each row are correlated according to the provided
+        correlation matrix.
+    """
+    # Generate independent random samples for each year
+    shape = (len(means), n_iterations)
+    independent_samples = normal_2d(shape, 0, 1, seed=seed)
+
+    # Apply Cholesky decomposition to the correlation matrix
+    cholesky_decomp = linalg.cholesky(correlation_matrix)
+
+    # Apply Cholesky transformation to introduce correlation across years (rows) for each sample
+    correlated_samples = dot(cholesky_decomp, independent_samples)
+
+    # Scale by standard deviations and shift by means
+    scaled_samples = (
+        correlated_samples
+        * repeat_1d_array_as_columns(n_iterations, sds)
+        + repeat_1d_array_as_columns(n_iterations, means)
+    )
+
+    return scaled_samples

hestia_earth/models/utils/blank_node.py

@@ -1,11 +1,7 @@
-import calendar
 from calendar import monthrange
 from collections import defaultdict
 from collections.abc import Iterable
 from datetime import datetime, timedelta
-from uuid import uuid4
-
-from dateutil.relativedelta import relativedelta
 from enum import Enum
 from functools import reduce
 from typing import (
@@ -16,8 +12,12 @@ from typing import (
     Optional,
     Union
 )
+
+from dateutil import parser
+from dateutil.relativedelta import relativedelta
 from hestia_earth.schema import TermTermType
 from hestia_earth.utils.api import download_hestia
+from hestia_earth.utils.blank_node import ArrayTreatment, get_node_value
 from hestia_earth.utils.model import filter_list_term_type
 from hestia_earth.utils.tools import (
     flatten,
@@ -26,19 +26,22 @@ from hestia_earth.utils.tools import (
     safe_parse_float,
     non_empty_list
 )
-from hestia_earth.utils.blank_node import ArrayTreatment, get_node_value
 
-from ..log import debugValues, log_as_table
-from . import is_from_model, _filter_list_term_unit, is_iterable, _omit
+from . import is_from_model, _filter_list_term_unit, is_iterable, full_date_str
 from .constant import Units
-from .property import get_node_property, get_node_property_value
 from .lookup import (
     is_model_siteType_allowed,
     is_siteType_allowed,
     is_product_id_allowed, is_product_termType_allowed,
     is_input_id_allowed, is_input_termType_allowed
 )
+from .property import get_node_property, get_node_property_value
 from .term import get_lookup_value
+from ..log import debugValues, log_as_table
+
+# TODO: verify those values
+MAX_DEPTH = 1000
+OLDEST_DATE = '1800'
 
 
 def merge_blank_nodes(source: list, new_values: list):
@@ -1228,7 +1231,11 @@ def get_inputs_from_properties(input: dict, term_types: Union[TermTermType, List
         A dictionary of nodes grouped by latest date, in the format `{date: list[node]}`.
     """
     input_value = list_sum(input.get('value', []))
-    properties = input.get('properties') or download_hestia(input.get('term', {}).get('@id')).get('defaultProperties')
+    properties = (
+        input.get('properties') or
+        input.get('term', {}).get('defaultProperties') or
+        download_hestia(input.get('term', {}).get('@id')).get('defaultProperties')
+    )
     inputs = non_empty_list([
         {
             'term': p.get('key'),
@@ -1238,97 +1245,145 @@ def get_inputs_from_properties(input: dict, term_types: Union[TermTermType, List
     return filter_list_term_type(inputs, term_types)
 
 
-def _get_condensed_nodes(nodes: list) -> tuple[list, bool]:
-    """Only considers nodes which already match on non-date criteria."""
-    CONDENSABLE_UNITS = [Units.BOOLEAN.value, Units.PERCENTAGE_AREA.value]
-    condensed_nodes = []
-    matched_uuids = set()
-    nodes_by_start_date = {_full_date_str(date_str=n["startDate"], is_end=True): n for n in nodes if "startDate" in n}
-    if len(nodes_by_start_date) != len(nodes):
-        return nodes, False
+def _should_group_node(node: dict): return node.get('startDate') and node.get('endDate')
+
+
+def _parse_date(node: dict, key: str):
+    return safe_parse_date(full_date_str(node.get(key), is_end=key == 'endDate'))
+
 
-    for node in nodes:
-        search_date = _offset_date(date_str=node.get("endDate", ""))
-        if node["uuid"] in matched_uuids:
-            continue
-        if (search_date in nodes_by_start_date and nodes_by_start_date[search_date]["uuid"] not in matched_uuids
-                and node.get("term", {}).get("units") in CONDENSABLE_UNITS):
-            new_node = node.copy()
-            new_node["endDate"] = nodes_by_start_date[search_date]["endDate"]
-            condensed_nodes.append(new_node)
-            matched_uuids.add(nodes_by_start_date[search_date]["uuid"])
-        elif node["uuid"] not in matched_uuids:
-            condensed_nodes.append(node)
+def _group_nodes_by_consecutive_dates(nodes: list):
+    """Groups dictionaries in a list based on consecutive start and end dates within a 1-day tolerance.
+
+    Args:
+        dicts: A list of dictionaries containing 'startDate' and 'endDate' keys.
+
+    Returns:
+        A list of lists, where each inner list contains dictionaries with consecutive start and end dates.
+    """
+    groups = []
+    group = []
+
+    # make sure the nodes are sorted by dates to group by consecutive dates
+    for n in sorted(nodes, key=lambda d: (_parse_date(d, 'startDate'), _parse_date(d, 'endDate'))):
+        if not group or (
+            _should_group_node(n) and
+            _parse_date(n, 'startDate') - _parse_date(group[-1], 'endDate') <= timedelta(days=1)
+        ):
+            group.append(n)
+        else:
+            groups.append(group)
+            group = [n]
 
-    return condensed_nodes, len(matched_uuids) > 0
+    if group:
+        groups.append(group)
+
+    return groups
+
+
+def _node_from_group(nodes: list):
+    # `nodes` contain list with consecutive dates
+    return nodes[0] if len(nodes) == 1 else nodes[0] | {
+        'startDate': min(n.get('startDate') for n in nodes),
+        'endDate': max(n.get('endDate') for n in nodes)
+    }
+
+
+def _condense_nodes(nodes: list):
+    # `nodes` contain list with same `term.@id` and `value`
+    grouped_nodes = _group_nodes_by_consecutive_dates(nodes)
+    return flatten(map(_node_from_group, grouped_nodes))
+
+
+def _group_nodes_to_condense(nodes: list) -> dict:
+    def _group_node(group: dict, node: dict):
+        value = node.get('value', [])
+        value = '-'.join(map(str, value if isinstance(value, list) else [value]))
+        properties = '_'.join(non_empty_list([
+            ';'.join(non_empty_list([
+                p.get('term', {}).get('@id'),
+                f"{p.get('value')}"
+            ])) for p in node.get('properties', [])
+        ]))
+        # group by term, value, and properties
+        group_key = '-'.join(non_empty_list([
+            node.get('term', {}).get('@id', ''),
+            value,
+            properties
+        ]))
+        group[group_key] = group.get(group_key, []) + [node]
+        return group
+
+    return reduce(_group_node, nodes, {})
 
 
 def condense_nodes(nodes: list) -> list:
-    grouped_nodes = _group_nodes_by_term_and_value(nodes)
-    condensed_nodes = dict()
-    any_changes_made = False
-
-    for key, node_group in grouped_nodes.items():
-        condensed_nodes[key] = node_group
-        while len(condensed_nodes[key]) > 1:
-            condensed_nodes[key], changes_made = _get_condensed_nodes(condensed_nodes[key])
-            if not changes_made:
-                break
-            any_changes_made = True
-
-    if not any_changes_made:
-        return [_omit(values=n, keys=["uuid"]) for n in nodes]
-
-    return sorted(
-        flatten([_omit(values=n, keys=["uuid"]) for nodes in condensed_nodes.values() for n in nodes]),
-        key=lambda x: x["startDate"]
-    )
+    grouped_nodes = _group_nodes_to_condense(nodes)
+    return flatten(map(_condense_nodes, grouped_nodes.values()))
 
 
-DATE_FORMAT = "%Y-%m-%d"
+def _node_date(node: dict): return parser.isoparse(node.get('endDate', OLDEST_DATE))
 
 
-def _variable_length_str_to_date(date_str: str, is_end: bool) -> datetime:
-    """Converts to date, adding start or end of year to YYYY strings as indicated by is_end."""
-    return datetime.strptime(_full_date_str(date_str, is_end=is_end), DATE_FORMAT)
+def _distance(node: dict, date): return abs((_node_date(node) - date).days)
 
 
-def _full_date_str(date_str: str, is_end: bool) -> str:
-    suffix = ""
-    if len(date_str) == 4:
-        # Format YYYY
-        suffix = "-12-31" if is_end else "-01-01"
-    elif len(date_str) == 7:
-        # Format YYYY-MM
-        suffix = f"-{calendar.monthrange(int(date_str[:4]), int(date_str[5:7]))[1]}" if is_end else "-01"
+def _most_recent_nodes(nodes: list, date: str) -> list:
+    closest_date = parser.isoparse(date)
+    min_distance = min([_distance(m, closest_date) for m in nodes])
+    return list(filter(lambda m: _distance(m, closest_date) == min_distance, nodes))
 
-    return date_str + suffix
 
+def _shallowest_node(nodes: list) -> dict:
+    min_depth = min([m.get('depthUpper', MAX_DEPTH) for m in nodes])
+    return next((m for m in nodes if m.get('depthUpper', MAX_DEPTH) == min_depth), {})
 
-def _with_full_dates(node: dict) -> dict:
-    output_node = node.copy()
-    if "startDate" in output_node:
-        output_node["startDate"] = _full_date_str(output_node["startDate"], is_end=False)
-    if "endDate" in output_node:
-        output_node["endDate"] = _full_date_str(output_node["endDate"], is_end=True)
 
-    return output_node
+def most_relevant_blank_node_by_type(nodes: List[dict],
+                                     term_type: Union[TermTermType, str, List[TermTermType], List[str]], date: str):
+    """
+    Given a list of cycle specific dated entries like
+    a list of measurements terms or a list of management terms,
+    find the entry closest to a given date
+    Parameters
+    ----------
+    nodes: List[dict]
+        should contain a 'endDate' field otherwise defaults to OLDEST_DATE
+    term_type : TermTermType or List[TermTermType]
+        The `termType` of the `Term`, or a list of `termType`. Example: `TermTermType.CROP`
+    date: str
+        An ISO-8601 datetime compatible string
 
+    Returns
+    -------
 
-def _offset_date(date_str: str, days: int = 1, is_end: bool = True) -> str:
-    return (
-        _variable_length_str_to_date(date_str=date_str, is_end=is_end) + timedelta(days=days)
-    ).strftime(DATE_FORMAT)
+    """
+    filtered_nodes = filter_list_term_type(nodes, term_type)
 
+    return {} if len(filtered_nodes) == 0 \
+        else _shallowest_node(_most_recent_nodes(filtered_nodes, date)) \
+        if date and len(filtered_nodes) > 1 else filtered_nodes[0]
 
-def _group_nodes_by_term_and_value(nodes: list) -> dict:
-    grouped_nodes = defaultdict(list)
 
-    for node in nodes:
-        term_id = node.get("term", {}).get("@id", "")
-        value = "-".join([str(v) for v in node.get("value")]) if isinstance(node.get("value"), list) \
-            else node.get("value")
-        node["uuid"] = uuid4()
-        grouped_nodes[(term_id, value)].append(_with_full_dates(node))
+def most_relevant_blank_node_by_id(nodes: list, term_id: str, date: str):
+    """
+        Given a list of nodes with term_id like
+        a list of measurements terms or a list of management terms,
+        find the entry closest to a given date
+        Parameters
+        ----------
+        nodes: List[dict]
+            should contain a 'endDate' field otherwise defaults to OLDEST_DATE
+        term_id : str
+            the term "@id" of the node we want to match to
+        date: str
+            An ISO-8601 datetime compatible string
+
+        Returns
+        -------
 
-    return grouped_nodes
+        """
+    filtered_nodes = [m for m in nodes if m.get('term', {}).get('@id') == term_id]
+    return {} if len(filtered_nodes) == 0 \
+        else _shallowest_node(_most_recent_nodes(filtered_nodes, date)) \
+        if date and len(filtered_nodes) > 1 else filtered_nodes[0]