essdiffraction 23.12.0__py3-none-any.whl

ess/diffraction/__init__.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+
+"""
+Components for diffraction experiments (powder and single crystal).
+"""
+
+import importlib.metadata
+
+from . import uncertainty
+from .correction import (
+    normalize_by_monitor,
+    normalize_by_proton_charge,
+    normalize_by_vanadium,
+)
+from .correction import providers as correction_providers
+from .filtering import crop_tof, filter_events
+from .filtering import providers as filtering_providers
+from .filtering import remove_bad_pulses
+from .grouping import finalize_histogram, group_by_two_theta, merge_all_pixels
+from .grouping import providers as grouping_providers
+from .smoothing import lowpass
+
+try:
+    __version__ = importlib.metadata.version(__package__ or __name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+del importlib
+
+providers = (
+    *correction_providers,
+    *filtering_providers,
+    *grouping_providers,
+    *uncertainty.providers,
+)
+"""Sciline providers for setting up a diffraction pipeline.
+
+These implement basic diffraction data-reduction functionality and need to be
+extended with instrument-specific and sub-technique-specific providers.
+"""
+del correction_providers, filtering_providers, grouping_providers
+
+__all__ = [
+    'crop_tof',
+    'filter_events',
+    'finalize_histogram',
+    'group_by_two_theta',
+    'lowpass',
+    'merge_all_pixels',
+    'normalize_by_monitor',
+    'normalize_by_proton_charge',
+    'normalize_by_vanadium',
+    'remove_bad_pulses',
+    'uncertainty',
+]

ess/diffraction/correction.py

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+from typing import Any, Dict, Optional
+
+import scipp as sc
+from scippneutron.conversion.graph import beamline, tof
+
+from .logging import get_logger
+from .smoothing import lowpass
+from .types import (
+    AccumulatedProtonCharge,
+    DspacingBins,
+    FilteredData,
+    FocussedData,
+    NormalizedByProtonCharge,
+    NormalizedByVanadium,
+    RunType,
+    SampleRun,
+    VanadiumRun,
+)
+
+
+def normalize_by_monitor(
+    data: sc.DataArray,
+    *,
+    monitor: sc.DataArray,
+    wavelength_edges: Optional[sc.Variable] = None,
+    smooth_args: Optional[Dict[str, Any]] = None,
+) -> sc.DataArray:
+    """
+    Normalize event data by a monitor.
+
+    The input is converted to wavelength if it does not already contain wavelengths.
+
+    Parameters
+    ----------
+    data:
+        Input event data.
+    monitor:
+        A histogrammed monitor.
+    wavelength_edges:
+        If given, rebin the monitor with these edges.
+    smooth_args:
+        If given, the monitor histogram is smoothed with
+        :func:`ess.diffraction.lowpass` before dividing into `data`.
+        `smooth_args` is passed as keyword arguments to
+        :func:`ess.diffraction.lowpass`. If ``None``, the monitor is not smoothed.
+
+    Returns
+    -------
+    :
+        `data` normalized by a monitor.
+    """
+    if 'wavelength' not in monitor.coords:
+        monitor = monitor.transform_coords(
+            'wavelength',
+            graph={**beamline.beamline(scatter=False), **tof.elastic("tof")},
+            keep_inputs=False,
+            keep_intermediate=False,
+            keep_aliases=False,
+        )
+
+    if wavelength_edges is not None:
+        monitor = monitor.rebin(wavelength=wavelength_edges)
+    if smooth_args is not None:
+        get_logger().info(
+            "Smoothing monitor for normalization using "
+            "ess.diffraction.smoothing.lowpass with %s.",
+            smooth_args,
+        )
+        monitor = lowpass(monitor, dim='wavelength', **smooth_args)
+    return data.bins / sc.lookup(func=monitor, dim='wavelength')
+
+
+def normalize_by_vanadium(
+    data: FocussedData[SampleRun],
+    vanadium: FocussedData[VanadiumRun],
+    edges: DspacingBins,
+) -> NormalizedByVanadium:
+    """
+    Normalize sample data by a vanadium measurement.
+
+    Parameters
+    ----------
+    data:
+        Sample data.
+    vanadium:
+        Vanadium data.
+    edges:
+        `vanadium` is histogrammed into these bins before dividing the data by it.
+
+    Returns
+    -------
+    :
+        `data` normalized by `vanadium`.
+    """
+    norm = sc.lookup(vanadium.hist({edges.dim: edges}), dim=edges.dim)
+    # Converting to unit 'one' because the division might produce a unit
+    # with a large scale if the proton charges in data and vanadium were
+    # measured with different units.
+    return (data.bins / norm).to(unit='one', copy=False)
+
+
+def normalize_by_proton_charge(
+    data: FilteredData[RunType], proton_charge: AccumulatedProtonCharge[RunType]
+) -> NormalizedByProtonCharge[RunType]:
+    """Normalize data by an accumulated proton charge.
+
+    Parameters
+    ----------
+    data:
+        Un-normalized data array as events or a histogram.
+    proton_charge:
+        Accumulated proton charge over the entire run.
+
+    Returns
+    -------
+    :
+        ``data / proton_charge``
+    """
+    return NormalizedByProtonCharge[RunType](data / proton_charge)
+
+
+providers = (normalize_by_proton_charge, normalize_by_vanadium)
+"""Sciline providers for diffraction corrections."""

ess/diffraction/external/__init__.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+"""
+Components for non-ESS diffraction experiments.
+
+WARNING This package will be removed in the future!
+It only serves as helpers to develop workflows until it is determined,
+which mechanisms and interfaces will be used at ESS.
+"""
+from pathlib import Path
+from typing import Dict, Optional, Union
+
+import numpy as np
+import scipp as sc
+import scippneutron as scn
+
+from ..logging import get_logger
+
+
+def _as_boolean_mask(var: sc.Variable) -> sc.Variable:
+    if var.dtype in ('float32', 'float64'):
+        if sc.any(var != var.to(dtype='int64')).value:
+            raise ValueError(
+                'Cannot construct boolean mask, the input mask has fractional values.'
+            )
+    return var.to(dtype=bool)
+
+
+def _parse_calibration_instrument_args(
+    filename: Union[str, Path],
+    *,
+    instrument_filename: Optional[str] = None,
+    instrument_name: Optional[str] = None,
+) -> Dict[str, str]:
+    if instrument_filename is not None:
+        if instrument_name is not None:
+            raise ValueError(
+                'Only one argument of `instrument_name` and '
+                '`instrument_filename` is allowed, got both.'
+            )
+        instrument_arg = {'InstrumentFilename': instrument_filename}
+        instrument_message = f'with instrument file {instrument_filename}'
+    else:
+        if instrument_name is None:
+            raise ValueError(
+                'Need one argument of `instrument_name` and '
+                '`instrument_filename` is allowed, got neither.'
+            )
+        instrument_arg = {'InstrumentName': instrument_name}
+        instrument_message = f'with instrument {instrument_name}'
+
+    get_logger().info(
+        'Loading calibration from file %s %s', filename, instrument_message
+    )
+    return instrument_arg
+
+
+def load_calibration(
+    filename: Union[str, Path],
+    *,
+    instrument_filename: Optional[str] = None,
+    instrument_name: Optional[str] = None,
+    mantid_args: Optional[dict] = None,
+) -> sc.Dataset:
+    """
+    Load and return calibration data.
+
+    Warning
+    -------
+    This function is designed to work with calibration files used by Mantid,
+    specifically for POWGEN. It does not represent the interface used at ESS
+    and will be removed in the future.
+
+    Uses the Mantid algorithm `LoadDiffCal
+    <https://docs.mantidproject.org/nightly/algorithms/LoadDiffCal-v1.html>`_
+    and stores the data in a :class:`scipp.Dataset`
+
+    Note that this function requires mantid to be installed and available in
+    the same Python environment as ess.
+
+    Parameters
+    ----------
+    filename:
+        The name of the calibration file to load.
+    instrument_filename:
+        Instrument definition file.
+    instrument_name:
+        Name of the instrument.
+    mantid_args:
+        Dictionary with additional arguments for the
+        `LoadDiffCal` Mantid algorithm.
+
+    Returns
+    -------
+    :
+        A Dataset containing the calibration data and masking.
+    """
+
+    mantid_args = {} if mantid_args is None else mantid_args
+    mantid_args.update(
+        _parse_calibration_instrument_args(
+            filename,
+            instrument_filename=instrument_filename,
+            instrument_name=instrument_name,
+        )
+    )
+
+    with scn.mantid.run_mantid_alg(
+        'LoadDiffCal',
+        Filename=str(filename),
+        MakeGroupingWorkspace=False,
+        **mantid_args,
+    ) as ws:
+        ds = scn.from_mantid(ws.OutputCalWorkspace)
+        mask_ws = ws.OutputMaskWorkspace
+        rows = mask_ws.getNumberHistograms()
+        mask = sc.array(
+            dims=['row'],
+            values=np.fromiter(
+                (mask_ws.readY(i)[0] for i in range(rows)), count=rows, dtype=np.bool_
+            ),
+            unit=None,
+        )
+    # This is deliberately not stored as a mask since that would make
+    # subsequent handling, e.g., with groupby, more complicated. The mask
+    # is conceptually not masking rows in this table, i.e., it is not
+    # marking invalid rows, but rather describes masking for other data.
+    ds["mask"] = _as_boolean_mask(mask)
+
+    # The file does not define units
+    # TODO why those units? Can we verify?
+    ds["difc"].unit = 'us / angstrom'
+    ds["difa"].unit = 'us / angstrom**2'
+    ds["tzero"].unit = 'us'
+
+    ds = ds.rename_dims({'row': 'detector'})
+    ds.coords['detector'] = ds['detid'].data
+    ds.coords['detector'].unit = None
+    del ds['detid']
+
+    return ds

ess/diffraction/external/powgen/__init__.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+"""
+Functions and classes for the POWGEN instrument.
+
+Note that this module is temporary and will be removed in favor of
+the ``dream`` module when that is available.
+"""
+
+from . import beamline, data
+from .instrument_view import instrument_view
+
+providers = (
+    *beamline.providers,
+    *data.providers,
+)
+"""Sciline Providers for POWGEN-specific functionality."""
+
+__all__ = [
+    'beamline',
+    'data',
+    'instrument_view',
+]

ess/diffraction/external/powgen/beamline.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+"""
+Beamline parameters and utilities for POWGEN.
+"""
+
+import scipp as sc
+
+from ...types import CalibrationData, RawCalibrationData
+from .types import DetectorInfo
+
+
+def map_detector_to_spectrum(
+    data: sc.Dataset, *, detector_info: sc.Dataset
+) -> sc.Dataset:
+    """
+    Transform 'detector' coords to 'spectrum'.
+
+    Parameters
+    ----------
+    data:
+        Input data whose 'detector' coord is transformed.
+    detector_info:
+        Defines mapping from detector numbers to spectra.
+
+    Returns
+    -------
+    :
+        `data` with 'detector' coord and dim replaced by 'spectrum'.
+    """
+    if not sc.identical(
+        data.coords['detector'].to(
+            dtype=detector_info.coords['detector'].dtype, copy=False
+        ),
+        detector_info.coords['detector'],
+    ):
+        raise sc.CoordError(
+            "The 'detector' coords of `data` and `detector_info` do not match."
+        )
+
+    out = data.copy(deep=False)
+    del out.coords['detector']
+    # Add 1 because spectrum numbers in the data start at 1 but
+    # detector_info contains spectrum indices which start at 0.
+    out.coords['spectrum'] = detector_info.coords['spectrum'] + sc.index(
+        1, dtype=detector_info.coords['spectrum'].dtype
+    )
+
+    return out.rename_dims({'detector': 'spectrum'})
+
+
+def preprocess_calibration_data(
+    data: RawCalibrationData, detector_info: DetectorInfo
+) -> CalibrationData:
+    """Convert calibration data to a format that can be used by Scipp.
+
+    The raw calibration data is encoded in terms of a `'detector'` coordinate.
+    This needs to be converted to a `'spectrum'` coordinate to align
+    if with sample data.
+    """
+    return CalibrationData(map_detector_to_spectrum(data, detector_info=detector_info))
+
+
+providers = (preprocess_calibration_data,)
+"""Sciline providers for POWGEN beamline processing."""

ess/diffraction/external/powgen/data.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+
+"""Utilities for loading example data for POWGEN."""
+
+import scipp as sc
+
+from ...types import (
+    AccumulatedProtonCharge,
+    CalibrationFilename,
+    Filename,
+    ProtonCharge,
+    RawCalibrationData,
+    RawData,
+    RawDataAndMetadata,
+    RawDataWithVariances,
+    RunType,
+    SampleRun,
+    VanadiumRun,
+)
+from .types import DetectorInfo
+
+_version = '1'
+
+__all__ = ['get_path']
+
+
+def _make_pooch():
+    import pooch
+
+    return pooch.create(
+        path=pooch.os_cache('ess/powgen'),
+        env='ESS_DATA_DIR',
+        base_url='https://public.esss.dk/groups/scipp/ess/powgen/{version}/',
+        version=_version,
+        registry={
+            # Files loadable with Mantid
+            'PG3_4844_event.nxs': 'md5:d5ae38871d0a09a28ae01f85d969de1e',
+            'PG3_4866_event.nxs': 'md5:3d543bc6a646e622b3f4542bc3435e7e',
+            'PG3_5226_event.nxs': 'md5:58b386ebdfeb728d34fd3ba00a2d4f1e',
+            'PG3_FERNS_d4832_2011_08_24.cal': 'md5:c181221ebef9fcf30114954268c7a6b6',
+            # Zipped Scipp HDF5 files
+            'PG3_4844_event.zip': 'md5:a644c74f5e740385469b67431b690a3e',
+            'PG3_4866_event.zip': 'md5:5bc49def987f0faeb212a406b92b548e',
+            'PG3_FERNS_d4832_2011_08_24.zip': 'md5:0fef4ed5f61465eaaa3f87a18f5bb80d',
+        },
+    )
+
+
+_pooch = _make_pooch()
+
+
+def get_path(name: str, unzip: bool = False) -> str:
+    """
+    Return the path to a data file bundled with scippneutron.
+
+    This function only works with example data and cannot handle
+    paths to custom files.
+    """
+    import pooch
+
+    return _pooch.fetch(name, processor=pooch.Unzip() if unzip else None)
+
+
+def mantid_sample_file() -> str:
+    return get_path('PG3_4844_event.nxs')
+
+
+def mantid_vanadium_file() -> str:
+    return get_path('PG3_4866_event.nxs')
+
+
+def mantid_empty_instrument_file() -> str:
+    return get_path('PG3_5226_event.nxs')
+
+
+def mantid_calibration_file() -> str:
+    return get_path('PG3_FERNS_d4832_2011_08_24.cal')
+
+
+def sample_file() -> str:
+    (path,) = get_path('PG3_4844_event.zip', unzip=True)
+    return path
+
+
+def vanadium_file() -> str:
+    (path,) = get_path('PG3_4866_event.zip', unzip=True)
+    return path
+
+
+def calibration_file() -> str:
+    (path,) = get_path('PG3_FERNS_d4832_2011_08_24.zip', unzip=True)
+    return path
+
+
+def pooch_load(filename: Filename[RunType]) -> RawDataAndMetadata[RunType]:
+    """Load a file with pooch.
+
+    If the file is a zip archive, it is extracted and a path to the contained
+    file is returned.
+
+    The loaded data holds both the events and any metadata from the file.
+    """
+    if filename.endswith('.zip'):
+        (path,) = get_path(filename, unzip=True)
+    else:
+        path = get_path(filename)
+    return RawDataAndMetadata[RunType](sc.io.load_hdf5(path))
+
+
+def pooch_load_calibration(filename: CalibrationFilename) -> RawCalibrationData:
+    """Load the calibration data for the POWGEN test data."""
+    if filename.endswith('.zip'):
+        (path,) = get_path(filename, unzip=True)
+    else:
+        path = get_path(filename)
+    return RawCalibrationData(sc.io.load_hdf5(path))
+
+
+# This can be generalized with https://github.com/scipp/sciline/issues/69.
+def extract_raw_data_sample(dg: RawDataAndMetadata[SampleRun]) -> RawData[SampleRun]:
+    """Return the events from a loaded data group."""
+    return RawData[SampleRun](dg['data'])
+
+
+def extract_raw_data_vanadium(
+    dg: RawDataAndMetadata[VanadiumRun],
+) -> RawDataWithVariances[VanadiumRun]:
+    """Return the events from a loaded data group."""
+    return RawDataWithVariances[VanadiumRun](dg['data'])
+
+
+def extract_detector_info(dg: RawDataAndMetadata[SampleRun]) -> DetectorInfo:
+    """Return the detector info from a loaded data group."""
+    return DetectorInfo(dg['detector_info'])
+
+
+def extract_proton_charge(dg: RawDataAndMetadata[RunType]) -> ProtonCharge[RunType]:
+    """Return the proton charge from a loaded data group."""
+    return ProtonCharge[RunType](dg['proton_charge'])
+
+
+def extract_accumulated_proton_charge(
+    data: RawData[RunType],
+) -> AccumulatedProtonCharge[RunType]:
+    """Return the stored accumulated proton charge from a loaded data group."""
+    return AccumulatedProtonCharge[RunType](data.coords['gd_prtn_chrg'])
+
+
+providers = (
+    pooch_load,
+    pooch_load_calibration,
+    extract_accumulated_proton_charge,
+    extract_detector_info,
+    extract_proton_charge,
+    extract_raw_data_sample,
+    extract_raw_data_vanadium,
+)
+"""Sciline Providers for loading POWGEN data."""

ess/diffraction/external/powgen/instrument_view.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+from typing import Optional
+
+import scipp as sc
+import scippneutron as scn
+
+
+def instrument_view(
+    da: sc.DataArray,
+    positions: str = "position",
+    pixel_size: Optional[float] = None,
+    components: Optional[dict] = None,
+    **kwargs,
+):
+    """
+    Instrument view for the POWGEN instrument, with adjusted default arguments.
+
+    Parameters
+    ----------
+    positions:
+        Key for coord holding positions to use for pixels
+    pixel_size:
+        Custom pixel size to use for detector pixels
+    components:
+        Dictionary containing display names and corresponding
+        settings (also a Dictionary) for additional components to display
+        items with known positions to be shown
+    kwargs:
+        See :func:`scippneutron.instrument_view`
+    """
+    # TODO: the camera argument does not work with the Plopp instrument view
+    # if 'camera' not in kwargs:
+    #     kwargs = {
+    #         **kwargs, 'camera': {
+    #             'position': sc.vector(value=[-3, 3, 3],
+    #                                   unit=da.coords[positions].unit)
+    #         }
+    #     }
+    return scn.instrument_view(
+        da, positions=positions, components=components, pixel_size=pixel_size, **kwargs
+    )

ess/diffraction/external/powgen/types.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
+
+"""This module defines the domain types used by POWGEN.
+
+The domain types are used to define parameters and to request results from a Sciline
+pipeline.
+"""
+
+from typing import NewType
+
+import scipp as sc
+
+# This is Mantid-specific and can probably be removed when the POWGEN
+# workflow is removed.
+DetectorInfo = NewType('DetectorInfo', sc.Dataset)
+"""Mapping between detector numbers and spectra."""
+
+del sc, NewType