Fit Gaussian kernel regression model using random feature expansion
fitrkernel
trains or crossvalidates a Gaussian kernel
regression model for nonlinear regression. fitrkernel
is more
practical to use for big data applications that have large training sets, but can also
be applied to smaller data sets that fit in memory.
fitrkernel
maps data in a lowdimensional space into a
highdimensional space, then fits a linear model in the highdimensional space by
minimizing the regularized objective function. Obtaining the linear model in the
highdimensional space is equivalent to applying the Gaussian kernel to the model in the
lowdimensional space. Available linear regression models include regularized support
vector machine (SVM) and leastsquares regression models.
To train a nonlinear SVM regression model on inmemory data, see fitrsvm
.
returns a kernel regression model with additional options specified by one or more
namevalue pair arguments. For example, you can implement leastsquares regression,
specify the number of dimension of the expanded space, or specify crossvalidation
options.Mdl
= fitrkernel(X
,Y
,Name,Value
)
[
also returns the hyperparameter optimization results when you optimize
hyperparameters by using the Mdl
,FitInfo
,HyperparameterOptimizationResults
] = fitrkernel(___)'OptimizeHyperparameters'
namevalue pair argument.
Train a kernel regression model for a tall array by using SVM.
When you perform calculations on tall arrays, MATLAB® uses either a parallel pool (default if you have Parallel Computing Toolbox™) or the local MATLAB session. If you want to run the example using the local MATLAB session when you have Parallel Computing Toolbox, you can change the global execution environment by using the mapreducer
function.
Create a datastore that references the folder location with the data. The data can be contained in a single file, a collection of files, or an entire folder. Treat 'NA'
values as missing data so that datastore
replaces them with NaN
values. Select a subset of the variables to use. Create a tall table on top of the datastore.
varnames = {'ArrTime','DepTime','ActualElapsedTime'}; ds = datastore('airlinesmall.csv','TreatAsMissing','NA',... 'SelectedVariableNames',varnames); t = tall(ds);
Starting parallel pool (parpool) using the 'local' profile ... Connected to the parallel pool (number of workers: 12).
Specify DepTime
and ArrTime
as the predictor variables (X
) and ActualElapsedTime
as the response variable (Y
). Select the observations for which ArrTime
is later than DepTime
.
daytime = t.ArrTime>t.DepTime; Y = t.ActualElapsedTime(daytime); % Response data X = t{daytime,{'DepTime' 'ArrTime'}}; % Predictor data
Standardize the predictor variables.
Z = zscore(X); % Standardize the data
Train a default Gaussian kernel regression model with the standardized predictors. Extract a fit summary to determine how well the optimization algorithm fits the model to the data.
[Mdl,FitInfo] = fitrkernel(Z,Y)
Found 6 chunks. =========================================================================  Solver  Iteration /  Objective  Gradient  Beta relative    Data Pass   magnitude  change  =========================================================================  INIT  0 / 1  4.307833e+01  4.345788e02  NaN   LBFGS  0 / 2  3.705713e+01  1.577301e02  9.988252e01   LBFGS  1 / 3  3.704022e+01  3.082836e02  1.338410e03   LBFGS  2 / 4  3.701398e+01  3.006488e02  1.116070e03   LBFGS  2 / 5  3.698797e+01  2.870642e02  2.234599e03   LBFGS  2 / 6  3.693687e+01  2.625581e02  4.479069e03   LBFGS  2 / 7  3.683757e+01  2.239620e02  8.997877e03   LBFGS  2 / 8  3.665038e+01  1.782358e02  1.815682e02   LBFGS  3 / 9  3.473411e+01  4.074480e02  1.778166e01   LBFGS  4 / 10  3.684246e+01  1.608942e01  3.294968e01   LBFGS  4 / 11  3.441595e+01  8.587703e02  1.420892e01   LBFGS  5 / 12  3.377755e+01  3.760006e02  4.640134e02   LBFGS  6 / 13  3.357732e+01  1.912644e02  3.842057e02   LBFGS  7 / 14  3.334081e+01  3.046709e02  6.211243e02   LBFGS  8 / 15  3.309239e+01  3.858085e02  6.411356e02   LBFGS  9 / 16  3.276577e+01  3.612292e02  6.938579e02   LBFGS  10 / 17  3.234029e+01  2.734959e02  1.144307e01   LBFGS  11 / 18  3.205763e+01  2.545990e02  7.323180e02   LBFGS  12 / 19  3.183341e+01  2.472411e02  3.689625e02   LBFGS  13 / 20  3.169307e+01  2.064613e02  2.998555e02  =========================================================================  Solver  Iteration /  Objective  Gradient  Beta relative    Data Pass   magnitude  change  =========================================================================  LBFGS  14 / 21  3.146896e+01  1.788395e02  5.967293e02   LBFGS  15 / 22  3.118171e+01  1.660696e02  1.124062e01   LBFGS  16 / 23  3.106224e+01  1.506147e02  7.947037e02   LBFGS  17 / 24  3.098395e+01  1.564561e02  2.678370e02   LBFGS  18 / 25  3.096029e+01  4.464104e02  4.547148e02   LBFGS  19 / 26  3.085475e+01  1.442800e02  1.677268e02   LBFGS  20 / 27  3.078140e+01  1.906548e02  2.275185e02  ========================================================================
Mdl = RegressionKernel PredictorNames: {'x1' 'x2'} ResponseName: 'Y' Learner: 'svm' NumExpansionDimensions: 64 KernelScale: 1 Lambda: 8.5385e06 BoxConstraint: 1 Epsilon: 5.9303 Properties, Methods
FitInfo = struct with fields:
Solver: 'LBFGStall'
LossFunction: 'epsiloninsensitive'
Lambda: 8.5385e06
BetaTolerance: 1.0000e03
GradientTolerance: 1.0000e05
ObjectiveValue: 30.7814
GradientMagnitude: 0.0191
RelativeChangeInBeta: 0.0228
FitTime: 117.2923
History: [1x1 struct]
Mdl
is a RegressionKernel
model. To inspect the regression error, you can pass Mdl
and the training data or new data to the loss
function. Or, you can pass Mdl
and new predictor data to the predict
function to predict responses for new observations. You can also pass Mdl
and the training data to the resume
function to continue training.
FitInfo
is a structure array containing optimization information. Use FitInfo
to determine whether optimization termination measurements are satisfactory.
For improved accuracy, you can increase the maximum number of optimization iterations ('IterationLimit'
) and decrease the tolerance values ('BetaTolerance'
and 'GradientTolerance'
) by using the namevalue pair arguments of fitrkernel
. Doing so can improve measures like ObjectiveValue
and RelativeChangeInBeta
in FitInfo
. You can also optimize model parameters by using the 'OptimizeHyperparameters'
namevalue pair argument.
Load the carbig
data set.
load carbig
Specify the predictor variables (X
) and the response variable (Y
).
X = [Acceleration,Cylinders,Displacement,Horsepower,Weight]; Y = MPG;
Delete rows of X
and Y
where either array has NaN
values. Removing rows with NaN
values before passing data to fitrkernel
can speed up training and reduce memory usage.
R = rmmissing([X Y]); % Data with missing entries removed
X = R(:,1:5);
Y = R(:,end);
Standardize the predictor variables.
Z = zscore(X);
Crossvalidate a kernel regression model using 5fold crossvalidation.
Mdl = fitrkernel(Z,Y,'Kfold',5)
Mdl = classreg.learning.partition.RegressionPartitionedKernel CrossValidatedModel: 'Kernel' ResponseName: 'Y' NumObservations: 392 KFold: 5 Partition: [1x1 cvpartition] ResponseTransform: 'none' Properties, Methods
numel(Mdl.Trained)
ans = 5
Mdl
is a RegressionPartitionedKernel
model. Because fitrkernel
implements fivefold crossvalidation, Mdl
contains five RegressionKernel
models that the software trains on trainingfold (infold) observations.
Examine the crossvalidation loss (mean squared error) for each fold.
kfoldLoss(Mdl,'mode','individual')
ans = 5×1
13.0610
14.0975
24.0104
21.1223
24.3979
Optimize hyperparameters automatically using the 'OptimizeHyperparameters'
namevalue pair argument.
Load the carbig
data set.
load carbig
Specify the predictor variables (X
) and the response variable (Y
).
X = [Acceleration,Cylinders,Displacement,Horsepower,Weight]; Y = MPG;
Delete rows of X
and Y
where either array has NaN
values. Removing rows with NaN
values before passing data to fitrkernel
can speed up training and reduce memory usage.
R = rmmissing([X Y]); % Data with missing entries removed
X = R(:,1:5);
Y = R(:,end);
Standardize the predictor variables.
Z = zscore(X);
Find hyperparameters that minimize fivefold crossvalidation loss by using automatic hyperparameter optimization. Specify 'OptimizeHyperparameters'
as 'auto'
so that fitrkernel
finds the optimal values of the 'KernelScale'
, 'Lambda'
, and 'Epsilon'
namevalue pair arguments. For reproducibility, set the random seed and use the 'expectedimprovementplus'
acquisition function.
rng('default') [Mdl,FitInfo,HyperparameterOptimizationResults] = fitrkernel(Z,Y,'OptimizeHyperparameters','auto',... 'HyperparameterOptimizationOptions',struct('AcquisitionFunctionName','expectedimprovementplus'))
====================================================================================================================  Iter  Eval  Objective:  Objective  BestSoFar  BestSoFar  KernelScale  Lambda  Epsilon    result  log(1+loss)  runtime  (observed)  (estim.)     ====================================================================================================================  1  Best  4.8295  2.0868  4.8295  4.8295  0.011518  6.8068e05  0.95918   2  Best  4.1488  0.38945  4.1488  4.1855  477.57  0.066115  0.091828   3  Accept  4.1521  0.37039  4.1488  4.1747  0.0080478  0.0052867  520.84   4  Accept  4.1506  0.53052  4.1488  4.1488  0.10935  0.35931  0.013372   5  Best  4.1446  0.61199  4.1446  4.1446  326.29  2.5457  0.22475   6  Accept  4.1521  0.38395  4.1446  4.1447  719.11  0.19478  881.84   7  Accept  4.1501  0.52479  4.1446  4.1461  0.052426  2.5402  0.051319   8  Accept  4.1521  1.0357  4.1446  4.1447  990.71  0.014203  702.34   9  Accept  4.1521  0.90439  4.1446  4.1465  415.85  0.054602  81.005   10  Accept  4.1454  0.83642  4.1446  4.1455  972.49  1.1601  1.8715   11  Accept  4.1495  0.28498  4.1446  4.1473  121.79  1.4077  0.061055   12  Accept  4.1521  0.4106  4.1446  4.1474  985.81  0.83297  213.45   13  Best  4.1374  0.7066  4.1374  4.1441  167.34  2.5497  4.8997   14  Accept  4.1434  0.34164  4.1374  4.1437  74.527  2.55  6.1044   15  Accept  4.1402  0.25475  4.1374  4.1407  877.17  2.5391  2.2888   16  Accept  4.1436  0.28335  4.1374  4.1412  0.0010354  0.017613  0.11811   17  Best  4.1346  0.49699  4.1346  4.1375  0.0010362  0.010401  8.9719   18  Accept  4.1521  0.25979  4.1346  4.1422  0.0010467  0.0094817  563.96   19  Accept  4.1508  0.32163  4.1346  4.1367  760.12  0.0079557  0.009087   20  Accept  4.1435  0.42598  4.1346  4.143  0.020647  0.0089063  2.3699  ====================================================================================================================  Iter  Eval  Objective:  Objective  BestSoFar  BestSoFar  KernelScale  Lambda  Epsilon    result  log(1+loss)  runtime  (observed)  (estim.)     ====================================================================================================================  21  Best  3.7172  0.48873  3.7172  3.7174  818.08  2.5529e06  2.1058   22  Accept  4.1521  0.35406  3.7172  3.7177  0.006272  2.5598e06  93.063   23  Accept  4.0567  0.57149  3.7172  3.7176  940.43  2.6941e06  0.12016   24  Best  2.8979  0.89562  2.8979  2.8979  37.141  2.5677e06  2.71   25  Accept  4.1521  0.28524  2.8979  2.898  13.817  2.5755e06  863.91   26  Best  2.795  0.65767  2.795  2.7953  20.022  2.6098e06  1.6561   27  Accept  2.8284  0.53842  2.795  2.7956  17.252  2.7719e06  0.82777   28  Best  2.7896  0.62811  2.7896  2.7898  11.432  7.621e06  2.094   29  Accept  2.821  1.007  2.7896  2.7899  8.5133  2.5872e06  2.0567   30  Accept  2.8061  0.54105  2.7896  2.7966  15.823  6.1956e06  2.0085  __________________________________________________________ Optimization completed. MaxObjectiveEvaluations of 30 reached. Total function evaluations: 30 Total elapsed time: 74.2175 seconds. Total objective function evaluation time: 17.4281 Best observed feasible point: KernelScale Lambda Epsilon ___________ _________ _______ 11.432 7.621e06 2.094 Observed objective function value = 2.7896 Estimated objective function value = 2.7966 Function evaluation time = 0.62811 Best estimated feasible point (according to models): KernelScale Lambda Epsilon ___________ __________ _______ 15.823 6.1956e06 2.0085 Estimated objective function value = 2.7966 Estimated function evaluation time = 0.62155
Mdl = RegressionKernel ResponseName: 'Y' Learner: 'svm' NumExpansionDimensions: 256 KernelScale: 15.8229 Lambda: 6.1956e06 BoxConstraint: 411.7488 Epsilon: 2.0085 Properties, Methods
FitInfo = struct with fields:
Solver: 'LBFGSfast'
LossFunction: 'epsiloninsensitive'
Lambda: 6.1956e06
BetaTolerance: 1.0000e04
GradientTolerance: 1.0000e06
ObjectiveValue: 1.3582
GradientMagnitude: 0.0051
RelativeChangeInBeta: 5.3944e05
FitTime: 0.0705
History: []
HyperparameterOptimizationResults = BayesianOptimization with properties: ObjectiveFcn: @createObjFcn/inMemoryObjFcn VariableDescriptions: [5x1 optimizableVariable] Options: [1x1 struct] MinObjective: 2.7896 XAtMinObjective: [1x3 table] MinEstimatedObjective: 2.7966 XAtMinEstimatedObjective: [1x3 table] NumObjectiveEvaluations: 30 TotalElapsedTime: 74.2175 NextPoint: [1x3 table] XTrace: [30x3 table] ObjectiveTrace: [30x1 double] ConstraintsTrace: [] UserDataTrace: {30x1 cell} ObjectiveEvaluationTimeTrace: [30x1 double] IterationTimeTrace: [30x1 double] ErrorTrace: [30x1 double] FeasibilityTrace: [30x1 logical] FeasibilityProbabilityTrace: [30x1 double] IndexOfMinimumTrace: [30x1 double] ObjectiveMinimumTrace: [30x1 double] EstimatedObjectiveMinimumTrace: [30x1 double]
For big data, the optimization procedure can take a long time. If the data set is too large to run the optimization procedure, you can try to optimize the parameters using only partial data. Use the datasample
function and specify 'Replace','false'
to sample data without replacement.
X
— Predictor dataPredictor data to which the regression model is fit, specified as an nbyp numeric matrix, where n is the number of observations and p is the number of predictor variables.
The length of Y
and the number of observations in
X
must be equal.
Data Types: single
 double
