diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index aab566fd2..9c9ec8961 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -76,7 +76,7 @@ chainladder-python/ │ │ ├── sparse.py # COO sparse array wrapper │ │ ├── cupy.py # CuPy GPU array shim │ │ ├── dask.py # Dask parallel shim -│ │ ├── utility_functions.py # num_to_nan, set_common_backend, etc. +│ │ ├── utility_functions.py # num_to_nan, set_common_backend, RandomStateMixin, etc. │ │ ├── weighted_regression.py # WeightedRegression helper │ │ ├── triangle_weight.py # Triangle weighting helpers │ │ ├── data/ # Bundled sample datasets (CSV) @@ -229,7 +229,7 @@ sklearn.BaseEstimator ├── CaseOutstanding development/outstanding.py ├── TweedieGLM development/glm.py │ └── BarnettZehnwirth development/barnzehn.py - ├── BootstrapODPSample adjustments/bootstrap.py + ├── BootstrapODPSample adjustments/bootstrap.py (also extends RandomStateMixin) ├── DisposalRate adjustments/disposal.py (also extends DisposalMixin) │ └── TailBase tails/base.py — appends tail column, extends DevelopmentBase @@ -247,7 +247,7 @@ sklearn.BaseEstimator ├── Chainladder methods/chainladder.py │ └── MackChainladder methods/mack.py │ - └── Benktander methods/benktander.py + └── Benktander methods/benktander.py (also extends RandomStateMixin) ├── BornhuetterFerguson methods/bornferg.py ├── CapeCod methods/capecod.py └── ExpectedLoss methods/expectedloss.py diff --git a/chainladder/adjustments/bootstrap.py b/chainladder/adjustments/bootstrap.py index f7d985488..4f328d633 100644 --- a/chainladder/adjustments/bootstrap.py +++ b/chainladder/adjustments/bootstrap.py @@ -4,13 +4,14 @@ from chainladder.methods.chainladder import Chainladder from chainladder.development import DevelopmentBase, Development +from chainladder.utils.utility_functions import RandomStateMixin import numpy as np import pandas as pd from warnings import warn import types -class BootstrapODPSample(DevelopmentBase): +class BootstrapODPSample(DevelopmentBase, RandomStateMixin): """ Class to generate bootstrap samples of triangles. Currently this Only supports 'single' triangles (single index and single column). @@ -38,8 +39,10 @@ class BootstrapODPSample(DevelopmentBase): random_state: int, RandomState instance or None, optional (default=None) If int, random_state is the seed used by the random number generator; If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by np.random. + If None, ``fit`` draws an integer seed from the RandomState instance + used by np.random and keeps it as ``random_state_``. With several + columns, each column then draws its own seed, so the columns' draws + stay independent. Attributes ---------- @@ -47,6 +50,13 @@ class BootstrapODPSample(DevelopmentBase): A set of triangles represented by each simulation scale_: The scale parameter to be used in generating process risk + random_state_: int or RandomState instance + The seed the draws used: ``random_state`` when it is an integer or a + RandomState instance, otherwise the integer ``fit`` drew. Passing it + back as ``random_state`` repeats the run, except on a triangle with + several columns fitted with ``random_state=None``: each column drew its + own seed and ``random_state_`` seeds only the process-variance draws, + so calling ``np.random.seed`` before ``fit`` repeats that run instead. See Also -------- @@ -165,11 +175,17 @@ def __init__( self.random_state = random_state def fit(self, X, y=None, sample_weight=None): + self._record_random_state() if X.shape[1] > 1: from chainladder.utils.utility_functions import concat + # With random_state=None each column draws its own seed, so the + # columns' residual draws are independent. An integer or a + # RandomState instance is passed to every column. + column_state = None if self.random_state is None else self.random_state_ + params = {**self.get_params(), "random_state": column_state} out = [ - BootstrapODPSample(**self.get_params()).fit(X.iloc[:, i]) + BootstrapODPSample(**params).fit(X.iloc[:, i]) for i in range(X.shape[1]) ] xp = X.get_array_module(out[0].design_matrix_) @@ -257,7 +273,7 @@ def _get_simulation(self, X, exp_incr_triangle): # Suggestions from Using the ODP Bootstrap Model: A Practitioners Guide adj_resid_dist = adj_resid_dist[adj_resid_dist != 0] adj_resid_dist = adj_resid_dist - xp.mean(adj_resid_dist) - random_state = xp.random.RandomState(self.random_state) + random_state = self._get_random_state(xp) resampled_residual = [ ( random_state.choice( @@ -360,7 +376,7 @@ def transform(self, X): X_new = X.copy() X_new = self.resampled_triangles_ X_new.scale_ = self.scale_ - X_new.random_state = self.random_state + X_new.random_state = self.random_state_ X_new._get_process_variance = types.MethodType(_get_process_variance, X_new) return X_new @@ -371,8 +387,8 @@ def _get_process_variance(self, full_triangle): # process_triangle = np.nan_to_num(np.array([random_state.poisson(lam=abs(item))*np.sign(np.nan_to_num(item))for item in sim_exp_incr_triangle])) xp = full_triangle.get_array_module() lower_tri = full_triangle.cum_to_incr() - self.cum_to_incr() - random_state = xp.random.RandomState( - None if not self.random_state else self.random_state + 1 + random_state = RandomStateMixin._check_random_state( + RandomStateMixin._process_variance_seed(self.random_state), xp ) lower_tri.values = random_state.gamma( shape=abs(lower_tri.values) / self.scale_, scale=self.scale_ diff --git a/chainladder/adjustments/tests/test_bootstrap.py b/chainladder/adjustments/tests/test_bootstrap.py index 7fee0daf8..eee824433 100644 --- a/chainladder/adjustments/tests/test_bootstrap.py +++ b/chainladder/adjustments/tests/test_bootstrap.py @@ -53,6 +53,150 @@ def test_hat_adjustment_is_zero_at_corners(genins): ) +def _bootstrap_run(tri, random_state): + """Return the resampled values and the Chainladder ultimates for one run.""" + sims = cl.BootstrapODPSample(n_sims=20, random_state=random_state).fit_transform( + tri + ) + return sims.values, cl.Chainladder().fit(sims).ultimate_.values + + +def _dense(values): + """Return ``values`` as a numpy array, densifying a sparse array.""" + return np.asarray(values.todense() if hasattr(values, "todense") else values) + + +def _assert_runs_differ(first, second): + """Check that two runs differ in both the resampled values and the ultimates.""" + for a, b in zip(first, second): + assert not np.array_equal(_dense(a), _dense(b), equal_nan=True) + + +def test_random_state_zero_reproduces_ultimates(raa): + """ + Check that ``random_state=0`` reproduces the process-variance draws. + + Seed 0 used to give the process-variance step an unseeded generator, so + the resampled triangles repeated and the ultimates did not (#1568). + """ + first, second = _bootstrap_run(raa, 0), _bootstrap_run(raa, 0) + np.testing.assert_array_equal(first[0], second[0]) + np.testing.assert_array_equal(first[1], second[1]) + + +def test_random_state_none_uses_global_generator(raa): + """ + Check that ``random_state=None`` draws from the global ``np.random`` + generator, as the docstring says, so ``np.random.seed`` repeats a run. + """ + np.random.seed(1) + first = _bootstrap_run(raa, None) + np.random.seed(1) + second = _bootstrap_run(raa, None) + np.testing.assert_array_equal(first[0], second[0]) + np.testing.assert_array_equal(first[1], second[1]) + + +def test_random_state_accepts_random_state_instance(raa): + """ + Check that a ``RandomState`` instance is used as the generator. + + The resampled triangles match those from the integer seed the instance + was built with. + """ + from_instance = _bootstrap_run(raa, np.random.RandomState(42)) + np.testing.assert_array_equal( + from_instance[0], _bootstrap_run(raa, np.random.RandomState(42))[0] + ) + np.testing.assert_array_equal(from_instance[0], _bootstrap_run(raa, 42)[0]) + + +def test_different_seeds_give_different_draws(raa): + """ + Check the converse of the three tests above. Different integer seeds, + different global ``np.random`` seeds with ``random_state=None``, and + ``RandomState`` instances built from different seeds give different + resampled triangles and ultimates. + """ + _assert_runs_differ(_bootstrap_run(raa, 0), _bootstrap_run(raa, 1)) + np.random.seed(1) + first = _bootstrap_run(raa, None) + np.random.seed(2) + _assert_runs_differ(first, _bootstrap_run(raa, None)) + _assert_runs_differ( + _bootstrap_run(raa, np.random.RandomState(42)), + _bootstrap_run(raa, np.random.RandomState(43)), + ) + + +def test_random_state_none_records_the_seed(raa): + """ + Check that ``fit`` records the integer it draws for ``random_state=None`` + as ``random_state_``, and that passing it back repeats the run (#1568). + """ + model = cl.BootstrapODPSample(n_sims=20).fit(raa) + seed = model.random_state_ + assert isinstance(seed, int) + sims = model.transform(raa) + assert sims.random_state == seed + ultimate = cl.Chainladder().fit(sims).ultimate_.values + repeat = _bootstrap_run(raa, seed) + np.testing.assert_array_equal(sims.values, repeat[0]) + np.testing.assert_array_equal(ultimate, repeat[1]) + + +def test_random_state_given_is_recorded(raa): + """Check that an integer or an instance passed in is kept as ``random_state_``.""" + assert cl.BootstrapODPSample(n_sims=5, random_state=42).fit(raa).random_state_ == 42 + generator = np.random.RandomState(42) + model = cl.BootstrapODPSample(n_sims=5, random_state=generator).fit(raa) + assert model.random_state_ is generator + + +def test_random_state_none_independent_columns(raa): + """ + Check that with several columns and ``random_state=None`` each column draws + its own seed, so two identical columns resample differently, that + ``np.random.seed`` repeats the run, and that an integer seed is still shared + by every column. + """ + tri = raa.copy() + tri["copy"] = tri["values"] + + def resampled(random_state=None): + model = cl.BootstrapODPSample(n_sims=5, random_state=random_state).fit(tri) + return _dense(model.resampled_triangles_.values) + + np.random.seed(3) + first = resampled() + assert not np.allclose(np.nan_to_num(first[:, 0]), np.nan_to_num(first[:, 1])) + np.random.seed(3) + np.testing.assert_array_equal(first, resampled()) + seeded = resampled(7) + np.testing.assert_array_equal(seeded[:, 0], seeded[:, 1]) + + +def test_check_random_state_on_a_module_with_its_own_generator(): + """ + Check that ``RandomStateMixin._check_random_state`` builds a generator + from the array module's own ``random.RandomState`` when it has one, as + cupy does, and returns an instance of that class unchanged. A stub module + stands in for cupy, which the test suite does not install. + """ + from types import SimpleNamespace + + from chainladder.utils.utility_functions import RandomStateMixin + + class StubRandomState: + def __init__(self, seed=None): + self.seed = seed + + xp = SimpleNamespace(random=SimpleNamespace(RandomState=StubRandomState)) + built = RandomStateMixin._check_random_state(42, xp) + assert isinstance(built, StubRandomState) and built.seed == 42 + assert RandomStateMixin._check_random_state(built, xp) is built + + def test_hat_matrix_fallback_leaves_hat_adj_unchanged(): # The hat matrix of this quarterly triangle cannot be computed (#33), so # fit falls back to residuals without the hat matrix adjustment. diff --git a/chainladder/methods/benktander.py b/chainladder/methods/benktander.py index add140083..a7878a6d5 100644 --- a/chainladder/methods/benktander.py +++ b/chainladder/methods/benktander.py @@ -2,10 +2,11 @@ # License, v. 2.0. If a copy of the MPL was not distributed with this # file, You can obtain one at https://mozilla.org/MPL/2.0/. from chainladder.methods import MethodBase +from chainladder.utils.utility_functions import RandomStateMixin import numpy as np -class Benktander(MethodBase): +class Benktander(MethodBase, RandomStateMixin): """ The Benktander (or iterated Bornhuetter-Ferguson) IBNR model @@ -28,8 +29,12 @@ class Benktander(MethodBase): using as a deterministic method. If int, random_state is the seed used by the random number generator; If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by np.random. + If None, ``fit`` draws an integer seed from the RandomState instance + used by np.random and keeps it as ``random_state_``, and each + ``predict`` draws a new seed the same way, so its aprioris differ from + the fit's. Pass an integer to get the same aprioris from ``fit`` and + every ``predict``. A RandomState instance keeps advancing, so each + ``predict`` continues its sequence. Attributes ---------- @@ -37,6 +42,11 @@ class Benktander(MethodBase): The ultimate losses per the method ibnr_: Triangle The IBNR per the method + random_state_: int, RandomState instance or None + The seed the apriori draws used: ``random_state`` when it is an integer + or a RandomState instance, otherwise the integer ``fit`` drew. Passing + it back as ``random_state`` repeats the draws. It is ``random_state`` + itself when ``apriori_sigma`` is 0, since no draw is made. See Also -------- @@ -196,7 +206,9 @@ def fit(self, X, y=None, sample_weight=None): """ if sample_weight is None: raise ValueError("sample_weight is required.") + super().fit(X, y, sample_weight) + self._record_random_state(draws=self.apriori_sigma != 0) self.expectation_ = self._get_benktander_aprioris(X, sample_weight) self.ultimate_ = self._get_ultimate(self.X_, self.expectation_) self.process_variance_ = self._include_process_variance() @@ -253,17 +265,24 @@ def predict(self, X, sample_weight=None): if sample_weight is None: raise ValueError("sample_weight is required.") X_new = super().predict(X, sample_weight) - X_new.expectation_ = self._get_benktander_aprioris(X, sample_weight) + X_new.expectation_ = self._get_benktander_aprioris( + X, sample_weight, redraw=True + ) X_new.ultimate_ = self._get_ultimate(X_new, X_new.expectation_) X_new.n_iters = self.n_iters X_new.apriori = self.apriori return X_new - def _get_benktander_aprioris(self, X, sample_weight): - """Private method to establish Benktander Apriori""" + def _get_benktander_aprioris(self, X, sample_weight, redraw=False): + """ + Private method to establish Benktander Apriori + + ``predict`` passes ``redraw=True`` so that with ``random_state=None`` it + draws new aprioris instead of repeating the fit's. + """ xp = X.get_array_module() if self.apriori_sigma != 0: - random_state = xp.random.RandomState(self.random_state) + random_state = self._get_random_state(xp, redraw=redraw) # Draw from lognormal with E[apriori] = self.apriori and SD = self.apriori_sigma. cov = self.apriori_sigma / self.apriori sigma_log = np.sqrt(np.log1p(cov**2)) diff --git a/chainladder/methods/bornferg.py b/chainladder/methods/bornferg.py index 1dd026236..cbe0bc745 100644 --- a/chainladder/methods/bornferg.py +++ b/chainladder/methods/bornferg.py @@ -28,8 +28,12 @@ class BornhuetterFerguson(Benktander): using as a deterministic method. If int, random_state is the seed used by the random number generator; If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by np.random. + If None, ``fit`` draws an integer seed from the RandomState instance + used by np.random and keeps it as ``random_state_``, and each + ``predict`` draws a new seed the same way, so its aprioris differ from + the fit's. Pass an integer to get the same aprioris from ``fit`` and + every ``predict``. A RandomState instance keeps advancing, so each + ``predict`` continues its sequence. Attributes ---------- @@ -37,6 +41,11 @@ class BornhuetterFerguson(Benktander): The ultimate losses per the method ibnr_: Triangle The IBNR per the method + random_state_: int, RandomState instance or None + The seed the apriori draws used: ``random_state`` when it is an integer + or a RandomState instance, otherwise the integer ``fit`` drew. Passing + it back as ``random_state`` repeats the draws. It is ``random_state`` + itself when ``apriori_sigma`` is 0, since no draw is made. See Also -------- diff --git a/chainladder/methods/capecod.py b/chainladder/methods/capecod.py index 33c40564a..cb0453e07 100644 --- a/chainladder/methods/capecod.py +++ b/chainladder/methods/capecod.py @@ -38,8 +38,12 @@ class CapeCod(Benktander): using as a deterministic method. If int, random_state is the seed used by the random number generator; If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by np.random. + If None, ``fit`` draws an integer seed from the RandomState instance + used by np.random and keeps it as ``random_state_``, and each + ``predict`` draws a new seed the same way, so its aprioris differ from + the fit's. Pass an integer to get the same aprioris from ``fit`` and + every ``predict``. A RandomState instance keeps advancing, so each + ``predict`` continues its sequence. Attributes @@ -56,6 +60,11 @@ class CapeCod(Benktander): given; see ``predict``. detrended_apriori_: The detrended apriori vector developed by the Cape Cod Method + random_state_: int, RandomState instance or None + The seed the apriori draws used: ``random_state`` when it is an integer + or a RandomState instance, otherwise the integer ``fit`` drew. Passing + it back as ``random_state`` repeats the draws. It is ``random_state`` + itself when ``apriori_sigma`` is 0, since no draw is made. See Also -------- diff --git a/chainladder/methods/expectedloss.py b/chainladder/methods/expectedloss.py index 060db0ea1..98eee2b49 100644 --- a/chainladder/methods/expectedloss.py +++ b/chainladder/methods/expectedloss.py @@ -25,8 +25,12 @@ class ExpectedLoss(Benktander): using as a deterministic method. If int, random_state is the seed used by the random number generator; If RandomState instance, random_state is the random number generator; - If None, the random number generator is the RandomState instance used - by np.random. + If None, ``fit`` draws an integer seed from the RandomState instance + used by np.random and keeps it as ``random_state_``, and each + ``predict`` draws a new seed the same way, so its aprioris differ from + the fit's. Pass an integer to get the same aprioris from ``fit`` and + every ``predict``. A RandomState instance keeps advancing, so each + ``predict`` continues its sequence. Attributes ---------- @@ -34,6 +38,11 @@ class ExpectedLoss(Benktander): The ultimate losses per the method ibnr_: Triangle The IBNR per the method + random_state_: int, RandomState instance or None + The seed the apriori draws used: ``random_state`` when it is an integer + or a RandomState instance, otherwise the integer ``fit`` drew. Passing + it back as ``random_state`` repeats the draws. It is ``random_state`` + itself when ``apriori_sigma`` is 0, since no draw is made. See Also -------- diff --git a/chainladder/methods/tests/test_benktander.py b/chainladder/methods/tests/test_benktander.py index 819501206..f2029eda5 100644 --- a/chainladder/methods/tests/test_benktander.py +++ b/chainladder/methods/tests/test_benktander.py @@ -135,3 +135,101 @@ def test_capecod_apriori_sigma_is_positive(genins: Triangle) -> None: vals = cc.expectation_.values vals = vals[np.isfinite(vals)] assert (vals > 0).all() # ~10% would be negative under the old normal + + +def test_apriori_sigma_random_state_forms(genins: Triangle) -> None: + """ + Check that ``random_state`` accepts ``None`` and a ``RandomState`` instance + for the apriori draws, as the docstring says (#1568). + """ + weight = genins.latest_diagonal * 0 + 1 + + def expectation(random_state): + return ( + cl + .BornhuetterFerguson(apriori_sigma=0.5, random_state=random_state) + .fit(genins, sample_weight=weight) + .expectation_.values + ) + + np.random.seed(3) + first = expectation(None) + np.random.seed(3) + np.testing.assert_array_equal(first, expectation(None)) + np.testing.assert_array_equal(expectation(np.random.RandomState(7)), expectation(7)) + + +def test_apriori_sigma_records_the_seed(genins: Triangle) -> None: + """ + Check that ``fit`` records the seed it draws for the aprioris as + ``random_state_``, and draws none when ``apriori_sigma`` is 0 (#1568). + """ + weight = genins.latest_diagonal * 0 + 1 + model = cl.BornhuetterFerguson(apriori_sigma=0.5).fit(genins, sample_weight=weight) + seed = model.random_state_ + assert isinstance(seed, int) + repeat = cl.BornhuetterFerguson(apriori_sigma=0.5, random_state=seed).fit( + genins, sample_weight=weight + ) + np.testing.assert_array_equal(model.expectation_.values, repeat.expectation_.values) + + state = np.random.get_state()[1].copy() + model = cl.BornhuetterFerguson().fit(genins, sample_weight=weight) + assert model.random_state_ is None + np.testing.assert_array_equal(np.random.get_state()[1], state) + + +@pytest.mark.parametrize( + "estimator", [cl.Benktander, cl.BornhuetterFerguson, cl.ExpectedLoss] +) +def test_apriori_sigma_predict_redraws_without_a_seed( + genins: Triangle, estimator +) -> None: + """ + Check that ``predict`` draws new aprioris when ``random_state`` is None and + repeats the fit's when ``random_state`` is an integer (#1568). + """ + weight = genins.latest_diagonal * 0 + 1 + + model = estimator(apriori_sigma=0.5).fit(genins, sample_weight=weight) + first = ( + model + .predict(genins, sample_weight=weight) + .expectation_.set_backend("numpy") + .values + ) + second = ( + model + .predict(genins, sample_weight=weight) + .expectation_.set_backend("numpy") + .values + ) + assert not np.array_equal(model.expectation_.set_backend("numpy").values, first) + assert not np.array_equal(first, second) + + np.random.seed(3) + repeat = ( + model + .predict(genins, sample_weight=weight) + .expectation_.set_backend("numpy") + .values + ) + np.random.seed(3) + np.testing.assert_array_equal( + repeat, + model + .predict(genins, sample_weight=weight) + .expectation_.set_backend("numpy") + .values, + ) + + model = estimator(apriori_sigma=0.5, random_state=7).fit( + genins, sample_weight=weight + ) + np.testing.assert_array_equal( + model.expectation_.set_backend("numpy").values, + model + .predict(genins, sample_weight=weight) + .expectation_.set_backend("numpy") + .values, + ) diff --git a/chainladder/methods/tests/test_capecod.py b/chainladder/methods/tests/test_capecod.py index 0d42feaf1..6953bd869 100644 --- a/chainladder/methods/tests/test_capecod.py +++ b/chainladder/methods/tests/test_capecod.py @@ -224,3 +224,31 @@ def test_capecod_onlevel_friedland_exhibit_ii(): # Exhibit II, Sheet 2 - projected ultimate claims total 504,300 assert np.isclose(cc.ultimate_.sum().sum(), 504300, rtol=5e-3) + + +def test_capecod_apriori_sigma_predict_redraws_without_a_seed(genins): + """ + Check that ``CapeCod.predict`` draws new aprioris when ``random_state`` is + None and repeats the fit's when it is an integer (#1568). + """ + premium = genins.latest_diagonal * 0 + 8e6 + + model = cl.CapeCod(apriori_sigma=0.5).fit(genins, sample_weight=premium) + first = ( + model + .predict(genins, sample_weight=premium) + .expectation_.set_backend("numpy") + .values + ) + assert not np.array_equal(model.expectation_.set_backend("numpy").values, first) + + model = cl.CapeCod(apriori_sigma=0.5, random_state=7).fit( + genins, sample_weight=premium + ) + np.testing.assert_array_equal( + model.expectation_.set_backend("numpy").values, + model + .predict(genins, sample_weight=premium) + .expectation_.set_backend("numpy") + .values, + ) diff --git a/chainladder/utils/utility_functions.py b/chainladder/utils/utility_functions.py index 1e92d9b59..f196c8329 100644 --- a/chainladder/utils/utility_functions.py +++ b/chainladder/utils/utility_functions.py @@ -1316,3 +1316,98 @@ def _get_axis_name(axis: int | str) -> str: Canonical axis name ('index', 'columns', 'origin', 'development'). """ return _axis_orders[_get_axis_number(axis)] + + +class RandomStateMixin: + """ + Seed handling shared by estimators that take a ``random_state`` parameter. + + ``fit`` calls ``_record_random_state`` to store the seed its draws use as + ``random_state_``, and the draws get their generator from + ``_get_random_state``. The static helpers below build generators and + seeds, and code outside an estimator, such as the process-variance step + of ``BootstrapODPSample``, calls them through the class. + """ + + @staticmethod + def _check_random_state( + seed: int | np.random.RandomState | None, xp: ModuleType = np + ) -> np.random.RandomState: + """ + Return a random number generator for ``seed`` on the array module ``xp``. + + ``sklearn.utils.check_random_state`` handles the three accepted forms: + ``None`` gives the global ``np.random`` generator, an integer seeds a new + ``RandomState``, and a ``RandomState`` instance is returned as it is. It + serves numpy and every module without a ``random.RandomState`` of its own, + such as ``sparse``, whose draws numpy then makes. A module that has one, + such as cupy, gets a ``RandomState`` built from ``seed`` unless ``seed`` is + already one. + """ + if xp is np or not hasattr(getattr(xp, "random", None), "RandomState"): + from sklearn.utils import check_random_state + + return check_random_state(seed) + if isinstance(seed, xp.random.RandomState): + return seed + return xp.random.RandomState(seed) + + @staticmethod + def _process_variance_seed( + seed: int | np.random.RandomState | None, + ) -> int | np.random.RandomState | None: + """ + Return the seed for the process-variance draws that follow the draws + seeded by ``seed``. + + An integer seed is offset by 1 so the two sets of draws differ, including + for seed 0. A ``RandomState`` instance or ``None`` is passed through. + """ + if isinstance(seed, (int, np.integer)) and not isinstance(seed, bool): + return int(seed) + 1 + return seed + + @staticmethod + def _record_seed( + seed: int | np.random.RandomState | None, + ) -> int | np.random.RandomState: + """ + Return the seed a fit records as ``random_state_``. + + For ``None``, one integer is drawn from the global ``np.random`` generator, + so ``np.random.seed`` still repeats a run and the drawn integer can be + passed back as ``random_state``. An integer or a ``RandomState`` instance + is returned as it is. + """ + if seed is None: + return int(np.random.randint(np.iinfo(np.int32).max)) + return seed + + def _record_random_state(self, draws: bool = True) -> None: + """ + Set ``random_state_`` from ``random_state``. + + When ``draws`` is true, the seed comes from ``_record_seed``, which + draws an integer for ``None``. A fit that makes no random draws passes + ``draws=False`` and keeps ``random_state`` as it is. + """ + self.random_state_ = ( + self._record_seed(self.random_state) if draws else self.random_state + ) + + def _get_random_state( + self, xp: ModuleType = np, redraw: bool = False + ) -> np.random.RandomState: + """ + Return a generator for the recorded seed on the array module ``xp``. + + Before a fit has recorded a seed, ``random_state`` is used. With + ``redraw`` true and ``random_state`` None, the generator uses a new + seed from ``_record_seed`` instead of the recorded one, so draws made + after the fit differ from the fit's. + """ + if redraw and self.random_state is None: + return self._check_random_state(self._record_seed(None), xp) + return self._check_random_state( + getattr(self, "random_state_", self.random_state), xp + )