API: stats.{PermutationMethod,BootstrapMethod}: transition to rng (SPEC 7) (scipy#21886)

* MAINT: stats.PermutationMethod: transition to rng (SPEC 7)

* Apply suggestions from code review

* STY: stats.PermutationMethod: fix mypy and lint complaints

* MAINT: stats.PermutationMethod: adjustments per review

* MAINT: stats.BootstrapMethod: transition to rng (SPEC 7)

Author: mdhaber

scipy/stats/_resampling.py

@@ -4,7 +4,7 @@
 import numpy as np
 from itertools import combinations, permutations, product
 from collections.abc import Sequence
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 import inspect
 
 from scipy._lib._util import (check_random_state, _rename_parameter, rng_integers,
@@ -2167,6 +2167,20 @@ def _asdict(self):
                     rvs=self.rvs)
 
 
+_rs_deprecation = ("Use of attribute `random_state` is deprecated and replaced by "
+                   "`rng`. Support for `random_state` will be removed in SciPy 1.19.0. "
+                   "To silence this warning and ensure consistent behavior in SciPy "
+                   "1.19.0, control the RNG using attribute `rng`. Values set using "
+                   "attribute `rng` will be validated by `np.random.default_rng`, so "
+                   "the behavior corresponding with a given value may change compared "
+                   "to use of `random_state`. For example, 1) `None` will result in "
+                   "unpredictable random numbers, 2) an integer will result in a "
+                   "different stream of random numbers, (with the same distribution), "
+                   "and 3) `np.random` or `RandomState` instances will result in an "
+                   "error. See the documentation of `default_rng` for more "
+                   "information.")
+
+
 @dataclass
 class PermutationMethod(ResamplingMethod):
     """Configuration information for a permutation hypothesis test.
@@ -2184,24 +2198,69 @@ class PermutationMethod(ResamplingMethod):
         the statistic. Batch sizes >>1 tend to be faster when the statistic
         is vectorized, but memory usage scales linearly with the batch size.
         Default is ``None``, which processes all resamples in a single batch.
-    random_state : {None, int, `numpy.random.Generator`,
-                    `numpy.random.RandomState`}, optional
-
-        Pseudorandom number generator state used to generate resamples.
+    rng : `numpy.random.Generator`, optional
+        Pseudorandom number generator used to perform resampling.
+
+        If `rng` is passed by keyword to the initializer or the `rng` attribute is used
+        directly, 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. Specify `rng` for repeatable behavior.
+
+        If this argument is passed by position, if `random_state` is passed by keyword
+        into the initializer, or if the `random_state` attribute is used directly,
+        legacy behavior for `random_state` applies:
+
+        - If `random_state` is None (or `numpy.random`), the `numpy.random.RandomState`
+          singleton is used.
+        - If `random_state` is an int, a new ``RandomState`` instance is used,
+          seeded with `random_state`.
+        - If `random_state` 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 attribute name was changed from
+            `random_state` to `rng`. For an interim period, both names will continue to
+            work, although only one may be specified at a time. After the interim
+            period, uses of `random_state` will emit warnings. The behavior of both
+            `random_state` and `rng` are outlined above, but only `rng` should be used
+            in new code.
 
-        If `random_state` is already a ``Generator`` or ``RandomState``
-        instance, then that instance is used.
-        If `random_state` is an int, a new ``RandomState`` instance is used,
-        seeded with `random_state`.
-        If `random_state` is ``None`` (default), the
-        `numpy.random.RandomState` singleton is used.
     """
-    random_state: object = None
+    rng: object  # type: ignore[misc]
+    _rng: object = field(init=False, repr=False, default=None)  # type: ignore[assignment]
+
+    @property
+    def random_state(self):
+        # Uncomment in SciPy 1.17.0
+        # warnings.warn(_rs_deprecation, DeprecationWarning, stacklevel=2)
+        return self._rng
+
+    @random_state.setter
+    def random_state(self, val):
+        # Uncomment in SciPy 1.17.0
+        # warnings.warn(_rs_deprecation, DeprecationWarning, stacklevel=2)
+        self._rng = val
+
+    @property  # type: ignore[no-redef]
+    def rng(self):  # noqa: F811
+        return self._rng
+
+    @random_state.setter
+    def rng(self, val):  # noqa: F811
+        self._rng = np.random.default_rng(val)
+
+    @_transition_to_rng('random_state', position_num=3, replace_doc=False)
+    def __init__(self, n_resamples=9999, batch=None, rng=None):
+        self._rng = rng  # don't validate with `default_rng` during SPEC 7 transition
+        super().__init__(n_resamples=n_resamples, batch=batch)
 
     def _asdict(self):
         # `dataclasses.asdict` deepcopies; we don't want that.
-        return dict(n_resamples=self.n_resamples, batch=self.batch,
-                    random_state=self.random_state)
+        return dict(n_resamples=self.n_resamples, batch=self.batch, rng=self.rng)
 
 
 @dataclass
@@ -2220,26 +2279,73 @@ class BootstrapMethod(ResamplingMethod):
         the statistic. Batch sizes >>1 tend to be faster when the statistic
         is vectorized, but memory usage scales linearly with the batch size.
         Default is ``None``, which processes all resamples in a single batch.
-    random_state : {None, int, `numpy.random.Generator`,
-                    `numpy.random.RandomState`}, optional
-
-        Pseudorandom number generator state used to generate resamples.
-
-        If `random_state` is already a ``Generator`` or ``RandomState``
-        instance, then that instance is used.
-        If `random_state` is an int, a new ``RandomState`` instance is used,
-        seeded with `random_state`.
-        If `random_state` is ``None`` (default), the
-        `numpy.random.RandomState` singleton is used.
-
-    method : {'bca', 'percentile', 'basic'}
+    rng : `numpy.random.Generator`, optional
+        Pseudorandom number generator used to perform resampling.
+
+        If `rng` is passed by keyword to the initializer or the `rng` attribute is used
+        directly, 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. Specify `rng` for repeatable behavior.
+
+        If this argument is passed by position, if `random_state` is passed by keyword
+        into the initializer, or if the `random_state` attribute is used directly,
+        legacy behavior for `random_state` applies:
+
+        - If `random_state` is None (or `numpy.random`), the `numpy.random.RandomState`
+          singleton is used.
+        - If `random_state` is an int, a new ``RandomState`` instance is used,
+          seeded with `random_state`.
+        - If `random_state` 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 attribute name was changed from
+            `random_state` to `rng`. For an interim period, both names will continue to
+            work, although only one may be specified at a time. After the interim
+            period, uses of `random_state` will emit warnings. The behavior of both
+            `random_state` and `rng` are outlined above, but only `rng` should be used
+            in new code.
+
+    method : {'BCa', 'percentile', 'basic'}
         Whether to use the 'percentile' bootstrap ('percentile'), the 'basic'
         (AKA 'reverse') bootstrap ('basic'), or the bias-corrected and
         accelerated bootstrap ('BCa', default).
+
     """
-    random_state: object = None
+    rng: object  # type: ignore[misc]
+    _rng: object = field(init=False, repr=False, default=None)  # type: ignore[assignment]
     method: str = 'BCa'
 
+    @property
+    def random_state(self):
+        # Uncomment in SciPy 1.17.0
+        # warnings.warn(_rs_deprecation, DeprecationWarning, stacklevel=2)
+        return self._rng
+
+    @random_state.setter
+    def random_state(self, val):
+        # Uncomment in SciPy 1.17.0
+        # warnings.warn(_rs_deprecation, DeprecationWarning, stacklevel=2)
+        self._rng = val
+
+    @property  # type: ignore[no-redef]
+    def rng(self):  # noqa: F811
+        return self._rng
+
+    @random_state.setter
+    def rng(self, val):  # noqa: F811
+        self._rng = np.random.default_rng(val)
+
+    @_transition_to_rng('random_state', position_num=3, replace_doc=False)
+    def __init__(self, n_resamples=9999, batch=None, rng=None, method='BCa'):
+        self._rng = rng  # don't validate with `default_rng` during SPEC 7 transition
+        self.method = method
+        super().__init__(n_resamples=n_resamples, batch=batch)
+
     def _asdict(self):
         # `dataclasses.asdict` deepcopies; we don't want that.
         return dict(n_resamples=self.n_resamples, batch=self.batch,

scipy/stats/tests/test_correlation.py

@@ -44,7 +44,7 @@ def test_permutation_asymptotic(self, y_continuous):
         x = rng.random(size=shape)
         y = (rng.random(size=shape) if y_continuous
              else rng.integers(0, 10, size=shape))
-        method = stats.PermutationMethod(random_state=rng)
+        method = stats.PermutationMethod(rng=rng)
         res = stats.chatterjeexi(x, y, method=method,
                                  y_continuous=y_continuous, axis=-1)
         ref = stats.chatterjeexi(x, y, y_continuous=y_continuous, axis=-1)

scipy/stats/tests/test_hypotests.py

@@ -1817,19 +1817,19 @@ def test_method(self):
         x, y = rng.random(size=(2, 10))
 
         rng = np.random.default_rng(1520514347193347862)
-        method = stats.PermutationMethod(n_resamples=10, random_state=rng)
+        method = stats.PermutationMethod(n_resamples=10, rng=rng)
         res1 = stats.bws_test(x, y, method=method)
 
         assert len(res1.null_distribution) == 10
 
         rng = np.random.default_rng(1520514347193347862)
-        method = stats.PermutationMethod(n_resamples=10, random_state=rng)
+        method = stats.PermutationMethod(n_resamples=10, rng=rng)
         res2 = stats.bws_test(x, y, method=method)
 
         assert_allclose(res1.null_distribution, res2.null_distribution)
 
         rng = np.random.default_rng(5205143471933478621)
-        method = stats.PermutationMethod(n_resamples=10, random_state=rng)
+        method = stats.PermutationMethod(n_resamples=10, rng=rng)
         res3 = stats.bws_test(x, y, method=method)
 
         assert not np.allclose(res3.null_distribution, res1.null_distribution)

scipy/stats/tests/test_morestats.py

@@ -464,7 +464,7 @@ def test_example2a(self):
         assert_allclose(p, 0.0041, atol=0.00025)
 
         rng = np.random.default_rng(6989860141921615054)
-        method = stats.PermutationMethod(n_resamples=9999, random_state=rng)
+        method = stats.PermutationMethod(n_resamples=9999, rng=rng)
         res = stats.anderson_ksamp(samples, midrank=False, method=method)
         assert_array_equal(res.statistic, Tk)
         assert_array_equal(res.critical_values, tm)
@@ -1728,14 +1728,15 @@ def test_permutation_method(self, size):
 
         x = rng.random(size=size*10)
         rng = np.random.default_rng(59234803482850134)
-        pm = stats.PermutationMethod(n_resamples=99, random_state=rng)
+        pm = stats.PermutationMethod(n_resamples=99, rng=rng)
         ref = stats.wilcoxon(x, method=pm)
+        # preserve use of old random_state during SPEC 7 transition
         rng = np.random.default_rng(59234803482850134)
         pm = stats.PermutationMethod(n_resamples=99, random_state=rng)
         res = stats.wilcoxon(x, method=pm)
 
         assert_equal(np.round(res.pvalue, 2), res.pvalue)  # n_resamples used
-        assert_equal(res.pvalue, ref.pvalue)  # random_state used
+        assert_equal(res.pvalue, ref.pvalue)  # rng/random_state used
 
     def test_method_auto_nan_propagate_ND_length_gt_50_gh20591(self):
         # When method!='asymptotic', nan_policy='propagate', and a slice of

scipy/stats/tests/test_stats.py

@@ -631,7 +631,7 @@ def test_resampling_pvalue(self, method, alternative):
         size = (2, 100) if method == 'permutation' else (2, 1000)
         x = rng.normal(size=size)
         y = rng.normal(size=size)
-        methods = {'permutation': stats.PermutationMethod(random_state=rng),
+        methods = {'permutation': stats.PermutationMethod(rng=rng),
                    'monte_carlo': stats.MonteCarloMethod(rvs=(rng.normal,)*2)}
         method = methods[method]
         res = stats.pearsonr(x, y, alternative=alternative, method=method, axis=-1)
@@ -647,12 +647,19 @@ def test_bootstrap_ci(self, alternative):
         y = rng.normal(size=(2, 100))
         res = stats.pearsonr(x, y, alternative=alternative, axis=-1)
 
+        # preserve use of old random_state during SPEC 7 transition
+        rng = np.random.default_rng(724358723498249852)
         method = stats.BootstrapMethod(random_state=rng)
         res_ci = res.confidence_interval(method=method)
         ref_ci = res.confidence_interval()
-
         assert_allclose(res_ci, ref_ci, atol=1.5e-2)
 
+        # `rng` is the new argument name`
+        rng = np.random.default_rng(724358723498249852)
+        method = stats.BootstrapMethod(rng=rng)
+        res_ci2 = res.confidence_interval(method=method)
+        assert_allclose(res_ci2, res_ci)
+
     @pytest.mark.skip_xp_backends(np_only=True)
     @pytest.mark.parametrize('axis', [0, 1])
     def test_axis01(self, axis, xp):