classificationKNNComponent

Pipeline component for classification using k-nearest neighbor model

Since R2026a

Description

classificationKNNComponent is a pipeline component that creates a k-nearest neighbor (KNN) classification model. The pipeline component uses the functionality of the fitcknn function during the learn phase to train the KNN classification model. The component uses the functionality of the predict and loss functions during the run phase to perform classification.

Creation

Syntax

component = classificationKNNComponent

component = classificationKNNComponent(Name=Value)

Description

component = classificationKNNComponent creates a pipeline component for a k-nearest neighbor classification model.

component = classificationKNNComponent(Name=Value) sets writable Properties using one or more name-value arguments. For example, you can specify the tie-breaking algorithm, distance metric, and observation weights.

Properties

Structural Parameters

The software sets structural parameters when you create the component. You cannot modify structural parameters after creating the component.

UseWeights — Observation weights flag

false or 0 (default) | true or 1

This property is read-only after the component is created.

Observation weights flag, specified as 0 (false) or 1 (true). If UseWeights is true, the component adds a third input "Weights" to the Inputs component property, and a third input tag 3 to the InputTags component property.

Example: c = classificationKNNComponent(UseWeights=1)

Data Types: logical

Learn Parameters

The software sets learn parameters when you create the component. You can modify learn parameters using dot notation any time before you use the learn object function. Any unset learn parameters use the corresponding default values.

BreakTies — Tie-breaking algorithm

"smallest" (default) | "nearest" | "random"

Tie-breaking algorithm used by the component if multiple classes have the same smallest cost, specified as 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.

Example: c = classificationKNNComponent(BreakTies="nearest")

Example: c.BreakTies = "random"

Data Types: char | string

BucketSize — Maximum data points in node

50 (default) | positive integer value

Maximum number of data points in the leaf node of the Kd-tree, specified as a positive integer value. This argument is meaningful only when NSMethod is "kdtree".

Example: c = classificationKNNComponent(BucketSize=40)

Example: c.BucketSize = 60

Data Types: single | double

Cost — Misclassification cost

square matrix (default) | structure

Misclassification cost, specified as a square matrix or a structure.

• If Cost is a square matrix, Cost(i,j) is the cost of classifying a point into class j if its true class is i.

• If Cost is a structure S, it has two fields: S.ClassificationCosts, which contains the cost matrix; and S.ClassNames, which contains the group names and defines the class order of the rows and columns of the cost matrix.

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

Example: c = classificationKNNComponent(Cost=[0 1; 2 0])

Example: c.Cost = [0 2; 1 0]

Data Types: single | double | struct

Cov — Covariance matrix

positive definite matrix of scalar values

Covariance matrix, specified as a positive definite matrix of scalar values used to compute the Mahalanobis distance. This argument is only valid when Distance is "mahalanobis".

The default value is cov(X,"omitrows"), where X is the first data argument of learn.

Example: c = classificationKNNComponent(Cov=[0.2 0.4 1.2; 0.4 0.3 0.7; 1.2 0.7 1.1])

Example: c.Cov = [0.8 0.2; 0.2 1.3]

Data Types: single | double

Distance — Distance metric

"euclidean" (default) | "cityblock" | "chebychev" | "correlation" | "cosine" | "hamming" | function handle | ...

Distance metric, specified as a function handle or one of the values in this table.

Distance Metric Names	Description
"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
"fasteuclidean" (since R2025a)	Euclidean distance computed by using an alternative algorithm that saves time when the number of predictors is at least 10. For more information, see Fast Euclidean Distance Algorithm.
"fastseuclidean" (since R2025a)	Standardized Euclidean distance computed by using an alternative algorithm that saves time when the number of predictors is at least 10. For more information, see Fast Euclidean Distance Algorithm.
"hamming"	Hamming distance, the 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. For more information, see Cov.
"minkowski"	Minkowski distance. For information on the Minkowski distance exponent, see Exponent.
"seuclidean"	Standardized Euclidean distance. For information on distance scaling, see Scale.
"spearman"	One minus the sample Spearman's rank correlation between observations (treated as sequences of values)

