modacor 1.0.0__py3-none-any.whl

modacor/modules/base_modules/find_scale_factor1d.py

@@ -0,0 +1,373 @@
+# 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 2025, The MoDaCor team"
+__date__ = "12/12/2025"
+__status__ = "Development"
+
+__all__ = ["FindScaleFactor1D"]
+__version__ = "20251212.2"
+
+from pathlib import Path
+from typing import Dict
+
+import numpy as np
+from attrs import define
+from scipy.interpolate import interp1d
+from scipy.optimize import least_squares
+
+from modacor import ureg
+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
+
+# -------------------------------------------------------------------------
+# Small data containers (attrs, not namedtuple)
+# -------------------------------------------------------------------------
+
+
+@define(slots=True)
+class DependentData1D:
+    y: np.ndarray
+    sigma: np.ndarray
+    weights: np.ndarray
+
+
+@define(slots=True)
+class FitData1D:
+    x: np.ndarray
+    y_ref: np.ndarray
+    y_work: np.ndarray
+    sigma_ref: np.ndarray
+    sigma_work: np.ndarray
+    weights: np.ndarray
+
+
+# -------------------------------------------------------------------------
+# Helpers
+# -------------------------------------------------------------------------
+
+
+def _combined_sigma(bd: BaseData) -> np.ndarray:
+    if not bd.uncertainties:
+        return np.asarray(1.0)
+
+    sig2 = None
+    for u in bd.uncertainties.values():
+        arr = np.asarray(u, dtype=float)
+        sig2 = arr * arr if sig2 is None else sig2 + arr * arr
+    return np.sqrt(sig2)
+
+
+def _extract_dependent(bd: BaseData) -> DependentData1D:
+    if bd.rank_of_data != 1:
+        raise ValueError("Dependent BaseData must be rank-1.")
+
+    y = np.asarray(bd.signal, dtype=float).squeeze()
+    if y.ndim != 1:
+        raise ValueError("Dependent signal must be 1D.")
+
+    sigma = np.asarray(_combined_sigma(bd), dtype=float)
+    weights = np.asarray(bd.weights, dtype=float)
+
+    if sigma.size == 1:
+        sigma = np.full_like(y, float(sigma))
+    else:
+        sigma = sigma.squeeze()
+
+    if weights.size == 1:
+        weights = np.full_like(y, float(weights))
+    else:
+        weights = weights.squeeze()
+
+    if sigma.shape != y.shape or weights.shape != y.shape:
+        raise ValueError("Uncertainties and weights must match dependent signal shape.")
+
+    sigma = np.where(sigma <= 0.0, np.nan, sigma)
+
+    return DependentData1D(y=y, sigma=sigma, weights=weights)
+
+
+def _overlap_range(x1: np.ndarray, x2: np.ndarray) -> tuple[float, float]:
+    return float(max(np.nanmin(x1), np.nanmin(x2))), float(min(np.nanmax(x1), np.nanmax(x2)))
+
+
+def _prepare_fit_data(
+    *,
+    x_work: np.ndarray,
+    dep_work: DependentData1D,
+    x_ref: np.ndarray,
+    dep_ref: DependentData1D,
+    require_overlap: bool,
+    interpolation_kind: str,
+    fit_min: float,
+    fit_max: float,
+    use_weights: bool,
+) -> FitData1D:
+    ov_min, ov_max = _overlap_range(x_ref, x_work)
+    if require_overlap and not (ov_min < ov_max):
+        raise ValueError("No overlap between working and reference x-axes.")
+
+    lo = max(fit_min, ov_min) if require_overlap else fit_min
+    hi = min(fit_max, ov_max) if require_overlap else fit_max
+    if not lo < hi:
+        raise ValueError("Empty fit range after overlap constraints.")
+
+    mask = (x_ref >= lo) & (x_ref <= hi)
+    if np.count_nonzero(mask) < 2:
+        raise ValueError("Not enough points in fit window.")
+
+    x_fit = x_ref[mask]
+    y_ref = dep_ref.y[mask]
+    sigma_ref = dep_ref.sigma[mask]
+    weights_ref = dep_ref.weights[mask]
+
+    # sort working data
+    order = np.argsort(x_work)
+    x_work = x_work[order]
+    y_work = dep_work.y[order]
+    sigma_work = dep_work.sigma[order]
+    weights_work = dep_work.weights[order]
+
+    bounds_error = require_overlap
+    fill_value = None if bounds_error else "extrapolate"
+
+    interp_y = interp1d(
+        x_work, y_work, kind=interpolation_kind, bounds_error=bounds_error, fill_value=fill_value, assume_sorted=True
+    )
+    interp_sigma = interp1d(
+        x_work, sigma_work, kind="linear", bounds_error=bounds_error, fill_value=fill_value, assume_sorted=True
+    )
+    interp_w = interp1d(
+        x_work, weights_work, kind="linear", bounds_error=bounds_error, fill_value=fill_value, assume_sorted=True
+    )
+
+    y_work_i = interp_y(x_fit)
+    sigma_work_i = interp_sigma(x_fit)
+    weights_work_i = interp_w(x_fit)
+
+    weights = (weights_ref * weights_work_i) if use_weights else np.ones_like(y_ref)
+
+    valid = (
+        np.isfinite(y_ref)
+        & np.isfinite(y_work_i)
+        & np.isfinite(sigma_ref)
+        & (sigma_ref > 0)
+        & np.isfinite(sigma_work_i)
+        & (sigma_work_i >= 0)
+        & np.isfinite(weights)
+        & (weights > 0)
+    )
+
+    if np.count_nonzero(valid) < 2:
+        raise ValueError("Not enough valid points after masking.")
+
+    return FitData1D(
+        x=x_fit[valid],
+        y_ref=y_ref[valid],
+        y_work=y_work_i[valid],
+        sigma_ref=sigma_ref[valid],
+        sigma_work=sigma_work_i[valid],
+        weights=weights[valid],
+    )
+
+
+# -------------------------------------------------------------------------
+# Main ProcessStep
+# -------------------------------------------------------------------------
+
+
+class FindScaleFactor1D(ProcessStep):
+    documentation = ProcessStepDescriber(
+        calling_name="Scale 1D curve to reference (compute-only)",
+        calling_id="FindScaleFactor1D",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={
+            "scale_factor": ["signal", "uncertainties", "units"],
+            "scale_background": ["signal", "uncertainties", "units"],
+        },
+        arguments={
+            "signal_key": {
+                "type": str,
+                "default": "signal",
+                "doc": "BaseData key for the dependent variable signal.",
+            },
+            "independent_axis_key": {
+                "type": str,
+                "default": "Q",
+                "doc": "BaseData key for the independent axis.",
+            },
+            "scale_output_key": {
+                "type": str,
+                "default": "scale_factor",
+                "doc": "BaseData key to store the scale factor output.",
+            },
+            "background_output_key": {
+                "type": str,
+                "default": "scale_background",
+                "doc": "BaseData key to store the fitted background output.",
+            },
+            "fit_background": {
+                "type": bool,
+                "default": False,
+                "doc": "Whether to fit a constant background offset.",
+            },
+            "fit_min_val": {
+                "type": (float, int, type(None)),
+                "default": None,
+                "doc": "Minimum x-value for the fit (in fit_val_units).",
+            },
+            "fit_max_val": {
+                "type": (float, int, type(None)),
+                "default": None,
+                "doc": "Maximum x-value for the fit (in fit_val_units).",
+            },
+            "fit_val_units": {
+                "type": (str, type(None)),
+                "default": None,
+                "doc": "Units for fit_min_val/fit_max_val if provided.",
+            },
+            "require_overlap": {
+                "type": bool,
+                "default": True,
+                "doc": "Require overlapping x-range between reference and work data.",
+            },
+            "interpolation_kind": {
+                "type": str,
+                "default": "linear",
+                "doc": "Interpolation kind passed to scipy/numpy interpolation.",
+            },
+            "robust_loss": {
+                "type": str,
+                "default": "huber",
+                "doc": "Robust loss function name for the fit.",
+            },
+            "robust_fscale": {
+                "type": (float, int),
+                "default": 1.0,
+                "doc": "Robust loss scale parameter.",
+            },
+            "use_basedata_weights": {
+                "type": bool,
+                "default": True,
+                "doc": "Use BaseData weights when fitting.",
+            },
+        },
+        step_keywords=["scale", "calibration", "1D"],
+        step_doc="Compute scale factor between two 1D curves using robust least squares.",
+    )
+
+    def calculate(self) -> Dict[str, DataBundle]:
+        cfg = self.configuration
+        keys = self._normalised_processing_keys()
+        if len(keys) != 2:
+            raise ValueError("FindScaleFactor1D requires exactly two processing keys in 'with_processing_keys'.")
+        work_key, ref_key = keys
+
+        sig_key = cfg.get("signal_key", "signal")
+        axis_key = cfg.get("independent_axis_key", "Q")
+
+        work_db = self.processing_data[work_key]
+        ref_db = self.processing_data[ref_key]
+
+        y_work_bd = work_db[sig_key].copy(with_axes=True)
+        y_ref_bd = ref_db[sig_key].copy(with_axes=True)
+
+        x_work_bd = work_db[axis_key].copy(with_axes=False)
+        x_ref_bd = ref_db[axis_key].copy(with_axes=False)
+
+        if x_work_bd.units != x_ref_bd.units:
+            x_work_bd.to_units(x_ref_bd.units)
+
+        x_work = np.asarray(x_work_bd.signal, dtype=float).squeeze()
+        x_ref = np.asarray(x_ref_bd.signal, dtype=float).squeeze()
+
+        dep_work = _extract_dependent(y_work_bd)
+        dep_ref = _extract_dependent(y_ref_bd)
+
+        fit_min = cfg.get("fit_min_val")
+        fit_max = cfg.get("fit_max_val")
+
+        fit_units = cfg.get("fit_val_units") or x_ref_bd.units
+        if fit_min is not None:
+            fit_min = ureg.Quantity(fit_min, fit_units).to(x_ref_bd.units).magnitude
+        else:
+            fit_min = np.nanmin(x_ref)
+
+        if fit_max is not None:
+            fit_max = ureg.Quantity(fit_max, fit_units).to(x_ref_bd.units).magnitude
+        else:
+            fit_max = np.nanmax(x_ref)
+
+        fit_data = _prepare_fit_data(
+            x_work=x_work,
+            dep_work=dep_work,
+            x_ref=x_ref,
+            dep_ref=dep_ref,
+            require_overlap=cfg.get("require_overlap", True),
+            interpolation_kind=cfg.get("interpolation_kind", "linear"),
+            fit_min=float(fit_min),
+            fit_max=float(fit_max),
+            use_weights=cfg.get("use_basedata_weights", True),
+        )
+
+        fit_background = bool(cfg.get("fit_background", False))
+
+        def residuals(p: np.ndarray) -> np.ndarray:
+            scale = p[0]
+            background = p[1] if fit_background else 0.0
+            model = scale * fit_data.y_work + background
+            sigma = np.sqrt(fit_data.sigma_ref**2 + (scale * fit_data.sigma_work) ** 2)
+            r = (fit_data.y_ref - model) / sigma
+            return np.sqrt(fit_data.weights) * r
+
+        if fit_background:
+            X = np.column_stack([fit_data.y_work, np.ones_like(fit_data.y_work)])
+            x0, *_ = np.linalg.lstsq(X, fit_data.y_ref, rcond=None)
+        else:
+            denom = np.dot(fit_data.y_work, fit_data.y_work) or 1.0
+            x0 = np.array([np.dot(fit_data.y_ref, fit_data.y_work) / denom])
+
+        res = least_squares(
+            residuals,
+            x0=x0,
+            loss=cfg.get("robust_loss", "huber"),
+            f_scale=float(cfg.get("robust_fscale", 1.0)),
+        )
+
+        J = res.jac
+        dof = max(1, len(res.fun) - len(res.x))
+        s_sq = np.sum(res.fun**2) / dof
+
+        cov = s_sq * np.linalg.pinv(J.T @ J)
+        sig_params = np.sqrt(np.clip(np.diag(cov), 0.0, np.inf))
+
+        scale = float(res.x[0])
+        scale_sigma = float(sig_params[0])
+
+        out_key = cfg.get("scale_output_key", "scale_factor")
+        work_db[out_key] = BaseData(
+            signal=np.array([scale]),
+            units="dimensionless",
+            uncertainties={"propagate_to_all": np.array([scale_sigma])},
+            rank_of_data=0,
+        )
+
+        if fit_background:
+            bg_key = cfg.get("background_output_key", "scale_background")
+            work_db[bg_key] = BaseData(
+                signal=np.array([float(res.x[1])]),
+                units=y_ref_bd.units,
+                uncertainties={"propagate_to_all": np.array([sig_params[1]])},
+                rank_of_data=0,
+            )
+
+        return {work_key: work_db}

