Documentation

This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

fitcknn

Fit k-nearest neighbor classifier

Syntax

Mdl = fitcknn(Tbl,ResponseVarName)
Mdl = fitcknn(Tbl,formula)
Mdl = fitcknn(Tbl,Y)
Mdl = fitcknn(X,Y)
Mdl = fitcknn(___,Name,Value)

Description

Mdl = fitcknn(Tbl,ResponseVarName) returns a k-nearest neighbor classification model based on the input variables (also known as predictors, features, or attributes) in the table Tbl and output (response) Tbl.ResponseVarName.
Mdl = fitcknn(Tbl,formula) returns a k-nearest neighbor classification model based on the input variables in the table Tbl. formula is an explanatory model of the response and a subset of predictor variables in Tbl.
Mdl = fitcknn(Tbl,Y) returns a k-nearest neighbor classification model based on the predictor variables in the table Tbl and response array Y.

example

Mdl = fitcknn(X,Y) returns a k-nearest neighbor classification model based on the predictor data X and response Y.

example

Mdl = fitcknn(___,Name,Value) fits a model with additional options specified by one or more name-value pair arguments, using any of the previous syntaxes. For example, you can specify the tie-breaking algorithm, distance metric, or observation weights.

Examples

collapse all

Construct a k-nearest neighbor classifier for Fisher's iris data, where k, the number of nearest neighbors in the predictors, is 5.

load fisheriris X = meas; Y = species; 

X is a numeric matrix that contains four petal measurements for 150 irises. Y is a cell array of character vectors that contains the corresponding iris species.

Train a 5-nearest neighbors classifier. It is good practice to standardize noncategorical predictor data.

Mdl = fitcknn(X,Y,'NumNeighbors',5,'Standardize',1) 
Mdl = ClassificationKNN ResponseName: 'Y' CategoricalPredictors: [] ClassNames: {'setosa' 'versicolor' 'virginica'} ScoreTransform: 'none' NumObservations: 150 Distance: 'euclidean' NumNeighbors: 5 

Mdl is a trained ClassificationKNN classifier, and some of its properties display in the Command Window.

To access the properties of Mdl, use dot notation.

Mdl.ClassNames Mdl.Prior 
ans = 3×1 cell array 'setosa' 'versicolor' 'virginica' ans = 0.3333 0.3333 0.3333 

Mdl.Prior contains the class prior probabilities, which are settable using the name-value pair argument 'Prior' in fitcknn. The order of the class prior probabilities corresponds to the order of the classes in Mdl.ClassNames. By default, the prior probabilities are the respective relative frequencies of the classes in the data.

You can also reset the prior probabilities after training. For example, set the prior probabilities to 0.5, 0.2, and 0.3 respectively.

Mdl.Prior = [0.5 0.2 0.3]; 

You can pass Mdl to, for example, ClassificationKNN.predict to label new measurements, or ClassificationKNN.crossval to cross validate the classifier.

load fisheriris X = meas; Y = species; 

X is a numeric matrix that contains four petal measurements for 150 irises. Y is a cell array of character vectors that contains the corresponding iris species.

Train a 3-nearest neighbors classifier using the Minkowski metric. To use the Minkowski metric, you must use an exhaustive searcher. It is good practice to standardize noncategorical predictor data.

Mdl = fitcknn(X,Y,'NumNeighbors',3,... 'NSMethod','exhaustive','Distance','minkowski',... 'Standardize',1); 

Mdl is a ClassificationKNN classifier.

You can examine the properties of Mdl by double-clicking Mdl in the Workspace window. This opens the Variable Editor.

Train a k-nearest neighbor classifier using the chi-square distance.

load fisheriris X = meas; % Predictors Y = species; % Response 

The chi-square distance between j-dimensional points x and z is

 

where is a weight associated with dimension j.

Specify the chi-square distance function. The distance function must:

• Take one row of X, e.g., x, and the matrix Z.

• Compare x to each row of Z.

• Return a vector D of length , where is the number of rows of Z. Each element of D is the distance between the observation corresponding to x and the observations corresponding to each row of Z.

chiSqrDist = @(x,Z,wt)sqrt((bsxfun(@minus,x,Z).^2)*wt); 

This example uses arbitrtary weights for illustration.

Train a 3-nearest neighbor classifier. It is good practoce to standardize noncategorical predictor data.

