Merge pull request #436 from scipp/load-with-mantid-name

Rename load to load_with_mantid

benchmarks/transform_coords.py

@@ -7,7 +7,7 @@
 
 class TransformCoords:
     def setup(self):
-        da = scn.load(scn.data.get_path('PG3_4844_event.nxs'))
+        da = scn.load_with_mantid(scn.data.get_path('PG3_4844_event.nxs'))
         self.var_tof = da
         self.var_wavelength = scn.convert(self.var_tof, "tof", "wavelength", False)
         self.var_energy = scn.convert(self.var_tof, "tof", "energy", False)

docs/about/release-notes.rst

@@ -27,12 +27,28 @@ Release Notes
    Stability, Maintainability, and Testing
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   Contributors
-   ~~~~~~~~~~~~
+v0.xy.0 (Unreleased)
+--------------------
+
+Features
+~~~~~~~~
+
+Breaking changes
+~~~~~~~~~~~~~~~~
+
+Bugfixes
+~~~~~~~~
+
+Documentation
+~~~~~~~~~~~~~
+
+Deprecations
+~~~~~~~~~~~~
 
-   Simon Heybrock :sup:`a`\ ,
-   Neil Vaytet :sup:`a`\ ,
-   and Jan-Lukas Wynen :sup:`a`
+* Renamed ``scipneutron.load`` to :func:`scippneutron.load_with_mantid` for clarity. The old name is deprecated `#436 <https://github.com/scipp/scippneutron/pull/436>`_.
+
+Stability, Maintainability, and Testing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 v23.04.0 (April 2023)
 ---------------------
@@ -53,24 +69,11 @@ Bugfixes
 
 * Conversion from ``mantid.MaskWorkspace`` now correctly sets ``unit=None`` instead of using dimensionless `#424 <https://github.com/scipp/scippneutron/pull/424>`_.
 
-Documentation
-~~~~~~~~~~~~~
-
-Deprecations
-~~~~~~~~~~~~
-
 Stability, Maintainability, and Testing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * Switched to black for Python code formatting `#429 <https://github.com/scipp/scippneutron/pull/429>`_.
 
-Contributors
-~~~~~~~~~~~~
-
-Simon Heybrock :sup:`a`\ ,
-Neil Vaytet :sup:`a`\ ,
-and Jan-Lukas Wynen :sup:`a`
-
 v23.03.0 (March 2023)
 ---------------------
 

docs/tutorials/powder-diffraction.ipynb

@@ -38,12 +38,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sample = scn.load(\n",
+    "sample = scn.load_with_mantid(\n",
     "    scn.data.get_path('PG3_4844_event.nxs'),\n",
     "    load_pulse_times=False,\n",
     "    mantid_args={'LoadMonitors': True},\n",
     ")\n",
-    "vanadium = scn.load(scn.data.get_path('PG3_4866_event.nxs'), load_pulse_times=False)"
+    "vanadium = scn.load_with_mantid(scn.data.get_path('PG3_4866_event.nxs'), load_pulse_times=False)"
    ]
   },
   {

docs/user-guide/groupby.ipynb

@@ -34,7 +34,7 @@
    "source": [
     "# Load event data. Here, we use `get_path` to find a data file that comes bundled\n",
     "# with scippneutron. Normally, we would simply pass a file path to `scn.load`.\n",
-    "events = scn.load(scn.data.get_path('PG3_4844_event.nxs'), load_pulse_times=False)"
+    "events = scn.load_with_mantid(scn.data.get_path('PG3_4844_event.nxs'), load_pulse_times=False)"
    ]
   },
   {

src/scippneutron/__init__.py

@@ -23,7 +23,7 @@
     two_theta,
 )
 from .core import convert
-from .mantid import from_mantid, to_mantid, load, fit
+from .mantid import from_mantid, to_mantid, load_with_mantid, load, fit
 from .instrument_view import instrument_view
 from .io.nexus.load_nexus import load_nexus, load_nexus_json
 from .data_streaming.data_stream import data_stream

src/scippneutron/data/__init__.py

@@ -3,7 +3,7 @@
 # @author Simon Heybrock
 import scipp as sc
 
-from ..mantid import load
+from ..mantid import load_with_mantid
 
 _version = '5'
 
@@ -52,7 +52,7 @@ def tutorial_event_data():
 
 
 def powder_sample():
-    return load(_pooch.fetch('PG3_4844_event.nxs'))
+    return load_with_mantid(_pooch.fetch('PG3_4844_event.nxs'))
 
 
 def powder_calibration():

