BayesianOptimization

Bayesian optimization results

Description

A BayesianOptimization object contains the results of a Bayesian optimization. It is the output of bayesopt or a fit function that accepts the OptimizeHyperparameters name-value pair such as fitcdiscr. In addition, a BayesianOptimization object contains data for each iteration of bayesopt that can be accessed by a plot function or an output function.

Creation

Create a BayesianOptimization object by using the bayesopt function or one of the following fit functions with the OptimizeHyperparameters name-value argument.

• Classification fit functions: fitcdiscr, fitcecoc, fitcensemble, fitcgam, fitckernel, fitcknn, fitclinear, fitcnb, fitcnet, fitcsvm, fitctree

• Regression fit functions: fitrensemble, fitrgam, fitrgp, fitrkernel, fitrlinear, fitrnet, fitrsvm, fitrtree

• Quantile regression fit functions: fitrqlinear, fitrqnet

You can also create a BayesianOptimization object by using the fitcauto and fitrauto functions, or by using the Classification Learner and Regression Learner apps. For more information, see Ways to Perform Bayesian Optimization.

Properties

Problem Definition Properties

ObjectiveFcn — ObjectiveFcn argument used by bayesopt

Read-only: function handle

This property is read-only.

ObjectiveFcn argument used by bayesopt, specified as a function handle.

• If you call bayesopt directly, ObjectiveFcn is the bayesopt objective function argument.

• If you call a fit function containing the 'OptimizeHyperparameters' name-value pair argument, ObjectiveFcn is a function handle that returns the misclassification rate for classification or returns the logarithm of one plus the cross-validation loss for regression, measured by five-fold cross-validation.

Data Types: function_handle

VariableDescriptions — VariableDescriptions argument that bayesopt used

Read-only: vector of optimizableVariable objects

This property is read-only.

VariableDescriptions argument that bayesopt used, specified as a vector of optimizableVariable objects.

• If you called bayesopt directly, VariableDescriptions is the bayesopt variable description argument.

• If you called a fit function with the OptimizeHyperparameters name-value pair, VariableDescriptions is the vector of hyperparameters.

Options — Options that bayesopt used

Read-only: structure

This property is read-only.

Options that bayesopt used, specified as a structure.

• If you called bayesopt directly, Options is the options used in bayesopt, which are the name-value pairs See bayesopt Input Arguments.

• If you called a fit function with the OptimizeHyperparameters name-value pair, Options are the default bayesopt options, modified by the HyperparameterOptimizationOptions name-value pair.

Options is a read-only structure containing the following fields.

Option Name	Meaning
AcquisitionFunctionName	Acquisition function name (with dashes removed). See Acquisition Function Types.
IsObjectiveDeterministic	true means the objective function is deterministic, false otherwise.
ExplorationRatio	Used only when AcquisitionFunctionName is 'expectedimprovementplus' or 'expectedimprovement-persecondplus'. See Plus.
MaxObjectiveEvaluations	Objective function evaluation limit.
MaxTime	Time limit.
XConstraintFcn	Deterministic constraints on variables. See Deterministic Constraints — XConstraintFcn.
ConditionalVariableFcn	Conditional variable constraints. See Conditional Constraints — ConditionalVariableFcn.
NumCoupledConstraints	Number of coupled constraints. See Coupled Constraints.
CoupledConstraintTolerances	Coupled constraint tolerances. See Coupled Constraints.
AreCoupledConstraintsDeterministic	Logical vector specifying whether each coupled constraint is deterministic.
Verbose	Command-line display level.
OutputFcn	Function called after each iteration. See Bayesian Optimization Output Functions.
SaveVariableName	Variable name for the @assignInBase output function.
SaveFileName	File name for the @saveToFile output function.
PlotFcn	Plot function called after each iteration. See Bayesian Optimization Plot Functions
InitialX	Points where bayesopt evaluated the objective function.
InitialObjective	Objective function values at InitialX.
InitialConstraintViolations	Coupled constraint function values at InitialX.
InitialErrorValues	Error values at InitialX.
InitialObjectiveEvaluationTimes	Objective function evaluation times at InitialX.
InitialIterationTimes	Time for each iteration, including objective function evaluation and other computations.