k = 3; w = [0.3; 0.3; 0.2; 0.2]; KNNMdl = fitcknn(X,Y,'Distance',@(x,Z)chiSqrDist(x,Z,w),... 'NumNeighbors',k,'Standardize',1); 

KNNMdl is a ClassificationKNN classifier.

Cross validate the KNN classifier using the default 10-fold cross validation. Examine the classification error.

rng(1); % For reproducibility CVKNNMdl = crossval(KNNMdl); classError = kfoldLoss(CVKNNMdl) 
classError = 0.0600 

CVKNNMdl is a ClassificationPartitionedModel classifier. The 10-fold classification error is 4%.

Compare the classifier with one that uses a different weighting scheme.

w2 = [0.2; 0.2; 0.3; 0.3]; CVKNNMdl2 = fitcknn(X,Y,'Distance',@(x,Z)chiSqrDist(x,Z,w2),... 'NumNeighbors',k,'KFold',10,'Standardize',1); classError2 = kfoldLoss(CVKNNMdl2) 
classError2 = 0.0400 

The second weighting scheme yields a classifier that has better out-of-sample performance.

This example shows how to optimize hyperparameters automatically using fitcknn. The example uses the Fisher iris data.

load fisheriris X = meas; Y = species; 

Find hyperparameters that minimize five-fold cross-validation loss by using automatic hyperparameter optimization.

For reproducibility, set the random seed and use the 'expected-improvement-plus' acquisition function.

rng(1) Mdl = fitcknn(X,Y,'OptimizeHyperparameters','auto',... 'HyperparameterOptimizationOptions',... struct('AcquisitionFunctionName','expected-improvement-plus')) 
|=================================================================================================| | Iter | Eval | Objective | Objective | BestSoFar | BestSoFar | NumNeighbors | Distance | | | result | | runtime | (observed) | (estim.) | | | |=================================================================================================| | 1 | Best | 0.08 | 0.80619 | 0.08 | 0.08 | 2 | seuclidean | | 2 | Best | 0.046667 | 0.31898 | 0.046667 | 0.04886 | 15 | seuclidean | | 3 | Accept | 0.33333 | 0.24066 | 0.046667 | 0.06353 | 3 | hamming | | 4 | Accept | 0.26 | 0.25105 | 0.046667 | 0.070286 | 19 | hamming | | 5 | Accept | 0.12667 | 0.21072 | 0.046667 | 0.04671 | 75 | seuclidean | | 6 | Accept | 0.046667 | 0.19513 | 0.046667 | 0.046614 | 7 | seuclidean | | 7 | Accept | 0.33333 | 0.25406 | 0.046667 | 0.046592 | 3 | spearman | | 8 | Best | 0.033333 | 0.32895 | 0.033333 | 0.033352 | 4 | minkowski | | 9 | Accept | 0.073333 | 0.17142 | 0.033333 | 0.033352 | 44 | minkowski | | 10 | Accept | 0.046667 | 0.14346 | 0.033333 | 0.033353 | 1 | minkowski | | 11 | Accept | 0.08 | 0.23016 | 0.033333 | 0.033353 | 4 | mahalanobis | | 12 | Accept | 0.25333 | 0.19546 | 0.033333 | 0.033347 | 75 | mahalanobis | | 13 | Accept | 0.086667 | 0.15695 | 0.033333 | 0.033346 | 1 | mahalanobis | | 14 | Best | 0.026667 | 0.16592 | 0.026667 | 0.026681 | 8 | chebychev | | 15 | Accept | 0.12667 | 0.15321 | 0.026667 | 0.02669 | 75 | chebychev | | 16 | Accept | 0.033333 | 0.16569 | 0.026667 | 0.026692 | 1 | chebychev | | 17 | Accept | 0.033333 | 0.16665 | 0.026667 | 0.02676 | 3 | chebychev | | 18 | Accept | 0.053333 | 0.14517 | 0.026667 | 0.026751 | 1 | cityblock | | 19 | Accept | 0.04 | 0.16216 | 0.026667 | 0.026753 | 22 | cityblock | | 20 | Accept | 0.046667 | 0.15667 | 0.026667 | 0.026762 | 5 | cityblock | |=================================================================================================| | Iter | Eval | Objective | Objective | BestSoFar | BestSoFar | NumNeighbors | Distance | | | result | | runtime | (observed) | (estim.) | | | |=================================================================================================| | 21 | Accept | 0.073333 | 0.14716 | 0.026667 | 0.026755 | 1 | correlation | | 22 | Accept | 0.04 | 0.15391 | 0.026667 | 0.026754 | 60 | correlation | | 23 | Accept | 0.04 | 0.12866 | 0.026667 | 0.026763 | 11 | correlation | | 24 | Best | 0.02 | 0.14244 | 0.02 | 0.02001 | 23 | cosine | | 25 | Accept | 0.04 | 0.1393 | 0.02 | 0.020008 | 2 | cosine | | 26 | Accept | 0.04 | 0.20342 | 0.02 | 0.020038 | 75 | cosine | | 27 | Accept | 0.12667 | 0.17599 | 0.02 | 0.020016 | 75 | euclidean | | 28 | Accept | 0.21333 | 0.19042 | 0.02 | 0.020061 | 1 | jaccard | | 29 | Accept | 0.026667 | 0.11836 | 0.02 | 0.020066 | 9 | cosine | | 30 | Accept | 0.046667 | 0.1692 | 0.02 | 0.020064 | 1 | euclidean | __________________________________________________________ Optimization completed. MaxObjectiveEvaluations of 30 reached. Total function evaluations: 30 Total elapsed time: 73.1383 seconds. Total objective function evaluation time: 6.1875 Best observed feasible point: NumNeighbors Distance ____________ ________ 23 cosine Observed objective function value = 0.02 Estimated objective function value = 0.020064 Function evaluation time = 0.14244 Best estimated feasible point (according to models): NumNeighbors Distance ____________ ________ 23 cosine Estimated objective function value = 0.020064 Estimated function evaluation time = 0.16357 Mdl = ClassificationKNN ResponseName: 'Y' CategoricalPredictors: [] ClassNames: {'setosa' 'versicolor' 'virginica'} ScoreTransform: 'none' NumObservations: 150 HyperparameterOptimizationResults: [1×1 BayesianOptimization] Distance: 'cosine' NumNeighbors: 23 

