optuna.trial.Trial
- class optuna.trial.Trial(study, trial_id)[源代码]
A trial is a process of evaluating an objective function.
This object is passed to an objective function and provides interfaces to get parameter suggestion, manage the trial’s state, and set/get user-defined attributes of the trial.
Note that the direct use of this constructor is not recommended. This object is seamlessly instantiated and passed to the objective function behind the
optuna.study.Study.optimize()
method; hence library users do not care about instantiation of this object.- 参数
study (optuna.study.Study) – A
Study
object.trial_id (int) – A trial ID that is automatically generated.
- 返回类型
None
Methods
report
(value, step)Report an objective function value for a given step.
set_system_attr
(key, value)Set system attributes to the trial.
set_user_attr
(key, value)Set user attributes to the trial.
Suggest whether the trial should be pruned or not.
suggest_categorical
(name, choices)Suggest a value for the categorical parameter.
suggest_discrete_uniform
(name, low, high, q)Suggest a value for the discrete parameter.
suggest_float
(name, low, high, *[, step, log])Suggest a value for the floating point parameter.
suggest_int
(name, low, high[, step, log])Suggest a value for the integer parameter.
suggest_loguniform
(name, low, high)Suggest a value for the continuous parameter.
suggest_uniform
(name, low, high)Suggest a value for the continuous parameter.
Attributes
Return start datetime.
Return distributions of parameters to be optimized.
Return trial's number which is consecutive and unique in a study.
Return parameters to be optimized.
Return system attributes.
Return user attributes.
- property datetime_start: Optional[datetime.datetime]
Return start datetime.
- 返回
Datetime where the
Trial
started.
- property distributions: Dict[str, optuna.distributions.BaseDistribution]
Return distributions of parameters to be optimized.
- 返回
A dictionary containing all distributions.
- property number: int
Return trial’s number which is consecutive and unique in a study.
- 返回
A trial number.
- property params: Dict[str, Any]
Return parameters to be optimized.
- 返回
A dictionary containing all parameters.
- report(value, step)[源代码]
Report an objective function value for a given step.
The reported values are used by the pruners to determine whether this trial should be pruned.
参见
Please refer to
BasePruner
.备注
The reported value is converted to
float
type by applyingfloat()
function internally. Thus, it accepts all float-like types (e.g.,numpy.float32
). If the conversion fails, aTypeError
is raised.示例
Report intermediate scores of SGDClassifier training.
import numpy as np from sklearn.datasets import load_iris from sklearn.linear_model import SGDClassifier from sklearn.model_selection import train_test_split import optuna X, y = load_iris(return_X_y=True) X_train, X_valid, y_train, y_valid = train_test_split(X, y) def objective(trial): clf = SGDClassifier(random_state=0) for step in range(100): clf.partial_fit(X_train, y_train, np.unique(y)) intermediate_value = clf.score(X_valid, y_valid) trial.report(intermediate_value, step=step) if trial.should_prune(): raise optuna.TrialPruned() return clf.score(X_valid, y_valid) study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=3)
- 参数
value (float) – A value returned from the objective function.
step (int) – Step of the trial (e.g., Epoch of neural network training). Note that pruners assume that
step
starts at zero. For example,MedianPruner
simply checks ifstep
is less thann_warmup_steps
as the warmup mechanism.
- 引发
NotImplementedError – If trial is being used for multi-objective optimization.
- 返回类型
None
- set_system_attr(key, value)[源代码]
Set system attributes to the trial.
Note that Optuna internally uses this method to save system messages such as failure reason of trials. Please use
set_user_attr()
to set users’ attributes.
- set_user_attr(key, value)[源代码]
Set user attributes to the trial.
The user attributes in the trial can be access via
optuna.trial.Trial.user_attrs()
.示例
Save fixed hyperparameters of neural network training.
import numpy as np from sklearn.datasets import load_iris from sklearn.model_selection import train_test_split from sklearn.neural_network import MLPClassifier import optuna X, y = load_iris(return_X_y=True) X_train, X_valid, y_train, y_valid = train_test_split(X, y, random_state=0) def objective(trial): trial.set_user_attr("BATCHSIZE", 128) momentum = trial.suggest_uniform("momentum", 0, 1.0) clf = MLPClassifier( hidden_layer_sizes=(100, 50), batch_size=trial.user_attrs["BATCHSIZE"], momentum=momentum, solver="sgd", random_state=0, ) clf.fit(X_train, y_train) return clf.score(X_valid, y_valid) study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=3) assert "BATCHSIZE" in study.best_trial.user_attrs.keys() assert study.best_trial.user_attrs["BATCHSIZE"] == 128
- should_prune()[源代码]
Suggest whether the trial should be pruned or not.
The suggestion is made by a pruning algorithm associated with the trial and is based on previously reported values. The algorithm can be specified when constructing a
Study
.备注
If no values have been reported, the algorithm cannot make meaningful suggestions. Similarly, if this method is called multiple times with the exact same set of reported values, the suggestions will be the same.
参见
Please refer to the example code in
optuna.trial.Trial.report()
.- 返回
A boolean value. If
True
, the trial should be pruned according to the configured pruning algorithm. Otherwise, the trial should continue.- 引发
NotImplementedError – If trial is being used for multi-objective optimization.
- 返回类型
- suggest_categorical(name, choices)[源代码]
Suggest a value for the categorical parameter.
The value is sampled from
choices
.示例
Suggest a kernel function of SVC.
import numpy as np from sklearn.datasets import load_iris from sklearn.model_selection import train_test_split from sklearn.svm import SVC import optuna X, y = load_iris(return_X_y=True) X_train, X_valid, y_train, y_valid = train_test_split(X, y) def objective(trial): kernel = trial.suggest_categorical("kernel", ["linear", "poly", "rbf"]) clf = SVC(kernel=kernel, gamma="scale", random_state=0) clf.fit(X_train, y_train) return clf.score(X_valid, y_valid) study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=3)
- 参数
- 返回类型
- suggest_discrete_uniform(name, low, high, q)[源代码]
Suggest a value for the discrete parameter.
The value is sampled from the range \([\mathsf{low}, \mathsf{high}]\), and the step of discretization is \(q\). More specifically, this method returns one of the values in the sequence \(\mathsf{low}, \mathsf{low} + q, \mathsf{low} + 2 q, \dots, \mathsf{low} + k q \le \mathsf{high}\), where \(k\) denotes an integer. Note that \(high\) may be changed due to round-off errors if \(q\) is not an integer. Please check warning messages to find the changed values.
示例
Suggest a fraction of samples used for fitting the individual learners of GradientBoostingClassifier.
import numpy as np from sklearn.datasets import load_iris from sklearn.ensemble import GradientBoostingClassifier from sklearn.model_selection import train_test_split import optuna X, y = load_iris(return_X_y=True) X_train, X_valid, y_train, y_valid = train_test_split(X, y) def objective(trial): subsample = trial.suggest_discrete_uniform("subsample", 0.1, 1.0, 0.1) clf = GradientBoostingClassifier(subsample=subsample, random_state=0) clf.fit(X_train, y_train) return clf.score(X_valid, y_valid) study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=3)
- suggest_float(name, low, high, *, step=None, log=False)[源代码]
Suggest a value for the floating point parameter.
Note that this is a wrapper method for
suggest_uniform()
,suggest_loguniform()
andsuggest_discrete_uniform()
.1.3.0 新版功能.
参见
Please see also
suggest_uniform()
,suggest_loguniform()
andsuggest_discrete_uniform()
.示例
Suggest a momentum, learning rate and scaling factor of learning rate for neural network training.
import numpy as np from sklearn.datasets import load_iris from sklearn.model_selection import train_test_split from sklearn.neural_network import MLPClassifier import optuna X, y = load_iris(return_X_y=True) X_train, X_valid, y_train, y_valid = train_test_split(X, y, random_state=0) def objective(trial): momentum = trial.suggest_float("momentum", 0.0, 1.0) learning_rate_init = trial.suggest_float( "learning_rate_init", 1e-5, 1e-3, log=True ) power_t = trial.suggest_float("power_t", 0.2, 0.8, step=0.1) clf = MLPClassifier( hidden_layer_sizes=(100, 50), momentum=momentum, learning_rate_init=learning_rate_init, solver="sgd", random_state=0, power_t=power_t, ) clf.fit(X_train, y_train) return clf.score(X_valid, y_valid) study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=3)
- 参数
name (str) – A parameter name.
low (float) – Lower endpoint of the range of suggested values.
low
is included in the range.high (float) –
Upper endpoint of the range of suggested values.
high
is excluded from the range.备注
If
step
is specified,high
is included as well aslow
because this method falls back tosuggest_discrete_uniform()
.A step of discretization.
备注
The
step
andlog
arguments cannot be used at the same time. To set thestep
argument to a float number, set thelog
argument toFalse
.log (bool) –
A flag to sample the value from the log domain or not. If
log
is true, the value is sampled from the range in the log domain. Otherwise, the value is sampled from the range in the linear domain. See alsosuggest_uniform()
andsuggest_loguniform()
.备注
The
step
andlog
arguments cannot be used at the same time. To set thelog
argument toTrue
, set thestep
argument toNone
.
- 引发
ValueError – If
step is not None
andlog = True
are specified.- 返回
A suggested float value.
- 返回类型
- suggest_int(name, low, high, step=1, log=False)[源代码]
Suggest a value for the integer parameter.
The value is sampled from the integers in \([\mathsf{low}, \mathsf{high}]\).
示例
Suggest the number of trees in RandomForestClassifier.
import numpy as np from sklearn.datasets import load_iris from sklearn.ensemble import RandomForestClassifier from sklearn.model_selection import train_test_split import optuna X, y = load_iris(return_X_y=True) X_train, X_valid, y_train, y_valid = train_test_split(X, y) def objective(trial): n_estimators = trial.suggest_int("n_estimators", 50, 400) clf = RandomForestClassifier(n_estimators=n_estimators, random_state=0) clf.fit(X_train, y_train) return clf.score(X_valid, y_valid) study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=3)
- 参数
name (str) – A parameter name.
low (int) – Lower endpoint of the range of suggested values.
low
is included in the range.high (int) – Upper endpoint of the range of suggested values.
high
is included in the range.step (int) –
A step of discretization.
备注
Note that \(\mathsf{high}\) is modified if the range is not divisible by \(\mathsf{step}\). Please check the warning messages to find the changed values.
备注
The method returns one of the values in the sequence \(\mathsf{low}, \mathsf{low} + \mathsf{step}, \mathsf{low} + 2 * \mathsf{step}, \dots, \mathsf{low} + k * \mathsf{step} \le \mathsf{high}\), where \(k\) denotes an integer.
备注
The
step != 1
andlog
arguments cannot be used at the same time. To set thestep
argument \(\mathsf{step} \ge 2\), set thelog
argument toFalse
.log (bool) –
A flag to sample the value from the log domain or not.
备注
If
log
is true, at first, the range of suggested values is divided into grid points of width 1. The range of suggested values is then converted to a log domain, from which a value is sampled. The uniformly sampled value is re-converted to the original domain and rounded to the nearest grid point that we just split, and the suggested value is determined. For example, if low = 2 and high = 8, then the range of suggested values is [2, 3, 4, 5, 6, 7, 8] and lower values tend to be more sampled than higher values.备注
The
step != 1
andlog
arguments cannot be used at the same time. To set thelog
argument toTrue
, set thestep
argument to 1.
- 引发
ValueError – If
step != 1
andlog = True
are specified.- 返回类型
- suggest_loguniform(name, low, high)[源代码]
Suggest a value for the continuous parameter.
The value is sampled from the range \([\mathsf{low}, \mathsf{high})\) in the log domain. When \(\mathsf{low} = \mathsf{high}\), the value of \(\mathsf{low}\) will be returned.
示例
Suggest penalty parameter
C
of SVC.import numpy as np from sklearn.datasets import load_iris from sklearn.model_selection import train_test_split from sklearn.svm import SVC import optuna X, y = load_iris(return_X_y=True) X_train, X_valid, y_train, y_valid = train_test_split(X, y) def objective(trial): c = trial.suggest_loguniform("c", 1e-5, 1e2) clf = SVC(C=c, gamma="scale", random_state=0) clf.fit(X_train, y_train) return clf.score(X_valid, y_valid) study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=3)
- suggest_uniform(name, low, high)[源代码]
Suggest a value for the continuous parameter.
The value is sampled from the range \([\mathsf{low}, \mathsf{high})\) in the linear domain. When \(\mathsf{low} = \mathsf{high}\), the value of \(\mathsf{low}\) will be returned.
示例
Suggest a momentum for neural network training.
import numpy as np from sklearn.datasets import load_iris from sklearn.model_selection import train_test_split from sklearn.neural_network import MLPClassifier import optuna X, y = load_iris(return_X_y=True) X_train, X_valid, y_train, y_valid = train_test_split(X, y) def objective(trial): momentum = trial.suggest_uniform("momentum", 0.0, 1.0) clf = MLPClassifier( hidden_layer_sizes=(100, 50), momentum=momentum, solver="sgd", random_state=0, ) clf.fit(X_train, y_train) return clf.score(X_valid, y_valid) study = optuna.create_study(direction="maximize") study.optimize(objective, n_trials=3)