optuna_dashboard.preferential.PreferentialStudy

class optuna_dashboard.preferential.PreferentialStudy(study)

A Study-like class for preferential optimization.

This object provides interfaces to create a new Trial, set/get results of pairwise comparison called preferences.

Note that the direct use of this constructor is not recommended. To create and load a study, please refer to the documentation of create_study() and load_study() respectively.

Note

Preferential optimization is an experimental feature (introduced in v0.13.0). The interface may change in newer versions without prior notice.

Methods

add_trial(trial)	Add a trial to the study.
add_trials(trials)	Add trials to the study.
ask([fixed_distributions])	Create a new trial from which hyperparameters can be suggested.
enqueue_trial(params[, user_attrs, ...])	Enqueue a trial with given parameter values.
get_preferences(*[, deepcopy])	Return results of pairwise comparison.
get_trials([deepcopy, states])	Return the trials that is not dominated by other trials.
report_preference(better_trials, worse_trials)	Report results of pairwise comparison.
set_user_attr(key, value)	Set a user attribute to the study.
should_generate()	Return whether the generator should generate a new trial now.

Attributes

best_trials	Return the trials that is not dominated by other trials.
preferences	Return results of pairwise comparison.
study_name	Return the name of the study.
trials	Return the all trials.
user_attrs	Return user attributes of the study.

Parameters:

study (optuna.Study)

add_trial(trial)

Add a trial to the study.

See also

See Study.add_trials() for details.

Parameters:

trial (FrozenTrial)

Return type:

None

add_trials(trials)

Add trials to the study.

See also

See Study.add_trials() for details.

Parameters:

trials (Iterable[FrozenTrial])

Return type:

None

ask(fixed_distributions=None)

Create a new trial from which hyperparameters can be suggested.

See also

See Study.ask for details.

Parameters:

fixed_distributions (dict[str, BaseDistribution] | None) – A dictionary containing the parameter names and parameter’s distributions. Each parameter in this dictionary is automatically suggested for the returned trial, even when the suggest method is not explicitly invoked by the user. If this argument is set to None, no parameter is automatically suggested.

Returns:

A Trial object.

Return type:

Trial

property best_trials: list[FrozenTrial]

Return the trials that is not dominated by other trials.

Returns:

A list of FrozenTrial object

enqueue_trial(params, user_attrs=None, skip_if_exists=False)

Enqueue a trial with given parameter values.

You can fix the next sampling parameters which will be evaluated in your objective function.

See also

See `Study.enqueue_trials`_ for details.

Parameters:

• params (dict[str, Any]) – Parameter values to pass your objective function.

• user_attrs (dict[str, Any] | None) – A dictionary of user-specific attributes other than params.

• skip_if_exists (bool) –

  When True, prevents duplicate trials from being enqueued again.

  Note

  This method might produce duplicated trials if called simultaneously by multiple processes at the same time with same params dict.

Return type:

None

get_preferences(*, deepcopy=True)

Return results of pairwise comparison.

Parameters:

deepcopy (bool) – Flag to control whether to apply copy.deepcopy() to the trials. Note that if you set the flag to False, you shouldn’t mutate any fields of the returned trial. Otherwise the internal state of the study may corrupt and unexpected behavior may happen.

Returns:

A list of the pair of FrozenTrial objects. The left trial is better than the right one.

Return type:

list[tuple[FrozenTrial, FrozenTrial]]

get_trials(deepcopy=True, states=None)

Return the trials that is not dominated by other trials.

See also

See `Study.get_trials`_ for details.

Parameters:

• deepcopy (bool) – Flag to control whether to apply copy.deepcopy() to the trials. Note that if you set the flag to False, you shouldn’t mutate any fields of the returned trial. Otherwise the internal state of the study may corrupt and unexpected behavior may happen.

• states (Container[TrialState] | None) – Trial states to filter on. If None, include all states.

Returns:

A list of FrozenTrial object

Return type:

list[FrozenTrial]

property preferences: list[tuple[FrozenTrial, FrozenTrial]]

Return results of pairwise comparison.

Returns:

A list of the pair of FrozenTrial objects. The left trial is better than the right one.

report_preference(better_trials, worse_trials)

Report results of pairwise comparison.

Parameters:

• better_trials (FrozenTrial | list[FrozenTrial]) – Trials that are better than worse_trials.

• worse_trials (FrozenTrial | list[FrozenTrial]) – Trials that are worse than better_trials.

Return type:

None

set_user_attr(key, value)

Set a user attribute to the study.

Parameters:

• key (str) – A key string of the attribute.

• value (Any) – A value of the attribute. The value should be JSON serializable.

Return type:

None

See also

See the tutorial for user attributes on Optuna’s documentation.

should_generate()

Return whether the generator should generate a new trial now.

Returns True if the number of trials not reported bad and not skipped are less than n_generate. Users are recommended to generate a new trial if this method returns True, and to wait for human evaluation if this method returns False.

Return type:

bool

property study_name: str

Return the name of the study.

Returns:

A string object

property trials: list[FrozenTrial]

Return the all trials.

See also

See Study.trials for details.

Returns:

A list of FrozenTrial object

property user_attrs: dict[str, Any]

Return user attributes of the study.

See also

See Study.user_attrs for details.

Returns:

A dictionary containing all user attributes