Input Arguments

collapse all

Sample data used to train the model, specified as a table. Each row of Tbl corresponds to one observation, and each column corresponds to one predictor variable. Optionally, Tbl can contain one additional column for the response variable. Multi-column variables and cell arrays other than cell arrays of character vectors are not allowed.

If Tbl contains the response variable, and you want to use all remaining variables in Tbl as predictors, then specify the response variable using ResponseVarName.

If Tbl contains the response variable, and you want to use only a subset of the remaining variables in Tbl as predictors, then specify a formula using formula.

If Tbl does not contain the response variable, then specify a response variable using Y. The length of response variable and the number of rows of Tbl must be equal.

Data Types: table

Response variable name, specified as the name of a variable in Tbl.

You must specify ResponseVarName as a character vector. For example, if the response variable Y is stored as Tbl.Y, then specify it as 'Y'. Otherwise, the software treats all columns of Tbl, including Y, as predictors when training the model.

The response variable must be a categorical or character array, logical or numeric vector, or cell array of character vectors. If Y is a character array, then each element must correspond to one row of the array.

It is good practice to specify the order of the classes using the ClassNames name-value pair argument.

Data Types: char

Explanatory model of the response and a subset of the predictor variables, specified as a character vector in the form of 'Y~X1+X2+X3'. In this form, Y represents the response variable, and X1, X2, and X3 represent the predictor variables. The variables must be variable names in Tbl (Tbl.Properties.VariableNames).

To specify a subset of variables in Tbl as predictors for training the model, use a formula. If you specify a formula, then the software does not use any variables in Tbl that do not appear in formula.

Data Types: char

Class labels, specified as a categorical or character array, logical or numeric vector, or cell array of character vectors. Each row of Y represents the classification of the corresponding row of X.

The software considers NaN, '' (empty character vector), and <undefined> values in Y to be missing values. Consequently, the software does not train using observations with a missing response.

Data Types: single | double | logical | char | cell

Predictor data, specified as numeric matrix.

Each row corresponds to one observation (also known as an instance or example), and each column corresponds to one predictor variable (also known as a feature).

The length of Y and the number of rows of X must be equal.

To specify the names of the predictors in the order of their appearance in X, use the PredictorNames name-value pair argument.

