modacor 1.0.0__py3-none-any.whl

modacor/modules/base_modules/bitwise_or_masks.py

@@ -0,0 +1,113 @@
+# 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__ = "09/01/2026"
+__status__ = "Development"  # "Development", "Production"
+# end of header and standard imports
+
+__all__ = ["BitwiseOrMasks"]
+__version__ = "20260109.3"
+
+from pathlib import Path
+
+import numpy as np
+
+from modacor.dataclasses.basedata import BaseData
+from modacor.dataclasses.databundle import DataBundle
+from modacor.dataclasses.process_step import ProcessStep
+from modacor.dataclasses.process_step_describer import ProcessStepDescriber
+
+
+class BitwiseOrMasks(ProcessStep):
+    """
+    Bitwise-OR one or more mask BaseData entries into a target mask BaseData entry
+    within the same DataBundle.
+
+    MoDaCor's Masks are 32-bit integer bitfields (NeXus convention). This step updates the
+    target mask in-place and preserves reason bits.
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Combine masks within one DataBundle (bitwise OR)",
+        calling_id="BitwiseOrMasksInBundle",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["mask"],
+        modifies={"mask": ["signal"]},
+        arguments={
+            "with_processing_keys": {
+                "type": list,
+                "required": True,
+                "default": ["sample"],
+                "doc": "Single processing key identifying the DataBundle to update.",
+            },
+            "target_mask_key": {
+                "type": str,
+                "default": "mask",
+                "doc": "BaseData key for the target mask inside the DataBundle.",
+            },
+            "source_mask_keys": {
+                "type": list,
+                "required": True,
+                "default": [],
+                "doc": "List of BaseData keys to OR into the target mask.",
+            },
+        },
+        step_keywords=["mask", "bitmask", "bitwise", "or", "databundle"],
+        step_doc="Combine multiple mask arrays stored as different BaseData keys in the same DataBundle.",
+        step_reference="NeXus mask bit-field convention (NXdata/NXdetector masks)",
+        step_note="""
+            Configuration:
+              with_processing_keys: [sample]     # required, single databundle key
+              target_mask_key: mask              # optional, default: mask
+              source_mask_keys: [bs_mask, ...]   # required, one or more
+
+            Performs:
+              target_mask |= source_mask  (in-place, for each source)
+        """,
+    )
+
+    @staticmethod
+    def _require_int(arr: np.ndarray, name: str) -> None:
+        assert np.issubdtype(arr.dtype, np.integer), f"{name} must be an integer mask, got {arr.dtype}."
+
+    def calculate(self) -> dict[str, DataBundle]:
+        cfg = self.configuration
+
+        keys = self._normalised_processing_keys()
+        assert len(keys) == 1, "BitwiseOrMasks requires a single databundle processing key."
+        processing_key = keys[0]
+        target_key = cfg.get("target_mask_key", "mask")
+        source_keys = cfg["source_mask_keys"]
+
+        assert isinstance(source_keys, list) and source_keys, "source_mask_keys must be a non-empty list."
+
+        bundle = self.processing_data[processing_key]
+        target_bd: BaseData = bundle[target_key]
+        tgt = target_bd.signal
+
+        self._require_int(tgt, f"{processing_key}::{target_key}")  # noqa: E231
+
+        # Canonicalize target to uint32 once (needed for NeXus-style 32-bit bitfields)
+        if tgt.dtype != np.uint32:
+            tgt = tgt.astype(np.uint32, copy=True)  # one-time allocation
+            target_bd.signal = tgt
+
+        for sk in source_keys:
+            src_bd: BaseData = bundle[sk]
+            src = src_bd.signal
+            self._require_int(src, f"{processing_key}::{sk}")  # noqa: E231
+
+            # Convert only if needed (uint8/int16/etc -> uint32)
+            src_u32 = src if src.dtype == np.uint32 else src.astype(np.uint32, copy=False)
+
+            # In-place OR; NumPy handles broadcasting or raises
+            np.bitwise_or(tgt, src_u32, out=tgt)
+
+        return {processing_key: bundle}

modacor/modules/base_modules/combine_uncertainties.py

@@ -0,0 +1,120 @@
+# 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__ = ["CombineUncertainties"]
+__version__ = "20260120.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
+from modacor.dataclasses.uncertainty_tools import (
+    combine_uncertainty_keys,
+    normalize_uncertainty_combinations,
+    quadrature_aggregator,
+)
+
+
+class CombineUncertainties(ProcessStep):
+    """Combine multiple uncertainty entries on a :class:`~modacor.dataclasses.basedata.BaseData` element.
+
+    The configured combinations are evaluated as root-sum-of-squares of the listed one-sigma
+    uncertainties. Each combination writes (or overwrites) the target uncertainty key.
+
+    Example configuration::
+
+        combinations:
+          stat_total: ["poisson", "readout"]
+          geometry: ["pixel_index_slow", "pixel_index_fast"]
+
+    The example above will create/update the keys ``"stat_total"`` and ``"geometry"`` on the
+    target BaseData, combining the referenced uncertainties in quadrature.
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Combine uncertainties in quadrature",
+        calling_id="CombineUncertainties",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={"signal": ["uncertainties"]},
+        arguments={
+            "target_basedata_key": {
+                "type": str,
+                "default": "signal",
+                "doc": "Name of the BaseData entry within each DataBundle to modify (default: 'signal').",
+            },
+            "combinations": {
+                "type": dict,
+                "required": True,
+                "default": {},
+                "doc": "Mapping of output uncertainty key to an iterable of source keys to combine.",
+            },
+            "drop_source_keys": {
+                "type": bool,
+                "default": False,
+                "doc": "Remove source uncertainty keys after combination (default: False).",
+            },
+            "ignore_missing": {
+                "type": bool,
+                "default": False,
+                "doc": (
+                    "If True, missing source keys are ignored (combinations use the available ones). "
+                    "If all listed keys are missing, the combination is skipped."
+                ),
+            },
+        },
+        step_keywords=["uncertainties", "combine", "quadrature", "propagation"],
+        step_doc="Combine selected uncertainties in quadrature and expose the result under new keys.",
+        step_reference="DOI 10.1088/0953-8984/25/38/383201",
+        step_note=(
+            "Designed for SAXS/SANS pipelines where uncertainties such as Poisson, readout noise, "
+            "and flat-field corrections are stored separately (see the MOUSE notebook examples)."
+        ),
+    )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def calculate(self) -> dict[str, DataBundle]:
+        combinations_raw = self.configuration.get("combinations", {})
+        combinations = normalize_uncertainty_combinations(combinations_raw)
+        if not combinations:
+            raise ValueError("CombineUncertainties requires a non-empty 'combinations' mapping in its configuration.")
+
+        target_basedata_key = str(self.configuration.get("target_basedata_key", "signal"))
+        drop_sources = bool(self.configuration.get("drop_source_keys", False))
+        ignore_missing = bool(self.configuration.get("ignore_missing", False))
+
+        output: dict[str, DataBundle] = {}
+
+        for processing_key in self._normalised_processing_keys():
+            databundle: DataBundle = self.processing_data.get(processing_key)
+            if target_basedata_key not in databundle:
+                raise KeyError(f"DataBundle '{processing_key}' does not contain BaseData '{target_basedata_key}'.")
+
+            combine_uncertainty_keys(
+                basedata=databundle[target_basedata_key],
+                combinations=combinations,
+                aggregator=quadrature_aggregator,
+                drop_sources=drop_sources,
+                ignore_missing=ignore_missing,
+                logger=self.logger,
+                target_name=f"BaseData '{target_basedata_key}' in DataBundle '{processing_key}'",
+            )
+
+            output[processing_key] = databundle
+
+        return output