modacor/modules/base_modules/multiply.py

@@ -0,0 +1,77 @@
+# 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__ = ["Multiply"]
+__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 Multiply(ProcessStep):
+    """
+    Multiply a DataBundle by a BaseData from an IoSource
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Multiply by IoSource data",
+        calling_id="MultiplyBySourceData",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={"signal": ["signal", "uncertainties", "units"]},
+        arguments={
+            "multiplier_source": {
+                "type": str,
+                "default": None,
+                "doc": "IoSources key for the multiplier signal.",
+            },
+            "multiplier_units_source": {
+                "type": str,
+                "default": None,
+                "doc": "IoSources key for multiplier units metadata.",
+            },
+            "multiplier_uncertainties_sources": {
+                "type": dict,
+                "default": {},
+                "doc": "Mapping of uncertainty name to IoSources key.",
+            },
+        },
+        step_keywords=["multiply", "scalar", "array"],
+        step_doc="Multiply a DataBundle element by a multiplier 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 multiplier BaseData object from the IoSources
+        multiplier = basedata_from_sources(
+            io_sources=self.io_sources,
+            signal_source=self.configuration.get("multiplier_source"),
+            units_source=self.configuration.get("multiplier_units_source", None),
+            uncertainty_sources=self.configuration.get("multiplier_uncertainties_sources", {}),
+        )
+
+        output: dict[str, DataBundle] = {}
+        # actual work happens here:
+        for key in self._normalised_processing_keys():
+            databundle = self.processing_data.get(key)
+            # multiply the data
+            databundle["signal"] *= multiplier
+            output[key] = databundle
+        return output

modacor/modules/base_modules/multiply_databundles.py

@@ -0,0 +1,73 @@
+# 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__ = "12/12/2025"
+__status__ = "Development"  # "Development", "Production"
+# end of header and standard imports
+
+__all__ = ["MultiplyDatabundles"]
+__version__ = "20251212.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 MultiplyDatabundles(ProcessStep):
+    """
+    Multiply a DataBundle with another DataBundle, useful for scaling or combining data
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Multiply another DataBundle",
+        calling_id="MultiplyDatabundles",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={"signal": ["signal", "uncertainties", "units"]},
+        arguments={
+            "multiplicand_data_key": {
+                "type": str,
+                "default": "signal",
+                "doc": "BaseData key to modify in the multiplicand DataBundle.",
+            },
+            "multiplier_data_key": {
+                "type": str,
+                "default": "signal",
+                "doc": "BaseData key to read from the multiplier DataBundle.",
+            },
+        },
+        step_keywords=["multiply", "scaling", "databundle"],
+        step_doc="Multiply a DataBundle element using another DataBundle",
+        step_reference="DOI 10.1088/0953-8984/25/38/383201",
+        step_note="""
+            This multiplies one DataBundle's signal with another, useful for scaling or combining data.
+            'with_processing_keys' in the configuration should contain two keys, the operation
+            will multiply the first key's DataBundle by the second key's DataBundle.
+        """,
+    )
+
+    def calculate(self) -> dict[str, DataBundle]:
+        # actual work happens here:
+        keys = self._normalised_processing_keys()
+        assert len(keys) == 2, (
+            "MultiplyDatabundles requires exactly two processing keys in 'with_processing_keys': "
+            "the first is the multiplicand, the second is the multiplier."
+        )
+        multiplicand_key = keys[0]
+        multiplicand = self.processing_data.get(multiplicand_key)
+        multiplier = self.processing_data.get(keys[1])
+        # multiply the data
+        multiplicand[self.configuration["multiplicand_data_key"]] *= multiplier[
+            self.configuration["multiplier_data_key"]
+        ]
+        output: dict[str, DataBundle] = {multiplicand_key: multiplicand}
+        return output