Data Types: double | single

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'NumNeighbors',3,'NSMethod','exhaustive','Distance','minkowski' specifies a classifier for three-nearest neighbors using the nearest neighbor search method and the Minkowski metric.
 Note:   You cannot use any cross-validation name-value pair along with OptimizeHyperparameters. You can modify the cross-validation for OptimizeHyperparameters only by using the HyperparameterOptimizationOptions name-value pair.

Model Parameters

collapse all

Tie-breaking algorithm used by the predict method if multiple classes have the same smallest cost, specified as the comma-separated pair consisting of 'BreakTies' and one of the following:

• 'smallest' — Use the smallest index among tied groups.

• 'nearest' — Use the class with the nearest neighbor among tied groups.

• 'random' — Use a random tiebreaker among tied groups.

By default, ties occur when multiple classes have the same number of nearest points among the K nearest neighbors.

Example: 'BreakTies','nearest'

Maximum number of data points in the leaf node of the kd-tree, specified as the comma-separated pair consisting of 'BucketSize' and a positive integer value. This argument is meaningful only when NSMethod is 'kdtree'.

Example: 'BucketSize',40

Data Types: single | double

Categorical predictor flag, specified as the comma-separated pair consisting of 'CategoricalPredictors' and one of the following:

• 'all' — All predictors are categorical.

• [] — No predictors are categorical.

When you set CategoricalPredictors to 'all', the default Distance is 'hamming'.

Example: 'CategoricalPredictors','all'

Names of classes to use for training, specified as the comma-separated pair consisting of 'ClassNames' and a categorical or character array, logical or numeric vector, or cell array of character vectors. ClassNames must be the same data type as Y.

If ClassNames is a character array, then each element must correspond to one row of the array.

Use ClassNames to:

• Order the classes during training.

• Specify the order of any input or output argument dimension that corresponds to the class order. For example, use ClassNames to specify the order of the dimensions of Cost or the column order of classification scores returned by predict.

• Select a subset of classes for training. For example, suppose that the set of all distinct class names in Y is {'a','b','c'}. To train the model using observations from classes 'a' and 'c' only, specify 'ClassNames',{'a','c'}.

The default is the set of all distinct class names in Y.

Example: 'ClassNames',{'b','g'}

Data Types: categorical | char | logical | single | double | cell

Cost of misclassification of a point, specified as the comma-separated pair consisting of 'Cost' and one of the following:

• Square matrix, where Cost(i,j) is the cost of classifying a point into class j if its true class is i (i.e., the rows correspond to the true class and the columns correspond to the predicted class). To specify the class order for the corresponding rows and columns of Cost, additionally specify the ClassNames name-value pair argument.

• Structure S having two fields: S.ClassNames containing the group names as a variable of the same type as Y, and S.ClassificationCosts containing the cost matrix.

The default is Cost(i,j)=1 if i~=j, and Cost(i,j)=0 if i=j.

Data Types: single | double | struct

Covariance matrix, specified as the comma-separated pair consisting of 'Cov' and a positive definite matrix of scalar values representing the covariance matrix when computing the Mahalanobis distance. This argument is only valid when 'Distance' is 'mahalanobis'.

You cannot simultaneously specify 'Standardize' and either of 'Scale' or 'Cov'.

Data Types: single | double

Tie inclusion flag, specified as the comma-separated pair consisting of 'IncludeTies' and a logical value indicating whether predict includes all the neighbors whose distance values are equal to the Kth smallest distance. If IncludeTies is true, predict includes all these neighbors. Otherwise, predict uses exactly K neighbors.

Example: 'IncludeTies',true

Data Types: logical

Nearest neighbor search method, specified as the comma-separated pair consisting of 'NSMethod' and 'kdtree' or 'exhaustive'.

• 'kdtree' — Create and use a kd-tree to find nearest neighbors. 'kdtree' is valid when the distance metric is one of the following:

• 'euclidean'

• 'cityblock'

• 'minkowski'

• 'chebychev'

• 'exhaustive' — Use the exhaustive search algorithm. The distance values from all points in X to each point in Y are computed to find nearest neighbors.

The default is 'kdtree' when X has 10 or fewer columns, X is not sparse, and the distance metric is a 'kdtree' type; otherwise, 'exhaustive'.

Example: 'NSMethod','exhaustive'

Predictor variable names, specified as the comma-separated pair consisting of 'PredictorNames' and a cell array of unique character vectors. The functionality of 'PredictorNames' depends on the way you supply the training data.

• If you supply X and Y, then you can use 'PredictorNames' to give the predictor variables in X names.