Y
— Response dataResponse data, specified as an ndimensional numeric vector. The
length of Y
and the number of observations in X
must be equal.
Data Types: single
 double
fitrkernel
removes missing observations, that is,
observations with any of these characteristics:
NaN
elements in the response
(Y
)
At least one NaN
value in a predictor observation
(row in X
)
NaN
value or 0
weight
('Weights'
)
Specify optional
commaseparated pairs of Name,Value
arguments. Name
is
the argument name and Value
is the corresponding value.
Name
must appear inside quotes. You can specify several name and value
pair arguments in any order as
Name1,Value1,...,NameN,ValueN
.
Mdl =
fitrkernel(X,Y,'Learner','leastsquares','NumExpansionDimensions',2^15,'KernelScale','auto')
implements leastsquares regression after mapping the predictor data to the
2^15
dimensional space using feature expansion with a kernel
scale parameter selected by a heuristic procedure.You cannot use any crossvalidation namevalue pair argument along with the
'OptimizeHyperparameters'
namevalue pair argument. You can modify
the crossvalidation for 'OptimizeHyperparameters'
only by using the
'HyperparameterOptimizationOptions'
namevalue pair
argument.
'BoxConstraint'
— Box constraint1
(default)  positive scalarBox
constraint, specified as the commaseparated pair consisting
of 'BoxConstraint'
and a positive scalar.
This argument is valid only when 'Learner'
is
'svm'
(default) and you do not specify a value for
the regularization term strength 'Lambda'
. You can
specify either 'BoxConstraint'
or
'Lambda'
because the box constraint
(C) and the regularization term strength
(λ) are related by C =
1/(λn), where n is the number of
observations (rows in X
).
Example: 'BoxConstraint',100
Data Types: single
 double
