optuna.importance.get_param_importances

optuna.importance.get_param_importances(study, *, evaluator=None, params=None, target=None, normalize=True)[source]

Evaluate parameter importances based on completed trials in the given study.

The parameter importances are returned as a dictionary where the keys consist of parameter names and their values importances. The importances are represented by non-negative floating point numbers, where higher values mean that the parameters are more important. The returned dictionary is ordered by its values in a descending order. By default, the sum of the importance values are normalized to 1.0.

If params is None, all parameter that are present in all of the completed trials are assessed. This implies that conditional parameters will be excluded from the evaluation. To assess the importances of conditional parameters, a list of parameter names can be specified via params. If specified, only completed trials that contain all of the parameters will be considered. If no such trials are found, an error will be raised.

If the given study does not contain completed trials, an error will be raised.

Note

If params is specified as an empty list, an empty dictionary is returned.

See also

See plot_param_importances() to plot importances.

Parameters:

  • study (Study) – An optimized study.

  • evaluator (BaseImportanceEvaluator | None) –

    An importance evaluator object that specifies which algorithm to base the importance assessment on. Defaults to FanovaImportanceEvaluator.

    Note

    FanovaImportanceEvaluator takes over 1 minute when given a study that contains 1000+ trials. We published optuna-fast-fanova library, that is a Cython accelerated fANOVA implementation. By using it, you can get hyperparameter importances within a few seconds. If n_trials is more than 10000, the Cython implementation takes more than a minute, so you can use PedAnovaImportanceEvaluator instead, enabling the evaluation to finish in a second.

  • params (list[str] | None) – A list of names of parameters to assess. If None, all parameters that are present in all of the completed trials are assessed.

  • target (Callable[[FrozenTrial], float] | None) –

    A function to specify the value to evaluate importances. If it is None and study is being used for single-objective optimization, the objective values are used. target must be specified if study is being used for multi-objective optimization.

    Note

    Specify this argument if study is being used for multi-objective optimization. For example, to get the hyperparameter importance of the first objective, use target=lambda t: t.values[0] for the target parameter.

  • normalize (bool) –

    A boolean option to specify whether the sum of the importance values should be normalized to 1.0. Defaults to True.

    Note

    Added in v3.0.0 as an experimental feature. The interface may change in newer versions without prior notice. See https://github.com/optuna/optuna/releases/tag/v3.0.0.

Returns:

A dict where the keys are parameter names and the values are assessed importances.

Return type:

dict[str, float]