modacor 1.0.0__py3-none-any.whl

modacor/modules/base_modules/reduce_dimensionality.py

@@ -0,0 +1,252 @@
+# 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__ = "16/11/2025"
+__status__ = "Development"  # "Development", "Production"
+
+__all__ = ["ReduceDimensionality"]
+__version__ = "20251116.1"
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from modacor.dataclasses.basedata import BaseData
+from modacor.dataclasses.databundle import DataBundle
+from modacor.dataclasses.messagehandler import MessageHandler
+from modacor.dataclasses.process_step import ProcessStep
+from modacor.dataclasses.process_step_describer import ProcessStepDescriber
+
+# Facility-pluggable logger; by default this uses std logging
+logger = MessageHandler(name=__name__)
+
+
+class ReduceDimensionality(ProcessStep):
+    """
+    Compute a (possibly weighted) average of a BaseData signal over one or more axes,
+    propagating uncertainties.
+
+    For each uncertainty key `k`, assumes uncorrelated errors:
+
+        μ = Σ w_i x_i / Σ w_i
+        σ_μ^2 = Σ (w_i^2 σ_i^2) / (Σ w_i)^2
+
+    NaN handling:
+        - If nan_policy == 'omit', NaNs in `signal` (and their σ) are ignored.
+        - If nan_policy == 'propagate', NaNs behave like in plain numpy: if any NaN is
+          present along the reduced axes, the result becomes NaN.
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="average or sum, weighted or unweighted, over axes",
+        calling_id="ReduceDimensionality",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={"signal": ["signal", "uncertainties", "units", "weights"]},
+        arguments={
+            "axes": {
+                "type": (int, list, tuple, type(None)),
+                "default": None,
+                "doc": "Axis or axes to reduce (int, list/tuple, or None for all).",
+            },
+            "use_weights": {
+                "type": bool,
+                "default": True,
+                "doc": "Use BaseData weights for weighted reduction.",
+            },
+            "nan_policy": {
+                "type": str,
+                "default": "omit",
+                "doc": "NaN handling policy: 'omit' or 'propagate'.",
+            },
+            "reduction": {
+                "type": str,
+                "default": "mean",
+                "doc": "Reduction method: 'mean' or 'sum'.",
+            },
+        },
+        step_keywords=["average", "mean", "weighted", "nanmean", "reduce", "axis", "sum"],
+        step_doc=(
+            "Compute (default weighted) mean of the BaseData signal over the given axes, "
+            "with proper uncertainty propagation."
+        ),
+        step_reference="DOI 10.1088/0953-8984/25/38/383201",
+        step_note=(
+            "This step reduces the dimensionality of the signal by averaging over one or more axes. "
+            "Units are preserved; axes metadata is currently not adjusted and is left empty on the result."
+        ),
+    )
+
+    # ---------------------------- helpers ---------------------------------
+
+    @staticmethod
+    def _normalize_axes(axes: Any) -> int | tuple[int, ...] | None:
+        """
+        Normalize configuration 'axes' into a numpy-compatible axis argument.
+        Allowed:
+          - None           → reduce over all axes
+          - int            → single axis
+          - list/tuple[int] → tuple of axes
+        """
+        if axes is None:
+            logger.debug("ReduceDimensionality: axes=None → reducing over all axes.")
+            return None
+        if isinstance(axes, int):
+            logger.debug(f"ReduceDimensionality: single axis requested: axes={axes}.")
+            return axes
+        # list/tuple of ints
+        normalized = tuple(int(a) for a in axes)
+        logger.debug(f"ReduceDimensionality: multiple axes requested: axes={normalized}.")
+        return normalized
+
+    @staticmethod
+    def _weighted_mean_with_uncertainty(
+        bd: BaseData,
+        axis: int | tuple[int, ...] | None,
+        use_weights: bool,
+        nan_policy: str,
+        reduction: str = "mean",  # NEW
+    ) -> BaseData:
+        """
+        Compute weighted reduction ('mean' or 'sum') of a BaseData over axis,
+        with uncertainty propagation.
+
+        reduction:
+            'mean' → μ = Σ w x / Σ w
+            'sum'  → S = Σ w x
+        """
+        x = np.asarray(bd.signal, dtype=float)
+
+        # Choose weights
+        if use_weights:
+            w = np.asarray(bd.weights, dtype=float)
+            w = np.broadcast_to(w, x.shape)
+        else:
+            w = np.ones_like(x, dtype=float)
+
+        # NaN handling
+        if nan_policy == "omit":
+            mask = np.isnan(x) | np.isnan(w)
+            x_eff = np.where(mask, 0.0, x)
+            w_eff = np.where(mask, 0.0, w)
+        elif nan_policy == "propagate":
+            mask = np.zeros_like(x, dtype=bool)
+            x_eff = x
+            w_eff = w
+        else:
+            raise ValueError(f"Invalid nan_policy: {nan_policy!r}. Use 'omit' or 'propagate'.")
+
+        # Weighted sums
+        w_sum = np.sum(w_eff, axis=axis)
+        wx_sum = np.sum(w_eff * x_eff, axis=axis)
+
+        # Σ w_i^2 σ_i^2 for each key
+        uncertainties_out: dict[str, np.ndarray] = {}
+
+        # Precompute denom for mean case
+        if reduction == "mean":
+            denom = np.where(w_sum == 0, np.nan, w_sum)
+            signal_out = wx_sum / denom
+        elif reduction == "sum":
+            # For sum, just take Σ w x (or Σ x when use_weights=False)
+            signal_out = wx_sum
+        else:
+            raise ValueError(f"Invalid reduction: {reduction!r}. Use 'mean' or 'sum'.")
+
+        for key, err in bd.uncertainties.items():
+            err_arr = np.asarray(err, dtype=float)
+            err_arr = np.broadcast_to(err_arr, x.shape)
+
+            if nan_policy == "omit":
+                err_arr_eff = np.where(mask, 0.0, err_arr)
+            else:
+                err_arr_eff = err_arr
+
+            var_sum = np.sum((w_eff**2) * (err_arr_eff**2), axis=axis)
+
+            if reduction == "mean":
+                sigma = np.sqrt(var_sum) / denom
+            else:  # 'sum'
+                sigma = np.sqrt(var_sum)
+
+            uncertainties_out[key] = sigma
+
+        # --- build result BaseData (numeric content) ---
+        result = BaseData(
+            signal=signal_out,
+            units=bd.units,
+            uncertainties=uncertainties_out,
+            weights=np.array(1.0) if reduction == "mean" else w_sum,
+        )
+
+        # --- metadata: axes + rank_of_data ---
+
+        # New dimensionality after reduction
+        new_ndim = result.signal.ndim
+
+        # Determine which axes were reduced, in normalized (non-negative) form
+        if axis is None:
+            # reducing over all axes
+            reduced_axes_tuple: tuple[int, ...] = tuple(range(x.ndim))
+        elif isinstance(axis, tuple):
+            reduced_axes_tuple = axis
+        else:
+            reduced_axes_tuple = (axis,)
+
+        reduced_axes_norm: set[int] = set()
+        for a in reduced_axes_tuple:
+            a_norm = a if a >= 0 else x.ndim + a
+            reduced_axes_norm.add(a_norm)
+
+        # Reduce axes metadata if we have a full set (one entry per dimension).
+        old_axes = bd.axes
+        if len(old_axes) == x.ndim:
+            # Keep only axes that were NOT reduced
+            new_axes = [ax for i, ax in enumerate(old_axes) if i not in reduced_axes_norm]
+        else:
+            # If metadata length does not match ndim, fall back to empty list
+            new_axes = []
+
+        result.axes = new_axes
+
+        # Rank of data: cannot exceed new ndim, and should not exceed original rank
+        result.rank_of_data = min(bd.rank_of_data, new_ndim)
+
+        return result
+
+    # ---------------------------- main API ---------------------------------
+
+    def calculate(self) -> dict[str, DataBundle]:
+        axis = self._normalize_axes(self.configuration.get("axes"))
+        use_weights = bool(self.configuration.get("use_weights", True))
+        nan_policy = self.configuration.get("nan_policy", "omit")
+        reduction = self.configuration.get("reduction", "mean")  # NEW
+
+        output: dict[str, DataBundle] = {}
+
+        for key in self._normalised_processing_keys():
+            databundle: DataBundle = self.processing_data.get(key)
+            bd: BaseData = databundle["signal"]
+
+            averaged = self._weighted_mean_with_uncertainty(
+                bd=bd,
+                axis=axis,
+                use_weights=use_weights,
+                nan_policy=nan_policy,
+                reduction=reduction,  # NEW
+            )
+
+            databundle["signal"] = averaged
+            output[key] = databundle
+
+        logger.info(f"ReduceDimensionality: calculation finished for {len(output)} keys.")
+
+        return output

modacor/modules/base_modules/sink_processing_data.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__coding__ = "utf-8"
+__authors__ = ["Brian R. Pauw"]
+__copyright__ = "Copyright 2026, The MoDaCor team"
+__date__ = "09/01/2026"
+__status__ = "Development"  # "Development", "Production"
+# end of header and standard imports
+
+__all__ = ["SinkProcessingData"]
+__version__ = "20260901.1"
+
+from pathlib import Path
+
+from modacor.dataclasses.databundle import DataBundle
+from modacor.dataclasses.messagehandler import MessageHandler
+from modacor.dataclasses.process_step import ProcessStep
+from modacor.dataclasses.process_step_describer import ProcessStepDescriber
+
+# Module-level handler; facilities can swap MessageHandler implementation as needed
+logger = MessageHandler(name=__name__)
+
+
+class SinkProcessingData(ProcessStep):
+    """
+    Export ProcessingData to an IoSink.
+
+    - target: 'sink_id::subpath' (for CSV usually 'export_csv::')
+    - data_paths: ProcessingData paths without '::', e.g. '/sample/Q/signal'
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Sink Processing Data",
+        calling_id="SinkProcessingData",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=[],  # no new databundle produced
+        modifies={},  # side-effect only (writing)
+        arguments={
+            "target": {
+                "type": str,
+                "required": True,
+                "default": "",
+                "doc": "Sink target in the form 'sink_id::subpath'.",
+            },
+            "data_paths": {
+                "type": (str, list),
+                "required": True,
+                "default": [],
+                "doc": "ProcessingData paths to write (string or list of strings).",
+            },
+        },
+        step_keywords=["sink", "export", "write"],
+        step_doc="Write selected ProcessingData leaves to an IoSink.",
+        step_reference="",
+        step_note="This step performs an export side-effect and returns an empty output dict.",
+    )
+
+    def calculate(self) -> dict[str, DataBundle]:
+        output: dict[str, DataBundle] = {}
+
+        target: str = self.configuration["target"]
+        data_paths: str | list[str] = self.configuration["data_paths"]
+
+        if isinstance(data_paths, str):
+            data_paths = [data_paths]
+
+        # Delegate determinism + validation to sink implementation
+        self.io_sinks.write_data(
+            target,
+            self.processing_data,
+            data_paths=data_paths,
+        )
+
+        logger.debug(f"SinkProcessingData wrote {len(data_paths)} paths to target '{target}'.")
+        return output