'Epsilon'
— Half width of epsiloninsensitive band'auto'
(default)  nonnegative scalar valueHalf the width of the epsiloninsensitive band, specified as the
commaseparated pair consisting of 'Epsilon'
and
'auto'
or a nonnegative scalar value.
For 'auto'
, the fitrkernel
function determines the value of Epsilon
as
iqr(Y)/13.49
, which is an estimate of a tenth of
the standard deviation using the interquartile range of the response
variable Y
. If iqr(Y)
is equal to
zero, then fitrkernel
sets the value of
Epsilon
to 0.1.
'Epsilon'
is valid only when
Learner
is svm
.
Example: 'Epsilon',0.3
Data Types: single
 double
'NumExpansionDimensions'
— Number of dimensions of expanded space'auto'
(default)  positive integerNumber of dimensions of the expanded space, specified as the
commaseparated pair consisting of
'NumExpansionDimensions'
and
'auto'
or a positive integer. For
'auto'
, the fitrkernel
function selects the number of dimensions using
2.^ceil(min(log2(p)+5,15))
, where
p
is the number of predictors.
Example: 'NumExpansionDimensions',2^15
Data Types: char
 string
 single
 double
'KernelScale'
— Kernel scale parameter1
(default)  'auto'
 positive scalarKernel scale parameter, specified as the commaseparated pair