modacor/modules/base_modules/combine_uncertainties_max.py

@@ -0,0 +1,105 @@
+# 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__ = ["CombineUncertaintiesMax"]
+__version__ = "20260120.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
+from modacor.dataclasses.uncertainty_tools import (
+    combine_uncertainty_keys,
+    maximum_aggregator,
+    normalize_uncertainty_combinations,
+)
+
+
+class CombineUncertaintiesMax(ProcessStep):
+    """Combine uncertainties by taking the element-wise maximum across selected keys."""
+
+    documentation = ProcessStepDescriber(
+        calling_name="Combine uncertainties by maximum",
+        calling_id="CombineUncertaintiesMax",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={"signal": ["uncertainties"]},
+        arguments={
+            "target_basedata_key": {
+                "type": str,
+                "default": "signal",
+                "doc": "Name of the BaseData entry within each DataBundle to modify (default: 'signal').",
+            },
+            "combinations": {
+                "type": dict,
+                "required": True,
+                "default": {},
+                "doc": "Mapping of output uncertainty key to an iterable of source keys to combine.",
+            },
+            "drop_source_keys": {
+                "type": bool,
+                "default": False,
+                "doc": "Remove source uncertainty keys after combination (default: False).",
+            },
+            "ignore_missing": {
+                "type": bool,
+                "default": False,
+                "doc": (
+                    "If True, missing source keys are ignored. "
+                    "If all listed keys are missing, the combination is skipped."
+                ),
+            },
+        },
+        step_keywords=["uncertainties", "combine", "maximum", "propagation"],
+        step_doc="Select the maximum absolute uncertainty among configured source keys.",
+        step_reference="DOI 10.1088/0953-8984/25/38/383201",
+        step_note=(
+            "Useful when systematic contributions must be bounded by the most conservative estimate, "
+            "mirroring needs in certain MOUSE workflows."
+        ),
+    )
+
+    def calculate(self) -> dict[str, DataBundle]:
+        combinations_raw = self.configuration.get("combinations", {})
+        combinations = normalize_uncertainty_combinations(combinations_raw)
+        if not combinations:
+            raise ValueError(
+                "CombineUncertaintiesMax requires a non-empty 'combinations' mapping in its configuration."
+            )
+
+        target_basedata_key = str(self.configuration.get("target_basedata_key", "signal"))
+        drop_sources = bool(self.configuration.get("drop_source_keys", False))
+        ignore_missing = bool(self.configuration.get("ignore_missing", False))
+
+        output: dict[str, DataBundle] = {}
+
+        for processing_key in self._normalised_processing_keys():
+            databundle: DataBundle = self.processing_data.get(processing_key)
+            if target_basedata_key not in databundle:
+                raise KeyError(f"DataBundle '{processing_key}' does not contain BaseData '{target_basedata_key}'.")
+
+            combine_uncertainty_keys(
+                basedata=databundle[target_basedata_key],
+                combinations=combinations,
+                aggregator=maximum_aggregator,
+                drop_sources=drop_sources,
+                ignore_missing=ignore_missing,
+                logger=self.logger,
+                target_name=f"BaseData '{target_basedata_key}' in DataBundle '{processing_key}'",
+            )
+
+            output[processing_key] = databundle
+
+        return output

