def plot_pareto_front(
study: MultiObjectiveStudy,
names: Optional[List[str]] = None,
include_dominated_trials: bool = False,
) -> "go.Figure":
"""Plot the pareto front of a study.
Example:
The following code snippet shows how to plot the pareto front of a study.
.. testcode::
import optuna
def objective(trial):
x = trial.suggest_float("x", 0, 5)
y = trial.suggest_float("y", 0, 3)
v0 = 4 * x ** 2 + 4 * y ** 2
v1 = (x - 5) ** 2 + (y - 5) ** 2
return v0, v1
study = optuna.multi_objective.create_study(["minimize", "minimize"])
study.optimize(objective, n_trials=50)
optuna.multi_objective.visualization.plot_pareto_front(study)
.. raw:: html
<iframe src="../../../_static/plot_pareto_front.html" width="100%" height="500px"
frameborder="0"></iframe>
Args:
study:
A :class:`~optuna.multi_objective.study.MultiObjectiveStudy` object whose trials
are plotted for their objective values.
names:
Objective name list used as the axis titles. If :obj:`None` is specified,
"Objective {objective_index}" is used instead.
include_dominated_trials:
A flag to include all dominated trial's objective values.
Returns:
A :class:`plotly.graph_objs.Figure` object.
Raises:
:exc:`ValueError`:
If the number of objectives of ``study`` isn't 2 or 3.
"""
_imports.check()
if study.n_objectives == 2:
return _get_pareto_front_2d(study, names, include_dominated_trials)
elif study.n_objectives == 3:
return _get_pareto_front_3d(study, names, include_dominated_trials)
else:
raise ValueError("`plot_pareto_front` function only supports 2 or 3 objective studies.")
def plot_param_importances(
study: Study,
evaluator = None,
params: Optional[List[str]] = None,
*,
target: Optional[Callable[[FrozenTrial], float]] = None,
target_name: str = "Objective Value",
):
_imports.check()
_check_plot_args(study, target, target_name)
layout = go.Layout(
title="Hyperparameter Importances",
xaxis={"title": f"Importance for {target_name}"},
yaxis={"title": "Hyperparameter"},
showlegend=False,
)
# Importances cannot be evaluated without completed trials.
# Return an empty figure for consistency with other visualization functions.
trials = [trial for trial in study.trials if trial.state == TrialState.COMPLETE]
if len(trials) == 0:
logger.warning("Study instance does not contain completed trials.")
return go.Figure(data=[], layout=layout)
if evaluator is None:
evaluator = ImportanceEvaluator()
try:
importances, importance_paras = get_param_importances(
study, evaluator=evaluator, params=params, target=target
)
except RuntimeError: # sometimes it is returning error e.g. when number of trials are < 4
return None, None, None
importances = OrderedDict(reversed(list(importances.items())))
importance_values = list(importances.values())
param_names = list(importances.keys())
fig = go.Figure(
data=[
go.Bar(
x=importance_values,
y=param_names,
text=importance_values,
texttemplate="%{text:.2f}",
textposition="outside",
cliponaxis=False, # Ensure text is not clipped.
hovertemplate=[
_make_hovertext(param_name, importance, study)
for param_name, importance in importances.items()
],
marker_color=[_get_color(param_name, study) for param_name in param_names],
orientation="h",
)
],
layout=layout,
)
return importances, importance_paras, fig
def plot_optimization_history(study: Study) -> "go.Figure":
"""Plot optimization history of all trials in a study.
Example:
The following code snippet shows how to plot optimization history.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_uniform("x", -100, 100)
y = trial.suggest_categorical("y", [-1, 0, 1])
return x ** 2 + y
study = optuna.create_study()
study.optimize(objective, n_trials=10)
optuna.visualization.plot_optimization_history(study)
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their objective
values.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
return _get_optimization_history_plot(study)
def plot_optimization_history(
study: Union[Study, Sequence[Study]],
*,
target: Optional[Callable[[FrozenTrial], float]] = None,
target_name: str = "Objective Value",
error_bar: bool = False,
) -> "go.Figure":
"""Plot optimization history of all trials in a study.
Example:
The following code snippet shows how to plot optimization history.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_float("x", -100, 100)
y = trial.suggest_categorical("y", [-1, 0, 1])
return x ** 2 + y
sampler = optuna.samplers.TPESampler(seed=10)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=10)
fig = optuna.visualization.plot_optimization_history(study)
fig.show()
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
You can pass multiple studies if you want to compare those optimization histories.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the axis label and the legend.
error_bar:
A flag to show the error bar.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
if isinstance(study, Study):
studies = [study]
else:
studies = list(study)
_check_plot_args(studies, target, target_name)
return _get_optimization_history_plot(studies, target, target_name, error_bar)
def plot_pareto_front(
study: MultiObjectiveStudy,
names: Optional[List[str]] = None,
include_dominated_trials: bool = False,
axis_order: Optional[List[int]] = None,
) -> "go.Figure":
"""Plot the pareto front of a study.
Example:
The following code snippet shows how to plot the pareto front of a study.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_float("x", 0, 5)
y = trial.suggest_float("y", 0, 3)
v0 = 4 * x ** 2 + 4 * y ** 2
v1 = (x - 5) ** 2 + (y - 5) ** 2
return v0, v1
study = optuna.multi_objective.create_study(["minimize", "minimize"])
study.optimize(objective, n_trials=50)
fig = optuna.multi_objective.visualization.plot_pareto_front(study)
fig.show()
Args:
study:
A :class:`~optuna.multi_objective.study.MultiObjectiveStudy` object whose trials
are plotted for their objective values. ``study.n_objectives`` must be eigher 2 or 3.
names:
Objective name list used as the axis titles. If :obj:`None` is specified,
"Objective {objective_index}" is used instead.
include_dominated_trials:
A flag to include all dominated trial's objective values.
axis_order:
A list of indices indicating the axis order. If :obj:`None` is specified,
default order is used.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
if study.n_objectives == 2:
return _get_pareto_front_2d(study, names, include_dominated_trials, axis_order)
elif study.n_objectives == 3:
return _get_pareto_front_3d(study, names, include_dominated_trials, axis_order)
else:
raise ValueError("`plot_pareto_front` function only supports 2 or 3 objective studies.")
def plot_contour(
study: Study,
params: Optional[List[str]] = None,
*,
target: Optional[Callable[[FrozenTrial], float]] = None,
target_name: str = "Objective Value",
) -> "go.Figure":
"""Plot the parameter relationship as contour plot in a study.
Note that, if a parameter contains missing values, a trial with missing values is not plotted.
Example:
The following code snippet shows how to plot the parameter relationship as contour plot.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_float("x", -100, 100)
y = trial.suggest_categorical("y", [-1, 0, 1])
return x ** 2 + y
sampler = optuna.samplers.TPESampler(seed=10)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=30)
fig = optuna.visualization.plot_contour(study, params=["x", "y"])
fig.show()
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
params:
Parameter list to visualize. The default is all parameters.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the color bar.
Returns:
A :class:`plotly.graph_objs.Figure` object.
Raises:
:exc:`ValueError`:
If ``target`` is :obj:`None` and ``study`` is being used for multi-objective
optimization.
"""
_imports.check()
_check_plot_args(study, target, target_name)
return _get_contour_plot(study, params, target, target_name)
def plot_intermediate_values(study: Study) -> "go.Figure":
"""Plot intermediate values of all trials in a study.
Example:
The following code snippet shows how to plot intermediate values.
.. testcode::
import optuna
def f(x):
return (x - 2) ** 2
def df(x):
return 2 * x - 4
def objective(trial):
lr = trial.suggest_loguniform("lr", 1e-5, 1e-1)
x = 3
for step in range(128):
y = f(x)
trial.report(y, step=step)
if trial.should_prune():
raise optuna.TrialPruned()
gy = df(x)
x -= gy * lr
return y
study = optuna.create_study()
study.optimize(objective, n_trials=16)
optuna.visualization.plot_intermediate_values(study)
.. raw:: html
<iframe src="../../_static/plot_intermediate_values.html"
width="100%" height="500px" frameborder="0">
</iframe>
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their intermediate
values.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
return _get_intermediate_plot(study)
def plot_parallel_coordinate(
study: Study,
params: Optional[List[str]] = None,
*,
target: Optional[Callable[[FrozenTrial], float]] = None,
target_name: str = "Objective Value",
) -> "go.Figure":
"""Plot the high-dimensional parameter relationships in a study.
Note that, if a parameter contains missing values, a trial with missing values is not plotted.
Example:
The following code snippet shows how to plot the high-dimensional parameter relationships.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_float("x", -100, 100)
y = trial.suggest_categorical("y", [-1, 0, 1])
return x ** 2 + y
sampler = optuna.samplers.TPESampler(seed=10)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=10)
fig = optuna.visualization.plot_parallel_coordinate(study, params=["x", "y"])
fig.show()
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
params:
Parameter list to visualize. The default is all parameters.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the axis label and the legend.
Returns:
A :class:`plotly.graph_objs.Figure` object.
.. note::
The colormap is reversed when the ``target`` argument isn't :obj:`None` or ``direction``
of :class:`~optuna.study.Study` is ``minimize``.
"""
_imports.check()
info = _get_parallel_coordinate_info(study, params, target, target_name)
return _get_parallel_coordinate_plot(info)
def plot_optimization_history(
study: Study,
*,
target: Optional[Callable[[FrozenTrial], float]] = None,
target_name: str = "Objective Value",
) -> "go.Figure":
"""Plot optimization history of all trials in a study.
Example:
The following code snippet shows how to plot optimization history.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_uniform("x", -100, 100)
y = trial.suggest_categorical("y", [-1, 0, 1])
return x ** 2 + y
sampler = optuna.samplers.TPESampler(seed=10)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=10)
optuna.visualization.plot_optimization_history(study)
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the axis label and the legend.
Returns:
A :class:`plotly.graph_objs.Figure` object.
Raises:
:exc:`ValueError`:
If ``target`` is :obj:`None` and ``study`` is being used for multi-objective
optimization.
"""
_imports.check()
if target is None and study._is_multi_objective():
raise ValueError(
"If the `study` is being used for multi-objective optimization, "
"please specify the `target`.")
return _get_optimization_history_plot(study, target, target_name)
def plot_intermediate_values(study: Study) -> "go.Figure":
"""Plot intermediate values of all trials in a study.
Example:
The following code snippet shows how to plot intermediate values.
.. plotly::
import optuna
def f(x):
return (x - 2) ** 2
def df(x):
return 2 * x - 4
def objective(trial):
lr = trial.suggest_float("lr", 1e-5, 1e-1, log=True)
x = 3
for step in range(128):
y = f(x)
trial.report(y, step=step)
if trial.should_prune():
raise optuna.TrialPruned()
gy = df(x)
x -= gy * lr
return y
sampler = optuna.samplers.TPESampler(seed=10)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=16)
fig = optuna.visualization.plot_intermediate_values(study)
fig.show()
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their intermediate
values.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
return _get_intermediate_plot(study)
def plot_parallel_coordinate(study: Study,
params: Optional[List[str]] = None
) -> "go.Figure":
"""Plot the high-dimentional parameter relationships in a study.
Note that, If a parameter contains missing values, a trial with missing values is not plotted.
Example:
The following code snippet shows how to plot the high-dimentional parameter relationships.
.. testcode::
import optuna
def objective(trial):
x = trial.suggest_uniform("x", -100, 100)
y = trial.suggest_categorical("y", [-1, 0, 1])
return x ** 2 + y
study = optuna.create_study()
study.optimize(objective, n_trials=10)
optuna.visualization.plot_parallel_coordinate(study, params=["x", "y"])
.. raw:: html
<iframe src="../../../_static/plot_parallel_coordinate.html"
width="100%" height="500px" frameborder="0">
</iframe>
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their objective
values.
params:
Parameter list to visualize. The default is all parameters.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
return _get_parallel_coordinate_plot(study, params)
def plot_optimization_history(
study: Study,
*,
target: Optional[Callable[[FrozenTrial], float]] = None,
target_name: str = "Objective Value",
) -> "go.Figure":
"""Plot optimization history of all trials in a study.
Example:
The following code snippet shows how to plot optimization history.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_uniform("x", -100, 100)
y = trial.suggest_categorical("y", [-1, 0, 1])
return x ** 2 + y
sampler = optuna.samplers.TPESampler(seed=10)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=10)
optuna.visualization.plot_optimization_history(study)
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their target values.
target:
A function to specify the value to display. If it is :obj:`None`, the objective values
are plotted.
target_name:
Target's name to display on the axis label and the legend.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
return _get_optimization_history_plot(study, target, target_name)
def plot_optimization_history(study: Study) -> "go.Figure":
"""Plot optimization history of all trials in a study.
Example:
The following code snippet shows how to plot optimization history.
.. testcode::
import optuna
def objective(trial):
x = trial.suggest_uniform("x", -100, 100)
y = trial.suggest_categorical("y", [-1, 0, 1])
return x ** 2 + y
study = optuna.create_study()
study.optimize(objective, n_trials=10)
optuna.visualization.plot_optimization_history(study)
.. raw:: html
<iframe src="../../_static/plot_optimization_history.html"
width="100%" height="500px" frameborder="0">
</iframe>
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their objective
values.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
return _get_optimization_history_plot(study)
def plot_slice(study: Study,
params: Optional[List[str]] = None) -> "go.Figure":
"""Plot the parameter relationship as slice plot in a study.
Note that, If a parameter contains missing values, a trial with missing values is not plotted.
Example:
The following code snippet shows how to plot the parameter relationship as slice plot.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_uniform("x", -100, 100)
y = trial.suggest_categorical("y", [-1, 0, 1])
return x ** 2 + y
sampler = optuna.samplers.TPESampler(seed=10)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=10)
optuna.visualization.plot_slice(study, params=["x", "y"])
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their objective
values.
params:
Parameter list to visualize. The default is all parameters.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
return _get_slice_plot(study, params)
def plot_edf(study: Union[Study, Sequence[Study]]) -> "go.Figure":
"""Plot the objective value EDF (empirical distribution function) of a study.
Note that only the complete trials are considered when plotting the EDF.
.. note::
EDF is useful to analyze and improve search spaces.
For instance, you can see a practical use case of EDF in the paper
`Designing Network Design Spaces <https://arxiv.org/abs/2003.13678>`_.
.. note::
The plotted EDF assumes that the value of the objective function is in
accordance with the uniform distribution over the objective space.
Example:
The following code snippet shows how to plot EDF.
.. plotly::
import math
import optuna
def ackley(x, y):
a = 20 * math.exp(-0.2 * math.sqrt(0.5 * (x ** 2 + y ** 2)))
b = math.exp(0.5 * (math.cos(2 * math.pi * x) + math.cos(2 * math.pi * y)))
return -a - b + math.e + 20
def objective(trial, low, high):
x = trial.suggest_float("x", low, high)
y = trial.suggest_float("y", low, high)
return ackley(x, y)
sampler = optuna.samplers.RandomSampler()
# Widest search space.
study0 = optuna.create_study(study_name="x=[0,5), y=[0,5)", sampler=sampler)
study0.optimize(lambda t: objective(t, 0, 5), n_trials=500)
# Narrower search space.
study1 = optuna.create_study(study_name="x=[0,4), y=[0,4)", sampler=sampler)
study1.optimize(lambda t: objective(t, 0, 4), n_trials=500)
# Narrowest search space but it doesn't include the global optimum point.
study2 = optuna.create_study(study_name="x=[1,3), y=[1,3)", sampler=sampler)
study2.optimize(lambda t: objective(t, 1, 3), n_trials=500)
optuna.visualization.plot_edf([study0, study1, study2])
Args:
study:
A target :class:`~optuna.study.Study` object.
You can pass multiple studies if you want to compare those EDFs.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
if isinstance(study, Study):
studies = [study]
else:
studies = list(study)
return _get_edf_plot(studies)
def plot_pareto_front(
study: Study,
*,
target_names: Optional[List[str]] = None,
include_dominated_trials: bool = True,
axis_order: Optional[List[int]] = None,
constraints_func: Optional[Callable[[FrozenTrial],
Sequence[float]]] = None,
) -> "go.Figure":
"""Plot the Pareto front of a study.
.. seealso::
Please refer to :ref:`multi_objective` for the tutorial of the Pareto front visualization.
Example:
The following code snippet shows how to plot the Pareto front of a study.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_float("x", 0, 5)
y = trial.suggest_float("y", 0, 3)
v0 = 4 * x ** 2 + 4 * y ** 2
v1 = (x - 5) ** 2 + (y - 5) ** 2
return v0, v1
study = optuna.create_study(directions=["minimize", "minimize"])
study.optimize(objective, n_trials=50)
fig = optuna.visualization.plot_pareto_front(study)
fig.show()
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their objective
values.
target_names:
Objective name list used as the axis titles. If :obj:`None` is specified,
"Objective {objective_index}" is used instead.
include_dominated_trials:
A flag to include all dominated trial's objective values.
axis_order:
A list of indices indicating the axis order. If :obj:`None` is specified,
default order is used.
constraints_func:
An optional function that computes the objective constraints. It must take a
:class:`~optuna.trial.FrozenTrial` and return the constraints. The return value must
be a sequence of :obj:`float` s. A value strictly larger than 0 means that a
constraint is violated. A value equal to or smaller than 0 is considered feasible.
This specification is the same as in, for example,
:class:`~optuna.integration.NSGAIISampler`.
If given, trials are classified into three categories: feasible and best, feasible but
non-best, and infeasible. Categories are shown in different colors. Here, whether a
trial is best (on Pareto front) or not is determined ignoring all infeasible trials.
Returns:
A :class:`plotly.graph_objs.Figure` object.
Raises:
:exc:`ValueError`:
If the number of objectives of ``study`` isn't 2 or 3.
"""
_imports.check()
n_dim = len(study.directions)
if n_dim not in (2, 3):
raise ValueError(
"`plot_pareto_front` function only supports 2 or 3 objective studies."
)
if target_names is None:
target_names = [f"Objective {i}" for i in range(n_dim)]
elif len(target_names) != n_dim:
raise ValueError(
f"The length of `target_names` is supposed to be {n_dim}.")
if constraints_func is not None:
feasible_trials = []
infeasible_trials = []
for trial in study.get_trials(states=(TrialState.COMPLETE, )):
if all(map(lambda x: x <= 0.0, constraints_func(trial))):
feasible_trials.append(trial)
else:
infeasible_trials.append(trial)
best_trials = _get_pareto_front_trials_by_trials(
feasible_trials, study.directions)
if include_dominated_trials:
non_best_trials = _get_non_pareto_front_trials(
feasible_trials, best_trials)
else:
non_best_trials = []
if len(best_trials) == 0:
_logger.warning(
"Your study does not have any completed and feasible trials.")
else:
best_trials = study.best_trials
if len(best_trials) == 0:
_logger.warning("Your study does not have any completed trials.")
if include_dominated_trials:
non_best_trials = _get_non_pareto_front_trials(
study.get_trials(deepcopy=False), best_trials)
else:
non_best_trials = []
infeasible_trials = []
if axis_order is None:
axis_order = list(range(n_dim))
else:
if len(axis_order) != n_dim:
raise ValueError(
f"Size of `axis_order` {axis_order}. Expect: {n_dim}, Actual: {len(axis_order)}."
)
if len(set(axis_order)) != n_dim:
raise ValueError(
f"Elements of given `axis_order` {axis_order} are not unique!."
)
if max(axis_order) > n_dim - 1:
raise ValueError(
f"Given `axis_order` {axis_order} contains invalid index {max(axis_order)} "
f"higher than {n_dim - 1}.")
if min(axis_order) < 0:
raise ValueError(
f"Given `axis_order` {axis_order} contains invalid index {min(axis_order)} "
"lower than 0.")
def _make_scatter_object(
trials: Sequence[FrozenTrial],
hovertemplate: str,
infeasible: bool = False,
dominated_trials: bool = False,
) -> Union["go.Scatter", "go.Scatter3d"]:
return _make_scatter_object_base(
n_dim,
trials,
axis_order, # type: ignore
include_dominated_trials,
hovertemplate=hovertemplate,
infeasible=infeasible,
dominated_trials=dominated_trials,
)
if constraints_func is None:
data = [
_make_scatter_object(
non_best_trials,
hovertemplate="%{text}<extra>Trial</extra>",
dominated_trials=True,
),
_make_scatter_object(
best_trials,
hovertemplate="%{text}<extra>Best Trial</extra>",
dominated_trials=False,
),
]
else:
data = [
_make_scatter_object(
infeasible_trials,
hovertemplate="%{text}<extra>Infeasible Trial</extra>",
infeasible=True,
),
_make_scatter_object(
non_best_trials,
hovertemplate="%{text}<extra>Feasible Trial</extra>",
dominated_trials=True,
),
_make_scatter_object(
best_trials,
hovertemplate="%{text}<extra>Best Trial</extra>",
dominated_trials=False,
),
]
if n_dim == 2:
layout = go.Layout(
title="Pareto-front Plot",
xaxis_title=target_names[axis_order[0]],
yaxis_title=target_names[axis_order[1]],
)
else:
layout = go.Layout(
title="Pareto-front Plot",
scene={
"xaxis_title": target_names[axis_order[0]],
"yaxis_title": target_names[axis_order[1]],
"zaxis_title": target_names[axis_order[2]],
},
)
return go.Figure(data=data, layout=layout)
def plot_param_importances(
study: Study,
evaluator: Optional[BaseImportanceEvaluator] = None,
params: Optional[List[str]] = None,
*,
target: Optional[Callable[[FrozenTrial], float]] = None,
target_name: str = "Objective Value",
) -> "go.Figure":
"""Plot hyperparameter importances.
Example:
The following code snippet shows how to plot hyperparameter importances.
.. plotly::
import optuna
def objective(trial):
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=10)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=100)
fig = optuna.visualization.plot_param_importances(study)
fig.show()
.. seealso::
This function visualizes the results of :func:`optuna.importance.get_param_importances`.
Args:
study:
An optimized study.
evaluator:
An importance evaluator object that specifies which algorithm to base the importance
assessment on.
Defaults to
:class:`~optuna.importance.FanovaImportanceEvaluator`.
params:
A list of names of parameters to assess.
If :obj:`None`, all parameters that are present in all of the completed trials are
assessed.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. 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.
target_name:
Target's name to display on the axis label.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
importances_info = _get_importances_info(study, evaluator, params, target,
target_name)
hover_template = _get_hover_template(importances_info, study)
return _get_importances_plot(importances_info, hover_template)
def plot_pareto_front(
study: Study,
*,
target_names: Optional[List[str]] = None,
include_dominated_trials: bool = True,
axis_order: Optional[List[int]] = None,
constraints_func: Optional[Callable[[FrozenTrial],
Sequence[float]]] = None,
targets: Optional[Callable[[FrozenTrial], Sequence[float]]] = None,
) -> "go.Figure":
"""Plot the Pareto front of a study.
.. seealso::
Please refer to :ref:`multi_objective` for the tutorial of the Pareto front visualization.
Example:
The following code snippet shows how to plot the Pareto front of a study.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_float("x", 0, 5)
y = trial.suggest_float("y", 0, 3)
v0 = 4 * x ** 2 + 4 * y ** 2
v1 = (x - 5) ** 2 + (y - 5) ** 2
return v0, v1
study = optuna.create_study(directions=["minimize", "minimize"])
study.optimize(objective, n_trials=50)
fig = optuna.visualization.plot_pareto_front(study)
fig.show()
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their objective
values. ``study.n_objectives`` must be eigher 2 or 3.
target_names:
Objective name list used as the axis titles. If :obj:`None` is specified,
"Objective {objective_index}" is used instead. If ``targets`` is specified
for a study that does not contain any completed trial,
``target_name`` must be specified.
include_dominated_trials:
A flag to include all dominated trial's objective values.
axis_order:
A list of indices indicating the axis order. If :obj:`None` is specified,
default order is used. ``axis_order`` and ``targets`` cannot be used at the same time.
constraints_func:
An optional function that computes the objective constraints. It must take a
:class:`~optuna.trial.FrozenTrial` and return the constraints. The return value must
be a sequence of :obj:`float` s. A value strictly larger than 0 means that a
constraint is violated. A value equal to or smaller than 0 is considered feasible.
This specification is the same as in, for example,
:class:`~optuna.integration.NSGAIISampler`.
If given, trials are classified into three categories: feasible and best, feasible but
non-best, and infeasible. Categories are shown in different colors. Here, whether a
trial is best (on Pareto front) or not is determined ignoring all infeasible trials.
targets:
A function that returns targets values to display.
The argument to this function is :class:`~optuna.trial.FrozenTrial`.
``axis_order`` and ``targets`` cannot be used at the same time.
If your study has more than 4 objectives, ``targets`` must be specified.
.. 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 :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
info = _get_pareto_front_info(study, target_names,
include_dominated_trials, axis_order,
constraints_func, targets)
if constraints_func is None:
data = [
_make_scatter_object(
info.n_targets,
info.axis_order,
include_dominated_trials,
info.non_best_trials_with_values,
hovertemplate="%{text}<extra>Trial</extra>",
dominated_trials=True,
),
_make_scatter_object(
info.n_targets,
info.axis_order,
include_dominated_trials,
info.best_trials_with_values,
hovertemplate="%{text}<extra>Best Trial</extra>",
dominated_trials=False,
),
]
else:
data = [
_make_scatter_object(
info.n_targets,
info.axis_order,
include_dominated_trials,
info.infeasible_trials_with_values,
hovertemplate="%{text}<extra>Infeasible Trial</extra>",
infeasible=True,
),
_make_scatter_object(
info.n_targets,
info.axis_order,
include_dominated_trials,
info.non_best_trials_with_values,
hovertemplate="%{text}<extra>Feasible Trial</extra>",
dominated_trials=True,
),
_make_scatter_object(
info.n_targets,
info.axis_order,
include_dominated_trials,
info.best_trials_with_values,
hovertemplate="%{text}<extra>Best Trial</extra>",
dominated_trials=False,
),
]
if info.n_targets == 2:
layout = go.Layout(
title="Pareto-front Plot",
xaxis_title=info.target_names[info.axis_order[0]],
yaxis_title=info.target_names[info.axis_order[1]],
)
else:
layout = go.Layout(
title="Pareto-front Plot",
scene={
"xaxis_title": info.target_names[info.axis_order[0]],
"yaxis_title": info.target_names[info.axis_order[1]],
"zaxis_title": info.target_names[info.axis_order[2]],
},
)
return go.Figure(data=data, layout=layout)
def plot_param_importances(study: Study,
evaluator: BaseImportanceEvaluator = None,
params: Optional[List[str]] = None) -> "go.Figure":
"""Plot hyperparameter importances.
Example:
The following code snippet shows how to plot hyperparameter importances.
.. testcode::
import optuna
def objective(trial):
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
study = optuna.create_study(sampler=optuna.samplers.RandomSampler())
study.optimize(objective, n_trials=100)
optuna.visualization.plot_param_importances(study)
.. raw:: html
<iframe src="../../_static/plot_param_importances.html"
width="100%" height="500px" frameborder="0">
</iframe>
.. seealso::
This function visualizes the results of :func:`optuna.importance.get_param_importances`.
Args:
study:
An optimized study.
evaluator:
An importance evaluator object that specifies which algorithm to base the importance
assessment on.
Defaults to
:class:`~optuna.importance._mean_decrease_impurity.MeanDecreaseImpurityImportanceEvaluator`.
params:
A list of names of parameters to assess.
If :obj:`None`, all parameters that are present in all of the completed trials are
assessed.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
layout = go.Layout(
title="Hyperparameter Importances",
xaxis={"title": "Importance"},
yaxis={"title": "Hyperparameter"},
showlegend=False,
)
# Importances cannot be evaluated without completed trials.
# Return an empty figure for consistency with other visualization functions.
trials = [
trial for trial in study.trials if trial.state == TrialState.COMPLETE
]
if len(trials) == 0:
logger.warning("Study instance does not contain completed trials.")
return go.Figure(data=[], layout=layout)
importances = optuna.importance.get_param_importances(study,
evaluator=evaluator,
params=params)
importances = OrderedDict(reversed(list(importances.items())))
importance_values = list(importances.values())
param_names = list(importances.keys())
fig = go.Figure(
data=[
go.Bar(
x=importance_values,
y=param_names,
text=importance_values,
texttemplate="%{text:.2f}",
textposition="outside",
cliponaxis=False, # Ensure text is not clipped.
hovertemplate=[
_make_hovertext(param_name, importance, study)
for param_name, importance in importances.items()
],
marker_color=[
_get_color(param_name, study) for param_name in param_names
],
orientation="h",
)
],
layout=layout,
)
return fig
def plot_edf(
study: Union[Study, Sequence[Study]],
*,
target: Optional[Callable[[FrozenTrial], float]] = None,
target_name: str = "Objective Value",
) -> "go.Figure":
"""Plot the objective value EDF (empirical distribution function) of a study.
Note that only the complete trials are considered when plotting the EDF.
.. note::
EDF is useful to analyze and improve search spaces.
For instance, you can see a practical use case of EDF in the paper
`Designing Network Design Spaces <https://arxiv.org/abs/2003.13678>`_.
.. note::
The plotted EDF assumes that the value of the objective function is in
accordance with the uniform distribution over the objective space.
Example:
The following code snippet shows how to plot EDF.
.. plotly::
import math
import optuna
def ackley(x, y):
a = 20 * math.exp(-0.2 * math.sqrt(0.5 * (x ** 2 + y ** 2)))
b = math.exp(0.5 * (math.cos(2 * math.pi * x) + math.cos(2 * math.pi * y)))
return -a - b + math.e + 20
def objective(trial, low, high):
x = trial.suggest_float("x", low, high)
y = trial.suggest_float("y", low, high)
return ackley(x, y)
sampler = optuna.samplers.RandomSampler(seed=10)
# Widest search space.
study0 = optuna.create_study(study_name="x=[0,5), y=[0,5)", sampler=sampler)
study0.optimize(lambda t: objective(t, 0, 5), n_trials=500)
# Narrower search space.
study1 = optuna.create_study(study_name="x=[0,4), y=[0,4)", sampler=sampler)
study1.optimize(lambda t: objective(t, 0, 4), n_trials=500)
# Narrowest search space but it doesn't include the global optimum point.
study2 = optuna.create_study(study_name="x=[1,3), y=[1,3)", sampler=sampler)
study2.optimize(lambda t: objective(t, 1, 3), n_trials=500)
fig = optuna.visualization.plot_edf([study0, study1, study2])
fig.show()
Args:
study:
A target :class:`~optuna.study.Study` object.
You can pass multiple studies if you want to compare those EDFs.
target:
A function to specify the value to display. If it is :obj:`None` and ``study`` is being
used for single-objective optimization, the objective values are plotted.
.. note::
Specify this argument if ``study`` is being used for multi-objective optimization.
target_name:
Target's name to display on the axis label.
Returns:
A :class:`plotly.graph_objs.Figure` object.
Raises:
:exc:`ValueError`:
If ``target`` is :obj:`None` and ``study`` is being used for multi-objective
optimization.
"""
_imports.check()
if isinstance(study, Study):
studies = [study]
else:
studies = list(study)
_check_plot_args(studies, target, target_name)
return _get_edf_plot(studies, target, target_name)
def plot_pareto_front(
study: Study,
*,
target_names: Optional[List[str]] = None,
include_dominated_trials: bool = True,
axis_order: Optional[List[int]] = None,
) -> "go.Figure":
"""Plot the Pareto front of a study.
Example:
The following code snippet shows how to plot the Pareto front of a study.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_float("x", 0, 5)
y = trial.suggest_float("y", 0, 3)
v0 = 4 * x ** 2 + 4 * y ** 2
v1 = (x - 5) ** 2 + (y - 5) ** 2
return v0, v1
study = optuna.create_study(directions=["minimize", "minimize"])
study.optimize(objective, n_trials=50)
optuna.visualization.plot_pareto_front(study)
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their objective
values.
target_names:
Objective name list used as the axis titles. If :obj:`None` is specified,
"Objective {objective_index}" is used instead.
include_dominated_trials:
A flag to include all dominated trial's objective values.
axis_order:
A list of indices indicating the axis order. If :obj:`None` is specified,
default order is used.
Returns:
A :class:`plotly.graph_objs.Figure` object.
Raises:
:exc:`ValueError`:
If the number of objectives of ``study`` isn't 2 or 3.
"""
_imports.check()
if len(study.directions) == 2:
return _get_pareto_front_2d(study, target_names,
include_dominated_trials, axis_order)
elif len(study.directions) == 3:
return _get_pareto_front_3d(study, target_names,
include_dominated_trials, axis_order)
else:
raise ValueError(
"`plot_pareto_front` function only supports 2 or 3 objective studies."
)
def plot_param_importances(
study: Study,
evaluator: Optional[BaseImportanceEvaluator] = None,
params: Optional[List[str]] = None,
*,
target: Optional[Callable[[FrozenTrial], float]] = None,
target_name: str = "Objective Value",
) -> "go.Figure":
"""Plot hyperparameter importances.
Example:
The following code snippet shows how to plot hyperparameter importances.
.. plotly::
import optuna
def objective(trial):
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=10)
study = optuna.create_study(sampler=sampler)
study.optimize(objective, n_trials=100)
optuna.visualization.plot_param_importances(study)
.. seealso::
This function visualizes the results of :func:`optuna.importance.get_param_importances`.
Args:
study:
An optimized study.
evaluator:
An importance evaluator object that specifies which algorithm to base the importance
assessment on.
Defaults to
:class:`~optuna.importance.FanovaImportanceEvaluator`.
params:
A list of names of parameters to assess.
If :obj:`None`, all parameters that are present in all of the completed trials are
assessed.
target:
A function to specify the value to evaluate importances. If it is :obj:`None`, the
objective values are used.
target_name:
Target's name to display on the axis label.
Returns:
A :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
layout = go.Layout(
title="Hyperparameter Importances",
xaxis={"title": f"Importance for {target_name}"},
yaxis={"title": "Hyperparameter"},
showlegend=False,
)
# Importances cannot be evaluated without completed trials.
# Return an empty figure for consistency with other visualization functions.
trials = [trial for trial in study.trials if trial.state == TrialState.COMPLETE]
if len(trials) == 0:
logger.warning("Study instance does not contain completed trials.")
return go.Figure(data=[], layout=layout)
importances = optuna.importance.get_param_importances(
study, evaluator=evaluator, params=params, target=target
)
importances = OrderedDict(reversed(list(importances.items())))
importance_values = list(importances.values())
param_names = list(importances.keys())
fig = go.Figure(
data=[
go.Bar(
x=importance_values,
y=param_names,
text=importance_values,
texttemplate="%{text:.2f}",
textposition="outside",
cliponaxis=False, # Ensure text is not clipped.
hovertemplate=[
_make_hovertext(param_name, importance, study)
for param_name, importance in importances.items()
],
marker_color=[_get_color(param_name, study) for param_name in param_names],
orientation="h",
)
],
layout=layout,
)
return fig
def plot_pareto_front(
study: Study,
*,
target_names: Optional[List[str]] = None,
include_dominated_trials: bool = True,
axis_order: Optional[List[int]] = None,
constraints_func: Optional[Callable[[FrozenTrial],
Sequence[float]]] = None,
targets: Optional[Callable[[FrozenTrial], Sequence[float]]] = None,
) -> "go.Figure":
"""Plot the Pareto front of a study.
.. seealso::
Please refer to :ref:`multi_objective` for the tutorial of the Pareto front visualization.
Example:
The following code snippet shows how to plot the Pareto front of a study.
.. plotly::
import optuna
def objective(trial):
x = trial.suggest_float("x", 0, 5)
y = trial.suggest_float("y", 0, 3)
v0 = 4 * x ** 2 + 4 * y ** 2
v1 = (x - 5) ** 2 + (y - 5) ** 2
return v0, v1
study = optuna.create_study(directions=["minimize", "minimize"])
study.optimize(objective, n_trials=50)
fig = optuna.visualization.plot_pareto_front(study)
fig.show()
Args:
study:
A :class:`~optuna.study.Study` object whose trials are plotted for their objective
values. ``study.n_objectives`` must be either 2 or 3 when ``targets`` is :obj:`None`.
target_names:
Objective name list used as the axis titles. If :obj:`None` is specified,
"Objective {objective_index}" is used instead. If ``targets`` is specified
for a study that does not contain any completed trial,
``target_name`` must be specified.
include_dominated_trials:
A flag to include all dominated trial's objective values.
axis_order:
A list of indices indicating the axis order. If :obj:`None` is specified,
default order is used. ``axis_order`` and ``targets`` cannot be used at the same time.
.. warning::
Deprecated in v3.0.0. This feature will be removed in the future. The removal of
this feature is currently scheduled for v5.0.0, but this schedule is subject to
change. See https://github.com/optuna/optuna/releases/tag/v3.0.0.
constraints_func:
An optional function that computes the objective constraints. It must take a
:class:`~optuna.trial.FrozenTrial` and return the constraints. The return value must
be a sequence of :obj:`float` s. A value strictly larger than 0 means that a
constraint is violated. A value equal to or smaller than 0 is considered feasible.
This specification is the same as in, for example,
:class:`~optuna.integration.NSGAIISampler`.
If given, trials are classified into three categories: feasible and best, feasible but
non-best, and infeasible. Categories are shown in different colors. Here, whether a
trial is best (on Pareto front) or not is determined ignoring all infeasible trials.
.. 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.
targets:
A function that returns targets values to display.
The argument to this function is :class:`~optuna.trial.FrozenTrial`.
``axis_order`` and ``targets`` cannot be used at the same time.
If ``study.n_objectives`` is neither 2 nor 3, ``targets`` must be specified.
.. 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 :class:`plotly.graph_objs.Figure` object.
"""
_imports.check()
info = _get_pareto_front_info(study, target_names,
include_dominated_trials, axis_order,
constraints_func, targets)
return _get_pareto_front_plot(info)
