Merge pull request scipy#21913 from mdhaber/directed_hausdorff_spec7

API: `spatial.directed_hausdorff`: transition to 'rng' keyword (SPEC 7)

Author: tylerjereddy

scipy/spatial/distance.py

@@ -112,7 +112,7 @@
 
 from collections.abc import Callable
 from functools import partial
-from scipy._lib._util import _asarray_validated
+from scipy._lib._util import _asarray_validated, _transition_to_rng
 from scipy._lib.deprecation import _deprecated
 
 from . import _distance_wrap
@@ -309,7 +309,8 @@ def _validate_weights(w, dtype=np.float64):
     return w
 
 
-def directed_hausdorff(u, v, seed=0):
+@_transition_to_rng('seed', position_num=2, replace_doc=False)
+def directed_hausdorff(u, v, rng=0):
     """
     Compute the directed Hausdorff distance between two 2-D arrays.
 
@@ -321,10 +322,35 @@ def directed_hausdorff(u, v, seed=0):
         Input array with M points in N dimensions.
     v : (O,N) array_like
         Input array with O points in N dimensions.
-    seed : int or `numpy.random.Generator` or None, optional
-        Local `numpy.random.RandomState` seed. Default is 0, a random
-        shuffling of u and v that guarantees reproducibility. Also
-        accepts a `numpy.random.Generator` object.
+    rng : int or `numpy.random.Generator` or None, optional
+        Pseudorandom number generator state. Default is 0 so the
+        shuffling of `u` and `v` is reproducible.
+
+        If `rng` is passed by keyword, types other than `numpy.random.Generator` are
+        passed to `numpy.random.default_rng` to instantiate a ``Generator``.
+        If `rng` is already a ``Generator`` instance, then the provided instance is
+        used.
+
+        If this argument is passed by position or `seed` is passed by keyword,
+        legacy behavior for the argument `seed` applies:
+
+        - If `seed` is None, a new ``RandomState`` instance is used. The state is
+          initialized using data from ``/dev/urandom`` (or the Windows analogue)
+          if available or from the system clock otherwise.
+        - If `seed` is an int, a new ``RandomState`` instance is used,
+          seeded with `seed`.
+        - If `seed` is already a ``Generator`` or ``RandomState`` instance, then
+          that instance is used.
+
+        .. versionchanged:: 1.15.0
+            As part of the `SPEC-007 <https://scientific-python.org/specs/spec-0007/>`_
+            transition from use of `numpy.random.RandomState` to
+            `numpy.random.Generator`, this keyword was changed from `seed` to `rng`.
+            For an interim period, both keywords will continue to work, although only
+            one may be specified at a time. After the interim period, function calls
+            using the `seed` keyword will emit warnings. The behavior of both `seed`
+            and `rng` are outlined above, but only the `rng` keyword should be used in
+            new code.
 
     Returns
     -------
@@ -407,7 +433,7 @@ def directed_hausdorff(u, v, seed=0):
     if u.shape[1] != v.shape[1]:
         raise ValueError('u and v need to have the same '
                          'number of columns')
-    result = _hausdorff.directed_hausdorff(u, v, seed)
+    result = _hausdorff.directed_hausdorff(u, v, rng)
     return result
 
 

scipy/spatial/tests/test_hausdorff.py

@@ -123,6 +123,7 @@ def test_invalid_dimensions(self):
         with pytest.raises(ValueError, match=msg):
             directed_hausdorff(A, B)
 
+    # preserve use of legacy keyword `seed` during SPEC 7 transition
     @pytest.mark.parametrize("A, B, seed, expected", [
         # the two cases from gh-11332
         ([(0,0)],
@@ -167,6 +168,11 @@ def test_subsets(self, A, B, seed, expected):
         # check indices
         assert actual[1:] == expected[1:]
 
+        if not isinstance(seed, np.random.RandomState):
+            # Check that new `rng` keyword is also accepted
+            actual = directed_hausdorff(u=A, v=B, rng=seed)
+            assert_allclose(actual[0], expected[0])
+
 
 @pytest.mark.xslow
 def test_massive_arr_overflow():