To specify a custom distance function, use function handle notation. For more information on custom distance functions, see Distance.

If NSMethod is "kdtree", you can only set the Distance property to "cityblock", "chebychev", "euclidean", or "minkowski".

Example: c = classificationKNNComponent(Distance="minkowski")

Example: c.Distance = "hamming"

Data Types: char | string | function_handle

DistanceWeight — Distance weighting function

"equal" (default) | "inverse" | "squaredinverse" | function handle

Distance weighting function, specified as a function handle or one of the values in this table.

Value	Description
"equal"	No weighting
"inverse"	Weight is 1/distance
"squaredinverse"	Weight is 1/distance2

To specify a custom distance weighting function, use function handle notation. The function must accept a matrix of nonnegative distances and return a matrix of the same size containing nonnegative distance weights.

Example: c = classificationKNNComponent(DistanceWeight="inverse")

Example: c.DistanceWeight = "squaredinverse"

Data Types: char | string | function_handle

Exponent — Minkowski distance exponent

2 (default) | positive scalar value

Minkowski distance exponent, specified as a positive scalar value. This argument is only valid when Distance is "minkowski".

Example: c = classificationKNNComponent(Exponent=3)

Example: c.Exponent = 4

Data Types: single | double

IncludeTies — Tie inclusion flag

false or 0 (default) | true or 1

Tie inclusion flag, specified as 0 (false) or 1 (true). If IncludeTies is true, then the component includes all neighbors whose distance values are equal to the kth smallest distance. Otherwise, the component uses exactly k neighbors.

Example: c = classificationKNNComponent(IncludeTies=true)

Example: c.IncludeTies = false

Data Types: logical

NSMethod — Nearest neighbor search method

"kdtree" | "exhaustive"

Nearest neighbor search method, specified as "kdtree" or "exhaustive".

• "kdtree" — This method creates and uses a K-d tree to find nearest neighbors. You can specify this method only when Distance is "euclidean", "cityblock", "minkowski", or "chebychev".

• "exhaustive" — This method uses the exhaustive search algorithm to find nearest neighbors. When predicting the class of a new point, the component computes the distance to all the points in the first data input of learn.

The default value is "kdtree" when the first data input of learn has 10 or fewer columns, is not sparse, and Distance is "euclidean", "cityblock", "minkowski", or "chebychev". Otherwise, the default value is "exhaustive".

Example: c = classificationKNNComponent(NSMethod="exhaustive")

Example: c.NSMethod = "kdtree"

Data Types: char | string

NumNeighbors — Number of nearest neighbors to find

1 (default) | positive integer value

Number of nearest neighbors to find for classifying each point during the run phase, specified as a positive integer value.

Example: c = classificationKNNComponent(NumNeighbors=3)

Example: c.NumNeighbors = 2

Data Types: single | double

Prior — Prior probabilities

"empirical" (default) | "uniform" | numeric vector | structure

Prior probabilities for each class, specified as a value in this table.

Value	Description
"empirical"	The class prior probabilities are the class relative frequencies. The class relative frequencies are determined by the second data argument of learn.
"uniform"	All class prior probabilities are equal to 1/K, where K is the number of classes.
numeric vector	A numeric vector with one value for each class. Each element is a class prior probability. The component normalizes the elements such that they sum to 1.
structure	A structure S with two fields: S.ClassNames contains a list of the class names. S.ClassProbs contains a vector of corresponding prior probabilities. The component normalizes the elements such that they sum to 1.

If you set UseWeights to true, the component renormalizes the weights to add up to the value of the prior probability in the respective class.

Example: c = classificationKNNComponent(Prior="uniform")

Example: c.Prior = "empirical"

Data Types: single | double | char | string | struct

Scale — Distance scale

vector of nonnegative scalar values

