essdiffraction 23.12.0__py3-none-any.whl

ess/diffraction/filtering.py

@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+# @author Jan-Lukas Wynen
+"""
+Prototype for event filtering.
+
+IMPORTANT Will be moved to a different place and potentially modified.
+"""
+from contextlib import contextmanager
+from numbers import Real
+
+import scipp as sc
+
+from .types import FilteredData, RawData, RunType, TofCroppedData, ValidTofRange
+
+
+def _equivalent_bin_indices(a, b) -> bool:
+    a_begin = a.bins.constituents['begin'].flatten(to='')
+    a_end = a.bins.constituents['end'].flatten(to='')
+    b_begin = b.bins.constituents['begin'].flatten(to='')
+    b_end = b.bins.constituents['end'].flatten(to='')
+    non_empty = a_begin != a_end
+    return (
+        sc.all((a_begin == b_begin)[non_empty]).value
+        and sc.all((a_end == b_end)[non_empty]).value
+    )
+
+
+@contextmanager
+def _temporary_bin_coord(data: sc.DataArray, name: str, coord: sc.Variable) -> None:
+    if not _equivalent_bin_indices(data, coord):
+        raise ValueError("data and coord do not have equivalent bin indices")
+    coord = sc.bins(
+        data=coord.bins.constituents['data'],
+        begin=data.bins.coords['pulse_time'].bins.constituents['begin'],
+        end=data.bins.coords['pulse_time'].bins.constituents['end'],
+        dim=coord.bins.constituents['dim'],
+    )
+    data.bins.coords[name] = coord
+    yield
+    del data.bins.coords[name]
+
+
+# TODO non-monotonic proton charge -> raise?
+def _with_pulse_time_edges(da: sc.DataArray, dim: str) -> sc.DataArray:
+    pulse_time = da.coords[dim]
+    one = sc.scalar(1, dtype='int64', unit=pulse_time.unit)
+    lo = pulse_time[0] - one
+    hi = pulse_time[-1] + one
+    mid = sc.midpoints(pulse_time)
+    da.coords[dim] = sc.concat([lo, mid, hi], dim)
+    return da
+
+
+def remove_bad_pulses(
+    data: sc.DataArray, *, proton_charge: sc.DataArray, threshold_factor: Real
+) -> sc.DataArray:
+    """
+    assumes that there are bad pulses
+    """
+    min_charge = proton_charge.data.mean() * threshold_factor
+    good_pulse = _with_pulse_time_edges(proton_charge >= min_charge, proton_charge.dim)
+    with _temporary_bin_coord(
+        data,
+        'good_pulse',
+        sc.lookup(good_pulse, good_pulse.dim)[data.bins.coords[good_pulse.dim]],
+    ):
+        filtered = data.group(sc.array(dims=['good_pulse'], values=[True]))
+    filtered = filtered.squeeze('good_pulse').copy(deep=False)
+    del filtered.coords['good_pulse']
+    return filtered
+
+
+def crop_tof(
+    data: RawData[RunType], tof_range: ValidTofRange
+) -> TofCroppedData[RunType]:
+    """Remove events outside the specified TOF range.
+
+    Parameters
+    ----------
+    data:
+        Data to be cropped.
+        Expected to have a coordinate called `'tof'`.
+    tof_range:
+        1d, len-2 variable containing the lower and upper bounds for
+        time-of-flight.
+
+    Returns
+    -------
+    :
+        Cropped data.
+    """
+    return TofCroppedData[RunType](
+        data.bin(tof=tof_range.to(unit=data.coords['tof'].unit))
+    )
+
+
+def filter_events(data: TofCroppedData[RunType]) -> FilteredData[RunType]:
+    """Remove bad events.
+
+    Attention
+    ---------
+    This function currently does nothing because it is unclear how to filter
+    events at ESS.
+    In the future, this function will filter out events that
+    cannot be used for analysis.
+
+    Parameters
+    ----------
+    data:
+        Input events to be filtered.
+
+    Returns
+    -------
+    :
+        `data` with bad events removed.
+    """
+    # TODO this needs to filter by proton charge once we know how
+    return FilteredData[RunType](data)
+
+
+providers = (
+    crop_tof,
+    filter_events,
+)
+"""Sciline providers for event filtering."""