• The order of the names in PredcitorNames must correspond to the column order of X. That is, PredictorNames{1} is the name of X(:,1), PredictorNames{2} is the name of X(:,2), and so on. Also, size(X,2) and numel(PredictorNames) must be equal.

• By default, PredictorNames is {x1,x2,...}.

• If you supply Tbl, then you can use 'PredictorNames' to choose which predictor variables to use in training. That is, fitcknn uses the predictor variables in PredictorNames and the response only in training.

• PredictorNames must be a subset of Tbl.Properties.VariableNames and cannot include the name of the response variable.

• By default, PredictorNames contains the names of all predictor variables.

• It good practice to specify the predictors for training using one of 'PredictorNames' or formula only.

Example: 'PredictorNames',{'SepalLength','SepalWidth','PedalLength','PedalWidth'}

Data Types: cell

Prior probabilities for each class, specified as the comma-separated pair consisting of 'Prior' and a value in this table.

ValueDescription
'empirical'The class prior probabilities are the class relative frequencies in Y.
'uniform'All class prior probabilities are equal to 1/K, where K is the number of classes.
numeric vectorEach element is a class prior probability. Order the elements according to Mdl.ClassNames or specify the order using the ClassNames name-value pair argument. The software normalizes the elements such that they sum to 1.
structure

A structure S with two fields:

• S.ClassNames contains the class names as a variable of the same type as Y.

• S.ClassProbs contains a vector of corresponding prior probabilities. The software normalizes the elements such that they sum to 1.

If you set values for both Weights and Prior, the weights are renormalized to add up to the value of the prior probability in the respective class.

Example: 'Prior','uniform'

Data Types: single | double | struct

Response variable name, specified as the comma-separated pair consisting of 'ResponseName' and a character vector.

Example: 'ResponseName','response'

Data Types: char

Distance scale, specified as the comma-separated pair consisting of 'Scale' and a vector containing nonnegative scalar values with length equal to the number of columns in X. Each coordinate difference between X and a query point is scaled by the corresponding element of Scale. This argument is only valid when 'Distance' is 'seuclidean'.

You cannot simultaneously specify 'Standardize' and either of 'Scale' or 'Cov'.

Data Types: single | double

Score transform function, specified as the comma-separated pair consisting of 'ScoreTransform' and a function handle or value in this table.

ValueFormula
'doublelogit'1/(1 + e–2x)
'invlogit'log(x / (1–x))
'ismax'Set the score for the class with the largest score to 1, and scores for all other classes to 0.
'logit'1/(1 + ex)
'none' or 'identity'x (no transformation)
'sign'–1 for x < 0
0 for x = 0
1 for x > 0
'symmetric'2x – 1
'symmetriclogit'2/(1 + ex) – 1
'symmetricismax'Set the score for the class with the largest score to 1, and scores for all other classes to -1.

For a MATLAB® function, or a function that you define, enter its function handle.

Mdl.ScoreTransform = @function;

function should accept a matrix (the original scores) and return a matrix of the same size (the transformed scores).

Example: 'ScoreTransform','logit'

Data Types: function_handle | char

Observation weights, specified as the comma-separated pair consisting of 'Weights' and a numeric vector of positive values or name of a variable in Tbl. The software weighs the observations in each row of X or Tbl with the corresponding value in Weights. The size of Weights must equal the number of rows of X or Tbl.

If you specify the input data as a table Tbl, then Weights can be the name of a variable in Tbl that contains a numeric vector. In this case, you must specify Weights as a character vector. For example, if the weights vector W is stored as Tbl.W, then specify it as 'W'. Otherwise, the software treats all columns of Tbl, including W, as predictors or the response when training the model.

The software normalizes Weights to sum up to the value of the prior probability in the respective class.

By default, Weights is ones(n,1), where n is the number of observations in X or Tbl.

Data Types: double | single | char

Cross Validation

collapse all

Cross-validation flag, specified as the comma-separated pair consisting of 'Crossval' and 'on' or 'off'.

If you specify 'on', then the software implements 10-fold cross-validation.

To override this cross-validation setting, use one of these name-value pair arguments: CVPartition, Holdout, KFold, or Leaveout. To create a cross-validated model, you can use one cross-validation name-value pair argument at a time only.

Alternatively, cross validate later by passing Mdl to crossval.

Example: 'CrossVal','on'