Data Types: struct

Solution Properties

MinObjective — Minimum observed value of objective function

Read-only: real scalar

This property is read-only.

Minimum observed value of objective function, specified as a real scalar. When there are coupled constraints or evaluation errors, this value is the minimum over all observed points that are feasible according to the final constraint and Error models.

Data Types: double

XAtMinObjective — Observed point with minimum objective function value

Read-only: 1-by-D table

This property is read-only.

Observed point with minimum objective function value, specified as a 1-by-D table, where D is the number of variables.

Data Types: table

MinEstimatedObjective — Estimated objective function value

Read-only: real scalar

This property is read-only.

Estimated objective function value at XAtMinEstimatedObjective, specified as a real scalar.

MinEstimatedObjective is the mean value of the posterior distribution of the final objective model. The software estimates the MinEstimatedObjective value by passing XAtMinEstimatedObjective to the object function predictObjective.

Data Types: double

XAtMinEstimatedObjective — Point with minimum upper confidence bound of objective function value

Read-only: 1-by-D table

This property is read-only.

Point with the minimum upper confidence bound of the objective function value among the visited points, specified as a 1-by-D table, where D is the number of variables. The software uses the final objective model to find the upper confidence bounds of the visited points.

XAtMinEstimatedObjective is the same as the best point returned by the bestPoint function with the default criterion ('min-visited-upper-confidence-interval').

Data Types: table

NumObjectiveEvaluations — Number of objective function evaluations

Read-only: positive integer

This property is read-only.

Number of objective function evaluations, specified as a positive integer. This includes the initial evaluations to form a posterior model as well as evaluation during the optimization iterations.

Data Types: double

TotalElapsedTime — Total elapsed time of optimization in seconds

Read-only: positive scalar

This property is read-only.

Total elapsed time of optimization in seconds, specified as a positive scalar.

Data Types: double

NextPoint — Next point to evaluate if optimization continues

Read-only: 1-by-D table

This property is read-only.

Next point to evaluate if optimization continues, specified as a 1-by-D table, where D is the number of variables.

Data Types: table

Trace Properties

XTrace — Points where the objective function was evaluated

Read-only: T-by-D table

This property is read-only.

Points where the objective function was evaluated, specified as a T-by-D table, where T is the number of evaluation points and D is the number of variables.

Data Types: table

ObjectiveTrace — Objective function values

Read-only: column vector of length T

This property is read-only.

Objective function values, specified as a column vector of length T, where T is the number of evaluation points. ObjectiveTrace contains the history of objective function evaluations.

Data Types: double

ObjectiveEvaluationTimeTrace — Objective function evaluation times

Read-only: column vector of length T

This property is read-only.

Objective function evaluation times, specified as a column vector of length T, where T is the number of evaluation points. ObjectiveEvaluationTimeTrace includes the time in evaluating coupled constraints, because the objective function computes these constraints.

Data Types: double

IterationTimeTrace — Iteration times

Read-only: column vector of length T

This property is read-only.

Iteration times, specified as a column vector of length T, where T is the number of evaluation points. IterationTimeTrace includes both objective function evaluation time and other overhead.

Data Types: double

ConstraintsTrace — Coupled constraint values

Read-only: T-by-K array

This property is read-only.

Coupled constraint values, specified as a T-by-K array, where T is the number of evaluation points and K is the number of coupled constraints.

Data Types: double

ErrorTrace — Error indications

Read-only: column vector of length T of -1 or 1 entries

This property is read-only.

Error indications, specified as a column vector of length T of -1 or 1 entries, where T is the number of evaluation points. Each 1 entry indicates that the objective function errored or returned NaN on the corresponding point in XTrace. Each -1 entry indicates that the objective function value was computed.

Data Types: double

FeasibilityTrace — Feasibility indications

Read-only: logical column vector of length T

This property is read-only.

Feasibility indications, specified as a logical column vector of length T, where T is the number of evaluation points. Each 1 entry indicates that the final constraint model predicts feasibility at the corresponding point in XTrace.

Data Types: logical

FeasibilityProbabilityTrace — Probability that evaluation point is feasible