modacor/modules/base_modules/subtract.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__coding__ = "utf-8"
+__authors__ = ["Brian R. Pauw", "Armin Moser"]  # add names to the list as appropriate
+__copyright__ = "Copyright 2025, The MoDaCor team"
+__date__ = "29/10/2025"
+__status__ = "Development"  # "Development", "Production"
+# end of header and standard imports
+
+__all__ = ["Subtract"]
+__version__ = "20251029.1"
+
+from pathlib import Path
+
+from modacor.dataclasses.databundle import DataBundle
+from modacor.dataclasses.helpers import basedata_from_sources
+from modacor.dataclasses.process_step import ProcessStep
+from modacor.dataclasses.process_step_describer import ProcessStepDescriber
+
+
+class Subtract(ProcessStep):
+    """
+    Subtract a DataBundle by a BaseData from an IoSource
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Subtract by IoSource data",
+        calling_id="SubtractBySourceData",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={"signal": ["signal", "uncertainties", "units"]},
+        arguments={
+            "subtrahend_source": {
+                "type": str,
+                "default": None,
+                "doc": "IoSources key for the subtrahend signal.",
+            },
+            "subtrahend_units_source": {
+                "type": str,
+                "default": None,
+                "doc": "IoSources key for subtrahend units metadata.",
+            },
+            "subtrahend_uncertainties_sources": {
+                "type": dict,
+                "default": {},
+                "doc": "Mapping of uncertainty name to IoSources key.",
+            },
+        },
+        step_keywords=["subtract", "scalar", "array"],
+        step_doc="Subtract a DataBundle element by a subtrahend loaded from a data source",
+        step_reference="DOI 10.1088/0953-8984/25/38/383201",
+        step_note="""This loads a scalar (value, units and uncertainty)
+            from an IOSource and applies it to the data signal""",
+    )
+
+    def calculate(self) -> dict[str, DataBundle]:
+        # build up the subtrahend BaseData object from the IoSources
+        subtrahend = basedata_from_sources(
+            io_sources=self.io_sources,
+            signal_source=self.configuration.get("subtrahend_source"),
+            units_source=self.configuration.get("subtrahend_units_source", None),
+            uncertainty_sources=self.configuration.get("subtrahend_uncertainties_sources", {}),
+        )
+        # Get the data
+        data = self.processing_data
+
+        output: dict[str, DataBundle] = {}
+        # actual work happens here:
+        for key in self._normalised_processing_keys():
+            databundle = data.get(key)
+            # subtract the data
+            # databundle['signal'] is a BaseData object
+            databundle["signal"] -= subtrahend
+            output[key] = databundle
+        return output

modacor/modules/base_modules/subtract_databundles.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__coding__ = "utf-8"
+__authors__ = ["Brian R. Pauw", "Armin Moser"]  # add names to the list as appropriate
+__copyright__ = "Copyright 2025, The MoDaCor team"
+__date__ = "29/10/2025"
+__status__ = "Development"  # "Development", "Production"
+# end of header and standard imports
+
+__all__ = ["SubtractDatabundles"]
+__version__ = "20251029.1"
+
+from pathlib import Path
+
+from modacor.dataclasses.databundle import DataBundle
+from modacor.dataclasses.process_step import ProcessStep
+from modacor.dataclasses.process_step_describer import ProcessStepDescriber
+
+
+class SubtractDatabundles(ProcessStep):
+    """
+    Subtract a DataBundle from a DataBundle, useful for background subtraction
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Subtract another DataBundle",
+        calling_id="SubtractDatabundles",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={"signal": ["signal", "uncertainties", "units"]},
+        arguments={
+            "with_processing_keys": {
+                "type": list,
+                "required": True,
+                "default": None,
+                "doc": "Two processing keys: minuend then subtrahend.",
+            },
+        },
+        step_keywords=["subtract", "background", "databundle"],
+        step_doc="Subtract a DataBundle element using another DataBundle",
+        step_reference="DOI 10.1088/0953-8984/25/38/383201",
+        step_note="""
+            This subtracts one DataBundle's signal from another, useful for background subtraction.
+            'with_processing_keys' in the configuration should contain two keys, the operation
+            will subtract the second key's DataBundle from the first key's DataBundle.
+        """,
+    )
+
+    def calculate(self) -> dict[str, DataBundle]:
+        # actual work happens here:
+        keys = self._normalised_processing_keys()
+        assert len(keys) == 2, (
+            "SubtractDatabundles requires exactly two processing keys in 'with_processing_keys': "
+            "the first is the minuend, the second is the subtrahend."
+        )
+        minuend_key = keys[0]
+        minuend = self.processing_data.get(minuend_key)
+        subtrahend = self.processing_data.get(keys[1])
+        # subtract the data
+        minuend["signal"] -= subtrahend["signal"]
+        output: dict[str, DataBundle] = {minuend_key: minuend}
+        return output