Cross-validation partition, specified as the comma-separated pair consisting of 'CVPartition' and a cvpartition partition object as created by cvpartition. The partition object specifies the type of cross-validation, and also the indexing for training and validation sets.

To create a cross-validated model, you can use one of these four name-value pair arguments only: CVPartition, Holdout, KFold, or Leaveout.

Fraction of data used for holdout validation, specified as the comma-separated pair consisting of 'Holdout' and a scalar value in the range (0,1). If you specify 'Holdout',p, then the software:

1. Randomly reserves p*100% of the data as validation data, and trains the model using the rest of the data

2. Stores the compact, trained model in the Trained property of the cross-validated model.

To create a cross-validated model, you can use one of these four name-value pair arguments only: CVPartition, Holdout, KFold, or Leaveout.

Example: 'Holdout',0.1

Data Types: double | single

Number of folds to use in a cross-validated model, specified as the comma-separated pair consisting of 'KFold' and a positive integer value greater than 1. If you specify, e.g., 'KFold',k, then the software:

1. Randomly partitions the data into k sets

2. For each set, reserves the set as validation data, and trains the model using the other k – 1 sets

3. Stores the k compact, trained models in the cells of a k-by-1 cell vector in the Trained property of the cross-validated model.

To create a cross-validated model, you can use one of these four name-value pair arguments only: CVPartition, Holdout, KFold, or Leaveout.

Example: 'KFold',5

Data Types: single | double

Leave-one-out cross-validation flag, specified as the comma-separated pair consisting of 'Leaveout' and 'on' or 'off'. If you specify 'Leaveout','on', then, for each of the n observations, where n is size(Mdl.X,1), the software:

1. Reserves the observation as validation data, and trains the model using the other n – 1 observations

2. Stores the n compact, trained models in the cells of an n-by-1 cell vector in the Trained property of the cross-validated model.

To create a cross-validated model, you can use one of these four name-value pair arguments only: CVPartition, Holdout, KFold, or Leaveout.

Example: 'Leaveout','on'

Data Types: char

Hyperparameters

collapse all

Distance metric, specified as the comma-separated pair consisting of 'Distance' and a valid distance metric name or function handle. The allowable distance metric names depend on your choice of a neighbor-searcher method (see NSMethod).

NSMethodDistance Metric Names
exhaustiveAny distance metric of ExhaustiveSearcher
kdtree'cityblock', 'chebychev', 'euclidean', or 'minkowski'

This table includes valid distance metrics of ExhaustiveSearcher.

Distance Metric NamesDescription
'cityblock'City block distance.
'chebychev'Chebychev distance (maximum coordinate difference).
'correlation'One minus the sample linear correlation between observations (treated as sequences of values).
'cosine'One minus the cosine of the included angle between observations (treated as vectors).
'euclidean'Euclidean distance.
'hamming'Hamming distance, percentage of coordinates that differ.
'jaccard'One minus the Jaccard coefficient, the percentage of nonzero coordinates that differ.
'mahalanobis'Mahalanobis distance, computed using a positive definite covariance matrix C. The default value of C is the sample covariance matrix of X, as computed by nancov(X). To specify a different value for C, use the 'Cov' name-value pair argument.
'minkowski'Minkowski distance. The default exponent is 2. To specify a different exponent, use the 'Exponent' name-value pair argument.
'seuclidean'Standardized Euclidean distance. Each coordinate difference between X and a query point is scaled, meaning divided by a scale value S. The default value of S is the standard deviation computed from X, S = nanstd(X). To specify another value for S, use the Scale name-value pair argument.
'spearman'One minus the sample Spearman's rank correlation between observations (treated as sequences of values).
@distfunDistance function handle. distfun has the form
function D2 = DISTFUN(ZI,ZJ) % calculation of distance ...
where
• ZI is a 1-by-N vector containing one row of X or Y.

• ZJ is an M2-by-N matrix containing multiple rows of X or Y.

• D2 is an M2-by-1 vector of distances, and D2(k) is the distance between observations ZI and ZJ(J,:).

If you specify CategoricalPredictors as 'all', then the default distance metric is 'hamming'. Otherwise, the default distance metric is 'euclidean'.

For definitions, see Distance Metrics.

Example: 'Distance','minkowski'

Data Types: function_handle | char

Distance weighting function, specified as the comma-separated pair consisting of 'DistanceWeight' and either a function handle or one of the values in this table.