Read-only: column vector of length T

This property is read-only.

Probability that evaluation point is feasible, specified as a column vector of length T, where T is the number of evaluation points. The probabilities come from the final constraint model, including the error constraint model, on the corresponding points in XTrace.

Data Types: double

IndexOfMinimumTrace — Which evaluation gave minimum feasible objective

Read-only: column vector of integer indices of length T

This property is read-only.

Which evaluation gave minimum feasible objective, specified as a column vector of integer indices of length T, where T is the number of evaluation points. Feasibility is determined with respect to the constraint models that existed at each iteration, including the error constraint model.

Data Types: double

ObjectiveMinimumTrace — Minimum observed objective

Read-only: column vector of length T

This property is read-only.

Minimum observed objective, specified as a column vector of length T, where T is the number of evaluation points.

Data Types: double

EstimatedObjectiveMinimumTrace — Estimated objective

Read-only: column vector of length T

This property is read-only.

Estimated objective, specified as a column vector of length T, where T is the number of evaluation points. The estimated objective at each iteration is determined with respect to the objective model at that iteration. At each iteration, the software uses the object function predictObjective to estimate the objective function value at the point with the minimum upper confidence bound of the objective function among the visited points.

Data Types: double

UserDataTrace — Auxiliary data from the objective function

Read-only: cell array of length T

This property is read-only.

Auxiliary data from the objective function, specified as a cell array of length T, where T is the number of evaluation points. Each entry in the cell array is the UserData returned in the third output of the objective function.

Data Types: cell

Object Functions

bestPoint	Best point in a Bayesian optimization according to a criterion
plot	Plot Bayesian optimization results
predictConstraints	Predict coupled constraint violations at a set of points
predictError	Predict error value at a set of points
predictObjective	Predict objective function at a set of points
predictObjectiveEvaluationTime	Predict objective function run times at a set of points
resume	Resume a Bayesian optimization

Examples

Create a BayesianOptimization Object Using bayesopt

This example shows how to create a BayesianOptimization object by using bayesopt to minimize cross-validation loss.

Optimize hyperparameters of a KNN classifier for the ionosphere data, that is, find KNN hyperparameters that minimize the cross-validation loss. Have bayesopt minimize over the following hyperparameters:

• Nearest-neighborhood sizes from 1 to 30

• Distance functions 'chebychev', 'euclidean', and 'minkowski'.

For reproducibility, set the random seed, set the partition, and set the AcquisitionFunctionName option to 'expected-improvement-plus'. To suppress iterative display, set 'Verbose' to 0. Pass the partition c and fitting data X and Y to the objective function fun by creating fun as an anonymous function that incorporates this data. See Parameterizing Functions.

load ionosphere
rng default
num = optimizableVariable('n',[1,30],'Type','integer');
dst = optimizableVariable('dst',{'chebychev','euclidean','minkowski'},'Type','categorical');
c = cvpartition(351,'Kfold',5);
fun = @(x)kfoldLoss(fitcknn(X,Y,'CVPartition',c,'NumNeighbors',x.n,...
    'Distance',char(x.dst),'NSMethod','exhaustive'));
results = bayesopt(fun,[num,dst],'Verbose',0,...
    'AcquisitionFunctionName','expected-improvement-plus')

results = 
  BayesianOptimization with properties:

                      ObjectiveFcn: @(x)kfoldLoss(fitcknn(X,Y,'CVPartition',c,'NumNeighbors',x.n,'Distance',char(x.dst),'NSMethod','exhaustive'))
              VariableDescriptions: [1×2 optimizableVariable]
                           Options: [1×1 struct]
                      MinObjective: 0.1197
                   XAtMinObjective: [1×2 table]
             MinEstimatedObjective: 0.1213
          XAtMinEstimatedObjective: [1×2 table]
           NumObjectiveEvaluations: 30
                  TotalElapsedTime: 22.5336
                         NextPoint: [1×2 table]
                            XTrace: [30×2 table]
                    ObjectiveTrace: [30×1 double]
                  ConstraintsTrace: []
                     UserDataTrace: {30×1 cell}
      ObjectiveEvaluationTimeTrace: [30×1 double]
                IterationTimeTrace: [30×1 double]
                        ErrorTrace: [30×1 double]
                  FeasibilityTrace: [30×1 logical]
       FeasibilityProbabilityTrace: [30×1 double]
               IndexOfMinimumTrace: [30×1 double]
             ObjectiveMinimumTrace: [30×1 double]
    EstimatedObjectiveMinimumTrace: [30×1 double]

