modacor 1.0.0__py3-none-any.whl

modacor/dataclasses/trace_event.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__coding__ = "utf-8"
+__authors__ = ["Brian R. Pauw"]  # add names to the list as appropriate
+__copyright__ = "Copyright 2025, The MoDaCor team"
+__date__ = "13/12/2025"
+__status__ = "Development"  # "Development", "Production"
+__version__ = "20251213.1"
+
+__all__ = ["TraceEvent"]
+
+import json
+from hashlib import sha256
+from typing import Any
+
+from attrs import define, field, validators
+
+
+def _to_jsonable(value: Any) -> Any:
+    """
+    Convert arbitrary objects into a JSON-serializable structure.
+
+    Rules:
+    - dict keys become strings
+    - tuples/sets become lists
+    - unknown objects become str(value)
+    """
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+
+    if isinstance(value, dict):
+        return {str(k): _to_jsonable(v) for k, v in value.items()}
+
+    if isinstance(value, (list, tuple, set)):
+        return [_to_jsonable(v) for v in value]
+
+    # Common numpy-like scalars without importing numpy
+    if hasattr(value, "item") and callable(getattr(value, "item")):
+        try:
+            return _to_jsonable(value.item())
+        except Exception:
+            pass
+
+    return str(value)
+
+
+def _stable_hash_dict(d: dict[str, Any]) -> str:
+    """
+    Stable content hash of a dict (order-independent).
+    """
+    canonical = json.dumps(_to_jsonable(d), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return sha256(canonical.encode("utf-8")).hexdigest()
+
+
+@define(frozen=True, slots=True)
+class TraceEvent:
+    """
+    A small, UI-friendly trace record for a single executed step.
+
+    Intended to be embedded into Pipeline.to_spec() so graph viewers can show:
+      - configuration used by the step
+      - what changed (units/dimensionality/shape/NaNs/etc.)
+      - optional human messages (later)
+
+    Notes
+    -----
+    Keep this JSON-friendly and lightweight: no arrays, no heavy objects.
+    """
+
+    step_id: str
+    module: str
+    label: str = ""
+
+    module_path: str = ""
+    version: str = ""
+
+    requires_steps: tuple[str, ...] = field(factory=tuple)
+
+    # configuration as used for execution (JSON-friendly)
+    config: dict[str, Any] = field(factory=dict)
+
+    # computed stable hash of config
+    config_hash: str = field(init=False)
+
+    # dataset key -> { "diff": [...], "prev": {...} | None, "now": {...} }
+    # Use a simple key like "sample.signal" or "sample_background.signal"
+    datasets: dict[str, Any] = field(factory=dict)
+
+    # reserved for later (MessageHandler, timing, etc.)
+    messages: list[dict[str, Any]] = field(factory=list)
+
+    # wall-clock runtime for this step execution (seconds)
+    duration_s: float | None = field(default=None, validator=validators.optional(validators.instance_of(float)))
+
+    def __attrs_post_init__(self) -> None:
+        object.__setattr__(self, "config_hash", _stable_hash_dict(self.config))
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        JSON-serializable representation suitable for Pipeline.to_spec().
+        """
+        return {
+            "step_id": self.step_id,
+            "module": self.module,
+            "label": self.label,
+            "module_path": self.module_path,
+            "version": self.version,
+            "requires_steps": list(self.requires_steps),
+            "config": _to_jsonable(self.config),
+            "config_hash": self.config_hash,
+            "duration_s": self.duration_s,
+            "datasets": _to_jsonable(self.datasets),
+            "messages": _to_jsonable(self.messages),
+        }

modacor/dataclasses/uncertainty_tools.py

@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__coding__ = "utf-8"
+__authors__ = ["Brian R. Pauw"]  # add names to the list as appropriate
+__copyright__ = "Copyright 2026, The MoDaCor team"
+__date__ = "20/01/2026"
+__status__ = "Development"  # "Development", "Production"
+# end of header and standard imports
+
+__all__ = [
+    "normalize_uncertainty_combinations",
+    "combine_uncertainty_keys",
+    "quadrature_aggregator",
+    "maximum_aggregator",
+]
+
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any
+
+import numpy as np
+
+from .basedata import BaseData
+from .messagehandler import MessageHandler
+
+Aggregator = Callable[[list[np.ndarray], tuple[int, ...]], np.ndarray]
+
+
+def normalize_uncertainty_combinations(raw: Mapping[str, Any] | None) -> dict[str, tuple[str, ...]]:
+    """Normalise combination configuration into deterministic tuples."""
+    if raw is None:
+        return {}
+    if not isinstance(raw, Mapping):
+        raise TypeError("'combinations' must be a mapping of output key -> iterable of source keys.")
+
+    normalised: dict[str, tuple[str, ...]] = {}
+    for dest_key, sources in raw.items():
+        if isinstance(sources, str):
+            source_tuple = (sources,)
+        elif isinstance(sources, Iterable):
+            source_tuple = tuple(str(s).strip() for s in sources if str(s).strip())
+        else:
+            raise TypeError("Each combinations entry must be a string or iterable of strings.")
+
+        dest_key_str = str(dest_key).strip()
+        if not dest_key_str:
+            raise ValueError("Combination keys must be non-empty strings.")
+        if not source_tuple:
+            raise ValueError(f"Combination '{dest_key_str}' must list at least one source uncertainty key.")
+        normalised[dest_key_str] = source_tuple
+    return normalised
+
+
+def quadrature_aggregator(uncertainties: list[np.ndarray], shape: tuple[int, ...]) -> np.ndarray:
+    """Combine absolute uncertainties via root-sum-of-squares."""
+    total_var: np.ndarray | None = None
+    for sigma in uncertainties:
+        arr = np.asarray(sigma, dtype=float)
+        broadcast = np.broadcast_to(arr, shape).astype(float, copy=False)
+        squared = np.square(broadcast)
+        total_var = squared if total_var is None else total_var + squared
+    if total_var is None:
+        raise RuntimeError("Cannot compute quadrature of an empty sequence.")
+    return np.sqrt(total_var)
+
+
+def maximum_aggregator(uncertainties: list[np.ndarray], shape: tuple[int, ...]) -> np.ndarray:
+    """Combine absolute uncertainties by taking the element-wise maximum."""
+    if not uncertainties:
+        raise RuntimeError("Cannot compute maximum of an empty sequence.")
+    broadcasted = [np.broadcast_to(np.asarray(sigma, dtype=float), shape) for sigma in uncertainties]
+    return np.maximum.reduce(broadcasted)
+
+
+def combine_uncertainty_keys(
+    *,
+    basedata: BaseData,
+    combinations: Mapping[str, tuple[str, ...]],
+    aggregator: Aggregator,
+    drop_sources: bool,
+    ignore_missing: bool,
+    logger: MessageHandler | None = None,
+    target_name: str = "",
+) -> None:
+    """Apply configured combinations to ``basedata.uncertainties`` in-place."""
+    signal_shape = basedata.signal.shape
+    new_keys: set[str] = set()
+    sources_to_remove: set[str] = set()
+
+    for dest_key, source_keys in combinations.items():
+        available: list[np.ndarray] = []
+        present_sources: list[str] = []
+        missing_sources: list[str] = []
+
+        for src_key in source_keys:
+            if src_key in basedata.uncertainties:
+                present_sources.append(src_key)
+                available.append(basedata.uncertainties[src_key])
+            else:
+                missing_sources.append(src_key)
+
+        if missing_sources and not ignore_missing:
+            missing_formatted = ", ".join(sorted(missing_sources))
+            target_descr = target_name or "BaseData"
+            raise KeyError(
+                f"Missing uncertainties {{{missing_formatted}}} required for '{dest_key}' on {target_descr}."
+            )
+
+        if not available:
+            if ignore_missing:
+                if logger is not None:
+                    logger.debug(
+                        "Skipping destination '%s' – none of the source keys were present.",
+                        dest_key,
+                    )
+                continue
+            target_descr = target_name or "BaseData"
+            raise RuntimeError(f"No uncertainties available to combine for destination '{dest_key}' on {target_descr}.")
+
+        combined = aggregator(available, signal_shape)
+        basedata.uncertainties[dest_key] = combined
+        new_keys.add(dest_key)
+
+        if drop_sources:
+            sources_to_remove.update(present_sources)
+
+    if drop_sources:
+        for source_key in sources_to_remove - new_keys:
+            basedata.uncertainties.pop(source_key, None)

modacor/dataclasses/validators.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__coding__ = "utf-8"
+__authors__ = ["Jérôme Kieffer", "Brian R. Pauw"]  # add names to the list as appropriate
+__copyright__ = "Copyright 2025, The MoDaCor team"
+__date__ = "16/11/2025"
+__status__ = "Development"  # "Development", "Production"
+# end of header and standard imports
+
+from numbers import Integral
+from typing import Any, Type
+
+import numpy as np
+
+from modacor import ureg
+
+from .databundle import DataBundle
+from .messagehandler import MessageHandler
+
+# from .scatteringdata import ScatteringData
+_dummy_handler = MessageHandler()
+
+__all__ = [
+    "check_data_element_and_units",
+    "is_list_of_ints",
+]
+
+
+def is_list_of_ints(instance: Type, attribute: str, value: Any):
+    """
+    Check if the value is a list of integers.
+    """
+    if not isinstance(value, list):
+        return False
+    return all(isinstance(i, Integral) for i in value)
+
+
+def check_data(
+    data: DataBundle,
+    data_element_name: str = None,
+    required_unit: ureg.Unit = None,
+    logger: MessageHandler = _dummy_handler,
+) -> bool:
+    """
+    Check that the required data element is present in the DataBundle object.
+    """
+    if not isinstance(data, DataBundle):
+        return False
+    if data_element_name is not None:
+        if (intensity_object := data.data.get(data_element_name, None)) is None:
+            logger.error(f"{data_element_name} is required.")
+            return False
+        if not (intensity_object.internal_units == required_unit):
+            logger.error(f"{data_element_name} should have units of {required_unit}.")
+            return False
+    return True
+
+
+def arrays_are_equal_shape(
+    array1: np.ndarray,
+    array2: np.ndarray,
+) -> bool:
+    """
+    Check if two arrays have the same shape.
+    """
+    if array1.shape != array2.shape:
+        return False
+    return True
+
+
+def check_data_element_and_units(
+    data: DataBundle,
+    data_element_name: str,
+    required_unit: ureg.Unit,
+    logger: MessageHandler,
+) -> bool:
+    """
+    Check that the required data element is present with the correct units in the DataBundle object.
+    """
+    return check_data(data, data_element_name, required_unit, logger)