consisting of 'KernelScale'
and
'auto'
or a positive scalar. MATLAB^{®} obtains the random basis for random feature expansion by
using the kernel scale parameter. For details, see Random Feature Expansion.
If you specify 'auto'
, then MATLAB selects an appropriate kernel scale parameter using a
heuristic procedure. This heuristic procedure uses subsampling, so
estimates can vary from one call to another. Therefore, to reproduce
results, set a random number seed by using rng
before
training.
Example: 'KernelScale','auto'
Data Types: char
 string
 single
 double
'Lambda'
— Regularization term strength'auto'
(default)  nonnegative scalarRegularization term strength, specified as the commaseparated pair
consisting of 'Lambda'
and 'auto'
or a nonnegative scalar.
For 'auto'
, the value of
'Lambda'
is 1/n, where
n is the number of observations (rows in
X
).
You can specify either 'BoxConstraint'
or
'Lambda'
because the box constraint
(C) and the regularization term strength
(λ) are related by C =
1/(λn).
Example: 'Lambda',0.01
Data Types: char
 string
 single
 double
'Learner'
— Linear regression model type'svm'
(default)  'leastsquares'
Linear regression model type, specified as the commaseparated pair
consisting of 'Learner'
and 'svm'
or 'leastsquares'
.
In the following table, $$f\left(x\right)=T(x)\beta +b.$$
x is an observation (row vector) from p predictor variables.
$$T(\xb7)$$ is a transformation of an observation (row vector) for feature expansion. T(x) maps x in $${\mathbb{R}}^{p}$$ to a highdimensional space ($${\mathbb{R}}^{m}$$).
β is a vector of m coefficients.
b is the scalar bias.
Value  Algorithm  Response range  Loss function 

'leastsquares'  Linear regression via ordinary least squares  y ∊ (∞,∞)  Mean squared error (MSE): $$\ell \left[y,f\left(x\right)\right]=\frac{1}{2}{\left[yf\left(x\right)\right]}^{2}$$ 
'svm'  Support vector machine regression  Same as 'leastsquares'  Epsiloninsensitive: $$\ell \left[y,f\left(x\right)\right]=\mathrm{max}\left[0,\leftyf\left(x\right)\right\epsilon \right]$$ 
Example: 'Learner','leastsquares'
'Verbose'
— Verbosity level0
(default)  1
Verbosity level, specified as the commaseparated pair consisting of
'Verbose'
and either 0
or
1
. Verbose
controls the amount
of diagnostic information fitrkernel
displays at
the command line.
Value  Description 

0  fitrkernel does not display
diagnostic information. 
1  fitrkernel displays and stores
the value of the objective function, gradient magnitude,
and other diagnostic information.
FitInfo.History contains the
diagnostic information. 
Example: 'Verbose',1
Data Types: single
 double
'BlockSize'
— Maximum amount of allocated memory4e^3
(4GB) (default)  positive scalarMaximum amount of allocated memory (in megabytes), specified as the
commaseparated pair consisting of 'BlockSize'
and a
positive scalar.
If fitrkernel
requires more memory than the value
of BlockSize
to hold the transformed predictor data,
then MATLAB uses a blockwise strategy. For details about the
blockwise strategy, see Algorithms.
Example: 'BlockSize',1e4
Data Types: single
 double