ess/diffraction/grouping.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+
+from scippneutron.conversion.graph import beamline
+
+from .types import (
+    DspacingBins,
+    DspacingData,
+    DspacingHistogram,
+    FocussedData,
+    NormalizedByVanadium,
+    RunType,
+    TwoThetaBins,
+)
+
+
+def group_by_two_theta(
+    data: DspacingData[RunType], edges: TwoThetaBins
+) -> FocussedData[RunType]:
+    """
+    Group data into two_theta bins.
+
+    Parameters
+    ----------
+    data:
+        Input data array with events. Must contain a coord called 'two_theta'
+        or coords that can be used to compute it.
+    edges:
+        Bin edges in two_theta. `data` is grouped into those bins.
+
+    Returns
+    -------
+    :
+        `data` grouped into two_theta bins.
+    """
+    out = data.transform_coords('two_theta', graph=beamline.beamline(scatter=True))
+    return FocussedData[RunType](
+        out.bin(two_theta=edges.to(unit=out.coords['two_theta'].unit, copy=False))
+    )
+
+
+def merge_all_pixels(data: DspacingData[RunType]) -> FocussedData[RunType]:
+    """Combine all pixels (spectra) of the detector.
+
+    Parameters
+    ----------
+    data:
+        Input data with a `'spectrum'` dimension.
+
+    Returns
+    -------
+    :
+        The input without a `'spectrum'` dimension.
+    """
+    return FocussedData(data.bins.concat('spectrum'))
+
+
+def finalize_histogram(
+    data: NormalizedByVanadium, edges: DspacingBins
+) -> DspacingHistogram:
+    """Finalize the d-spacing histogram.
+
+    Histograms the input data into the given d-spacing bins.
+
+    Parameters
+    ----------
+    data:
+        Data to be histogrammed.
+    edges:
+        Bin edges in d-spacing.
+
+    Returns
+    -------
+    :
+        Histogrammed data.
+    """
+    return DspacingHistogram(data.hist(dspacing=edges))
+
+
+providers = (merge_all_pixels, finalize_histogram)
+"""Sciline providers for grouping pixels."""

ess/diffraction/logging.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+
+import logging
+
+
+def get_logger() -> logging.Logger:
+    """Return the logger for ess.diffraction.
+
+    Returns
+    -------
+    :
+        The requested logger.
+    """
+    return logging.getLogger('scipp.ess.diffraction')

ess/diffraction/powder/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+"""
+Components for powder diffraction experiments.
+"""
+from .conversion import providers as conversion_providers
+from .conversion import to_dspacing_with_calibration
+from .correction import merge_calibration
+
+providers = (*conversion_providers,)
+"""Sciline providers for powder diffraction."""
+del conversion_providers
+
+__all__ = ['merge_calibration', 'to_dspacing_with_calibration']

