classificationNeuralNetworkComponent

Pipeline component for classification using neural network model

Since R2026a

Description

classificationNeuralNetworkComponent is a pipeline component that creates a feedforward, fully connected neural network for classification. The pipeline component uses the functionality of the fitcnet function during the learn phase to train a neural network model. The component uses the functionality of the predict and loss functions during the run phase to evaluate the model on new data.

Creation

Syntax

component = classificationNeuralNetworkComponent

component = classificationNeuralNetworkComponent(Name=Value)

Description

component = classificationNeuralNetworkComponent creates a pipeline component for a neural network model for classification.

component = classificationNeuralNetworkComponent(Name=Value) sets writable Properties using one or more name-value arguments. For example, you can specify the activation functions, regularization term strength, and size of fully connected layers.

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 = classificationNeuralNetworkComponent(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.

Activations — Activation functions for fully connected layers

"relu" (default) | "tanh" | "sigmoid" | "none" | string array | cell array of character vectors

Activation functions for the fully connected layers of the neural network model, specified as one or more of the values in this table.

Value	Description
"relu"	Rectified linear unit (ReLU) function — Performs a threshold operation on each element of the input, where any value less than zero is set to zero, that is, $$f\left(x\right)=\{\begin{array}{cc}x,& x\ge 0\\ 0,& x<0\end{array}$$
"tanh"	Hyperbolic tangent (tanh) function — Applies the tanh function to each input element
"sigmoid"	Sigmoid function — Performs the following operation on each input element: $$f(x)=\frac{1}{1+e^{-x}}$$
"none"	Identity function — Returns each input element without performing any transformation, that is, f(x) = x

If Activations is one of the table values, the component uses the specified activation function for each of the fully connected layers of the model, excluding the final fully connected layer. The activation function for the final fully connected layer is always softmax. For more information, see Neural Network Structure.

If Activations is a string array or cell array of character vectors containing multiple table values, the component uses the ith element of Activations for the ith fully connected layer of the model.

Example: c = classificationNeuralNetworkComponent(Activations="sigmoid")

Example: c.Activations = ["relu","tanh"]

Data Types: char | string | cell

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 = classificationNeuralNetworkComponent(Cost=[0 1; 2 0])

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

Data Types: single | double | struct

GradientTolerance — Relative gradient tolerance

1e-6 (default) | nonnegative scalar

Relative gradient tolerance, specified as a nonnegative scalar.

Let $${ℒ}_t$$ be the loss function at training iteration t, $$\nabla {ℒ}_t$$ be the gradient of the loss function with respect to the weights and biases at iteration t, and $$\nabla {ℒ}_0$$ be the gradient of the loss function at an initial point. If $$\max \left|\nabla {ℒ}_t\right|\le a\cdot \text{GradientTolerance}$$, where $$a=\max \left(1,\min \left|{ℒ}_t\right|,\max \left|\nabla {ℒ}_0\right|\right)$$, the training process terminates.

Example: c = classificationNeuralNetworkComponent(GradientTolerance=1e-5)

Example: c.GradientTolerance = 1e-7

Data Types: single | double

InitialStepSize — Initial step size

[] (default) | positive scalar | "auto"

Initial step size, specified as a positive scalar or "auto". By default, the component does not use the initial step size to determine the initial Hessian approximation used to train the model. However, if you specify an initial step size $${\Vert s_0\Vert }_{\infty }$$, then the initial inverse-Hessian approximation is $$\frac{{\Vert s_0\Vert }_{\infty }}{{\Vert \nabla {ℒ}_0\Vert }_{\infty }}I$$. $$\nabla {ℒ}_0$$ is the initial gradient vector, and $$I$$ is the identity matrix.

If you specify "auto", the component determines an initial step size by using $${\Vert s_0\Vert }_{\infty }=0.5{\Vert {\eta }_0\Vert }_{\infty }+0.1$$. $$s_0$$ is the initial step vector, and $${\eta }_0$$ is the vector of unconstrained initial weights and biases.

Example: c = classificationNeuralNetworkComponent(InitialStepSize="auto")

Example: c.InitialStepSize = 0.2

Data Types: single | double | char | string

IterationLimit — Maximum number of training iterations

1e3 (default) | positive integer scalar

Maximum number of training iterations, specified as a positive integer scalar.

When the component completes IterationLimit training iterations, it updates TrainedModel regardless of whether the training routine successfully converges.

Example: c = classificationNeuralNetworkComponent(IterationLimit=1e8)

Example: c.IterationLimit = 1e5

Data Types: single | double

Lambda — Regularization term strength

0 (default) | nonnegative scalar

Regularization term strength, specified as a nonnegative scalar. The component forms the objective function for minimization from the cross-entropy loss function and the ridge (L2) penalty term.

Example: c = classificationNeuralNetworkComponent(Lambda=1e-4)

Example: c.Lambda = 1e-2

Data Types: single | double

LayerBiasesInitializer — Type of initial fully connected layer biases

"zeros" (default) | "ones"

Type of initial fully connected layer biases, specified as "zeros" or "ones".

If you specify "zeros", each fully connected layer has an initial bias value of 0. If you specify "ones", each fully connected layer has an initial bias value of 1.

Example: c = classificationNeuralNetworkComponent(LayerBiasesInitializer="ones")

Example: c.LayerBiasesInitializer = "zeros"

Data Types: char | string

LayerSizes — Size of fully connected layers

10 (default) | positive integer vector

Size of the fully connected layers in the neural network model, specified as a positive integer vector. The ith element of LayerSizes is the number of outputs in the ith fully connected layer of the neural network model.

LayerSizes does not include the size of the final fully connected layer, which uses the softmax activation function. For more information, see Neural Network Structure.

Example: c = classificationNeuralNetworkComponent(LayerSizes=[100 25 10])

Example: c.LayerSizes = [50 20 10]

Data Types: single | double

LayerWeightsInitializer — Function used to initialize fully connected layer weights

"glorot" (default) | "he"

Function used to initialize the fully connected layer weights, specified as "glorot" or "he".

• If you specify "glorot", the component initializes the weights using the Glorot initializer [1] (also known as the Xavier initializer). For each layer, the Glorot initializer independently samples from a uniform distribution with zero mean and variance 2/(I+O), where I is the input size and O is the output size for the layer.

• If you specify "he", the component initializes the weights using the He initializer [2]. For each layer, the He initializer samples from a normal distribution with zero mean and variance 2/I, where I is the input size for the layer.

Example: c = classificationNeuralNetworkComponent(LayerWeightsInitializer="he")

Example: c.LayerWeightsInitializer = "glorot"

Data Types: char | string

LossTolerance — Loss tolerance

1e-6 (default) | nonnegative scalar

Loss tolerance, specified as a nonnegative scalar.

If the function loss at an iteration is smaller than LossTolerance, the training process terminates.

Example: c = classificationNeuralNetworkComponent(LossTolerance=1e-8)

Example: c.LossTolerance = 1e-5

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 = classificationNeuralNetworkComponent(Prior="uniform")

Example: c.Prior = "empirical"

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

Standardize — Flag to standardize predictor data

false or 0 (default) | true or 1

Flag to standardize the predictor data, specified as a numeric or logical 0 (false) or 1 (true). If Standardize is true, the component centers and scales each numeric predictor variable by the corresponding column mean and standard deviation. The component does not standardize categorical predictors.

Example: c = classificationNeuralNetworkComponent(Standardize=true)

Example: c.Standardize = 0

Data Types: single | double | logical

StepTolerance — Step size tolerance

1e-6 (default) | nonnegative scalar

Step size tolerance, specified as a nonnegative scalar.

If the step size at an iteration is smaller than StepTolerance, the training process terminates.

Example: c = classificationNeuralNetworkComponent(StepTolerance=1e-4)

Example: c.StepTolerance = 1e-8

Data Types: single | double

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" | "crossentropy" | "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
"crossentropy"	Cross-entropy loss
"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 = classificationNeuralNetworkComponent(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 = classificationNeuralNetworkComponent(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

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

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

Example: c = classificationNeuralNetworkComponent(Name="NeuralNetwork")

Example: c.Name = "NeuralNetworkClassifier"

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 component adds the input port "Weights" to Inputs.

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

Example: c.Inputs = ["X1","Y1"]

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 = classificationNeuralNetworkComponent(Outputs=["Class","ClassScore","LossVal"])

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

Data Types: char | string | cell

InputTags — Tags that enable automatic connection of component inputs

[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 = classificationNeuralNetworkComponent(InputTags=[0 1])

Example: c.InputTags = [1 0]

Data Types: single | double

OutputTags — Tags that enable automatic connection of component outputs

[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 = classificationNeuralNetworkComponent(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: CompactClassificationNeuralNetwork model object

This property is read-only.

Trained model, returned as a CompactClassificationNeuralNetwork 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 Neural Network Classification

Create a classificationNeuralNetworkComponent pipeline component.

component = classificationNeuralNetworkComponent

component = 
  classificationNeuralNetworkComponent with properties:

            Name: "ClassificationNeuralNetwork"
          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 classificationNeuralNetworkComponent object that contains one learnable, TrainedModel. This property remains empty until you pass data to the component during the learn phase.

To use the sigmoid activation function for the fully connected layers of the neural network model, set the Activations property of the component to "sigmoid".

component.Activations = "sigmoid";

Load the ionosphere data set and save the data in two tables.

load ionosphere
X = array2table(X);
Y = array2table(Y);

Use the learn object function to train the classificationNeuralNetworkComponent object using the entire data set.

component = learn(component,X,Y)

component = 
  classificationNeuralNetworkComponent with properties:

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

   
Learnables (HasLearned = true)
    TrainedModel: [1×1 classreg.learning.classif.CompactClassificationNeuralNetwork]

   
Structural Parameters (locked)
      UseWeights: 0

   
Learn Parameters (locked)
     Activations: 'sigmoid'


Show all parameters

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

More About

Neural Network Structure

The default neural network classifier has the following layer structure.

Structure	Description
	Input — This layer corresponds to the predictor data in the first data argument of the learn or run function.
	First fully connected layer — This layer has 10 outputs by default. You can widen the layer or add more fully connected layers to the network by specifying the LayerSizes property. You can find the weights and biases for this layer in the TrainedModel.LayerWeights{1} and TrainedModel.LayerBiases{1} properties of TrainedModel, respectively.
	ReLU activation function — The component applies this activation function to the first fully connected layer. You can change the activation function by specifying the Activations property.
	Final fully connected layer — This layer has K outputs, where K is the number of classes in the response variable. You can find the weights and biases for this layer in the TrainedModel.LayerWeights{end} and TrainedModel.LayerBiases{end} properties of TrainedModel, respectively.
	Softmax function (for both binary and multiclass classification) — The component applies this activation function to the final fully connected layer. The function takes each input xi and returns the following, where K is the number of classes in the response variable: $$f(x_i)=\frac{\exp (x_i)}{{\displaystyle \sum _{j=1}^K\exp (x_j)}}.$$ The results correspond to the predicted classification scores (or posterior probabilities).
	Output — This layer corresponds to the predicted class labels.

References

[1] Glorot, Xavier, and Yoshua Bengio. “Understanding the Difficulty of Training Deep Feedforward Neural Networks.” In Proceedings of the 13th International Conference on Artificial Intelligence and Statistics, 2010, pp. 249–256.

[2] He, Kaiming, Xiangyu Zhang, Shaoqing Ren, and Jian Sun. “Delving Deep into Rectifiers: Surpassing Human-Level Performance on Imagenet Classification.” In Proceedings of the IEEE International Conference on Computer Vision, 2015, pp. 1026–1034.

Version History

Introduced in R2026a