'RandomStream'
— Random number streamRandom number stream for reproducibility of data transformation,
specified as the commaseparated pair consisting of
'RandomStream'
and a random stream object. For
details, see Random Feature Expansion.
Use 'RandomStream'
to reproduce the random basis
functions that fitrkernel
uses to transform the data
in X
to a highdimensional space. For details, see
Managing the Global Stream (MATLAB) and Creating and Controlling a Random Number Stream (MATLAB).
Example: 'RandomStream',RandStream('mlfg6331_64')
'ResponseTransform'
— Response transformation'none'
(default)  function handleResponse transformation, specified as the commaseparated pair consisting of
'ResponseTransform'
and either 'none'
or a
function handle. The default is 'none'
, which means
@(y)y
, or no transformation. For a MATLAB function or a function you define, use its function handle. The function
handle must accept a vector (the original response values) and return a vector of the
same size (the transformed response values).
Example: Suppose you create a function handle that applies an exponential
transformation to an input vector by using myfunction = @(y)exp(y)
.
Then, you can specify the response transformation as
'ResponseTransform',myfunction
.
Data Types: char
 string
 function_handle
'Weights'
— Observation weightsones(n,1)/n
(default)  numeric vector of positive valuesObservation weights, specified as the commaseparated pair consisting
of 'Weights'
and a numeric vector of positive values.
fitrkernel
weighs the observations in
X
with the corresponding values in
Weights
. The size of Weights
must equal n, the number of observations (rows in
X
).
fitrkernel
normalizes Weights
to sum to 1.
Data Types: double
 single
'CrossVal'
— Crossvalidation flag'off'
(default)  'on'
Crossvalidation flag, specified as the commaseparated pair
consisting of 'Crossval'
and 'on'
or 'off'
.
If you specify 'on'
, then the software implements
10fold crossvalidation.
You can override this crossvalidation setting using the
CVPartition
, Holdout
,
KFold
, or Leaveout
namevalue pair argument. You can use only one crossvalidation
namevalue pair argument at a time to create a crossvalidated
model.
Example: 'Crossval','on'
'CVPartition'
— Crossvalidation partition[]
(default)  cvpartition
partition objectCrossvalidation partition, specified as the commaseparated pair consisting of
'CVPartition'
and a cvpartition
partition
object created by cvpartition
. The partition object
specifies the type of crossvalidation and the indexing for the training and validation
sets.
To create a crossvalidated model, you can use one of these four namevalue pair arguments
only: CVPartition
, Holdout
,
KFold
, or Leaveout
.
Example: Suppose you create a random partition for 5fold crossvalidation on 500
observations by using cvp = cvpartition(500,'KFold',5)
. Then, you can
specify the crossvalidated model by using
'CVPartition',cvp
.
'Holdout'
— Fraction of data for holdout validationFraction of the data used for holdout validation, specified as the commaseparated pair
consisting of 'Holdout'
and a scalar value in the range (0,1). If you
specify 'Holdout',p
, then the software completes these steps:
Randomly select and reserve p*100
% of the data as
validation data, and train the model using the rest of the data.
Store the compact, trained model in the Trained
property of the crossvalidated model.
To create a crossvalidated model, you can use one of these
four namevalue pair arguments only: CVPartition
, Holdout
, KFold
,
or Leaveout
.
Example: 'Holdout',0.1
Data Types: double
 single
'KFold'
— Number of folds10
(default)  positive integer value greater than 1Number of folds to use in a crossvalidated model, specified as the commaseparated pair
consisting of 'KFold'
and a positive integer value greater than 1. If
you specify 'KFold',k
, then the software completes these steps:
Randomly partition the data into k
sets.
For each set, reserve the set as validation data, and train the model
using the other k
– 1 sets.
Store the k
compact, trained models in the cells of a
k
by1 cell vector in the Trained
property of the crossvalidated model.
To create a crossvalidated model, you can use one of these
four namevalue pair arguments only: CVPartition
, Holdout
, KFold
,
or Leaveout
.
Example: 'KFold',5
Data Types: single
 double
'Leaveout'
— Leaveoneout crossvalidation flag'off'
(default)  'on'
Leaveoneout crossvalidation flag, specified as the commaseparated pair consisting of
'Leaveout'
and 'on'
or
'off'
. If you specify 'Leaveout','on'
, then,
for each of the n observations (where n is the
number of observations excluding missing observations), the software completes these
steps:
Reserve the observation as validation data, and train the model using the other n – 1 observations.
Store the n compact, trained models in the cells of an
nby1 cell vector in the Trained
property of the crossvalidated model.
To create a crossvalidated model, you can use one of these
four namevalue pair arguments only: CVPartition
, Holdout
, KFold
,
or Leaveout
.
Example: 'Leaveout','on'
'BetaTolerance'
— Relative tolerance on linear coefficients and bias term1e5
(default)  nonnegative scalarRelative tolerance on the linear coefficients and the bias term (intercept), specified as the commaseparated pair consisting of 'BetaTolerance'
and a nonnegative scalar.
Let $${B}_{t}=\left[{\beta}_{t}{}^{\prime}\text{\hspace{0.17em}}\text{\hspace{0.17em}}{b}_{t}\right]$$, that is, the vector of the coefficients and the bias term at optimization iteration t. If $${\Vert \frac{{B}_{t}{B}_{t1}}{{B}_{t}}\Vert}_{2}<\text{BetaTolerance}$$, then optimization terminates.
If you also specify GradientTolerance
, then optimization terminates when the software satisfies either stopping criterion.
Example: 'BetaTolerance',1e6
Data Types: single
 double