modacor/modules/base_modules/units_label_update.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__coding__ = "utf-8"
+__authors__ = ["Brian R. Pauw", "Armin Moser"]  # add names to the list as appropriate
+__copyright__ = "Copyright 2025, The MoDaCor team"
+__date__ = "16/12/2025"
+__status__ = "Development"  # "Development", "Production"
+
+__all__ = ["UnitsLabelUpdate"]
+__version__ = "20251216.1"
+
+from pathlib import Path
+
+from modacor import ureg
+from modacor.dataclasses.databundle import DataBundle
+from modacor.dataclasses.process_step import ProcessStep
+from modacor.dataclasses.process_step_describer import ProcessStepDescriber
+
+
+class UnitsLabelUpdate(ProcessStep):
+    """
+    Update the units of one or more BaseData elements in a DataBundle.
+    Note: this only changes the *unit label* (no numerical conversion).
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Update unit labels",
+        calling_id="UnitsLabelUpdate",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=[""],  # provided via update_pairs
+        modifies={"": ["units"]},
+        arguments={
+            "update_pairs": {
+                "type": dict,
+                "required": True,
+                "default": {},
+                "doc": "Mapping of BaseData key to unit string or {'units': str}.",
+            },
+        },
+        step_keywords=["units", "update", "standardize"],
+        step_doc="Update unit labels of one or more BaseData elements (no conversion).",
+        step_reference="DOI 10.1088/0953-8984/25/38/383201",
+    )
+
+    def calculate(self) -> dict[str, DataBundle]:
+        pairs = self.configuration["update_pairs"]
+        parsed = {
+            bd_key: ureg.Unit(spec["units"] if isinstance(spec, dict) else spec) for bd_key, spec in pairs.items()
+        }
+
+        output: dict[str, DataBundle] = {}
+        for key in self._normalised_processing_keys():
+            databundle = self.processing_data.get(key)
+            for bd_key, unit in parsed.items():
+                databundle[bd_key].units = unit
+            output[key] = databundle
+            info_msg = f"UnitsLabelUpdate: updated units for DataBundle '{key}': " + ", ".join(
+                f"{bd_key} -> {databundle[bd_key].units}" for bd_key in parsed.keys()
+            )
+            self.logger.info(info_msg)
+        return output

modacor/modules/instrument_modules/readme.md

@@ -0,0 +1,9 @@
+Instrument modules structure explainer:
+--
+
+Welcome to the location for instrument-specfific modules. If neither the base modules or the technique-specific modules satisfy the needs for data from a given instrument, you can write sprcific modules that are purpose-built and put them in here.
+
+The subdirectory structure to place these in is recommended to follow the following convention:
+./institute_abbreviation/instrument_name/module_name.
+
+Please follow the code practices of the project, and consider making your modules available to the wider world. This will be considered if modules have the standard header, use ProcessStepDescriber to describe the module, and have tests in the corresponding directory in src/modacor/tests/modules/instrument_modules/...

modacor/modules/technique_modules/scattering/geometry_helpers.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__coding__ = "utf-8"
+__authors__ = ["Brian R. Pauw"]
+__copyright__ = "Copyright 2026, The MoDaCor team"
+__date__ = "06/01/2026"
+__status__ = "Development"  # "Development", "Production"
+
+__version__ = "20260106.1"
+__all__ = ["unit_vec3", "require_scalar", "prepare_static_scalar"]
+
+from typing import Tuple
+
+import numpy as np
+import pint
+
+from modacor import ureg
+from modacor.dataclasses.basedata import BaseData
+
+
+def unit_vec3(v: Tuple[float, float, float] | np.ndarray, *, name: str = "vector") -> np.ndarray:
+    """Normalize a 3-vector to unit length."""
+    v = np.asarray(v, dtype=float).reshape(3)
+    n = float(np.linalg.norm(v))
+    if n == 0.0:
+        raise ValueError(f"{name} must be non-zero")
+    return v / n
+
+
+def require_scalar(name: str, bd: BaseData) -> BaseData:
+    """Ensure a BaseData is scalar; returns a squeezed copy with RoD=0."""
+    out = bd.squeeze().copy()
+    if np.size(out.signal) != 1:
+        raise ValueError(f"{name} must be scalar (size==1). Got shape={np.shape(out.signal)}.")
+    out.rank_of_data = 0
+    return out
+
+
+def prepare_static_scalar(
+    bd: BaseData,
+    *,
+    require_units: pint.Unit = ureg.m,
+    uncertainty_key: str = "static_config_jitter",
+) -> BaseData:
+    """
+    Reduce a possibly-array BaseData to a scalar via weighted mean (bd.weights) and
+    assign uncertainty as standard error of the mean (SEM).
+
+    - If bd is already scalar: squeeze+RoD=0 and return.
+    - If bd.weights is None: uniform weights are assumed.
+
+    Notes
+    -----
+    SEM here uses:
+      - weighted mean
+      - weighted variance (about mean)
+      - effective sample size n_eff = (sum(w)^2) / sum(w^2)
+      - sem = sqrt(var) / sqrt(n_eff)
+    """
+    if not bd.units.is_compatible_with(require_units):
+        raise ValueError(f"Value must be in {require_units}, got {bd.units}")
+
+    # scalar passthrough
+    if np.size(bd.signal) == 1:
+        out = bd.squeeze().copy()
+        out.rank_of_data = 0
+        return out
+
+    x = np.asarray(bd.signal, dtype=float).ravel()
+
+    # --- robust weights handling ---
+    if bd.weights is None:
+        w = np.ones_like(x)
+    else:
+        w_raw = np.asarray(bd.weights, dtype=float)
+
+        # allow scalar/length-1 weights
+        if w_raw.size == 1:
+            w = np.full_like(x, float(w_raw.reshape(-1)[0]))
+        else:
+            # allow broadcastable weights (e.g. (5,1,1,1) vs (5,))
+            try:
+                w = np.broadcast_to(w_raw, np.shape(bd.signal)).ravel()
+            except ValueError as e:
+                raise ValueError(
+                    f"weights shape {w_raw.shape} does not match signal shape {np.shape(bd.signal)}"
+                ) from e
+
+        if w.size != x.size:
+            raise ValueError(f"weights size {w.size} does not match signal size {x.size}")
+
+    wsum = float(np.sum(w))
+    if wsum <= 0:
+        raise ValueError("weights must sum to > 0")
+
+    mean = float(np.sum(w * x) / wsum)
+
+    # effective N for SEM (works for equal weights too)
+    n_eff = float((wsum**2) / np.sum(w**2))
+
+    # weighted population variance about the weighted mean
+    var = float(np.sum(w * (x - mean) ** 2) / wsum)
+    sem = float(np.sqrt(var) / np.sqrt(n_eff))
+
+    return BaseData(
+        signal=np.array(mean, dtype=float),
+        units=bd.units,
+        uncertainties={uncertainty_key: np.array(sem, dtype=float)},
+        rank_of_data=0,
+    )