regressionCustomNeuralNetworkComponent

R2026b

Pipeline component for regression using custom neural network model

Since R2026b

Description

regressionCustomNeuralNetworkComponent is a pipeline component that creates a neural network model for regression using custom architecture. The pipeline component uses the functionality of the fitrnet 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 = regressionCustomNeuralNetworkComponent(network)

component = regressionCustomNeuralNetworkComponent(Name=Value)

Description

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

component = regressionCustomNeuralNetworkComponent(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 = regressionCustomNeuralNetworkComponent(net)

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

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 = regressionCustomNeuralNetworkComponent(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 = regressionCustomNeuralNetworkComponent(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 = regressionCustomNeuralNetworkComponent(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 = regressionCustomNeuralNetworkComponent(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 = regressionCustomNeuralNetworkComponent(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 = regressionCustomNeuralNetworkComponent(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 = regressionCustomNeuralNetworkComponent(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

"mse" (default) | function handle

Loss function, specified as "mse" (mean squared error) or a function handle.

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

Example: c = regressionCustomNeuralNetworkComponent(net,LossFun=@lossfun)

Example: c.LossFun = "mse"

Data Types: char | string | function_handle

ResponseTransform — Function for transforming raw response values

"none" (default) | function handle | function name

Function for transforming raw response values, specified as a function handle or function name. The default is "none", which means @(y)y, or no transformation. The function must accept a vector (the original response values) and return a vector of the same size (the transformed response values).

Example: c = regressionCustomNeuralNetworkComponent(net,ResponseTransform=@(y)exp(y))

Example: c.ResponseTransform = "exp"

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

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

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

Example: c = regressionCustomNeuralNetworkComponent(net,Name="NeuralNetwork")

Example: c.Name = "NeuralNetworkRegression"

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 = regressionCustomNeuralNetworkComponent(net,Inputs=["X","Y"])

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

Data Types: char | string | cell

Outputs — Names of output ports

["Predictions","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 = regressionCustomNeuralNetworkComponent(net,Outputs=["Responses","LossVal"])

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

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

Example: c.InputTags = [1 0]

Data Types: single | double

OutputTags — Tags that enable automatic connection of component outputs

[1 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 = regressionCustomNeuralNetworkComponent(net,OutputTags=[0 1])

Example: c.OutputTags=[1 2]

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: CompactRegressionNeuralNetwork model object

This property is read-only.

Trained model, returned as a CompactRegressionNeuralNetwork 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 Regression with Custom Neural Network

Load the carsmall data set and save the data in two tables. Use the Cylinders, Displacement, Horsepower, and Weight variables as numeric predictors and the MPG variable as the response.

load carsmall
X = table(Cylinders,Displacement,Horsepower,Weight);
Y = table(MPG);

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

net = dlnetwork;

layers = [
    featureInputLayer(4,Name="input")
    fullyConnectedLayer(16,Name="fc1")
    reluLayer(Name="relu1")
    fullyConnectedLayer(16,Name="fc2")
    additionLayer(2,Name="add")
    reluLayer(Name="relu2")
    fullyConnectedLayer(1,Name="fc3")
    ];

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

Create a regressionCustomNeuralNetworkComponent pipeline component using the custom network.

component = regressionCustomNeuralNetworkComponent(net)

component = 
  regressionCustomNeuralNetworkComponent with properties:

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

   
Learnables (HasLearned = false)
    TrainedModel: []

   
Structural Parameters (locked)
      UseWeights: 0

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


Show all parameters

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

To standardize the predictor data, set the Standardize property to true.

component.Standardize = true;

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

component = learn(component,X,Y)

component = 
  regressionCustomNeuralNetworkComponent with properties:

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

   
Learnables (HasLearned = true)
    TrainedModel: [1×1 classreg.learning.regr.CompactRegressionNeuralNetwork]

   
Structural Parameters (locked)
      UseWeights: 0

   
Learn Parameters (locked)
     Standardize: 1
         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 predict the response values for new data using the run object function.

Version History

Introduced in R2026b