Merge pull request scipy#21881 from mdhaber/stats_spec7

Author: tupui

scipy/stats/_fit.py

@@ -2,7 +2,7 @@
 from collections import namedtuple
 import numpy as np
 from scipy import optimize, stats
-from scipy._lib._util import check_random_state
+from scipy._lib._util import check_random_state, _transition_to_rng
 
 
 def _combine_bounds(name, user_bounds, shape_domain, integral):
@@ -738,9 +738,10 @@ def nlpsf(free_params, data=data):  # bind data NOW
                                   'null_distribution'))
 
 
+@_transition_to_rng('random_state')
 def goodness_of_fit(dist, data, *, known_params=None, fit_params=None,
                     guessed_params=None, statistic='ad', n_mc_samples=9999,
-                    random_state=None):
+                    rng=None):
     r"""
     Perform a goodness of fit test comparing data to a distribution family.
 
@@ -797,18 +798,11 @@ def goodness_of_fit(dist, data, *, known_params=None, fit_params=None,
         The number of Monte Carlo samples drawn from the null hypothesized
         distribution to form the null distribution of the statistic. The
         sample size of each is the same as the given `data`.
-    random_state : {None, int, `numpy.random.Generator`,
-                    `numpy.random.RandomState`}, optional
-
-        Pseudorandom number generator state used to generate the Monte Carlo
-        samples.
-
-        If `random_state` is ``None`` (default), 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 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``.
 
     Returns
     -------
@@ -996,7 +990,7 @@ def goodness_of_fit(dist, data, *, known_params=None, fit_params=None,
 
     >>> known_params = {'loc': loc, 'scale': scale}
     >>> res = stats.goodness_of_fit(stats.norm, x, known_params=known_params,
-    ...                             statistic='ks', random_state=rng)
+    ...                             statistic='ks', rng=rng)
     >>> res.statistic, res.pvalue
     (0.1119257570456813, 0.2788)
 
@@ -1030,7 +1024,7 @@ def goodness_of_fit(dist, data, *, known_params=None, fit_params=None,
     as described above. This is where `goodness_of_fit` excels.
 
     >>> res = stats.goodness_of_fit(stats.norm, x, statistic='ks',
-    ...                             random_state=rng)
+    ...                             rng=rng)
     >>> res.statistic, res.pvalue
     (0.1119257570456813, 0.0196)
 
@@ -1062,7 +1056,7 @@ def goodness_of_fit(dist, data, *, known_params=None, fit_params=None,
     estimate it directly.
 
     >>> res = stats.goodness_of_fit(stats.norm, x, statistic='ad',
-    ...                             random_state=rng)
+    ...                             rng=rng)
     >>> res.statistic, res.pvalue
     (1.2139573337497467, 0.0034)
 
@@ -1078,7 +1072,7 @@ def goodness_of_fit(dist, data, *, known_params=None, fit_params=None,
     >>> rng = np.random.default_rng()
     >>> x = stats.chi(df=2.2, loc=0, scale=2).rvs(size=1000, random_state=rng)
     >>> res = stats.goodness_of_fit(stats.rayleigh, x, statistic='cvm',
-    ...                             known_params={'loc': 0}, random_state=rng)
+    ...                             known_params={'loc': 0}, rng=rng)
 
     This executes fairly quickly, but to check the reliability of the ``fit``
     method, we should inspect the fit result.
@@ -1118,9 +1112,9 @@ def goodness_of_fit(dist, data, *, known_params=None, fit_params=None,
 
     """
     args = _gof_iv(dist, data, known_params, fit_params, guessed_params,
-                   statistic, n_mc_samples, random_state)
+                   statistic, n_mc_samples, rng)
     (dist, data, fixed_nhd_params, fixed_rfd_params, guessed_nhd_params,
-     guessed_rfd_params, statistic, n_mc_samples_int, random_state) = args
+     guessed_rfd_params, statistic, n_mc_samples_int, rng) = args
 
     # Fit null hypothesis distribution to data
     nhd_fit_fun = _get_fit_fun(dist, data, guessed_nhd_params,
@@ -1129,7 +1123,7 @@ def goodness_of_fit(dist, data, *, known_params=None, fit_params=None,
     nhd_dist = dist(*nhd_vals)
 
     def rvs(size):
-        return nhd_dist.rvs(size=size, random_state=random_state)
+        return nhd_dist.rvs(size=size, random_state=rng)
 
     # Define statistic
     fit_fun = _get_fit_fun(dist, data, guessed_rfd_params, fixed_rfd_params)
@@ -1299,7 +1293,7 @@ def _cramer_von_mises(dist, data, axis):
 
 
 def _gof_iv(dist, data, known_params, fit_params, guessed_params, statistic,
-            n_mc_samples, random_state):
+            n_mc_samples, rng):
 
     if not isinstance(dist, stats.rv_continuous):
         message = ("`dist` must be a (non-frozen) instance of "
@@ -1349,7 +1343,7 @@ def _gof_iv(dist, data, known_params, fit_params, guessed_params, statistic,
         message = "`n_mc_samples` must be an integer."
         raise TypeError(message)
 
-    random_state = check_random_state(random_state)
+    rng = check_random_state(rng)
 
     return (dist, data, fixed_nhd_params, fixed_rfd_params, guessed_nhd_params,
-            guessed_rfd_params, statistic, n_mc_samples_int, random_state)
+            guessed_rfd_params, statistic, n_mc_samples_int, rng)

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', replace_doc=False)
 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,21 @@ 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.
-
-        The random number generator is used to control the randomized
-        Quasi-Monte Carlo integration of the multivariate-t distribution.
+    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
+
+            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. Following a
+            deprecation period, the `random_state` keyword will be removed.
 
     Returns
     -------
@@ -311,7 +321,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 +352,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/_sensitivity_analysis.py

@@ -13,6 +13,7 @@
 from scipy.stats._qmc import check_random_state
 from scipy.stats._resampling import BootstrapResult
 from scipy.stats import qmc, bootstrap
+from scipy._lib._util import _transition_to_rng
 
 
 if TYPE_CHECKING:
@@ -61,7 +62,7 @@ def f_ishigami(x: npt.ArrayLike) -> np.ndarray:
 def sample_A_B(
     n: IntNumber,
     dists: list[PPFDist],
-    random_state: SeedType = None
+    rng: SeedType = None
 ) -> np.ndarray:
     """Sample two matrices A and B.
 
@@ -80,7 +81,7 @@ def sample_A_B(
        :doi:`10.1016/j.cpc.2009.09.018`, 2010.
     """
     d = len(dists)
-    A_B = qmc.Sobol(d=2*d, seed=random_state, bits=64).random(n).T
+    A_B = qmc.Sobol(d=2*d, seed=rng, bits=64).random(n).T
     A_B = A_B.reshape(2, d, -1)
     try:
         for d_, dist in enumerate(dists):
@@ -246,14 +247,15 @@ def ppf(self) -> Callable[..., float]:
         ...
 
 
+@_transition_to_rng('random_state', replace_doc=False)
 def sobol_indices(
     *,
     func: Callable[[np.ndarray], npt.ArrayLike] |
           dict[Literal['f_A', 'f_B', 'f_AB'], np.ndarray],
     n: IntNumber,
     dists: list[PPFDist] | None = None,
     method: Callable | Literal['saltelli_2010'] = 'saltelli_2010',
-    random_state: SeedType = None
+    rng: SeedType = None
 ) -> SobolResult:
     r"""Global sensitivity indices of Sobol'.
 
@@ -309,11 +311,21 @@ def sobol_indices(
         The output is a tuple of the first and total indices with
         shape ``(s, d)``.
         This is an advanced feature and misuse can lead to wrong analysis.
-    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
+
+            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. Following a
+            deprecation period, the `random_state` keyword will be removed.
 
     Returns
     -------
@@ -466,7 +478,7 @@ def sobol_indices(
     ...         uniform(loc=-np.pi, scale=2*np.pi),
     ...         uniform(loc=-np.pi, scale=2*np.pi)
     ...     ],
-    ...     random_state=rng
+    ...     rng=rng
     ... )
     >>> indices.first_order
     array([0.31637954, 0.43781162, 0.00318825])
@@ -587,7 +599,7 @@ def sobol_indices(
     conclude on high-order terms. Hence the benefit of using Sobol' indices.
 
     """
-    random_state = check_random_state(random_state)
+    rng = check_random_state(rng)
 
     n_ = int(n)
     if not (n_ & (n_ - 1) == 0) or n != n_:
@@ -637,7 +649,7 @@ def indices_method(f_A, f_B, f_AB):
         def wrapped_func(x):
             return np.atleast_2d(func(x))
 
-        A, B = sample_A_B(n=n, dists=dists, random_state=random_state)
+        A, B = sample_A_B(n=n, dists=dists, rng=rng)
         AB = sample_AB(A=A, B=B)
 
         f_A = wrapped_func(A)