modacor/modules/base_modules/divide.py

@@ -0,0 +1,82 @@
+# 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__ = ["Divide"]
+__version__ = "20251029.1"
+
+from pathlib import Path
+
+# from modacor import ureg
+# from modacor.dataclasss.basedata import BaseData
+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 Divide(ProcessStep):
+    """
+    Divide DataBundle by a BaseData from an IoSource
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Divide by IoSource data",
+        calling_id="DivideBySourceData",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={"signal": ["signal", "uncertainties", "units"]},
+        arguments={
+            "divisor_source": {
+                "type": str,
+                "default": None,
+                "doc": "IoSources key for the divisor signal.",
+            },
+            "divisor_units_source": {
+                "type": str,
+                "default": None,
+                "doc": "IoSources key for divisor units metadata.",
+            },
+            "divisor_uncertainties_sources": {
+                "type": dict,
+                "default": {},
+                "doc": "Mapping of uncertainty name to IoSources key.",
+            },
+        },
+        step_keywords=["divide", "scalar", "array"],
+        step_doc="Divide a DataBundle element by a divisor 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 divisor BaseData object from the IoSources
+
+        divisor = basedata_from_sources(
+            io_sources=self.io_sources,
+            signal_source=self.configuration.get("divisor_source"),
+            units_source=self.configuration.get("divisor_units_source", None),
+            uncertainty_sources=self.configuration.get("divisor_uncertainties_sources", {}),
+        )
+
+        output: dict[str, DataBundle] = {}
+
+        # actual work happens here:
+        for key in self._normalised_processing_keys():
+            databundle = self.processing_data.get(key)
+            # divide the data
+            # Rely on BaseData.__truediv__ for units + uncertainty propagation
+            databundle["signal"] /= divisor
+            output[key] = databundle
+        return output