ess/diffraction/powder/conversion.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+"""
+Coordinate transformations for powder diffraction.
+"""
+
+import uuid
+from typing import Optional
+
+import scipp as sc
+
+from ..logging import get_logger
+from ..types import CalibrationData, DspacingData, NormalizedByProtonCharge, RunType
+from .correction import merge_calibration
+
+
+def _dspacing_from_diff_calibration_generic_impl(t, t0, a, c):
+    """
+    This function implements the solution to
+      t = a * d^2 + c * d + t0
+    for a != 0.
+    It uses the following way of expressing the solution with an order of operations
+    that is optimized for low memory usage.
+      d = (sqrt([x-t0+t] / x) - 1) * c / (2a)
+      x = c^2 / (4a)
+    """
+    x = c**2 / (4 * a)
+    out = (x - t0) + t
+    out /= x
+    del x
+    sc.sqrt(out, out=out)
+    out -= 1
+    out *= c / (2 * a)
+    return out
+
+
+def _dspacing_from_diff_calibration_a0_impl(t, t0, c):
+    """
+    This function implements the solution to
+      t = a * d^2 + c * d + t0
+    for a == 0.
+    """
+    out = t - t0
+    out /= c
+    return out
+
+
+def dspacing_from_diff_calibration(
+    tof: sc.Variable,
+    tzero: sc.Variable,
+    difa: sc.Variable,
+    difc: sc.Variable,
+    _tag_positions_consumed: sc.Variable,
+) -> sc.Variable:
+    r"""
+    Compute d-spacing from calibration parameters.
+
+    d-spacing is the positive solution of
+
+    .. math:: \mathsf{tof} = \mathsf{DIFA} * d^2 + \mathsf{DIFC} * d + t_0
+
+    This function can be used with :func:`scipp.transform_coords`.
+
+    See Also
+    --------
+    ess.diffraction.conversions.to_dspacing_with_calibration
+    """
+    if sc.all(difa == sc.scalar(0.0, unit=difa.unit)).value:
+        return _dspacing_from_diff_calibration_a0_impl(tof, tzero, difc)
+    return _dspacing_from_diff_calibration_generic_impl(tof, tzero, difa, difc)
+
+
+def _restore_tof_if_in_wavelength(data: sc.DataArray) -> sc.DataArray:
+    if 'wavelength' not in data.dims:
+        return data
+
+    get_logger().info("Discarding coordinate 'wavelength' in favor of 'tof'.")
+    temp_name = uuid.uuid4().hex
+    aux = data.transform_coords(
+        temp_name,
+        {temp_name: lambda wavelength, tof: tof},
+        keep_inputs=False,
+        quiet=True,
+    )
+    return aux.transform_coords(
+        'tof', {'tof': temp_name}, keep_inputs=False, quiet=True
+    )
+
+
+def _consume_positions(position, sample_position, source_position):
+    _ = position
+    _ = sample_position
+    _ = source_position
+    return sc.scalar(0)
+
+
+def to_dspacing_with_calibration(
+    data: NormalizedByProtonCharge[RunType],
+    calibration: Optional[CalibrationData] = None,
+) -> DspacingData[RunType]:
+    """
+    Transform coordinates to d-spacing from calibration parameters.
+
+    Computes d-spacing from time-of-flight stored in `data`.
+
+    Attention
+    ---------
+    `data` may have a wavelength coordinate and dimension,
+    but those are discarded.
+    Only the stored time-of-flight is used, that is, any modifications to
+    the wavelength coordinate after it was computed from time-of-flight are lost.
+
+    Raises
+    ------
+    KeyError
+        If `data` does not contain a 'tof' coordinate.
+
+    Parameters
+    ----------
+    data:
+        Input data in tof or wavelength dimension.
+        Must have a tof coordinate.
+    calibration:
+        Calibration data. If given, use it for the conversion.
+        Otherwise, the calibration data must be stored in `data`.
+
+    Returns
+    -------
+    :
+        A DataArray with the same data as the input and a 'dspacing' coordinate.
+
+    See Also
+    --------
+    ess.diffraction.conversions.dspacing_from_diff_calibration
+    """
+    if calibration is not None:
+        out = merge_calibration(into=data, calibration=calibration)
+    else:
+        out = data
+
+    out = _restore_tof_if_in_wavelength(out)
+    graph = {
+        'dspacing': dspacing_from_diff_calibration,
+    }
+
+    if 'position' in out.coords:
+        graph['_tag_positions_consumed'] = _consume_positions
+    else:
+        out.coords['_tag_positions_consumed'] = sc.scalar(0)
+
+    out = out.transform_coords('dspacing', graph=graph, keep_intermediate=False)
+    out.coords.pop('_tag_positions_consumed', None)
+    return DspacingData[RunType](out)
+
+
+providers = (to_dspacing_with_calibration,)
+"""Sciline providers for coordinate transformations."""

ess/diffraction/powder/correction.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+import scipp as sc
+
+
+def merge_calibration(*, into: sc.DataArray, calibration: sc.Dataset) -> sc.DataArray:
+    """
+    Return a scipp.DataArray containing calibration metadata as coordinates.
+
+    Parameters
+    ----------
+    into:
+        Base data and metadata for the returned object.
+    calibration:
+        Calibration parameters.
+
+    Returns
+    -------
+    :
+        Copy of `into` with additional coordinates and masks
+        from `calibration`.
+
+    See Also
+    --------
+    ess.diffraction.load_calibration
+    """
+    dim = calibration.dim
+    if not sc.identical(into.coords[dim], calibration.coords[dim]):
+        raise ValueError(
+            f'Coordinate {dim} of calibration and target dataset do not agree.'
+        )
+    out = into.copy(deep=False)
+    for name in ('difa', 'difc', 'tzero'):
+        if name in out.coords:
+            raise ValueError(
+                f"Cannot add calibration parameter '{name}' to data, "
+                "there already is metadata with the same name."
+            )
+        out.coords[name] = calibration[name].data
+    if 'calibration' in out.masks:
+        raise ValueError(
+            "Cannot add calibration mask 'calibration' tp data, "
+            "there already is a mask with the same name."
+        )
+    out.masks['calibration'] = calibration['mask'].data
+    return out

