MAINT: stats.dunnett: transition to rng (SPEC 7)

Author: mdhaber

scipy/stats/_multicomp.py

@@ -11,6 +11,8 @@
 from scipy.stats._common import ConfidenceInterval
 from scipy.stats._qmc import check_random_state
 from scipy.stats._stats_py import _var
+from scipy._lib._util import _transition_to_rng
+
 
 if TYPE_CHECKING:
     import numpy.typing as npt
@@ -180,11 +182,12 @@ def confidence_interval(
         return self._ci
 
 
+@_transition_to_rng('random_state')
 def dunnett(
     *samples: npt.ArrayLike,  # noqa: D417
     control: npt.ArrayLike,
     alternative: Literal['two-sided', 'less', 'greater'] = "two-sided",
-    random_state: SeedType = None
+    rng: SeedType = None
 ) -> DunnettResult:
     """Dunnett's test: multiple comparisons of means against a control group.
 
@@ -211,14 +214,20 @@ def dunnett(
         * 'greater': the means of the distributions underlying the
           samples are greater than the mean of the distribution underlying
           the control.
-    random_state : {None, int, `numpy.random.Generator`}, optional
-        If `random_state` is an int or None, a new `numpy.random.Generator` is
-        created using ``np.random.default_rng(random_state)``.
-        If `random_state` is already a ``Generator`` instance, then the
-        provided instance is used.
+    rng : `numpy.random.Generator`, optional
+        Pseudorandom number generator state. When `rng` is None, a new
+        `numpy.random.Generator` is created using entropy from the
+        operating system. Types other than `numpy.random.Generator` are
+        passed to `numpy.random.default_rng` to instantiate a ``Generator``.
+
+        .. versionchanged:: 1.15.0
 
-        The random number generator is used to control the randomized
-        Quasi-Monte Carlo integration of the multivariate-t distribution.
+            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 `random_state` 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
+            `random_state` keyword will emit warnings.
 
     Returns
     -------
@@ -311,7 +320,7 @@ def dunnett(
     """
     samples_, control_, rng = _iv_dunnett(
         samples=samples, control=control,
-        alternative=alternative, random_state=random_state
+        alternative=alternative, rng=rng
     )
 
     rho, df, n_group, n_samples, n_control = _params_dunnett(
@@ -342,10 +351,10 @@ def _iv_dunnett(
     samples: Sequence[npt.ArrayLike],
     control: npt.ArrayLike,
     alternative: Literal['two-sided', 'less', 'greater'],
-    random_state: SeedType
+    rng: SeedType
 ) -> tuple[list[np.ndarray], np.ndarray, SeedType]:
     """Input validation for Dunnett's test."""
-    rng = check_random_state(random_state)
+    rng = check_random_state(rng)
 
     if alternative not in {'two-sided', 'less', 'greater'}:
         raise ValueError(

scipy/stats/tests/test_multicomp.py

@@ -220,7 +220,7 @@ def test_critical_values(
     def test_basic(self, samples, control, pvalue, statistic):
         rng = np.random.default_rng(11681140010308601919115036826969764808)
 
-        res = stats.dunnett(*samples, control=control, random_state=rng)
+        res = stats.dunnett(*samples, control=control, rng=rng)
 
         assert isinstance(res, DunnettResult)
         assert_allclose(res.statistic, statistic, rtol=5e-5)
@@ -239,6 +239,7 @@ def test_ttest_ind(self, alternative):
             sample = rng.integers(-100, 100, size=(10,))
             control = rng.integers(-100, 100, size=(10,))
 
+            # preserve use of old random_state during SPEC 7 transition
             res = stats.dunnett(
                 sample, control=control,
                 alternative=alternative, random_state=rng
@@ -270,7 +271,7 @@ def test_alternatives(self, alternative, pvalue):
 
         res = stats.dunnett(
             sample_less, sample_greater, control=control,
-            alternative=alternative, random_state=rng
+            alternative=alternative, rng=rng
         )
         assert_allclose(res.pvalue, pvalue, atol=1e-7)
 
@@ -301,7 +302,7 @@ def test_against_R_multicomp_glht(self, case, alternative):
         p_ref = case['pvalues'][alternative.replace('-', '')]
 
         res = stats.dunnett(*samples, control=control, alternative=alternative,
-                            random_state=rng)
+                            rng=rng)
         # atol can't be tighter because R reports some pvalues as "< 1e-4"
         assert_allclose(res.pvalue, p_ref, rtol=5e-3, atol=1e-4)
 
@@ -328,7 +329,7 @@ def test_str(self, alternative):
 
         res = stats.dunnett(
             *self.samples_3, control=self.control_3, alternative=alternative,
-            random_state=rng
+            rng=rng
         )
 
         # check some str output
@@ -350,7 +351,7 @@ def test_warnings(self):
         rng = np.random.default_rng(189117774084579816190295271136455278291)
 
         res = stats.dunnett(
-            *self.samples_3, control=self.control_3, random_state=rng
+            *self.samples_3, control=self.control_3, rng=rng
         )
         msg = r"Computation of the confidence interval did not converge"
         with pytest.warns(UserWarning, match=msg):
@@ -396,7 +397,7 @@ def test_shapes(self, n_samples):
         rng = np.random.default_rng(689448934110805334)
         samples = rng.normal(size=(n_samples, 10))
         control = rng.normal(size=10)
-        res = stats.dunnett(*samples, control=control, random_state=rng)
+        res = stats.dunnett(*samples, control=control, rng=rng)
         assert res.statistic.shape == (n_samples,)
         assert res.pvalue.shape == (n_samples,)
         ci = res.confidence_interval()