'GradientTolerance'
— Absolute gradient tolerance1e6
(default)  nonnegative scalarAbsolute gradient tolerance, specified as the commaseparated pair consisting of 'GradientTolerance'
and a nonnegative scalar.
Let $$\nabla {\mathcal{L}}_{t}$$ be the gradient vector of the objective function with respect to the coefficients and bias term at optimization iteration t. If $${\Vert \nabla {\mathcal{L}}_{t}\Vert}_{\infty}=\mathrm{max}\left\nabla {\mathcal{L}}_{t}\right<\text{GradientTolerance}$$, then optimization terminates.
If you also specify BetaTolerance
, then optimization terminates when the
software satisfies either stopping criterion.
Example: 'GradientTolerance',1e5
Data Types: single
 double
'HessianHistorySize'
— Size of history buffer for Hessian approximation15
(default)  positive integerSize of the history buffer for Hessian approximation, specified as the
commaseparated pair consisting of
'HessianHistorySize'
and a positive integer. At
each iteration, fitrkernel
composes the Hessian by
using statistics from the latest HessianHistorySize
iterations.
Example: 'HessianHistorySize',10
Data Types: single
 double
'IterationLimit'
— Maximum number of optimization iterationsMaximum number of optimization iterations, specified as the
commaseparated pair consisting of 'IterationLimit'
and a positive integer.
The default value is 1000 if the transformed data fits in memory, as
specified by BlockSize
. Otherwise, the default
value is 100.
Example: 'IterationLimit',500
Data Types: single
 double
'OptimizeHyperparameters'
— Parameters to optimize'none'
(default)  'auto'
 'all'
 string array or cell array of eligible parameter names  vector of optimizableVariable
objectsParameters to optimize, specified as the commaseparated pair
consisting of 'OptimizeHyperparameters'
and one of
these values:
'none'
— Do not optimize.
'auto'
— Use
{'KernelScale','Lambda','Epsilon'}
.
'all'
— Optimize all eligible
parameters.
Cell array of eligible parameter names.
Vector of optimizableVariable
objects,
typically the output of hyperparameters
.
The optimization attempts to minimize the crossvalidation loss
(error) for fitrkernel
by varying the parameters.
To control the crossvalidation type and other aspects of the
optimization, use the
HyperparameterOptimizationOptions
namevalue
pair argument.
'OptimizeHyperparameters'
values override any values you set using
other namevalue pair arguments. For example, setting
'OptimizeHyperparameters'
to 'auto'
causes the
'auto'
values to apply.
The eligible parameters for fitrkernel
are:
Epsilon
—
fitrkernel
searches among positive
values, by default logscaled in the range
[1e3,1e2]*iqr(Y)/1.349
.
KernelScale
—
fitrkernel
searches among positive
values, by default logscaled in the range
[1e3,1e3]
.
Lambda
—
fitrkernel
searches among positive
values, by default logscaled in the range
[1e3,1e3]/n
, where n
is the number of observations.
Learner
—
fitrkernel
searches among
'svm'
and
'leastsquares'
.
NumExpansionDimensions
—
fitrkernel
searches among positive
integers, by default logscaled in the range
[100,10000]
.
Set nondefault parameters by passing a vector of
optimizableVariable
objects that have nondefault
values. For example:
load carsmall params = hyperparameters('fitrkernel',[Horsepower,Weight],MPG); params(2).Range = [1e4,1e6];
Pass params
as the value of
'OptimizeHyperparameters'
.
By default, iterative display appears at the command line, and
plots appear according to the number of hyperparameters in the optimization. For the
optimization and plots, the objective function is log(1 + crossvalidation loss) for regression and the misclassification rate for classification. To control
the iterative display, set the Verbose
field of the
'HyperparameterOptimizationOptions'
namevalue pair argument. To
control the plots, set the ShowPlots
field of the
'HyperparameterOptimizationOptions'
namevalue pair argument.
For an example, see Optimize Kernel Regression.
Example: 'OptimizeHyperparameters','auto'
'HyperparameterOptimizationOptions'
— Options for optimizationOptions for optimization, specified as the commaseparated pair consisting of
'HyperparameterOptimizationOptions'
and a structure. This
argument modifies the effect of the OptimizeHyperparameters
namevalue pair argument. All fields in the structure are optional.
Field Name  Values  Default 

Optimizer 
 'bayesopt' 
AcquisitionFunctionName 
Acquisition functions whose names include
 'expectedimprovementpersecondplus' 
MaxObjectiveEvaluations  Maximum number of objective function evaluations.  30 for 'bayesopt' or 'randomsearch' , and the entire grid for 'gridsearch' 
MaxTime  Time limit, specified as a positive real. The time limit is in seconds, as measured by  Inf 
NumGridDivisions  For 'gridsearch' , the number of values in each dimension. The value can be
a vector of positive integers giving the number of
values for each dimension, or a scalar that
applies to all dimensions. This field is ignored
for categorical variables.  10 
ShowPlots  Logical value indicating whether to show plots. If true , this field plots
the best objective function value against the
iteration number. If there are one or two
optimization parameters, and if
Optimizer is
'bayesopt' , then
ShowPlots also plots a model of
the objective function against the
parameters.  true 
SaveIntermediateResults  Logical value indicating whether to save results when Optimizer is
'bayesopt' . If
true , this field overwrites a
workspace variable named
'BayesoptResults' at each
iteration. The variable is a BayesianOptimization object.  false 
Verbose  Display to the command line.
For details, see the
 1 
