classificationCustomNeuralNetworkComponent

R2026b

Pipeline component for classification using custom neural network model

Since R2026b

Description

classificationCustomNeuralNetworkComponent is a pipeline component that creates a neural network model for classification using custom architecture. 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 = classificationCustomNeuralNetworkComponent(network)

component = classificationCustomNeuralNetworkComponent(network,Name=Value)

Description

component = classificationCustomNeuralNetworkComponent(network) creates a pipeline component for classification using a neural network model with architecture specified by network.

component = classificationCustomNeuralNetworkComponent(network,Name=Value) sets writable Properties using one or more name-value arguments. For example, you can specify the relative gradient tolerance, regularization term strength, and loss tolerance.

Input Arguments

network — Custom neural network architecture

dlnetwork object | layer array

Custom neural network architecture, specified as a dlnetwork (Deep Learning Toolbox) object or a layer array (requires Deep Learning Toolbox™).

The component automatically encodes any categorical predictors using one-hot encoding. If the input data includes categorical predictors, the neural network architecture must account for the effect of automatic encoding on the number of input variables. To ensure the architecture meets this requirement, follow one of these approaches:

• The simplest approach is to specify a layer array that does not have an input layer. When you pass data to the component during the learn phase, the component automatically determines the network input size based on the training data and adds an input layer with the appropriate size.

• If you want to use functionality provided by input layers, you can specify a dlnetwork or layer array that has an input layer. The size of the input layer must be consistent with the number of variables after the component encodes the categorical predictors. To determine the size, you must consider the number of numeric variables and the number of categories in each categorical variable.

  If you standardize the predictors using the Standardize property, then the input layer of the network must not perform normalization.

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)

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

Observation weights flag, specified as 0 (false).

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.

Network — Custom neural network architecture

dlnetwork object | layer array

Custom neural network architecture, specified as a dlnetwork (Deep Learning Toolbox) object or a layer array (requires Deep Learning Toolbox). By default, the component uses the object specified by network.

The component automatically encodes any categorical predictors using one-hot encoding. If the input data includes categorical predictors, the neural network architecture must account for the effect of automatic encoding on the number of input variables. To ensure the architecture meets this requirement, follow one of these approaches:

• The simplest approach is to specify a layer array that does not have an input layer. When you pass data to the component during the learn phase, the component automatically determines the network input size based on the training data and adds an input layer with the appropriate size.

• If you want to use functionality provided by input layers, you can specify a dlnetwork or layer array that has an input layer. The size of the input layer must be consistent with the number of variables after the component encodes the categorical predictors. To determine the size, you must consider the number of numeric variables and the number of categories in each categorical variable.

  If you standardize the predictors using the Standardize property, then the input layer of the network must not perform normalization.

Example: c = classificationCustomNeuralNetworkComponent(net)

Example: c.Network = [sequenceInputLayer(12),lstmLayer(100),fullyConnectedLayer(9),softmaxLayer]

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 = classificationCustomNeuralNetworkComponent(net,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 = classificationCustomNeuralNetworkComponent(net,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 = classificationCustomNeuralNetworkComponent(net,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 = classificationCustomNeuralNetworkComponent(net,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 = classificationCustomNeuralNetworkComponent(net,Lambda=1e-4)

Example: c.Lambda = 1e-2

Data Types: single | double

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 = classificationCustomNeuralNetworkComponent(net,LossTolerance=1e-8)

Example: c.LossTolerance = 1e-5

Data Types: single | double

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 = classificationCustomNeuralNetworkComponent(net,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 = classificationCustomNeuralNetworkComponent(net,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 = classificationCustomNeuralNetworkComponent(net,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 = classificationCustomNeuralNetwork(net,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

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

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

Example: c = classificationCustomNeuralNetworkComponent(net,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.

Example: c = classificationCustomNeuralNetworkComponent(net,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 = classificationCustomNeuralNetworkComponent(net,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.

Example: c = classificationCustomNeuralNetworkComponent(net,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 = classificationCustomNeuralNetworkComponent(net,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 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 Classification with Custom Neural Network

Load the ionosphere data set and save the data in two tables. The data set has 34 numeric predictors and classifies observations into two classes.

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

Define a custom neural network with a residual connection as a dlnetwork.

net = dlnetwork;

layers = [
    featureInputLayer(34,Name="input")
    fullyConnectedLayer(20,Name="fc1")
    reluLayer(Name="relu1")
    fullyConnectedLayer(20,Name="fc2")
    additionLayer(2,Name="add")
    reluLayer(Name="relu2")
    fullyConnectedLayer(2,Name="fc3")
    softmaxLayer(Name="softmax")
    ];

net = addLayers(net,layers);
net = connectLayers(net,"fc1","add/in2");

Create a classificationCustomNeuralNetworkComponent pipeline component using the custom network.

component = classificationCustomNeuralNetworkComponent(net)

component = 
  classificationCustomNeuralNetworkComponent with properties:

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

   
Learnables (HasLearned = false)
    TrainedModel: []

   
Structural Parameters (locked)
      UseWeights: 0

   
Learn Parameters (unlocked)
         Network: [1×1 dlnetwork]


Show all parameters

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

To decrease the maximum number of training iterations, set the IterationLimit property of the component to 500.

component.IterationLimit = 500;

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

component = learn(component,X,Y)

component = 
  classificationCustomNeuralNetworkComponent with properties:

              Name: "ClassificationCustomNeuralNetwork"
            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)
    IterationLimit: 500
           Network: [1×1 dlnetwork]


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.

Version History

Introduced in R2026b