ValueDescription
'equal'No weighting
'inverse'Weight is 1/distance
'squaredinverse'Weight is 1/distance2
@fcnfcn is a function that accepts a matrix of nonnegative distances, and returns a matrix the same size containing nonnegative distance weights. For example, 'squaredinverse' is equivalent to @(d)d.^(-2).

Example: 'DistanceWeight','inverse'

Data Types: function_handle | char

Minkowski distance exponent, specified as the comma-separated pair consisting of 'Exponent' and a positive scalar value. This argument is only valid when 'Distance' is 'minkowski'.

Example: 'Exponent',3

Data Types: single | double

Number of nearest neighbors in X to find for classifying each point when predicting, specified as the comma-separated pair consisting of 'NumNeighbors' and a positive integer value.

Example: 'NumNeighbors',3

Data Types: single | double

Flag to standardize the predictors, specified as the comma-separated pair consisting of 'Standardize' and true (1) or false (0).

If you set 'Standardize',true, then the software centers and scales each column of the predictor data (X) by the column mean and standard deviation, respectively.

The software does not standardize categorical predictors, and throws an error if all predictors are categorical.

You cannot simultaneously specify 'Standardize',1 and either of 'Scale' or 'Cov'.

It is good practice to standardize the predictor data.

Example: 'Standardize',true

Data Types: logical

Hyperparameter Optimization

collapse all

Parameters to optimize, specified as:

• 'none' — Do not optimize.

• 'auto' — Use {'Distance','NumNeighbors'}

• '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 cross-validation loss (error) for fitcknn by varying the parameters. For information about cross-validation loss (albeit in a different context), see Classification Loss. To control the cross-validation type and other aspects of the optimization, use the HyperparameterOptimizationOptions name-value pair.

 Note:   OptimizeHyperparameters values override any values you set using other name-value pairs. For example, setting OptimizeHyperparameters to 'auto' causes the 'auto' values to apply.

The eligible parameters for fitcknn are:

• Distancefitcknn searches among 'cityblock', 'chebychev', 'correlation', 'cosine', 'euclidean', 'hamming', 'jaccard', 'mahalanobis', 'minkowski', 'seuclidean', and 'spearman'.

• DistanceWeightfitcknn searches among 'equal', 'inverse', and 'squaredinverse'.

• Exponentfitcknn searches among positive real values, by default in the range [0.5,3].

• NumNeighborsfitcknn searches among positive integer values, by default log-scaled in the range [1, max(2,round(NumObservations/2))].

• Standardizefitcknn searches among the values 'true' and 'false'.

Set nondefault parameters by passing a vector of optimizableVariable objects that have nondefault values. For example,

load fisheriris params = hyperparameters('fitcknn',meas,species); params(1).Range = [1,20];

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 + cross-validation loss) for regression, and the misclassification rate for classification. To control the iterative display, set the HyperparameterOptimizationOptions name-value pair, Verbose field. To control the plots, set the HyperparameterOptimizationOptions name-value pair, ShowPlots field.

For an example, see Optimize Fitted KNN Classifier.

Example: 'auto'

Data Types: char | cell

Options for optimization, specified as a structure. Modifies the effect of the OptimizeHyperparameters name-value pair. All fields in the structure are optional.

Field NameValuesDefault
Optimizer
• 'bayesopt' — Use Bayesian optimization. Internally, this setting calls bayesopt.

• 'gridsearch' — Use grid search with NumGridDivisions values per dimension.

• 'randomsearch' — Search at random among MaxObjectiveEvaluations points.

'gridsearch' searches in a random order, using uniform sampling without replacement from the grid. After optimization, you can get a table in grid order by using the commandsortrows(Mdl.ParameterOptimizationResults).

'bayesopt'
AcquisitionFunctionName
• 'expected-improvement-per-second-plus'

• 'expected-improvement'

• 'expected-improvement-plus'

• 'expected-improvement-per-second'

• 'lower-confidence-bound'

• 'probability-of-improvement'

