optuna.importance.get_param_importances

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

Evaluate parameter importances (PedAnovaImportanceEvaluator by default) 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.

By default, this function uses PedAnovaImportanceEvaluator. For details on this evaluator, please refer to the following papers:

• PED-ANOVA: Efficiently Quantifying Hyperparameter Importance in Arbitrary Subspaces (IJCAI 2023)

• Conditional PED-ANOVA: Hyperparameter Importance in Hierarchical & Dynamic Search Spaces (KDD 2026)

When using this evaluator in your project, please consider citing both papers.

With the default evaluator, PedAnovaImportanceEvaluator, params=None assesses all parameters that appear in completed trials, including conditional parameters. Other evaluators assess only parameters that are present in all of the completed trials and therefore exclude conditional parameters. If params is specified, only the specified parameters are assessed. When using PedAnovaImportanceEvaluator, each specified parameter must appear in at least one completed trial. When using other evaluators, at least one completed trial must contain all specified parameters.

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 PedAnovaImportanceEvaluator.

• params (list[str] | None) – A list of names of parameters to assess. If None, PedAnovaImportanceEvaluator assesses all parameters that appear in completed trials, including conditional parameters, while other evaluators assess parameters present in all completed trials.

• target (Callable[[FrozenTrial], float] | None) – A function that returns the value used to evaluate importances. If None, objective values are used for single-objective optimization. For multi-objective optimization, None is supported only by PedAnovaImportanceEvaluator. When using another evaluator, specify target, for example target=lambda t: t.values[0], to evaluate importances for a specific objective.

• 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]

Example

import optuna


def objective(trial: optuna.trial.Trial) -> float:
    x = trial.suggest_int("x", 0, 2)
    y = trial.suggest_float("y", -1.0, 1.0)
    z = trial.suggest_float("z", 0.0, 1.5)
    return x**2 + y**3 - z**4

sampler = optuna.samplers.RandomSampler(seed=42)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=100)

importances = optuna.importance.get_param_importances(study)