UseParallel  Logical value indicating whether to run Bayesian optimization in parallel, which requires Parallel Computing Toolbox™. Due to the nonreproducibility of parallel timing, parallel Bayesian optimization does not necessarily yield reproducible results. For details, see Parallel Bayesian Optimization.  false 
Repartition  Logical value indicating whether to repartition the crossvalidation at every iteration. If
 false 
Use no more than one of the following three field names.  
CVPartition  A cvpartition object, as created by cvpartition .  'Kfold',5 if you do not specify any crossvalidation
field 
Holdout  A scalar in the range (0,1) representing the holdout fraction.  
Kfold  An integer greater than 1. 
Example: 'HyperparameterOptimizationOptions',struct('MaxObjectiveEvaluations',60)
Data Types: struct
Mdl
— Trained kernel regression modelRegressionKernel
model object  RegressionPartitionedKernel
crossvalidated model
objectTrained kernel regression model, returned as a RegressionKernel
model object or RegressionPartitionedKernel
crossvalidated model
object.
If you set any of the namevalue pair arguments
CrossVal
, CVPartition
,
Holdout
, KFold
, or
Leaveout
, then Mdl
is a
RegressionPartitionedKernel
crossvalidated model.
Otherwise, Mdl
is a RegressionKernel
model.
To reference properties of Mdl
, use dot notation. For
example, enter Mdl.NumExpansionDimensions
in the Command
Window to display the number of dimensions of the expanded space.
Unlike other regression models, and for economical memory usage, a
RegressionKernel
model object does not store the
training data or training process details (for example, convergence
history).
FitInfo
— Optimization detailsOptimization details, returned as a structure array including fields described in this table. The fields contain final values or namevalue pair argument specifications.
Field  Description 

Solver 
Objective function minimization technique:

LossFunction  Loss function. Either mean squared error (MSE) or
epsiloninsensitive, depending on the type of linear
regression model. See Learner . 
Lambda  Regularization term strength. See
Lambda . 
BetaTolerance  Relative tolerance on the linear coefficients and the
bias term. See BetaTolerance . 
GradientTolerance  Absolute gradient tolerance. See
GradientTolerance . 
ObjectiveValue  Value of the objective function when optimization terminates. The regression loss plus the regularization term compose the objective function. 
GradientMagnitude  Infinite norm of the gradient vector of the objective
function when optimization terminates. See
GradientTolerance . 
RelativeChangeInBeta  Relative changes in the linear coefficients and the bias
term when optimization terminates. See
BetaTolerance . 
FitTime  Elapsed, wallclock time (in seconds) required to fit the model to the data. 
History  History of optimization information. This field also
includes the optimization information from training
Mdl . This field is empty
([] ) if you specify
'Verbose',0 . For details, see
Verbose and Algorithms. 
To access fields, use dot notation. For example, to access the vector of
objective function values for each iteration, enter
FitInfo.ObjectiveValue
in the Command Window.
Examine the information provided by FitInfo
to assess
whether convergence is satisfactory.
HyperparameterOptimizationResults
— Crossvalidation optimization of hyperparametersBayesianOptimization
object  table of hyperparameters and associated valuesCrossvalidation optimization of hyperparameters, returned as a BayesianOptimization
object or a table of hyperparameters and associated
values. The output is nonempty when the value of
'OptimizeHyperparameters'
is not 'none'
. The
output value depends on the Optimizer
field value of the
'HyperparameterOptimizationOptions'
namevalue pair
argument:
Value of Optimizer Field  Value of HyperparameterOptimizationResults 