For details, see the bayesopt AcquisitionFunctionName name-value pair, or Acquisition Function Types.
'expected-improvement-per-second-plus'
MaxObjectiveEvaluationsMaximum number of objective function evaluations.30 for 'bayesopt' or 'randomsearch', and the entire grid for 'gridsearch'
NumGridDivisionsFor 'gridsearch', the number of values in each dimension. Can be a vector of positive integers giving the number of values for each dimension, or a scalar that applies to all dimensions. Ignored for categorical variables.10
ShowPlotsLogical value indicating whether to show plots. If true, plots the best objective function value against 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
SaveIntermediateResultsLogical value indicating whether to save results when Optimizer is 'bayesopt'. If true, overwrites a workspace variable named 'BayesoptResults' at each iteration. The variable is a BayesianOptimization object.false
VerboseDisplay to the command line.
• 0 — No iterative display

• 1 — Iterative display

• 2 — Iterative display with extra information

For details, see the bayesoptVerbose name-value pair.
1
Repartition

Logical value indicating whether to repartition the cross-validation at every iteration. If false, the optimizer uses a single partition for the optimization.

true usually gives the most robust results because this setting takes partitioning noise into account. However, for good results, true requires at least twice as many function evaluations.

false
Use no more than one of the following three field names.
CVPartitionA cvpartition object, as created by cvpartitionKfold = 5
HoldoutA scalar in the range (0,1) representing the holdout fraction.
KfoldAn integer greater than 1.

Example: struct('MaxObjectiveEvaluations',60)

Data Types: struct

Output Arguments

collapse all

Trained k-nearest neighbor classification model, returned as a ClassificationKNN model object or a ClassificationPartitionedModel cross-validated model object.

If you set any of the name-value pair arguments KFold, Holdout, CrossVal, or CVPartition, then Mdl is a ClassificationPartitionedModel cross-validated model object. Otherwise, Mdl is a ClassificationKNN model object.

To reference properties of Mdl, use dot notation. For example, to display the distance metric at the Command Window, enter Mdl.Distance.

collapse all

Prediction

ClassificationKNN predicts the classification of a point Xnew using a procedure equivalent to this:

1. Find the NumNeighbors points in the training set X that are nearest to Xnew.

2. Find the NumNeighbors response values Y to those nearest points.

3. Assign the classification label Ynew that has the largest posterior probability among the values in Y.

For details, see Posterior Probability in the predict documentation.

Algorithms

• NaNs or <undefined>s indicate missing observations. The following describes the behavior of fitcknn when the data set or weights contain missing observations.

• If any value of Y or any weight is missing, then fitcknn removes those values from Y, the weights, and the corresponding rows of X from the data. The software renormalizes the weights to sum to 1.

• If you specify to standardize predictors ('Standardize',1) or the standardized Euclidean distance ('Distance','seuclidean') without a scale, then fitcknn removes missing observations from individual predictors before computing the mean and standard deviation. In other words, the software implements nanmean and nanstd on each predictor.

• If you specify the Mahalanobis distance ('Distance','mahalanbois') without its covariance matrix, then fitcknn removes rows of X that contain at least one missing value. In other words, the software implements nancov on the predictor matrix X.

• Suppose that you set 'Standardize',1.

• If you also specify Prior or Weights, then the software takes the observation weights into account. Specifically, the weighted mean of predictor j is

${\overline{x}}_{j}=\sum _{{B}_{j}}^{}{w}_{k}{x}_{jk}$

and the weighted standard deviation is

${s}_{j}=\sum _{Bj}^{}{w}_{k}\left({x}_{jk}-{\overline{x}}_{j}\right),$

where Bj is the set of indices k for which xjk and wk are not missing.

• If you also set 'Distance','mahalanobis' or 'Distance','seuclidean', then you cannot specify Scale or Cov. Instead, the software:

1. Computes the means and standard deviations of each predictor

2. Standardizes the data using the results of step 1

3. Computes the distance parameter values using their respective default.

• If you specify Scale and either of Prior or Weights, then the software scales observed distances by the weighted standard deviations.

• If you specify Cov and either of Prior or Weights, then the software applies the weighted covariance matrix to the distances. In other words,

$Cov=\frac{\sum _{B}{w}_{j}}{{\left(\sum _{B}{w}_{j}\right)}^{2}-\sum _{B}{w}_{j}^{2}}\sum _{B}^{}{w}_{j}{\left({x}_{j}-\overline{x}\right)}^{\prime }\left({x}_{j}-\overline{x}\right),$

where B is the set of indices j for which the observation xj does not have any missing values and wj is not missing.

Alternatives

Although fitcknn can train a multiclass KNN classifier, you can reduce a multiclass learning problem to a series of KNN binary learners using fitcecoc.