modacor/modules/base_modules/poisson_uncertainties.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+__coding__ = "utf-8"
+__authors__ = ["Malte Storm", "Tim Snow", "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
+
+__version__ = "20250522.1"
+__all__ = ["PoissonUncertainties"]
+
+from pathlib import Path
+
+import numpy as np
+
+# from modacor.dataclasses.databundle import DataBundle
+from modacor.dataclasses.process_step import ProcessStep
+from modacor.dataclasses.process_step_describer import ProcessStepDescriber
+
+# from typing import Any
+
+
+class PoissonUncertainties(ProcessStep):
+    """
+    Adding Poisson uncertainties to the data
+    """
+
+    documentation = ProcessStepDescriber(
+        calling_name="Add Poisson Uncertainties",
+        calling_id="PoissonUncertainties",
+        calling_module_path=Path(__file__),
+        calling_version=__version__,
+        required_data_keys=["signal"],
+        modifies={"variances": ["Poisson"]},
+        arguments={
+            "with_processing_keys": {
+                "type": list,
+                "required": True,
+                "default": None,
+                "doc": "ProcessingData keys to update with Poisson variances.",
+            },
+        },
+        step_keywords=["uncertainties", "Poisson"],
+        step_doc="Add Poisson uncertainties to the data",
+        step_reference="DOI 10.1088/0953-8984/25/38/383201",
+        step_note="This is a simple Poisson uncertainty calculation based on the signal intensity",
+    )
+
+    def calculate(self):
+        """
+        Calculate the Poisson uncertainties for the data
+        """
+
+        # Get the data
+        data = self.processing_data
+        output = {}
+        for key in self._normalised_processing_keys():
+            databundle = data.get(key)
+            signal = databundle["signal"].signal
+
+            # Add the variance to the data
+            databundle["signal"].variances["Poisson"] = np.clip(signal, 1, None)
+            output[key] = databundle
+        return output