ess/diffraction/smoothing.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+"""
+Smoothing arrays data.
+"""
+
+from typing import Optional
+
+import scipp as sc
+from scipp.scipy.signal import butter
+
+from .logging import get_logger
+
+
+def _ensure_no_variances(var: sc.DataArray) -> sc.DataArray:
+    if var.variances is not None:
+        get_logger().warning(
+            'Tried to smoothen data with uncertainties. '
+            'This is not supported because the results would be highly correlated.\n'
+            'Instead, the variances are ignored and the output '
+            'will be returned without any!'
+            '\n--------------------------------------------------\n'
+            'If you know a good solution for handling uncertainties in such a case, '
+            'please contact the scipp developers! (e.g. via https://github.com/scipp)'
+            '\n--------------------------------------------------\n'
+        )
+        return sc.values(var)
+    return var
+
+
+def lowpass(
+    da: sc.DataArray, *, dim: str, N: int, Wn: sc.Variable, coord: Optional[str] = None
+) -> sc.DataArray:
+    """
+    Smooth data using a lowpass frequency filter.
+
+    Applies a lowpass Butterworth filter to `da.data` based on the sampling rate
+    defined by `coord`.
+    See :py:func:`scipp.signal.butter` for information on filter design.
+
+    Important
+    ---------
+    If `coord` is bin-edges, it is first converted to bin-centers using
+    :func:`scipp.midpoints`.
+    This is only valid for linearly-spaced edges.
+
+    Parameters
+    ----------
+    da:
+        Data to smoothen.
+    dim:
+        Dimension along which to smooth.
+    coord:
+        Name of the coordinate that defines the sampling frequency.
+        Defaults to `dim`.
+    N:
+        Order of the lowpass filter.
+    Wn:
+        Critical frequency of the filter.
+
+    Returns
+    -------
+    :
+        Smoothed `da`.
+
+    See Also
+    --------
+    scipp.signal.butter scipp.signal.sosfiltfilt
+
+    Examples
+    --------
+
+       >>> from ess.diffraction import lowpass
+       >>> x = sc.linspace(dim='x', start=1.1, stop=4.0, num=1000, unit='m')
+       >>> y = sc.sin(x * sc.scalar(1.0, unit='rad/m'))
+       >>> y += sc.sin(x * sc.scalar(400.0, unit='rad/m'))
+       >>> noisy = sc.DataArray(data=y, coords={'x': x})
+       >>> smooth = lowpass(noisy, dim='x', N=4, Wn=20 / x.unit)
+    """
+    da = _ensure_no_variances(da)
+    coord = dim if coord is None else coord
+
+    if da.coords[coord].sizes[dim] == da.sizes[dim] + 1:
+        da = da.copy(deep=False)
+        da.coords[coord] = sc.midpoints(da.coords[coord], dim)
+
+    return butter(da.coords[coord], N=N, Wn=Wn).filtfilt(da, dim)

