# Source code for surprise.model_selection.search

```
from abc import ABC, abstractmethod
from itertools import product
import numpy as np
from joblib import delayed, Parallel
from ..dataset import DatasetUserFolds
from ..utils import get_rng
from .split import get_cv
from .validation import fit_and_score
class BaseSearchCV(ABC):
"""Base class for hyper parameter search with cross-validation."""
@abstractmethod
def __init__(
self,
algo_class,
measures=["rmse", "mae"],
cv=None,
refit=False,
return_train_measures=False,
n_jobs=1,
pre_dispatch="2*n_jobs",
joblib_verbose=0,
):
self.algo_class = algo_class
self.measures = [measure.lower() for measure in measures]
self.cv = cv
if isinstance(refit, str):
if refit.lower() not in self.measures:
raise ValueError(
"It looks like the measure you want to use "
"with refit ({}) is not in the measures "
"parameter"
)
self.refit = refit.lower()
elif refit is True:
self.refit = self.measures[0]
else:
self.refit = False
self.return_train_measures = return_train_measures
self.n_jobs = n_jobs
self.pre_dispatch = pre_dispatch
self.joblib_verbose = joblib_verbose
def _parse_options(self, params):
# As sim_options and bsl_options are dictionaries, they require a
# special treatment.
if "sim_options" in params:
sim_options = params["sim_options"]
sim_options_list = [
dict(zip(sim_options, v)) for v in product(*sim_options.values())
]
params["sim_options"] = sim_options_list
if "bsl_options" in params:
bsl_options = params["bsl_options"]
bsl_options_list = [
dict(zip(bsl_options, v)) for v in product(*bsl_options.values())
]
params["bsl_options"] = bsl_options_list
return params
def fit(self, data):
"""Runs the ``fit()`` method of the algorithm for all parameter
combinations, over different splits given by the ``cv`` parameter.
Args:
data (:obj:`Dataset <surprise.dataset.Dataset>`): The dataset on
which to evaluate the algorithm, in parallel.
"""
if self.refit and isinstance(data, DatasetUserFolds):
raise ValueError(
"refit cannot be used when data has been "
"loaded with load_from_folds()."
)
cv = get_cv(self.cv)
delayed_list = (
delayed(fit_and_score)(
self.algo_class(**params),
trainset,
testset,
self.measures,
self.return_train_measures,
)
for params, (trainset, testset) in product(
self.param_combinations, cv.split(data)
)
)
out = Parallel(
n_jobs=self.n_jobs,
pre_dispatch=self.pre_dispatch,
verbose=self.joblib_verbose,
)(delayed_list)
(test_measures_dicts, train_measures_dicts, fit_times, test_times) = zip(*out)
# test_measures_dicts is a list of dict like this:
# [{'mae': 1, 'rmse': 2}, {'mae': 2, 'rmse': 3} ...]
# E.g. for 5 splits, the first 5 dicts are for the first param
# combination, the next 5 dicts are for the second param combination,
# etc...
# We convert it into a dict of list:
# {'mae': [1, 2, ...], 'rmse': [2, 3, ...]}
# Each list is still of size n_parameters_combinations * n_splits.
# Then, reshape each list to have 2-D arrays of shape
# (n_parameters_combinations, n_splits). This way we can easily compute
# the mean and std dev over all splits or over all param comb.
test_measures = dict()
train_measures = dict()
new_shape = (len(self.param_combinations), cv.get_n_folds())
for m in self.measures:
test_measures[m] = np.asarray([d[m] for d in test_measures_dicts])
test_measures[m] = test_measures[m].reshape(new_shape)
if self.return_train_measures:
train_measures[m] = np.asarray([d[m] for d in train_measures_dicts])
train_measures[m] = train_measures[m].reshape(new_shape)
cv_results = dict()
best_index = dict()
best_params = dict()
best_score = dict()
best_estimator = dict()
for m in self.measures:
# cv_results: set measures for each split and each param comb
for split in range(cv.get_n_folds()):
cv_results[f"split{split}_test_{m}"] = test_measures[m][:, split]
if self.return_train_measures:
cv_results[f"split{split}_train_{m}"] = train_measures[m][:, split]
# cv_results: set mean and std over all splits (testset and
# trainset) for each param comb
mean_test_measures = test_measures[m].mean(axis=1)
cv_results[f"mean_test_{m}"] = mean_test_measures
cv_results[f"std_test_{m}"] = test_measures[m].std(axis=1)
if self.return_train_measures:
mean_train_measures = train_measures[m].mean(axis=1)
cv_results[f"mean_train_{m}"] = mean_train_measures
cv_results[f"std_train_{m}"] = train_measures[m].std(axis=1)
# cv_results: set rank of each param comb
# also set best_index, and best_xxxx attributes
indices = cv_results[f"mean_test_{m}"].argsort()
cv_results[f"rank_test_{m}"] = np.empty_like(indices)
if m in ("mae", "rmse", "mse"):
cv_results[f"rank_test_{m}"][indices] = (
np.arange(len(indices)) + 1
) # sklearn starts at 1 as well
best_index[m] = mean_test_measures.argmin()
elif m in ("fcp",):
cv_results[f"rank_test_{m}"][indices] = np.arange(len(indices), 0, -1)
best_index[m] = mean_test_measures.argmax()
best_params[m] = self.param_combinations[best_index[m]]
best_score[m] = mean_test_measures[best_index[m]]
best_estimator[m] = self.algo_class(**best_params[m])
# Cv results: set fit and train times (mean, std)
fit_times = np.array(fit_times).reshape(new_shape)
test_times = np.array(test_times).reshape(new_shape)
for s, times in zip(("fit", "test"), (fit_times, test_times)):
cv_results[f"mean_{s}_time"] = times.mean(axis=1)
cv_results[f"std_{s}_time"] = times.std(axis=1)
# cv_results: set params key and each param_* values
cv_results["params"] = self.param_combinations
for param in self.param_combinations[0]:
cv_results["param_" + param] = [
comb[param] for comb in self.param_combinations
]
if self.refit:
best_estimator[self.refit].fit(data.build_full_trainset())
self.best_index = best_index
self.best_params = best_params
self.best_score = best_score
self.best_estimator = best_estimator
self.cv_results = cv_results
def test(self, testset, verbose=False):
"""Call ``test()`` on the estimator with the best found parameters
(according the the ``refit`` parameter). See :meth:`AlgoBase.test()
<surprise.prediction_algorithms.algo_base.AlgoBase.test>`.
Only available if ``refit`` is not ``False``.
"""
if not self.refit:
raise ValueError("refit is False, cannot use test()")
return self.best_estimator[self.refit].test(testset, verbose)
def predict(self, *args):
"""Call ``predict()`` on the estimator with the best found parameters
(according the the ``refit`` parameter). See :meth:`AlgoBase.predict()
<surprise.prediction_algorithms.algo_base.AlgoBase.predict>`.
Only available if ``refit`` is not ``False``.
"""
if not self.refit:
raise ValueError("refit is False, cannot use predict()")
return self.best_estimator[self.refit].predict(*args)
[docs]
class GridSearchCV(BaseSearchCV):
"""The :class:`GridSearchCV` class computes accuracy metrics for an
algorithm on various combinations of parameters, over a cross-validation
procedure. This is useful for finding the best set of parameters for a
prediction algorithm. It is analogous to `GridSearchCV
<https://scikit-learn.org/stable/modules/generated/sklearn.
model_selection.GridSearchCV.html>`_ from scikit-learn.
See an example in the :ref:`User Guide <tuning_algorithm_parameters>`.
Args:
algo_class(:obj:`AlgoBase \
<surprise.prediction_algorithms.algo_base.AlgoBase>`): The class
of the algorithm to evaluate.
param_grid(dict): Dictionary with algorithm parameters as keys and
list of values as keys. All combinations will be evaluated with
desired algorithm. Dict parameters such as ``sim_options`` require
special treatment, see :ref:`this note<grid_search_note>`.
measures(list of string): The performance measures to compute. Allowed
names are function names as defined in the :mod:`accuracy
<surprise.accuracy>` module. Default is ``['rmse', 'mae']``.
cv(cross-validation iterator, int or ``None``): Determines how the
``data`` parameter will be split (i.e. how trainsets and testsets
will be defined). If an int is passed, :class:`KFold
<surprise.model_selection.split.KFold>` is used with the
appropriate ``n_splits`` parameter. If ``None``, :class:`KFold
<surprise.model_selection.split.KFold>` is used with
``n_splits=5``.
refit(bool or str): If ``True``, refit the algorithm on the whole
dataset using the set of parameters that gave the best average
performance for the first measure of ``measures``. Other measures
can be used by passing a string (corresponding to the measure
name). Then, you can use the ``test()`` and ``predict()`` methods.
``refit`` can only be used if the ``data`` parameter given to
``fit()`` hasn't been loaded with :meth:`load_from_folds()
<surprise.dataset.Dataset.load_from_folds>`. Default is ``False``.
return_train_measures(bool): Whether to compute performance measures on
the trainsets. If ``True``, the ``cv_results`` attribute will
also contain measures for trainsets. Default is ``False``.
n_jobs(int): The maximum number of parallel training procedures.
- If ``-1``, all CPUs are used.
- If ``1`` is given, no parallel computing code is used at all,\
which is useful for debugging.
- For ``n_jobs`` below ``-1``, ``(n_cpus + n_jobs + 1)`` are\
used. For example, with ``n_jobs = -2`` all CPUs but one are\
used.
Default is ``1``.
pre_dispatch(int or string): Controls the number of jobs that get
dispatched during parallel execution. Reducing this number can be
useful to avoid an explosion of memory consumption when more jobs
get dispatched than CPUs can process. This parameter can be:
- ``None``, in which case all the jobs are immediately created\
and spawned. Use this for lightweight and fast-running\
jobs, to avoid delays due to on-demand spawning of the\
jobs.
- An int, giving the exact number of total jobs that are\
spawned.
- A string, giving an expression as a function of ``n_jobs``,\
as in ``'2*n_jobs'``.
Default is ``'2*n_jobs'``.
joblib_verbose(int): Controls the verbosity of joblib: the higher, the
more messages.
Attributes:
best_estimator (dict of AlgoBase):
Using an accuracy measure as key, get the algorithm that gave the
best accuracy results for the chosen measure, averaged over all
splits.
best_score (dict of floats):
Using an accuracy measure as key, get the best average score
achieved for that measure.
best_params (dict of dicts):
Using an accuracy measure as key, get the parameters combination
that gave the best accuracy results for the chosen measure (on
average).
best_index (dict of ints):
Using an accuracy measure as key, get the index that can be used
with ``cv_results`` that achieved the highest accuracy for that
measure (on average).
cv_results (dict of arrays):
A dict that contains accuracy measures over all splits, as well as
train and test time for each parameter combination. Can be imported
into a pandas `DataFrame` (see :ref:`example
<cv_results_example>`).
"""
def __init__(
self,
algo_class,
param_grid,
measures=["rmse", "mae"],
cv=None,
refit=False,
return_train_measures=False,
n_jobs=1,
pre_dispatch="2*n_jobs",
joblib_verbose=0,
):
super().__init__(
algo_class=algo_class,
measures=measures,
cv=cv,
refit=refit,
return_train_measures=return_train_measures,
n_jobs=n_jobs,
pre_dispatch=pre_dispatch,
joblib_verbose=joblib_verbose,
)
self.param_grid = self._parse_options(param_grid.copy())
self.param_combinations = [
dict(zip(self.param_grid, v)) for v in product(*self.param_grid.values())
]
[docs]
class RandomizedSearchCV(BaseSearchCV):
"""The :class:`RandomizedSearchCV` class computes accuracy metrics for an
algorithm on various combinations of parameters, over a cross-validation
procedure. As opposed to GridSearchCV, which uses an exhaustive
combinatorial approach, RandomizedSearchCV samples randomly from the
parameter space. This is useful for finding the best set of parameters
for a prediction algorithm, especially using a coarse to fine approach.
It is analogous to `RandomizedSearchCV <https://scikit-learn.org/stable/
modules/generated/sklearn.model_selection.RandomizedSearchCV.html>`_ from
scikit-learn.
See an example in the :ref:`User Guide <tuning_algorithm_parameters>`.
Args:
algo_class(:obj:`AlgoBase \
<surprise.prediction_algorithms.algo_base.AlgoBase>`): The class
of the algorithm to evaluate.
param_distributions(dict): Dictionary with algorithm parameters as
keys and distributions or lists of parameters to try. Distributions
must provide a rvs method for sampling (such as those from
scipy.stats.distributions). If a list is given, it is sampled
uniformly. Parameters will be sampled n_iter times.
n_iter(int): Number of times parameter settings are sampled. Default is
``10``.
measures(list of string): The performance measures to compute. Allowed
names are function names as defined in the :mod:`accuracy
<surprise.accuracy>` module. Default is ``['rmse', 'mae']``.
cv(cross-validation iterator, int or ``None``): Determines how the
``data`` parameter will be split (i.e. how trainsets and testsets
will be defined). If an int is passed, :class:`KFold
<surprise.model_selection.split.KFold>` is used with the
appropriate ``n_splits`` parameter. If ``None``, :class:`KFold
<surprise.model_selection.split.KFold>` is used with
``n_splits=5``.
refit(bool or str): If ``True``, refit the algorithm on the whole
dataset using the set of parameters that gave the best average
performance for the first measure of ``measures``. Other measures
can be used by passing a string (corresponding to the measure
name). Then, you can use the ``test()`` and ``predict()`` methods.
``refit`` can only be used if the ``data`` parameter given to
``fit()`` hasn't been loaded with :meth:`load_from_folds()
<surprise.dataset.Dataset.load_from_folds>`. Default is ``False``.
return_train_measures(bool): Whether to compute performance measures on
the trainsets. If ``True``, the ``cv_results`` attribute will
also contain measures for trainsets. Default is ``False``.
n_jobs(int): The maximum number of parallel training procedures.
- If ``-1``, all CPUs are used.
- If ``1`` is given, no parallel computing code is used at all,\
which is useful for debugging.
- For ``n_jobs`` below ``-1``, ``(n_cpus + n_jobs + 1)`` are\
used. For example, with ``n_jobs = -2`` all CPUs but one are\
used.
Default is ``1``.
pre_dispatch(int or string): Controls the number of jobs that get
dispatched during parallel execution. Reducing this number can be
useful to avoid an explosion of memory consumption when more jobs
get dispatched than CPUs can process. This parameter can be:
- ``None``, in which case all the jobs are immediately created\
and spawned. Use this for lightweight and fast-running\
jobs, to avoid delays due to on-demand spawning of the\
jobs.
- An int, giving the exact number of total jobs that are\
spawned.
- A string, giving an expression as a function of ``n_jobs``,\
as in ``'2*n_jobs'``.
Default is ``'2*n_jobs'``.
random_state(int, RandomState or None): Pseudo random number
generator seed used for random uniform sampling from lists of
possible values instead of scipy.stats distributions. 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``. Default is ``None``.
joblib_verbose(int): Controls the verbosity of joblib: the higher, the
more messages.
Attributes:
best_estimator (dict of AlgoBase):
Using an accuracy measure as key, get the algorithm that gave the
best accuracy results for the chosen measure, averaged over all
splits.
best_score (dict of floats):
Using an accuracy measure as key, get the best average score
achieved for that measure.
best_params (dict of dicts):
Using an accuracy measure as key, get the parameters combination
that gave the best accuracy results for the chosen measure (on
average).
best_index (dict of ints):
Using an accuracy measure as key, get the index that can be used
with ``cv_results`` that achieved the highest accuracy for that
measure (on average).
cv_results (dict of arrays):
A dict that contains accuracy measures over all splits, as well as
train and test time for each parameter combination. Can be imported
into a pandas `DataFrame` (see :ref:`example
<cv_results_example>`).
"""
def __init__(
self,
algo_class,
param_distributions,
n_iter=10,
measures=["rmse", "mae"],
cv=None,
refit=False,
return_train_measures=False,
n_jobs=1,
pre_dispatch="2*n_jobs",
random_state=None,
joblib_verbose=0,
):
super().__init__(
algo_class=algo_class,
measures=measures,
cv=cv,
refit=refit,
return_train_measures=return_train_measures,
n_jobs=n_jobs,
pre_dispatch=pre_dispatch,
joblib_verbose=joblib_verbose,
)
self.n_iter = n_iter
self.random_state = random_state
self.param_distributions = self._parse_options(param_distributions.copy())
self.param_combinations = self._sample_parameters(
self.param_distributions, self.n_iter, self.random_state
)
@staticmethod
def _sample_parameters(param_distributions, n_iter, random_state=None):
"""Samples ``n_iter`` parameter combinations from
``param_distributions`` using ``random_state`` as a seed.
Non-deterministic iterable over random candidate combinations for
hyper-parameter search. If all parameters are presented as a list,
sampling without replacement is performed. If at least one parameter
is given as a distribution, sampling with replacement is used.
It is highly recommended to use continuous distributions for continuous
parameters.
Note that before SciPy 0.16, the ``scipy.stats.distributions`` do not
accept a custom RNG instance and always use the singleton RNG from
``numpy.random``. Hence setting ``random_state`` will not guarantee a
deterministic iteration whenever ``scipy.stats`` distributions are used
to define the parameter search space. Deterministic behavior is however
guaranteed from SciPy 0.16 onwards.
Args:
param_distributions(dict): Dictionary where the keys are
parameters and values are distributions from which a parameter
is to be sampled. Distributions either have to provide a
``rvs`` function to sample from them, or can be given as a list
of values, where a uniform distribution is assumed.
n_iter(int): Number of parameter settings produced.
Default is ``10``.
random_state(int, RandomState instance or None):
Pseudo random number generator seed used for random uniform
sampling from lists of possible values instead of scipy.stats
distributions. If ``None``, the random number generator is the
random state instance used by np.random. Default is ``None``.
Returns:
combos(list): List of parameter dictionaries with sampled values.
"""
# check if all distributions are given as lists
# if so, sample without replacement
all_lists = np.all(
[not hasattr(v, "rvs") for v in param_distributions.values()]
)
rnd = get_rng(random_state)
# sort for reproducibility
items = sorted(param_distributions.items())
if all_lists:
# create exhaustive combinations
param_grid = [
dict(zip(param_distributions, v))
for v in product(*param_distributions.values())
]
combos = np.random.choice(param_grid, n_iter, replace=False)
else:
combos = []
for _ in range(n_iter):
params = dict()
for k, v in items:
if hasattr(v, "rvs"):
params[k] = v.rvs(random_state=rnd)
else:
params[k] = v[rnd.randint(len(v))]
combos.append(params)
return combos
```