Distance scale, specified as a vector of nonnegative scalar values. Each coordinate difference between the first data input of learn and a query point is scaled by the corresponding element of Scale. This argument is only valid when Distance is "seuclidean".

The default value is std(X,"omitnan"), where X is the first data input of learn.

Example: c = classificationKNNComponent(Scale=[0.6 0.5 0.1])

Example: c.Scale = [0.2 0.9]

Data Types: single | double

Standardize — Flag to standardize predictors

false or 0 (default) | true or 1

Flag to standardize the predictors, specified as 0 (false) or 1 (true). If Standardize is true, then the component centers and scales each column of the first data input of learn by the column mean and standard deviation, respectively.

The component does not standardize categorical predictors, and issues an error if all predictors are categorical.

You cannot set Standardize to true if either the Scale property or the Cov property is nonempty.

Example: c = classificationKNNComponent(Standardize=true)

Example: c.Standardize = false

Data Types: logical

Run Parameters

The software sets run parameters when you create the component. You can modify the run parameters using dot notation at any time. Any unset run parameters use the corresponding default values.

LossFun — Loss function

"mincost" (default) | "binodeviance" | "classifcost" | "classiferror" | "exponential" | "hinge" | "logit" | "quadratic" | function handle

Loss function, specified as a built-in loss function name or a function handle.

This table lists the available built-in loss functions.

Value	Description
"binodeviance"	Binomial deviance
"classifcost"	Observed misclassification cost
"classiferror"	Misclassified rate in decimal
"exponential"	Exponential loss
"hinge"	Hinge loss
"logit"	Logistic loss
"mincost"	Minimal expected misclassification cost (for classification scores that are posterior probabilities)
"quadratic"	Quadratic loss

To specify a custom loss function, use function handle notation. For more information on custom loss functions, see LossFun.

Example: c = classificationKNNComponent(LossFun="classifcost")

Example: c.LossFun = "hinge"

Data Types: char | string | function_handle

ScoreTransform — Score transformation

"none" (default) | "doublelogit" | "invlogit" | "ismax" | "logit" | "identity" | "sign" | "symmetric" | "symmetricismax" | "symmetriclogit" | function handle

Score transformation, specified as a built-in function name or a function handle.

This table summarizes the available built-in score transform functions.

Value	Description
"doublelogit"	1/(1 + e–2x)
"invlogit"	log(x / (1 – x))
"ismax"	Sets the score for the class with the largest score to 1, and sets the scores for all other classes to 0
"logit"	1/(1 + e–x)
"none" or "identity"	x (no transformation)
"sign"	–1 for x < 0 0 for x = 0 1 for x > 0
"symmetric"	2x – 1
"symmetricismax"	Sets the score for the class with the largest score to 1, and sets the scores for all other classes to –1
"symmetriclogit"	2/(1 + e–x) – 1

To specify a custom score transform function, use function handle notation. The function must accept a matrix containing the original scores and return a matrix of the same size containing the transformed scores.

Example: c = classificationKNNComponent(ScoreTransform="logit")

Example: c.ScoreTransform = "symmetric"

Data Types: char | string | function_handle

Component Properties

The software sets component properties when you create the component. You can modify the component properties (excluding HasLearnables and HasLearned) using dot notation at any time. You cannot modify the HasLearnables and HasLearned properties directly.

Name — Component identifier

"ClassificationKNN" (default) | character vector | string scalar

Component identifier, specified as a character vector or string scalar.

Example: c = classificationKNNComponent(Name="KNN")

Example: c.Name = "KNNClassifier"

Data Types: char | string

Inputs — Names of input ports

["Predictors","Response"] (default) | character vector | string array | cell array of character vectors

Names of the input ports, specified as a character vector, string array, or cell array of character vectors. If UseWeights is true, the software adds the input port "Weights" to Inputs.

Example: c = classificationKNNComponent(Inputs=["X","Y"])

Example: c.Inputs = ["In1","In2"]

Data Types: char | string | cell

Outputs — Names of output ports

["Predictions","Scores","Loss"] (default) | character vector | string array | cell array of character vectors