Create a BayesianOptimization Object Using a Fit Function

This example shows how to minimize the cross-validation loss in the ionosphere data using Bayesian optimization of an SVM classifier.

Load the data.

load ionosphere

Optimize the classification using the 'auto' parameters.

rng default % For reproducibility
Mdl = fitcsvm(X,Y,'OptimizeHyperparameters','auto')

|====================================================================================================================|
| Iter | Eval   | Objective   | Objective   | BestSoFar   | BestSoFar   | BoxConstraint|  KernelScale |  Standardize |
|      | result |             | runtime     | (observed)  | (estim.)    |              |              |              |
|====================================================================================================================|
|    1 | Best   |     0.35897 |     0.55068 |     0.35897 |     0.35897 |       3.8653 |       961.53 |         true |
|    2 | Best   |     0.12821 |       8.937 |     0.12821 |     0.15646 |       429.99 |       0.2378 |        false |
|    3 | Accept |     0.35897 |    0.080821 |     0.12821 |      0.1315 |      0.11801 |       8.9479 |        false |
|    4 | Accept |      0.1339 |      4.3802 |     0.12821 |     0.12965 |    0.0010694 |    0.0032063 |         true |
|    5 | Accept |     0.15954 |      10.212 |     0.12821 |     0.12824 |       973.65 |      0.15179 |        false |
|    6 | Accept |     0.13105 |     0.85587 |     0.12821 |     0.12824 |     0.020515 |      0.01138 |        false |
|    7 | Best   |     0.12536 |    0.069402 |     0.12536 |     0.12553 |     0.091384 |      0.21792 |        false |
|    8 | Accept |      0.1339 |       8.434 |     0.12536 |     0.12549 |     0.088519 |    0.0054531 |        false |
|    9 | Accept |      0.1339 |    0.052871 |     0.12536 |     0.12549 |     0.061486 |      0.54498 |        false |
|   10 | Accept |     0.12821 |     0.05382 |     0.12536 |     0.12418 |      0.02717 |      0.33435 |        false |
|   11 | Best   |     0.12251 |    0.065479 |     0.12251 |      0.1245 |     0.038981 |       0.3315 |        false |
|   12 | Accept |     0.12251 |    0.053891 |     0.12251 |     0.12477 |    0.0011259 |     0.052658 |        false |
|   13 | Best   |     0.11681 |    0.073661 |     0.11681 |     0.11708 |    0.0010027 |     0.024565 |        false |
|   14 | Accept |     0.14245 |     0.17818 |     0.11681 |     0.11732 |    0.0010009 |    0.0075154 |        false |
|   15 | Accept |      0.2906 |      10.238 |     0.11681 |     0.11727 |       979.26 |      0.02028 |         true |
|   16 | Accept |     0.13675 |     0.21964 |     0.11681 |     0.11822 |       1.9733 |      0.38946 |        false |
|   17 | Accept |     0.12821 |    0.066743 |     0.11681 |     0.12263 |     0.001006 |     0.030975 |        false |
|   18 | Accept |      0.1339 |      7.9797 |     0.11681 |     0.12274 |    0.0010127 |    0.0010426 |        false |
|   19 | Accept |      0.1339 |      8.7074 |     0.11681 |     0.12269 |    0.0010861 |    0.0010317 |         true |
|   20 | Accept |     0.13675 |    0.063674 |     0.11681 |     0.12189 |     0.001002 |      0.23902 |        false |
|====================================================================================================================|
| Iter | Eval   | Objective   | Objective   | BestSoFar   | BestSoFar   | BoxConstraint|  KernelScale |  Standardize |
|      | result |             | runtime     | (observed)  | (estim.)    |              |              |              |
|====================================================================================================================|
|   21 | Accept |     0.12251 |    0.066291 |     0.11681 |     0.12186 |     0.001003 |     0.027317 |        false |
|   22 | Accept |     0.12821 |    0.062326 |     0.11681 |     0.12323 |    0.0010185 |     0.030548 |        false |
|   23 | Accept |     0.11966 |    0.091185 |     0.11681 |     0.12249 |    0.0010061 |     0.026187 |        false |
|   24 | Accept |       0.151 |    0.053297 |     0.11681 |      0.1171 |     0.055134 |       2.1942 |        false |
|   25 | Accept |      0.1396 |    0.068534 |     0.11681 |     0.11717 |     0.025994 |       1.1409 |        false |
|   26 | Accept |      0.1339 |     0.13741 |     0.11681 |     0.11726 |    0.0010044 |     0.087741 |        false |
|   27 | Accept |     0.12251 |    0.081239 |     0.11681 |     0.11857 |     0.001003 |     0.018287 |        false |
|   28 | Accept |     0.13105 |     0.20438 |     0.11681 |     0.12355 |    0.0052604 |     0.022691 |        false |
|   29 | Accept |     0.12251 |    0.047222 |     0.11681 |      0.1235 |    0.0010272 |     0.041927 |        false |
|   30 | Accept |     0.12251 |    0.049391 |     0.11681 |     0.12305 |    0.0010012 |     0.041882 |        false |

