docs: deprecate convert

src/scippneutron/core/conversions.py

@@ -2,6 +2,7 @@
 # Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
 # @author Jan-Lukas Wynen
 
+import warnings
 from collections.abc import Callable
 
 import scipp as sc
@@ -140,8 +141,21 @@ def convert(
     :seealso: :py:func:`scippneutron.deduce_conversion_graph` and
               :py:func:`scippneutron.conversion_graph` to inspect
               the possible conversions.
+
+    .. deprecated:: 26.8.0
+       Use :py:meth:`scipp.DataArray.transform_coords` or
+       :py:meth:`scipp.Dataset.transform_coords` with a graph from
+       :py:mod:`scippneutron.conversion.graph` instead.
     """
 
+    warnings.warn(
+        "scippneutron.convert is deprecated and will be removed in a future "
+        "release. Use scipp.transform_coords with a graph from "
+        "scippneutron.conversion.graph instead.",
+        sc.VisibleDeprecationWarning,
+        stacklevel=2,
+    )
+
     graph = deduce_conversion_graph(data, origin, target, scatter)
 
     try:

tests/convert_test.py

@@ -11,6 +11,10 @@
 
 import scippneutron as scn
 
+pytestmark = pytest.mark.filterwarnings(
+    'ignore:scippneutron.convert is deprecated:scipp.VisibleDeprecationWarning'
+)
+
 
 def make_source_position():
     return sc.vector(value=[0.0, 0.0, -10.0], unit='m')
@@ -88,6 +92,16 @@ def make_test_data(coords=(), dataset=False):
     return da
 
 
+def test_convert_is_deprecated():
+    tof = make_test_data(coords=('tof', 'Ltotal'))
+    with pytest.warns(
+        sc.VisibleDeprecationWarning,
+        match=r'scippneutron\.convert is deprecated.*scipp\.transform_coords',
+    ) as warnings:
+        scn.convert(tof, origin='tof', target='wavelength', scatter=True)
+    assert warnings[0].filename == __file__
+
+
 def make_tof_binned_events():
     buffer = sc.DataArray(
         sc.zeros(dims=['event'], shape=[7], dtype=float),

tests/mantid_scipp_comparison/neutron_convert_units_test.py

@@ -79,7 +79,15 @@ def test_mantid_convert_tof_to_wavelength():
     out_mantid = mantid_convert_units(in_ws, 'wavelength')
 
     in_da = scn.mantid.from_mantid(in_ws)['data']
-    out_scipp = scn.convert(data=in_da, origin='tof', target='wavelength', scatter=True)
+    out_scipp = in_da.transform_coords(
+        'wavelength',
+        graph=scn.conversion_graph(
+            origin='tof',
+            target='wavelength',
+            scatter=True,
+            energy_mode='elastic',
+        ),
+    )
 
     assert sc.allclose(
         out_scipp.coords['wavelength'],
@@ -94,7 +102,15 @@ def test_mantid_convert_tof_to_dspacing():
     out_mantid = mantid_convert_units(in_ws, 'dspacing')
 
     in_da = scn.mantid.from_mantid(in_ws)['data']
-    out_scipp = scn.convert(data=in_da, origin='tof', target='dspacing', scatter=True)
+    out_scipp = in_da.transform_coords(
+        'dspacing',
+        graph=scn.conversion_graph(
+            origin='tof',
+            target='dspacing',
+            scatter=True,
+            energy_mode='elastic',
+        ),
+    )
 
     assert sc.allclose(
         out_scipp.coords['dspacing'],
@@ -109,7 +125,15 @@ def test_mantid_convert_tof_to_energy():
     out_mantid = mantid_convert_units(in_ws, 'energy')
 
     in_da = scn.mantid.from_mantid(in_ws)['data']
-    out_scipp = scn.convert(data=in_da, origin='tof', target='energy', scatter=True)
+    out_scipp = in_da.transform_coords(
+        'energy',
+        graph=scn.conversion_graph(
+            origin='tof',
+            target='energy',
+            scatter=True,
+            energy_mode='elastic',
+        ),
+    )
 
     # Mantid reverses the order of the energy dim.
     mantid_energy = sc.empty_like(out_mantid.coords['energy'])
@@ -130,8 +154,14 @@ def test_mantid_convert_tof_to_direct_energy_transfer():
     )
 
     in_da = scn.mantid.from_mantid(in_ws)['data']
-    out_scipp = scn.convert(
-        data=in_da, origin='tof', target='energy_transfer', scatter=True
+    out_scipp = in_da.transform_coords(
+        'energy_transfer',
+        graph=scn.conversion_graph(
+            origin='tof',
+            target='energy_transfer',
+            scatter=True,
+            energy_mode='direct_inelastic',
+        ),
     )
 
     # The conversion consists of multiplications and additions, thus the relative error

tests/mantid_test.py

@@ -169,7 +169,15 @@ def test_unit_conversion(self):
         )['data']
         da = da.hist(tof=target_tof)
         d = sc.Dataset(data={da.name: da})
-        converted = scn.convert(d, 'tof', 'wavelength', scatter=True)
+        converted = d.transform_coords(
+            'wavelength',
+            graph=scn.conversion_graph(
+                origin='tof',
+                target='wavelength',
+                scatter=True,
+                energy_mode='elastic',
+            ),
+        )
 
         assert sc.allclose(
             converted_mantid['data'].data, converted[""].data.to(dtype='float64')
@@ -203,7 +211,15 @@ def test_inelastic_unit_conversion(self):
         da.coords['position'] *= np.sqrt(scale)
         low_tof = da.bins.constituents['data'].coords['tof'] < 49000.0 * sc.units.us
         da.coords['incident_energy'] = 3.0 * sc.units.meV
-        da = scn.convert(da, 'tof', 'energy_transfer', scatter=True)
+        da = da.transform_coords(
+            'energy_transfer',
+            graph=scn.conversion_graph(
+                origin='tof',
+                target='energy_transfer',
+                scatter=True,
+                energy_mode='direct_inelastic',
+            ),
+        )
         assert sc.all(
             sc.isnan(da.coords['energy_transfer'])
             | sc.isclose(