Study

class optuna.study.Study(study_name, storage, sampler=None, pruner=None, direction='minimize')[source]

A study corresponds to an optimization task, i.e., a set of trials.

This object provides interfaces to run a new Trial, access trials’ history, set/get user-defined attributes of the study itself.

Parameters:
  • study_name – Study’s name. Each study has a unique name as an identifier.
  • storage – Database URL such as sqlite:///example.db. Optuna internally uses SQLAlchemy to handle databases. Please refer to SQLAlchemy’s document for further details.
  • sampler – A sampler object that implements background algorithm for value suggestion. If None is specified, TPESampler is used as the default. See also samplers.
  • pruner – A pruner object that decides early stopping of unpromising trials. If None is specified, MedianPruner is used as the default. See also pruners.
  • direction – Direction of optimization. Set minimize for minimization and maximize for maximization. Note that maximize is currently unsupported.
best_params

Return parameters of the best trial in the Study.

Returns:A dictionary containing parameters of the best trial.
best_trial

Return the best trial in the Study.

Returns:A FrozenTrial object of the best trial.
best_value

Return the best objective value in the Study.

Returns:A float representing the best objective value.
direction

Return the direction of the Study.

Returns:A StudyDirection object.
optimize(func, n_trials=None, timeout=None, n_jobs=1, catch=(<class 'Exception'>, ))[source]

Optimize an objective function.

Parameters:
  • func – A callable that implements objective function.
  • n_trials – The number of trials. If this argument is set to None, there is no limitation on the number of trials. If timeout is also set to None, the study continues to create trials until it receives a termination signal such as Ctrl+C or SIGTERM.
  • timeout – Stop study after the given number of second(s). If this argument is set to None, the study is executed without time limitation. If n_trials is also set to None, the study continues to create trials until it receives a termination signal such as Ctrl+C or SIGTERM.
  • n_jobs – The number of parallel jobs. If this argument is set to -1, the number is set to CPU counts.
  • catch – A study continues to run even when a trial raises one of exceptions specified in this argument. Default is (Exception,), where all non-exit exceptions are handled by this logic.
set_user_attr(key, value)[source]

Set a user attribute to the Study.

Parameters:
  • key – A key string of the attribute.
  • value – A value of the attribute. The value should be JSON serializable.
trials

Return all trials in the Study.

Returns:A list of FrozenTrial objects.
trials_dataframe(include_internal_fields=False)[source]

Export trials as a pandas DataFrame.

The DataFrame provides various features to analyze studies. It is also useful to draw a histogram of objective values and to export trials as a CSV file. Note that DataFrames returned by trials_dataframe() employ MultiIndex, and columns have a hierarchical structure. Please refer to the example below to access DataFrame elements.

Example

Get an objective value and a value of parameter x in the first row.

>>> df = study.trials_dataframe()
>>> df
>>> df.value[0]
0.0
>>> df.params.x[0]
1.0
Parameters:include_internal_fields – By default, internal fields of FrozenTrial are excluded from a DataFrame of trials. If this argument is True, they will be included in the DataFrame.
Returns:A pandas DataFrame of trials in the Study.
user_attrs

Return user attributes.

Returns:A dictionary containing all user attributes.
optuna.study.create_study(storage=None, sampler=None, pruner=None, study_name=None, direction='minimize', load_if_exists=False)[source]

Create a new Study.

Parameters:
  • storage – Database URL. If this argument is set to None, in-memory storage is used, and the Study will not be persistent.
  • sampler – A sampler object that implements background algorithm for value suggestion. See also samplers.
  • pruner – A pruner object that decides early stopping of unpromising trials. See also pruners.
  • study_name – Study’s name. If this argument is set to None, a unique name is generated automatically.
  • direction – Direction of optimization. Set minimize for minimization and maximize for maximization. Note that maximize is currently unsupported.
  • load_if_exists – Flag to control the behavior to handle a conflict of study names. In the case where a study named study_name already exists in the storage, a DuplicatedStudyError is raised if load_if_exists is set to False. Otherwise, the creation of the study is skipped, and the existing one is returned.
Returns:

A Study object.

optuna.study.get_all_study_summaries(storage)[source]

Get all history of studies stored in a specified storage.

Parameters:storage – Database URL.
Returns:List of study history summarized as StudySummary objects.