Names of the output ports, specified as a character vector, string array, or cell array of character vectors.

Example: c = classificationKNNComponent(Outputs=["Class","ClassScore","LossVal"])

Example: c.Outputs = ["X","Y","Z"]

Data Types: char | string | cell

InputTags — Tags that enable automatic connection

[1 2] (default) | nonnegative integer vector

Tags that enable the automatic connection of the component inputs with other components or pipelines, specified as a nonnegative integer vector. If you specify InputTags, the number of tags must match the number of inputs in Inputs. If UseWeights is true, the component adds a third input tag to InputTags.

Example: c = classificationKNNComponent(InputTags=[1 0])

Example: c.InputTags = [0 1]

Data Types: single | double

OutputTags — Tags that enable automatic connection

[1 0 0] (default) | nonnegative integer vector

Tags that enable the automatic connection of the component outputs with other components or pipelines, specified as a nonnegative integer vector. If you specify OutputTags, the number of tags must match the number of outputs in Outputs.

Example: c = classificationKNNComponent(OutputTags=[1 0 4])

Example: c.OutputTags = [1 2 0]

Data Types: single | double

HasLearnables — Indicator for learnables

Read-only: 1 (true) (default)

This property is read-only.

Indicator for the learnables, returned as 1 (true). A value of 1 indicates that the component contains Learnables.

Data Types: logical

HasLearned — Indicator showing learning status of component

Read-only: 0 (false) (default) | 1 (true)

This property is read-only.

Indicator showing the learning status of the component, returned as 0 (false) or 1 (true). A value of 1 indicates that the learn object function has been applied to the component, and the Learnables are nonempty.

Data Types: logical

Learnables

The software sets learnables when you use the learn object function. You cannot modify learnables directly.

TrainedModel — Trained model

Read-only: ClassificationKNN model object

This property is read-only.

Trained model, returned as a ClassificationKNN model object.

Object Functions

learn	Initialize and evaluate pipeline or component
run	Execute pipeline or component for inference after learning
reset	Reset pipeline or component
series	Connect components in series to create pipeline
parallel	Connect components or pipelines in parallel to create pipeline
view	View diagram of pipeline inputs, outputs, components, and connections

Examples

Create and Train Pipeline Component for KNN Classification

Create a classificationKNNComponent component.

component = classificationKNNComponent

component = 
  classificationKNNComponent with properties:

            Name: "ClassificationKNN"
          Inputs: ["Predictors"    "Response"]
       InputTags: [1 2]
         Outputs: ["Predictions"    "Scores"    "Loss"]
      OutputTags: [1 0 0]

   
Learnables (HasLearned = false)
    TrainedModel: []

   
Structural Parameters (locked)
      UseWeights: 0


Show all parameters

component is a classificationKNNComponent object that contains one learnable, TrainedModel. This property remains empty until you pass data to the component during the learn phase.

To use five nearest neighbors for prediction, set the NumNeighbors property of the component to 5.

component.NumNeighbors = 5;

Read the fisheriris data set into a table. Store predictor and response data in tables X and Y.

fisheriris = readtable("fisheriris.csv");
X = fisheriris(:,1:end-1);
Y = fisheriris(:,end);

Train the classificationKNNComponent object.

component = learn(comp,X,Y)

component = 
  classificationKNNComponent with properties:

            Name: "ClassificationKNN"
          Inputs: ["Predictors"    "Response"]
       InputTags: [1 2]
         Outputs: ["Predictions"    "Scores"    "Loss"]
      OutputTags: [1 0 0]

   
Learnables (HasLearned = true)
    TrainedModel: [1×1 ClassificationKNN]

   
Structural Parameters (locked)
      UseWeights: 0

   
Learn Parameters (locked)
    NumNeighbors: 5


Show all parameters

Note that the HasLearned property is set to true, which indicates that the software trained the KNN model TrainedModel. You can use component to classify new data using the run function.

Version History

Introduced in R2026a