regressionNeuralNetworkComponent

Pipeline component for regression using neural network model

Since R2026a

Description

regressionNeuralNetworkComponent is a pipeline component that creates a feedforward, fully connected neural network for regression. 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 = regressionNeuralNetworkComponent

component = regressionNeuralNetworkComponent(Name=Value)

Description

component = regressionNeuralNetworkComponent creates a pipeline component for a neural network model for regression.

component = regressionNeuralNetworkComponent(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 the 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 = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(Activations="sigmoid")

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

Data Types: char | string | cell

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 = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(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 mean squared error (MSE) loss function and the ridge (L2) penalty term.

Example: c = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(LayerSizes=[100 25 10])

Example: c.LayerSizes = [50 20 10]

Data Types: single | double

LayerWeightsInitializer — Function 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 = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(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.

Example: c = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(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

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

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

Example: c = regressionNeuralNetworkComponent(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. If UseWeights is true, the component adds the input port "Weights" to Inputs.

Example: c = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(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. If UseWeights is true, the component adds a third input tag to InputTags.

Example: c = regressionNeuralNetworkComponent(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 = regressionNeuralNetworkComponent(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 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: 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 Neural Network Regression

Create a regressionNeuralNetworkComponent pipeline component.

component = regressionNeuralNetworkComponent

component = 
  regressionNeuralNetworkComponent with properties:

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

   
Learnables (HasLearned = false)
    TrainedModel: []

   
Structural Parameters (locked)
      UseWeights: 0


Show all parameters

component is a regressionNeuralNetworkComponent 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;

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

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

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

component = learn(component,X,Y)

component = 
  regressionNeuralNetworkComponent with properties:

            Name: "RegressionNeuralNetwork"
          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


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.

More About

Neural Network Structure

The default neural network regression model has the following 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 one output for each 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.
	Output — This layer corresponds to the predicted response values.

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