src/scippneutron/mantid.py

@@ -859,7 +859,7 @@ def from_mantid(workspace, **kwargs):
     return scipp_obj
 
 
-def load(
+def load_with_mantid(
     filename: Union[str, Path] = "",
     load_pulse_times=True,
     instrument_filename=None,
@@ -914,12 +914,13 @@ def load(
 
     Examples
     --------
-    >>> from scippneutron import load
+    >>> from scippneutron import load_with_mantid
     >>> d = sc.Dataset()
-    >>> d["sample"] = load(filename='PG3_4844_event.nxs',
-    ...                    load_pulse_times=False,
-    ...                    mantid_args={'BankName': 'bank184',
-    ...                                 'LoadMonitors': True})  # doctest: +SKIP
+    >>> d["sample"] = load_with_mantid(filename='PG3_4844_event.nxs',
+    ...                                load_pulse_times=False,
+    ...                                mantid_args={
+    ...                                     'BankName': 'bank184',
+    ...                                     'LoadMonitors': True})  # doctest: +SKIP
     """
 
     if mantid_args is None:
@@ -952,6 +953,92 @@ def load(
         )
 
 
+def load(
+    filename: Union[str, Path] = "",
+    load_pulse_times=True,
+    instrument_filename=None,
+    error_connection=None,
+    mantid_alg='Load',
+    mantid_args=None,
+    advanced_geometry=False,
+) -> sc.Dataset:
+    """Load a file using Mantid.
+
+    Wraps Mantid's loaders and converts the result to a scipp dataset.
+
+    See also the neutron-data tutorial.
+
+    Note that this function requires mantid to be installed and available in
+    the same Python environment as scipp.
+
+    Parameters
+    ----------
+    filename:
+        The name of the Nexus/HDF file to be loaded.
+    load_pulse_times:
+        Read the pulse times if True.
+    instrument_filename:
+        If specified, over-write the instrument definition
+        in the final dataset with the geometry contained in the file.
+    error_connection:
+        Dict with data column names as keys to names of their error column.
+        Only used when the loaded workspace is a TableWorkspace.
+        See scippneutron.mantid.convert_TableWorkspace_to_dataset
+    mantid_alg:
+        Mantid algorithm to use for loading. Default is `Load`.
+    mantid_args:
+        Dict of keyword arguments to forward to Mantid.
+    advanced_geometry:
+        If True, load the full detector geometry including shapes and rotations.
+        The positions of grouped detectors are spherically averaged.
+        If False, load only the detector position, and return
+        the cartesian average of the grouped detector positions.
+
+    Returns
+    -------
+    :
+        A Dataset containing the neutron event/histogram data and the
+        instrument geometry.
+
+    Raises
+    ------
+    RuntimeError
+        If the Mantid workspace type returned by the Mantid loader is not
+        either EventWorkspace or Workspace2D.
+
+    Examples
+    --------
+    >>> from scippneutron import load_with_mantid
+    >>> d = sc.Dataset()
+    >>> d["sample"] = load(filename='PG3_4844_event.nxs',
+    ...                    load_pulse_times=False,
+    ...                    mantid_args={'BankName': 'bank184',
+    ...                                 'LoadMonitors': True})  # doctest: +SKIP
+
+    .. deprecated:: 23.05.0
+       Renamed to load_with_mantid.
+    """
+    import warnings
+
+    from scipp.core.util import VisibleDeprecationWarning
+
+    warnings.warn(
+        "scippneutron.load has been renamed to scippneutron.load_with_mantid. "
+        "The old function is deprecated and is scheduled for removal in "
+        "scippneutron v23.10.0",
+        VisibleDeprecationWarning,
+    )
+    return load_with_mantid(
+        filename,
+        load_pulse_times,
+        instrument_filename,
+        error_connection,
+        mantid_alg,
+        mantid_args,
+        advanced_geometry,
+    )
+
+
 def _is_mantid_loadable(filename):
     from mantid.api import FileFinder
 

tests/mantid_test.py

@@ -10,7 +10,6 @@
 import numpy as np
 import pytest
 import scipp as sc
-import scipp.spatial
 
 import scippneutron as scn
 
@@ -348,7 +347,7 @@ def test_Workspace2D_with_separate_monitors(self):
 
         mtd.clear()
         # This test would use 20 GB of memory if "SpectrumMax" was not set
-        ds = scn.load(
+        ds = scn.load_with_mantid(
             scn.data.get_path("WISH00016748.raw"),
             mantid_args={"LoadMonitors": "Separate", "SpectrumMax": 10000},
         )
@@ -374,7 +373,7 @@ def test_Workspace2D_with_include_monitors(self):
 
         mtd.clear()
         # This test would use 20 GB of memory if "SpectrumMax" was not set
-        ds = scn.load(
+        ds = scn.load_with_mantid(
             scn.data.get_path("WISH00016748.raw"),
             mantid_args={"LoadMonitors": "Include", "SpectrumMax": 100},
         )
@@ -398,7 +397,7 @@ def test_EventWorkspace_with_monitors(self):
         from mantid.simpleapi import mtd
 
         mtd.clear()
-        ds = scn.load(
+        ds = scn.load_with_mantid(
             scn.data.get_path("CNCS_51936_event.nxs"),
             mantid_args={"LoadMonitors": True, "SpectrumMax": 1},
         )
@@ -539,7 +538,7 @@ def test_fit(self):
 
         mtd.clear()
 
-        data = scn.load(scn.data.get_path("iris26176_graphite002_sqw.nxs"))
+        data = scn.load_with_mantid(scn.data.get_path("iris26176_graphite002_sqw.nxs"))
 
         params, diff = scn.fit(
             data['Q', 0],
@@ -1043,7 +1042,7 @@ def test_extract_energy_initial():
     from mantid.simpleapi import mtd
 
     mtd.clear()
-    ds = scn.load(
+    ds = scn.load_with_mantid(
         scn.data.get_path("CNCS_51936_event.nxs"), mantid_args={"SpectrumMax": 1}
     )
     assert sc.identical(
@@ -1097,7 +1096,7 @@ def test_duplicate_monitor_names():
 @pytest.mark.skipif(not mantid_is_available(), reason='Mantid framework is unavailable')
 def test_load_error_when_file_not_found_via_fuzzy_match():
     with pytest.raises(ValueError):
-        scn.load("fictional.nxs")
+        scn.load_with_mantid("fictional.nxs")
 
 
 def make_dynamic_algorithm_without_fileproperty(alg_name):
@@ -1136,7 +1135,7 @@ def test_load_error_when_file_not_found_via_exact_match():
     with pytest.raises(ValueError):
         # DummyLoader has no FileProperty and forces
         # load to evaluate the path given as an absolute path
-        scn.load("fictional.nxs", mantid_alg="DummyLoader")
+        scn.load_with_mantid("fictional.nxs", mantid_alg="DummyLoader")
 
 
 @pytest.mark.skipif(not mantid_is_available(), reason='Mantid framework is unavailable')
@@ -1145,7 +1144,7 @@ def test_load_via_exact_match():
     # scn.load will need to check file exists
     # DummyLoader simply returns a TableWorkspace
     with tempfile.NamedTemporaryFile() as fp:
-        scn.load(fp.name, mantid_alg="DummyLoader")
+        scn.load_with_mantid(fp.name, mantid_alg="DummyLoader")
         # Sanity check corrupt full path will fail
         with pytest.raises(ValueError):
-            scn.load("fictional_" + fp.name, mantid_alg="DummyLoader")
+            scn.load_with_mantid("fictional_" + fp.name, mantid_alg="DummyLoader")

tools/make_tutorial_data.ipynb

@@ -14,7 +14,7 @@
     "\n",
     "url = 'https://github.com/ess-dmsc-dram/loki_tube_scripts/raw/master/test/test_data/LARMOR00049338.nxs'\n",
     "filename, _ = urllib.request.urlretrieve(url)\n",
-    "data = scn.load(filename=filename)\n",
+    "data = scn.load_with_mantid(filename=filename)\n",
     "edges = sc.array(dims=['tof'], unit='us', values=np.linspace(5.0, 100000.0, num=201))\n",
     "data = sc.rebin(data, 'tof', edges)\n",
     "for i in [1, 2, 3, 4, 5]:\n",
@@ -46,7 +46,7 @@
     "import scipp as sc\n",
     "import scippneutron as scn\n",
     "\n",
-    "da = scn.load(filename=f'PG3_4844_event.nxs', load_pulse_times=True)\n",
+    "da = scn.load_with_mantid(filename=f'PG3_4844_event.nxs', load_pulse_times=True)\n",
     "\n",
     "# Fake d-spacing shift\n",
     "da = scn.convert(da, 'tof', 'dspacing', scatter=True)\n",