ess/diffraction/types.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+
+"""This module defines the domain types used in ess.diffraction.
+
+The domain types are used to define parameters and to request results from a Sciline
+pipeline.
+"""
+
+from typing import NewType, TypeVar
+
+import sciline
+import scipp as sc
+
+# 1 TypeVars used to parametrize the generic parts of the workflow
+
+# 1.1 Run types
+EmptyInstrumentRun = NewType('EmptyInstrumentRun', int)
+"""Empty instrument run."""
+SampleRun = NewType('SampleRun', int)
+"""Sample run."""
+VanadiumRun = NewType('VanadiumRun', int)
+"""Vanadium run."""
+RunType = TypeVar('RunType', EmptyInstrumentRun, SampleRun, VanadiumRun)
+"""TypeVar used for specifying the run."""
+
+
+# 2 Workflow parameters
+
+CalibrationFilename = NewType('CalibrationFilename', str)
+"""Filename of the instrument calibration file."""
+
+DspacingBins = NewType('DSpacingBins', sc.Variable)
+"""Bin edges for d-spacing."""
+
+
+class Filename(sciline.Scope[RunType, str], str):
+    """Filename of a run."""
+
+
+OutFilename = NewType('OutFilename', str)
+"""Filename of the output."""
+
+TwoThetaBins = NewType('TwoThetaBins', sc.Variable)
+"""Bin edges for grouping in 2theta.
+
+This is used by an alternative focussing step that groups detector
+pixels by scattering angle into bins given by these edges.
+"""
+
+ValidTofRange = NewType('ValidTofRange', sc.Variable)
+"""Min and max tof value of the instrument."""
+
+# 3 Workflow (intermediate) results
+
+
+class AccumulatedProtonCharge(sciline.Scope[RunType, sc.Variable], sc.Variable):
+    """Total proton charge."""
+
+
+CalibrationData = NewType('CalibrationData', sc.Dataset)
+"""Detector calibration data."""
+
+
+class DspacingData(sciline.Scope[RunType, sc.DataArray], sc.DataArray):
+    """Data converted to d-spacing."""
+
+
+class DspacingDataWithoutVariances(sciline.Scope[RunType, sc.DataArray], sc.DataArray):
+    """Data converted to d-spacing where variances where removed."""
+
+
+DspacingHistogram = NewType('DspacingHistogram', sc.DataArray)
+"""Histogrammed intensity vs d-spacing."""
+
+
+class FilteredData(sciline.Scope[RunType, sc.DataArray], sc.DataArray):
+    """Raw data without invalid events."""
+
+
+class FocussedData(sciline.Scope[RunType, sc.DataArray], sc.DataArray):
+    """Intensity vs d-spacing after focussing pixels."""
+
+
+class NormalizedByProtonCharge(sciline.Scope[RunType, sc.DataArray], sc.DataArray):
+    """Data that has been normalized by proton charge."""
+
+
+NormalizedByVanadium = NewType('NormalizedByVanadium', sc.DataArray)
+"""Data that has been normalized by a vanadium run."""
+
+
+class ProtonCharge(sciline.Scope[RunType, sc.DataArray], sc.DataArray):
+    """Time-dependent proton charge."""
+
+
+RawCalibrationData = NewType('RawCalibrationData', sc.Dataset)
+"""Calibration data as loaded from file, needs preprocessing before using."""
+
+
+class RawData(sciline.Scope[RunType, sc.DataArray], sc.DataArray):
+    """Raw data."""
+
+
+class RawDataWithVariances(sciline.Scope[RunType, sc.DataArray], sc.DataArray):
+    """Raw data that has variances which need special handling."""
+
+
+class RawDataAndMetadata(sciline.Scope[RunType, sc.DataGroup], sc.DataGroup):
+    """Raw data and associated metadata."""
+
+
+class TofCroppedData(sciline.Scope[RunType, sc.DataArray], sc.DataArray):
+    """Raw data cropped to the valid TOF range."""
+
+
+del sc, sciline, NewType, TypeVar

ess/diffraction/uncertainty.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+"""Tools for handling statistical uncertainties."""
+
+from .types import RawData, RawDataWithVariances, VanadiumRun
+
+
+def drop_variances(data: RawDataWithVariances[VanadiumRun]) -> RawData[VanadiumRun]:
+    res = data.copy(deep=False)
+    if res.bins is not None:
+        res.bins.constituents['data'].variances = None
+    else:
+        res.variances = None
+    return RawData[VanadiumRun](res)
+
+
+providers = (drop_variances,)
+"""Sciline providers for handling statistical uncertainties."""

ess/dream/__init__.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+
+"""
+Components for DREAM
+"""
+import importlib.metadata
+
+from . import data
+from .io import fold_nexus_detectors, load_nexus
+
+try:
+    __version__ = importlib.metadata.version(__package__ or __name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+del importlib
+
+__all__ = [
+    "data",
+    "fold_nexus_detectors",
+    "load_nexus",
+]