essreduce 25.11.2__py3-none-any.whl → 25.11.4__py3-none-any.whl

ess/reduce/__init__.py

@@ -4,7 +4,7 @@
 
 import importlib.metadata
 
-from . import nexus, time_of_flight, uncertainty
+from . import nexus, normalization, time_of_flight, uncertainty
 
 try:
     __version__ = importlib.metadata.version("essreduce")
@@ -13,4 +13,4 @@ except importlib.metadata.PackageNotFoundError:
 
 del importlib
 
-__all__ = ["nexus", "time_of_flight", "uncertainty"]
+__all__ = ["nexus", "normalization", "time_of_flight", "uncertainty"]

ess/reduce/live/raw.py

@@ -21,7 +21,7 @@ options:
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
-from math import ceil
+from math import ceil, prod
 from typing import Literal, NewType
 
 import numpy as np
@@ -138,6 +138,139 @@ class Histogrammer:
         return self._hist(replicated, coords=self._coords) / self.replicas
 
 
+class LogicalView:
+    """
+    Logical view for detector data.
+
+    Implements a view by applying a user-defined transform (e.g., fold or slice
+    operations) optionally followed by reduction (summing) over specified dimensions.
+    Transformation and reduction must be specified separately for `LogicalView` to
+    construct a mapping from output indices to input indices. So `transform` must not
+    perform any reductions.
+
+    This class provides both data transformation (__call__) and index mapping
+    (input_indices) using the same transform, ensuring consistency for ROI filtering.
+    """
+
+    def __init__(
+        self,
+        transform: Callable[[sc.DataArray], sc.DataArray],
+        reduction_dim: str | list[str] | None = None,
+        input_sizes: dict[str, int] | None = None,
+    ):
+        """
+        Create a logical view.
+
+        Parameters
+        ----------
+        transform:
+            Callable that transforms input data by reshaping or selecting pixels.
+            Examples:
+            - Fold: lambda da: da.fold('x', {'x': 512, 'x_bin': 2})
+            - Slice: lambda da: da['z', 0]  (select front layer of volume)
+            - Combined: lambda da: da.fold('x', {'x': 4, 'z': 8})['z', 0]
+        reduction_dim:
+            Dimension(s) to sum over after applying transform. If None or empty,
+            no reduction is performed (pure transform).
+            Example: 'x_bin' or ['x_bin', 'y_bin']
+        input_sizes:
+            Dictionary defining the input dimension sizes.
+            Required for input_indices().
+            If not provided, input_indices() will raise an error.
+            When used with RollingDetectorView, this is automatically
+            inferred from detector_number.
+        """
+        self._transform = transform
+        if reduction_dim is None:
+            self._reduction_dim = []
+        elif isinstance(reduction_dim, str):
+            self._reduction_dim = [reduction_dim]
+        else:
+            self._reduction_dim = reduction_dim
+        self._input_sizes = input_sizes
+
+    @property
+    def replicas(self) -> int:
+        """Number of replicas. Always 1 for LogicalView."""
+        return 1
+
+    def __call__(self, da: sc.DataArray) -> sc.DataArray:
+        """
+        Apply transform and optionally sum over reduction dimensions.
+
+        Parameters
+        ----------
+        da:
+            Data to downsample.
+
+        Returns
+        -------
+        :
+            Transformed (and optionally reduced) data array.
+        """
+        transformed = self._transform(da)
+        if self._reduction_dim:
+            return transformed.sum(self._reduction_dim)
+        return transformed
+
+    def input_indices(self) -> sc.DataArray:
+        """
+        Create index mapping for ROI filtering.
+
+        Returns a DataArray mapping output pixels to input indices (as indices into
+        the flattened input array). If reduction dimensions are specified, returns
+        binned data where each output pixel contains a list of contributing input
+        indices. If no reduction, returns dense indices (1:1 mapping).
+
+        Returns
+        -------
+        :
+            DataArray mapping output pixels to input indices.
+
+        Raises
+        ------
+        ValueError:
+            If input_sizes was not provided during initialization.
+        """
+        if self._input_sizes is None:
+            raise ValueError(
+                "input_sizes is required for input_indices(). "
+                "Provide it during LogicalView initialization."
+            )
+
+        # Create sequential indices (0, 1, 2, ...) and fold to input shape
+        total_size = prod(self._input_sizes.values())
+        indices = sc.arange('_temp', total_size, dtype='int64', unit=None)
+        indices = indices.fold(dim='_temp', sizes=self._input_sizes)
+
+        # Apply transform to get the grouping structure
+        transformed = self._transform(sc.DataArray(data=indices))
+
+        if not self._reduction_dim:
+            # No reduction: 1:1 mapping, return dense indices
+            return sc.DataArray(data=transformed.data)
+
+        # Flatten reduction dimensions to a single dimension.
+        # First transpose to make reduction dims contiguous at the end.
+        output_dims = [d for d in transformed.dims if d not in self._reduction_dim]
+        transformed = transformed.transpose(output_dims + self._reduction_dim)
+        transformed = transformed.flatten(dims=self._reduction_dim, to='_reduction')
+
+        # Convert dense array to binned structure where each output pixel
+        # contains a bin with the indices of contributing input pixels.
+        bin_size = transformed.sizes['_reduction']
+        output_shape = [transformed.sizes[d] for d in output_dims]
+        data_flat = transformed.data.flatten(to='_flat')
+        begin = sc.array(
+            dims=output_dims,
+            values=np.arange(0, data_flat.size, bin_size, dtype=np.int64).reshape(
+                output_shape
+            ),
+            unit=None,
+        )
+        return sc.DataArray(sc.bins(begin=begin, dim='_flat', data=data_flat))
+
+
 class Detector:
     def __init__(self, detector_number: sc.Variable):
         self._data = sc.DataArray(
@@ -220,6 +353,48 @@ class RollingDetectorView(Detector):
         self._cumulative: sc.DataArray
         self.clear_counts()
 
+    @staticmethod
+    def with_logical_view(
+        *,
+        detector_number: sc.Variable,
+        window: int,
+        transform: Callable[[sc.DataArray], sc.DataArray],
+        reduction_dim: str | list[str] | None = None,
+    ) -> RollingDetectorView:
+        """
+        Create a RollingDetectorView with a LogicalView projection.
+
+        This factory method creates a LogicalView with input_sizes
+        automatically inferred from detector_number.sizes.
+
+        Parameters
+        ----------
+        detector_number:
+            Detector number for each pixel.
+        window:
+            Size of the rolling window.
+        transform:
+            Transform function for the LogicalView.
+        reduction_dim:
+            Reduction dimension(s) for the LogicalView. If None or empty,
+            no reduction is performed (pure transform).
+
+        Returns
+        -------
+        :
+            RollingDetectorView with LogicalView projection.
+        """
+        view = LogicalView(
+            transform=transform,
+            reduction_dim=reduction_dim,
+            input_sizes=dict(detector_number.sizes),
+        )
+        return RollingDetectorView(
+            detector_number=detector_number,
+            window=window,
+            projection=view,
+        )
+
     @property
     def max_window(self) -> int:
         return self._window
@@ -249,9 +424,11 @@ class RollingDetectorView(Detector):
     def make_roi_filter(self) -> roi.ROIFilter:
         """Return a ROI filter operating via the projection plane of the view."""
         norm = 1.0
-        if isinstance(self._projection, Histogrammer):
+        # Use duck typing: check if projection has input_indices method
+        if hasattr(self._projection, 'input_indices'):
             indices = self._projection.input_indices()
-            norm = self._projection.replicas
+            # Get replicas property if it exists (Histogrammer has it, default to 1.0)
+            norm = getattr(self._projection, 'replicas', 1.0)
         else:
             indices = sc.ones(sizes=self.data.sizes, dtype='int32', unit=None)
             indices = sc.cumsum(indices, mode='exclusive')
@@ -292,10 +469,11 @@ class RollingDetectorView(Detector):
                     if not sc.identical(det_num, self.detector_number):
                         raise sc.CoordError("Mismatching detector numbers in weights.")
                 weights = weights.data
-        if isinstance(self._projection, Histogrammer):
+        # Use duck typing: check for apply_full method (Histogrammer)
+        if hasattr(self._projection, 'apply_full'):
             xs = self._projection.apply_full(weights)  # Use all replicas
         elif self._projection is not None:
-            xs = self._projection(weights)
+            xs = self._projection(weights)  # LogicalDownsampler or callable
         else:
             xs = weights.copy()
         nonempty = xs.values[xs.values > 0]

ess/reduce/normalization.py

@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2025 Scipp contributors (https://github.com/scipp)
+"""Normalization routines for neutron data reduction."""
+
+import functools
+
+import scipp as sc
+
+from .uncertainty import UncertaintyBroadcastMode, broadcast_uncertainties
+
+
+def normalize_by_monitor_histogram(
+    detector: sc.DataArray,
+    *,
+    monitor: sc.DataArray,
+    uncertainty_broadcast_mode: UncertaintyBroadcastMode,
+) -> sc.DataArray:
+    """Normalize detector data by a normalized histogrammed monitor.
+
+    This normalization accounts for both the (wavelength) profile of the incident beam
+    and the integrated neutron flux, meaning measurement duration and source strength.
+
+    - For *event* detectors, the monitor values are mapped to the detector
+      using :func:`scipp.lookup`. That is, for detector event :math:`d_i`,
+      :math:`m_i` is the monitor bin value at the same coordinate.
+    - For *histogram* detectors, the monitor is rebinned using to the detector
+      binning using :func:`scipp.rebin`. Thus, detector value :math:`d_i` and
+      monitor value :math:`m_i` correspond to the same bin.
+
+    In both cases, let :math:`x_i` be the lower bound of monitor bin :math:`i`
+    and let :math:`\\Delta x_i = x_{i+1} - x_i` be the width of that bin.
+
+    The detector is normalized according to
+
+    .. math::
+
+        d_i^\\text{Norm} = \\frac{d_i}{m_i} \\Delta x_i
+
+    Parameters
+    ----------
+    detector:
+        Input detector data.
+        Must have a coordinate named ``monitor.dim``, that is, the single
+        dimension name of the **monitor**.
+    monitor:
+        A histogrammed monitor.
+        Must be one-dimensional and have a dimension coordinate, typically "wavelength".
+    uncertainty_broadcast_mode:
+        Choose how uncertainties of the monitor are broadcast to the sample data.
+
+    Returns
+    -------
+    :
+        ``detector`` normalized by ``monitor``.
+        If the monitor has masks or contains non-finite values, the output has a mask
+        called '_monitor_mask' constructed from the monitor masks and non-finite values.
+
+    See also
+    --------
+    normalize_by_monitor_integrated:
+        Normalize by an integrated monitor.
+    """
+    _check_monitor_range_contains_detector(monitor=monitor, detector=detector)
+
+    dim = monitor.dim
+
+    if detector.bins is None:
+        monitor = monitor.rebin({dim: detector.coords[dim]})
+    detector = _mask_detector_for_norm(detector=detector, monitor=monitor)
+    coord = monitor.coords[dim]
+    delta_w = sc.DataArray(coord[1:] - coord[:-1], masks=monitor.masks)
+    norm = broadcast_uncertainties(
+        monitor / delta_w, prototype=detector, mode=uncertainty_broadcast_mode
+    )
+
+    if detector.bins is None:
+        return detector / norm.rebin({dim: detector.coords[dim]})
+    return detector.bins / sc.lookup(norm, dim=dim)
+
+
+def normalize_by_monitor_integrated(
+    detector: sc.DataArray,
+    *,
+    monitor: sc.DataArray,
+    uncertainty_broadcast_mode: UncertaintyBroadcastMode,
+) -> sc.DataArray:
+    """Normalize detector data by an integrated monitor.
+
+    This normalization accounts only for the integrated neutron flux,
+    meaning measurement duration and source strength.
+    It does *not* account for the (wavelength) profile of the incident beam.
+    For that, see :func:`normalize_by_monitor_histogram`.
+
+    Let :math:`d_i` be a detector event or the counts in a detector bin.
+    The normalized detector is
+
+    .. math::
+
+        d_i^\\text{Norm} = \\frac{d_i}{\\sum_j\\, m_j}
+
+    where :math:`m_j` is the monitor counts in bin :math:`j`.
+    Note that this is not a true integral but only a sum over monitor events.
+
+    The result depends on the range of the monitor but not its
+    binning within that range.
+
+    Parameters
+    ----------
+    detector:
+        Input detector data.
+    monitor:
+        A histogrammed monitor.
+        Must be one-dimensional and have a dimension coordinate, typically "wavelength".
+    uncertainty_broadcast_mode:
+        Choose how uncertainties of the monitor are broadcast to the sample data.
+
+    Returns
+    -------
+    :
+        `detector` normalized by a monitor.
+        If the monitor has masks or contains non-finite values, the output has a mask
+        called '_monitor_mask' constructed from the monitor masks and non-finite values.
+
+    See also
+    --------
+    normalize_by_monitor_histogram:
+        Normalize by a monitor histogram.
+    """
+    _check_monitor_range_contains_detector(monitor=monitor, detector=detector)
+    detector = _mask_detector_for_norm(detector=detector, monitor=monitor)
+    norm = monitor.nansum().data
+    norm = broadcast_uncertainties(
+        norm, prototype=detector, mode=uncertainty_broadcast_mode
+    )
+    return detector / norm
+
+
+def _check_monitor_range_contains_detector(
+    *, monitor: sc.DataArray, detector: sc.DataArray
+) -> None:
+    dim = monitor.dim
+    if not monitor.coords.is_edges(dim):
+        raise sc.CoordError(
+            f"Monitor coordinate '{dim}' must be bin-edges to integrate the monitor."
+        )
+
+    # Prefer a bin coord over an event coord because this makes the behavior for binned
+    # and histogrammed data consistent. If we used an event coord, we might allow a
+    # monitor range that is less than the detector bins which is fine for the events,
+    # but would be wrong if the detector was subsequently histogrammed.
+    if (det_coord := detector.coords.get(dim)) is not None:
+        lo = det_coord[dim, :-1].nanmin()
+        hi = det_coord[dim, 1:].nanmax()
+    elif (det_coord := detector.bins.coords.get(dim)) is not None:
+        lo = det_coord.nanmin()
+        hi = det_coord.nanmax()
+    else:
+        raise sc.CoordError(
+            f"Missing '{dim}' coordinate in detector for monitor normalization."
+        )
+
+    if monitor.coords[dim].min() > lo or monitor.coords[dim].max() < hi:
+        raise ValueError(
+            f"Cannot normalize by monitor: The {dim} range of the monitor "
+            f"({monitor.coords[dim].min():c} to {monitor.coords[dim].max():c}) "
+            f"is smaller than the range of the detector ({lo:c} to {hi:c})."
+        )
+
+
+def _mask_detector_for_norm(
+    *, detector: sc.DataArray, monitor: sc.DataArray
+) -> sc.DataArray:
+    """Mask the detector where the monitor is masked.
+
+    For performance, this applies the monitor mask to the detector bins.
+    This can lead to masking more events than strictly necessary if we
+    used an event mask.
+    """
+    dim = monitor.dim
+
+    if (monitor_mask := _monitor_mask(monitor)) is None:
+        return detector
+
+    if (detector_coord := detector.coords.get(monitor.dim)) is not None:
+        # Apply the mask to the bins or a dense detector.
+        # Use rebin to reshape the mask to the detector.
+        mask = sc.DataArray(monitor_mask, coords={dim: monitor.coords[dim]}).rebin(
+            {dim: detector_coord}
+        ).data != sc.scalar(0, unit=None)
+        return detector.assign_masks({"_monitor_mask": mask})
+
+    # else: Apply the mask to the events.
+    if dim not in detector.bins.coords:
+        raise sc.CoordError(
+            f"Detector must have coordinate '{dim}' to mask by monitor."
+        )
+    event_mask = sc.lookup(
+        sc.DataArray(monitor_mask, coords={dim: monitor.coords[dim]})
+    )[detector.bins.coords[dim]]
+    return detector.bins.assign_masks({"_monitor_mask": event_mask})
+
+
+def _monitor_mask(monitor: sc.DataArray) -> sc.Variable | None:
+    """Mask nonfinite and zero monitor values and combine all masks."""
+    masks = list(monitor.masks.values())
+
+    finite = sc.isfinite(monitor.data)
+    nonzero = monitor.data != sc.scalar(0, unit=monitor.unit)
+    valid = finite & nonzero
+    if not valid.all():
+        masks.append(~valid)
+
+    if not masks:
+        return None
+    return functools.reduce(sc.logical_or, masks)

{essreduce-25.11.2.dist-info → essreduce-25.11.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: essreduce
-Version: 25.11.2
+Version: 25.11.4
 Summary: Common data reduction tools for the ESS facility
 Author: Scipp contributors
 License-Expression: BSD-3-Clause

{essreduce-25.11.2.dist-info → essreduce-25.11.4.dist-info}/RECORD

@@ -1,5 +1,6 @@
-ess/reduce/__init__.py,sha256=o1pWRP9YGwTukM_k-qlG6KcoXOpMb0PDVH59vod12lw,419
+ess/reduce/__init__.py,sha256=9iqQ57K3stwyujDzOk30hj7WqZt1Ycnb9AVDDDmk3K0,451
 ess/reduce/logging.py,sha256=6n8Czq4LZ3OK9ENlKsWSI1M3KvKv6_HSoUiV4__IUlU,357
+ess/reduce/normalization.py,sha256=B4O5W3CV_ti-zeU7tyQEAXk5pCUebZ0BG30YN2I3TyY,7844
 ess/reduce/parameter.py,sha256=4sCfoKOI2HuO_Q7JLH_jAXnEOFANSn5P3NdaOBzhJxc,4635
 ess/reduce/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ess/reduce/streaming.py,sha256=zbqxQz5dASDq4ZVyx-TdbapBXMyBttImCYz_6WOj4pg,17978
@@ -9,7 +10,7 @@ ess/reduce/workflow.py,sha256=738-lcdgsORYfQ4A0UTk2IgnbVxC3jBdpscpaOFIpdc,3114
 ess/reduce/data/__init__.py,sha256=uDtqkmKA_Zwtj6II25zntz9T812XhdCn3tktYev4uyY,486
 ess/reduce/data/_registry.py,sha256=50qY36y5gd2i3JP0Ks6bXApGcW6l70qA6riO0m9Bz4o,11475
 ess/reduce/live/__init__.py,sha256=jPQVhihRVNtEDrE20PoKkclKV2aBF1lS7cCHootgFgI,204
-ess/reduce/live/raw.py,sha256=d86s5fBjdf6tI_FWNMG4ZG67GCY2JADOobrinncNIjE,24367
+ess/reduce/live/raw.py,sha256=CkPqp4VMNvj0IcFPp1J0n7sVt5PNKdIXnDlALCg9W_Q,31031
 ess/reduce/live/roi.py,sha256=Hs-pW98k41WU6Kl3UQ41kQawk80c2QNOQ_WNctLzDPE,3795
 ess/reduce/live/workflow.py,sha256=bsbwvTqPhRO6mC__3b7MgU7DWwAnOvGvG-t2n22EKq8,4285
 ess/reduce/nexus/__init__.py,sha256=xXc982vZqRba4jR4z5hA2iim17Z7niw4KlS1aLFbn1Q,1107
@@ -40,9 +41,9 @@ ess/reduce/widgets/_spinner.py,sha256=2VY4Fhfa7HMXox2O7UbofcdKsYG-AJGrsgGJB85nDX
 ess/reduce/widgets/_string_widget.py,sha256=iPAdfANyXHf-nkfhgkyH6gQDklia0LebLTmwi3m-iYQ,1482
 ess/reduce/widgets/_switchable_widget.py,sha256=fjKz99SKLhIF1BLgGVBSKKn3Lu_jYBwDYGeAjbJY3Q8,2390
 ess/reduce/widgets/_vector_widget.py,sha256=aTaBqCFHZQhrIoX6-sSqFWCPePEW8HQt5kUio8jP1t8,1203
-essreduce-25.11.2.dist-info/licenses/LICENSE,sha256=nVEiume4Qj6jMYfSRjHTM2jtJ4FGu0g-5Sdh7osfEYw,1553
-essreduce-25.11.2.dist-info/METADATA,sha256=BiPKZU7f3M7bof_N1dQWwIfG8TAEHATY18zU6s4ihxk,1937
-essreduce-25.11.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-essreduce-25.11.2.dist-info/entry_points.txt,sha256=PMZOIYzCifHMTe4pK3HbhxUwxjFaZizYlLD0td4Isb0,66
-essreduce-25.11.2.dist-info/top_level.txt,sha256=0JxTCgMKPLKtp14wb1-RKisQPQWX7i96innZNvHBr-s,4
-essreduce-25.11.2.dist-info/RECORD,,
+essreduce-25.11.4.dist-info/licenses/LICENSE,sha256=nVEiume4Qj6jMYfSRjHTM2jtJ4FGu0g-5Sdh7osfEYw,1553
+essreduce-25.11.4.dist-info/METADATA,sha256=Foul2luwyG1rhulA2Q5KlXbxtrYFGlp99ApSkGjAKOE,1937
+essreduce-25.11.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+essreduce-25.11.4.dist-info/entry_points.txt,sha256=PMZOIYzCifHMTe4pK3HbhxUwxjFaZizYlLD0td4Isb0,66
+essreduce-25.11.4.dist-info/top_level.txt,sha256=0JxTCgMKPLKtp14wb1-RKisQPQWX7i96innZNvHBr-s,4
+essreduce-25.11.4.dist-info/RECORD,,