'bayesopt' (default)  Object of class BayesianOptimization 
'gridsearch' or 'randomsearch'  Table of hyperparameters used, observed objective function values (crossvalidation loss), and rank of observations from lowest (best) to highest (worst) 
fitrkernel
does not accept initial conditions for the
linear coefficients beta (β) and bias term
(b) used to determine the decision function, $$f\left(x\right)=T(x)\beta +b.$$
fitrkernel
does not support standardization and
crossvalidation options.
fitrkernel
does not accept table inputs.
Random feature expansion, such as Random Kitchen Sinks[1] and Fastfood[2], is a scheme to approximate Gaussian kernels of the kernel regression algorithm for big data in a computationally efficient way. Random feature expansion is more practical for big data applications that have large training sets but can also be applied to smaller data sets that fit in memory.
The kernel regression algorithm searches for an optimal function that deviates from each response data point (y_{i}) by values no greater than the epsilon margin (ε) after mapping the predictor data into a highdimensional space.
Some regression problems cannot be described adequately using a linear model. In such cases, obtain a nonlinear regression model by replacing the dot product x_{1}x_{2}′ with a nonlinear kernel function $$G({x}_{1},{x}_{2})=\langle \phi ({x}_{1}),\phi ({x}_{2})\rangle $$, where x_{i} is the ith observation (row vector) and φ(x_{i}) is a transformation that maps x_{i} to a highdimensional space (called the “kernel trick”). However, evaluating G(x_{1},x_{2}) , the Gram matrix, for each pair of observations is computationally expensive for a large data set (large n).
The random feature expansion scheme finds a random transformation so that its dot product approximates the Gaussian kernel. That is,
$$G({x}_{1},{x}_{2})=\langle \phi ({x}_{1}),\phi ({x}_{2})\rangle \approx T({x}_{1})T({x}_{2})\text{'},$$
where T(x) maps x in $${\mathbb{R}}^{p}$$ to a highdimensional space ($${\mathbb{R}}^{m}$$). The Random Kitchen Sink[1] scheme uses the random transformation
$$T(x)={m}^{1/2}\mathrm{exp}\left(iZx\text{'}\right)\text{'},$$
where $$Z\in {\mathbb{R}}^{m\times p}$$ is a sample drawn from $$N\left(0,{\sigma}^{2}\right)$$ and σ^{2} is a kernel scale. This scheme requires O(mp) computation and storage. The Fastfood[2] scheme introduces
another random basis V instead of Z using Hadamard
matrices combined with Gaussian scaling matrices. This random basis reduces computation cost
to O(mlog
p) and reduces storage to O(m).
You can specify values for m and σ^{2}, using the NumExpansionDimensions
and
KernelScale
namevalue pair arguments of
fitrkernel
, respectively.
The fitrkernel
function uses the Fastfood scheme for random feature
expansion and uses linear regression to train a Gaussian kernel regression model. Unlike
solvers in the fitrsvm
function, which require computation of the
nbyn Gram matrix, the solver in
fitrkernel
only needs to form a matrix of size
nbym, with m typically much
less than n for big data.
A box constraint is a parameter that controls the maximum penalty imposed on observations that lie outside the epsilon margin (ε), and helps to prevent overfitting (regularization). Increasing the box constraint can lead to longer training times.
The box constraint (C) and the regularization term strength (λ) are related by C = 1/(λn), where n is the number of observations.
fitrkernel
minimizes the regularized objective function using a Limitedmemory BroydenFletcherGoldfarbShanno (LBFGS) solver with ridge (L_{2}) regularization. To find the type of LBFGS solver used for training, type FitInfo.Solver
in the Command Window.
'LBFGSfast'
— LBFGS solver.
'LBFGSblockwise'
— LBFGS solver with a blockwise strategy. If fitrkernel
requires more memory than the value of BlockSize
to hold the transformed predictor data, then it uses a blockwise strategy.
'LBFGStall'
— LBFGS solver with a blockwise strategy for tall arrays.
When fitrkernel
uses a blockwise strategy, fitrkernel
implements LBFGS by distributing the calculation of the loss and gradient among different parts of the data at each iteration. Also, fitrkernel
refines the initial estimates of the linear coefficients and the bias term by fitting the model locally to parts of the data and combining the coefficients by averaging. If you specify 'Verbose',1
, then fitrkernel
displays diagnostic information for each data pass and stores the information in the History
field of FitInfo
.
When fitrkernel
does not use a blockwise strategy, the initial estimates are zeros. If you specify 'Verbose',1
, then fitrkernel
displays diagnostic information for each iteration and stores the information in the History
field of FitInfo
.
[1] Rahimi, A., and B. Recht. “Random Features for LargeScale Kernel Machines.” Advances in Neural Information Processing Systems. Vol. 20, 2008, pp. 1177–1184.
[2] Le, Q., T. Sarlós, and A. Smola. “Fastfood — Approximating Kernel Expansions in Loglinear Time.” Proceedings of the 30th International Conference on Machine Learning. Vol. 28, No. 3, 2013, pp. 244–252.
[3] Huang, P. S., H. Avron, T. N. Sainath, V. Sindhwani, and B. Ramabhadran. “Kernel methods match Deep Neural Networks on TIMIT.” 2014 IEEE International Conference on Acoustics, Speech and Signal Processing. 2014, pp. 205–209.
Usage notes and limitations:
Some namevalue pair arguments have different defaults compared to the default values
for the inmemory fitrkernel
function. Supported namevalue pair
arguments, and any differences, are:
'BoxConstraint'
'Epsilon'
'NumExpansionDimensions'
'KernelScale'
'Lambda'
'Learner'
'Verbose'
— Default value is
1
.
'BlockSize'
'RandomStream'
'ResponseTransform'
'Weights'
— Value must be a tall array.
'BetaTolerance'
— Default value is relaxed to
1e–3
.
'GradientTolerance'
— Default value is relaxed to
1e–5
.
'HessianHistorySize'
'IterationLimit'
— Default value is relaxed to
20
.
'OptimizeHyperparameters'
'HyperparameterOptimizationOptions'
— For
crossvalidation, tall optimization supports only 'Holdout'
validation. For example, you can specify
fitrkernel(X,Y,'OptimizeHyperparameters','auto','HyperparameterOptimizationOptions',struct('Holdout',0.2))
.
If 'KernelScale'
is 'auto'
, then
fitrkernel
uses the random stream controlled by tallrng
for subsampling. For reproducibility, you must set a random number seed for both the
global stream and the random stream controlled by tallrng
.
If 'Lambda'
is 'auto'
, then
fitrkernel
might take an extra pass through the data to
calculate the number of observations in X
.
fitrkernel
uses a blockwise strategy. For details, see Algorithms.
For more information, see Tall Arrays (MATLAB).
To run in parallel, set the 'UseParallel'
option to true
.
To perform parallel hyperparameter optimization, use the 'HyperparameterOptions', struct('UseParallel',true)
namevalue pair argument in the call to this function.
For more information on parallel hyperparameter optimization, see Parallel Bayesian Optimization.
For more general information about parallel computing, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).
RegressionKernel
 RegressionPartitionedKernel
 bayesopt
 bestPoint
 fitrlinear
 fitrsvm
 loss
 predict
 resume
A modified version of this example exists on your system. Do you want to open this version instead?
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
Select web siteYou can also select a web site from the following list:
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.