__________________________________________________________
Optimization completed.
MaxObjectiveEvaluations of 30 reached.
Total function evaluations: 30
Total elapsed time: 72.8542 seconds
Total objective function evaluation time: 62.1341

Best observed feasible point:
    BoxConstraint    KernelScale    Standardize
    _____________    ___________    ___________

      0.0010027       0.024565         false   

Observed objective function value = 0.11681
Estimated objective function value = 0.12279
Function evaluation time = 0.073661

Best estimated feasible point (according to models):
    BoxConstraint    KernelScale    Standardize
    _____________    ___________    ___________

      0.0010061       0.026187         false   

Estimated objective function value = 0.12305
Estimated function evaluation time = 0.06941

Mdl = 
  ClassificationSVM
                         ResponseName: 'Y'
                CategoricalPredictors: []
                           ClassNames: {'b'  'g'}
                       ScoreTransform: 'none'
                      NumObservations: 351
    HyperparameterOptimizationResults: [1×1 BayesianOptimization]
                                Alpha: [100×1 double]
                                 Bias: -4.5478
                     KernelParameters: [1×1 struct]
                       BoxConstraints: [351×1 double]
                      ConvergenceInfo: [1×1 struct]
                      IsSupportVector: [351×1 logical]
                               Solver: 'SMO'


  Properties, Methods

The fit achieved about 12% loss for the default 5-fold cross validation.

Examine the BayesianOptimization object that is returned in the HyperparameterOptimizationResults property of the returned model.

disp(Mdl.HyperparameterOptimizationResults)

  BayesianOptimization with properties:

                      ObjectiveFcn: @createObjFcn/inMemoryObjFcn
              VariableDescriptions: [5×1 optimizableVariable]
                           Options: [1×1 struct]
                      MinObjective: 0.1168
                   XAtMinObjective: [1×3 table]
             MinEstimatedObjective: 0.1230
          XAtMinEstimatedObjective: [1×3 table]
           NumObjectiveEvaluations: 30
                  TotalElapsedTime: 72.8542
                         NextPoint: [1×3 table]
                            XTrace: [30×3 table]
                    ObjectiveTrace: [30×1 double]
                  ConstraintsTrace: []
                     UserDataTrace: {30×1 cell}
      ObjectiveEvaluationTimeTrace: [30×1 double]
                IterationTimeTrace: [30×1 double]
                        ErrorTrace: [30×1 double]
                  FeasibilityTrace: [30×1 logical]
       FeasibilityProbabilityTrace: [30×1 double]
               IndexOfMinimumTrace: [30×1 double]
             ObjectiveMinimumTrace: [30×1 double]
    EstimatedObjectiveMinimumTrace: [30×1 double]

Version History

Introduced in R2016b