pycaret.classification.tune_model#

pycaret.classification.tune_model(estimator, fold: int | Any | None = None, round: int = 4, n_iter: int = 10, custom_grid: Dict[str, list] | Any | None = None, optimize: str = 'Accuracy', custom_scorer=None, search_library: str = 'scikit-learn', search_algorithm: str | None = None, early_stopping: Any = False, early_stopping_max_iters: int = 10, choose_better: bool = True, fit_kwargs: dict | None = None, groups: str | Any | None = None, return_tuner: bool = False, verbose: bool = True, tuner_verbose: int | bool = True, return_train_score: bool = False, **kwargs) → Any[source]#

This function tunes the hyperparameters of a given estimator. The output of this function is a score grid with CV scores by fold of the best selected model based on optimize parameter. Metrics evaluated during CV can be accessed using the get_metrics function. Custom metrics can be added or removed using add_metric and remove_metric function.

Example

>>> from pycaret.datasets import get_data
>>> juice = get_data('juice')
>>> from pycaret.classification import *
>>> exp_name = setup(data = juice,  target = 'Purchase')
>>> lr = create_model('lr')
>>> tuned_lr = tune_model(lr)
estimator: scikit-learn compatible object

Trained model object

fold: int or scikit-learn compatible CV generator, default = None

Controls cross-validation. If None, the CV generator in the fold_strategy parameter of the setup function is used. When an integer is passed, it is interpreted as the ‘n_splits’ parameter of the CV generator in the setup function.

round: int, default = 4

Number of decimal places the metrics in the score grid will be rounded to.

n_iter: int, default = 10

Number of iterations in the grid search. Increasing ‘n_iter’ may improve model performance but also increases the training time.

custom_grid: dictionary, default = None

To define custom search space for hyperparameters, pass a dictionary with parameter name and values to be iterated. Custom grids must be in a format supported by the defined search_library.

optimize: str, default = ‘Accuracy’

Metric name to be evaluated for hyperparameter tuning. It also accepts custom metrics that are added through the add_metric function.

custom_scorer: object, default = None

custom scoring strategy can be passed to tune hyperparameters of the model. It must be created using sklearn.make_scorer. It is equivalent of adding custom metric using the add_metric function and passing the name of the custom metric in the optimize parameter. Will be deprecated in future.

search_library: str, default = ‘scikit-learn’

The search library used for tuning hyperparameters. Possible values:

search_algorithm: str, default = None

The search algorithm depends on the search_library parameter. Some search algorithms require additional libraries to be installed. If None, will use search library-specific default algorithm.

  • ‘scikit-learn’ possible values:

    • ‘random’ : random grid search (default)

    • ‘grid’ : grid search

  • ‘scikit-optimize’ possible values:

    • ‘bayesian’ : Bayesian search (default)

  • ‘tune-sklearn’ possible values:

    • ‘random’ : random grid search (default)

    • ‘grid’ : grid search

    • ‘bayesian’ : pip install scikit-optimize

    • ‘hyperopt’ : pip install hyperopt

    • ‘optuna’ : pip install optuna

    • ‘bohb’ : pip install hpbandster ConfigSpace

  • ‘optuna’ possible values:

    • ‘random’ : randomized search

    • ‘tpe’ : Tree-structured Parzen Estimator search (default)

early_stopping: bool or str or object, default = False

Use early stopping to stop fitting to a hyperparameter configuration if it performs poorly. Ignored when search_library is scikit-learn, or if the estimator does not have ‘partial_fit’ attribute. If False or None, early stopping will not be used. Can be either an object accepted by the search library or one of the following:

  • ‘asha’ for Asynchronous Successive Halving Algorithm

  • ‘hyperband’ for Hyperband

  • ‘median’ for Median Stopping Rule

  • If False or None, early stopping will not be used.

early_stopping_max_iters: int, default = 10

Maximum number of epochs to run for each sampled configuration. Ignored if early_stopping is False or None.

choose_better: bool, default = True

When set to True, the returned object is always better performing. The metric used for comparison is defined by the optimize parameter.

fit_kwargs: dict, default = {} (empty dict)

Dictionary of arguments passed to the fit method of the tuner.

groups: str or array-like, with shape (n_samples,), default = None

Optional group labels when GroupKFold is used for the cross validation. It takes an array with shape (n_samples, ) where n_samples is the number of rows in training dataset. When string is passed, it is interpreted as the column name in the dataset containing group labels.

return_tuner: bool, default = False

When set to True, will return a tuple of (model, tuner_object).

verbose: bool, default = True

Score grid is not printed when verbose is set to False.

tuner_verbose: bool or in, default = True

If True or above 0, will print messages from the tuner. Higher values print more messages. Ignored when verbose param is False.

return_train_score: bool, default = False

If False, returns the CV Validation scores only. If True, returns the CV training scores along with the CV validation scores. This is useful when the user wants to do bias-variance tradeoff. A high CV training score with a low corresponding CV validation score indicates overfitting.

**kwargs:

Additional keyword arguments to pass to the optimizer.

Returns:

Trained Model and Optional Tuner Object when return_tuner is True.

Warning

  • Using ‘grid’ as search_algorithm may result in very long computation. Only recommended with smaller search spaces that can be defined in the custom_grid parameter.

  • search_library ‘tune-sklearn’ does not support GPU models.

On this page