incrementalLearner

R2026b

Convert neural network regression model to incremental learner

Since R2026b

Syntax

IncrementalMdl = incrementalLearner(Mdl)

IncrementalMdl = incrementalLearner(Mdl,Name=Value)

Description

IncrementalMdl = incrementalLearner(Mdl) returns a neural network regression model for incremental learning, IncrementalMdl, using the traditionally trained neural network model in Mdl.

The property values of IncrementalMdl reflect the knowledge gained from Mdl (parameters and hyperparameters of the model). Therefore, IncrementalMdl can predict labels given new observations, and it is warm, meaning that its predictive performance is tracked.

example

IncrementalMdl = incrementalLearner(Mdl,Name=Value) uses additional options specified by one or more name-value arguments. Some options require you to train IncrementalMdl before its predictive performance is tracked. For example, MetricsWarmupPeriod=50,MetricsWindowSize=100 specifies a preliminary incremental training period of 50 observations before performance metrics are tracked, and specifies processing 100 observations before updating the window performance metrics.

example

Examples

collapse all

Convert Traditionally Trained Model to Incremental Learner

Open Live Script

Train a neural network regression model by using fitrnet, and then convert it to an incremental learner.

Load and Preprocess Data

Load the 2015 NYC housing data set. For more details on the data, see NYC Open Data.

load NYCHousing2015

Extract the response variable SALEPRICE from the table. For numerical stability, scale SALEPRICE by 1e6.

Y = NYCHousing2015.SALEPRICE/1e6;
NYCHousing2015.SALEPRICE = [];

To reduce computational cost for this example, remove the NEIGHBORHOOD column, which contains a categorical variable with 254 categories.

NYCHousing2015.NEIGHBORHOOD = [];

Create dummy variable matrices from the other categorical predictors.

catvars = ["BOROUGH","BUILDINGCLASSCATEGORY"];
dumvarstbl = varfun(@(x)dummyvar(categorical(x)),NYCHousing2015, ...
    InputVariables=catvars);
dumvarmat = table2array(dumvarstbl);
NYCHousing2015(:,catvars) = [];

Treat all other numeric variables in the table as predictors of sales price. Concatenate the matrix of dummy variables to the rest of the predictor data.

idxnum = varfun(@isnumeric,NYCHousing2015,OutputFormat="uniform");
X = [dumvarmat NYCHousing2015{:,idxnum}];

Train Neural Network Regression Model

Fit a neural network regression model to the entire data set. Standardize the predictor data.

Mdl = fitrnet(X,Y,Standardize=true)

Mdl = 
  RegressionNeuralNetwork
             ResponseName: 'Y'
    CategoricalPredictors: []
        ResponseTransform: 'none'
          NumObservations: 91446
               LayerSizes: 10
              Activations: 'relu'
    OutputLayerActivation: 'none'
                   Solver: 'LBFGS'
          ConvergenceInfo: [1×1 struct]
          TrainingHistory: [1000×7 table]


  Properties, Methods

Mdl is a RegressionNeuralNetwork model object representing a traditionally trained neural network regression model.

Convert Trained Model

Convert the traditionally trained neural network regression model to a model for incremental learning.

IncrementalMdl = incrementalLearner(Mdl)

IncrementalMdl = 
  incrementalRegressionNeuralNetwork

                   IsWarm: 0
                  Metrics: [1×2 table]
        ResponseTransform: 'none'
               LayerSizes: 10
              Activations: "relu"
    OutputLayerActivation: "none"
                   Solver: "minibatch-lbfgs"


  Properties, Methods

IncrementalMdl is an incrementalRegressionNeuralNetwork model object prepared for incremental learning.

The incrementalLearner function initializes the incremental learner by passing model parameters to it, along with other information Mdl extracted from the training data.
IncrementalMdl is not warm (IsWarm is 0), which means that incremental learning functions do not start tracking performance metrics.

Predict Responses

An incremental learner created from converting a traditionally trained model can generate predictions without further processing.

Predict sales prices for all observations using both models.

ttyfit = predict(Mdl,X);
ilyfit = predict(IncrementalMdl,X);
compareyfit = norm(ttyfit - ilyfit)

compareyfit = 
0

The difference between the fitted values generated by the models is 0.

Configure Performance Metric Options

Open Live Script

Use a trained neural network regression model to initialize an incremental learner. Prepare the incremental learner by specifying a metrics warm-up period and a metrics window size.

Load the robot arm data set.

load robotarm

For details on the data set, enter Description at the command line.

Randomly partition the data into 5% and 95% sets: the first set for training a model traditionally, and the second set for incremental learning.

n = numel(ytrain);

rng(1) % For reproducibility
cvp = cvpartition(n,Holdout=0.95);
idxtt = training(cvp);
idxil = test(cvp);

% 5% set for traditional training
Xtt = Xtrain(idxtt,:);
Ytt = ytrain(idxtt);

% 95% set for incremental learning
Xil = Xtrain(idxil,:);
Yil = ytrain(idxil);

Fit a neural network regression model to the first set.

TTMdl = fitrnet(Xtt,Ytt);

Convert the traditionally trained neural network regression model to a model for incremental learning. Specify the following:

A performance metrics warm-up period of 2000 observations.
A metrics window size of 500 observations.
Use of MSE and mean absolute error (MAE) to measure the performance of the model. The software supports MSE. Create an anonymous function that measures the absolute error of each new observation. Create a structure array containing the name MeanAbsoluteError and its corresponding function.

maefcn = @(z,zfit)abs(z - zfit);
maemetric = struct(MeanAbsoluteError=maefcn);
IncrementalMdl = incrementalLearner(TTMdl,MetricsWarmupPeriod=2000,MetricsWindowSize=500, ...
    Metrics={"mse",maemetric});

Fit the incremental model to the rest of the data by using the updateMetricsAndFit function. At each iteration:

Simulate a data stream by processing 50 observations at a time.
Overwrite the previous incremental model with a new one fitted to the incoming observations.
Store the cumulative metrics, window metrics, and number of training observations to see how they evolve during incremental learning.

% Preallocation
nil = numel(Yil);
numObsPerChunk = 50;
nchunk = floor(nil/numObsPerChunk);
mse = array2table(zeros(nchunk,2),VariableNames=["Cumulative","Window"]);
mae = array2table(zeros(nchunk,2),VariableNames=["Cumulative","Window"]);
numtrainobs = [IncrementalMdl.NumTrainingObservations; zeros(nchunk+1,1)];

% Incremental fitting
for j = 1:nchunk
    ibegin = min(nil,numObsPerChunk*(j-1) + 1);
    iend   = min(nil,numObsPerChunk*j);
    idx = ibegin:iend;    
    IncrementalMdl = updateMetricsAndFit(IncrementalMdl,Xil(idx,:),Yil(idx));
    mse{j,:} = IncrementalMdl.Metrics{"MeanSquaredError",:};
    mae{j,:} = IncrementalMdl.Metrics{"MeanAbsoluteError",:};
    numtrainobs(j+1) = IncrementalMdl.NumTrainingObservations;
end

IncrementalMdl is an incrementalRegressionNeuralNetwork model object trained on all the data in the stream. During incremental learning and after the model is warmed up, updateMetricsAndFit checks the performance of the model on the incoming observations, and then fits the model to those observations.

Plot a trace plot of the number of training observations and the performance metrics on separate tiles.

t = tiledlayout(4,1);
nexttile
plot(numtrainobs)
xlim([0 nchunk])
xline(IncrementalMdl.TrainingOptions.TuningPeriod/numObsPerChunk,"b--")
ylabel(["Number of Training","Observations"])
nexttile
plot(mse.Variables)
xlim([0 nchunk])
ylabel("MSE")
xline((IncrementalMdl.TrainingOptions.TuningPeriod + ...
    IncrementalMdl.MetricsWarmupPeriod)/numObsPerChunk,"r--")
nexttile
plot(mae.Variables)
xlim([0 nchunk])
ylabel("MAE")
xline((IncrementalMdl.TrainingOptions.TuningPeriod + ...
    IncrementalMdl.MetricsWarmupPeriod)/numObsPerChunk,"r--")
xlabel(t,"Iteration")

Figure contains 3 axes objects. Axes object 1 with ylabel Number of Training Observations contains 2 objects of type line, constantline. Axes object 2 with ylabel MSE contains 3 objects of type line, constantline. Axes object 3 with ylabel MAE contains 3 objects of type line, constantline.

The plot suggests that updateMetricsAndFit does the following:

Fit the model during all incremental learning iterations after the solver tuning period.
Compute the performance metrics after the solver tuning period and metrics warm-up period only.
Compute the cumulative metrics during each iteration.
Compute the window metrics after processing 500 observations.

Input Arguments

collapse all

`Mdl` — Traditionally trained neural network regression model
`RegressionNeuralNetwork` model object

Traditionally trained neural network regression model, specified as a RegressionNeuralNetwork model object returned by fitrnet.

Note

Incremental learning functions support only numeric input predictor data. If Mdl was trained on categorical data, you must prepare an encoded version of the categorical data to use incremental learning functions. Use dummyvar to convert each categorical variable to a numeric matrix of dummy variables. Then, concatenate all dummy variable matrices and any other numeric predictors, in the same way that the training function encodes categorical data. For more details, see Dummy Variables.

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: incrementalLearner(Mdl,MetricsWindowSize=100) specifies processing 100 observations before updating the window performance metrics.

`Metrics` — Model performance metrics to track during incremental learning
`"mse"` (default) | function handle | cell vector | structure array | ...

Model performance metrics to track during incremental learning with updateMetrics and updateMetricsAndFit, specified as "mse", a function handle (@metricName), a structure array of function handles, or a cell vector of function handles or structure arrays. The default setting ("mse") is the weighted mean squared error.

For more information, see loss.

Example: Metrics=@myMetricsFun

To specify a custom function that returns a performance metric, use function handle notation. The function must have this form:

metric = customMetric(Y,YFit)

The output argument metric is an n-by-1 numeric vector, where each element is the loss of the corresponding observation in the data processed by the incremental learning functions during a learning cycle.
You select the function name (customMetric).
Y is a length n numeric vector of observed responses, where n is the sample size.
YFit is a length n numeric vector of corresponding predicted responses.

To specify multiple custom metrics and assign a custom name to each, use a structure array. To specify a combination of built-in and custom metrics, use a cell vector.

Example: Metrics=struct("Metric1",@customMetric1,"Metric2",@customMetric2)

Example: Metrics={@customMetric1 @customMetric2 'mse' struct(Metric3=@customMetric3)}

updateMetrics and updateMetricsAndFit store specified metrics in a table in the property IncrementalMdl.Metrics. The data type of Metrics determines the row names of the table.

`Metrics` Value Data Type	Description of `Metrics` Property Row Name	Example
Structure array	Field name	Row name for `struct(Metric1=@customMetric1)` is `"Metric1"`
Function handle to function stored in a program file	Name of function	Row name for `@customMetric` is `"customMetric"`
Anonymous function	`CustomMetric_j`, where `j` is metric `j` in `Metrics`	Row name for `@(Y,YFit)customMetric(Y,YFit)...` is `CustomMetric_1`

For more details on performance metrics options, see Performance Metrics.

Data Types: char | string | struct | cell | function_handle

`MetricsWarmupPeriod` — Number of observations to fit during warm-up period
`0` (default) | nonnegative integer

Number of observations to fit during the metrics warm-up period, specified as a nonnegative integer. The metrics warm-up period takes place after the solver tuning period and estimation period (if specified). The metrics warm-up period is completed when the incremental fitting functions have processed MetricsWarmupPeriod observations and at least one observation from each expected class. After the metrics warm-up period, the model object is warm and the incremental fitting functions compute and store performance metrics.

For more details, see Incremental Training Periods.

Example: MetricsWarmupPeriod=50

Data Types: single | double

`MetricsWindowSize` — Number of observations to use to compute window performance metrics
`200` (default) | positive integer

Number of observations to use to compute window performance metrics, specified as a positive integer.

For more details on performance metrics options, see Performance Metrics.

Example: MetricsWindowSize=250

Data Types: single | double

`TrainingOptions` — Solver training options
`TrainingOptionsMiniBatchLBFGS` object | `TrainingOptionsFREEREX` object

Solver training options, specified as a TrainingOptionsMiniBatchLBFGS or TrainingOptionsFREEREX object returned by incrementalTrainingOptions. The training options specify the solver algorithm and its hyperparameters. For more information about solver algorithms, see the Limited-Memory BFGS and FreeRex sections of the incrementalTrainingOptions reference page.

Example: TrainingOptions=incrementalTrainingOptions("freerex")

Output Arguments

collapse all

`IncrementalMdl` — Neural network regression model for incremental learning
`incrementalRegressionNeuralNetwork` model object

Neural network regression model for incremental learning, returned as an incrementalRegressionNeuralNetwork model object. IncrementalMdl is also configured to generate predictions given new data (see predict).

The incrementalLearner function initializes IncrementalMdl for incremental learning using the model information in Mdl. The following table shows the Mdl properties that incrementalLearner passes to corresponding properties of IncrementalMdl.

Property	Description
`LayerSizes`	Sizes of fully connected layers
`Activations`	Activation functions for fully connected layers
`LayerWeights`	Trained layer weight matrices,
`LayerWeightsInitializer`	Initialization method for layer weights (stored in `Mdl.ModelParameters`)
`LayerBiases`	Trained layer bias vectors
`LayerBiasesInitializer`	Initialization method for layer biases (stored in `Mdl.ModelParameters`)
`Mu`	Predictor variable means
`Sigma`	Predictor variable standard deviations
`NumPredictors`	Number of predictors (inferred from the `X` property of `Mdl`)
`Lambda`	Regularization term strength (stored in `Mdl.ModelParameters` and passed to `IncrementalMdl.L2Regularization`)
`ResponseMean`	Mean of response variable. The function passes this property when `StandardizeResponses=true`.
`ResponseStandardDeviation`	Standard deviation of response variable. The function passes this property when `StandardizeResponses=true`.

If you specify TrainingOptions, the function passes to IncrementalMdl.L2Regularization the L2Regularization property value of the incremental training options object (default value = 1e-5) instead of the Lambda property value of Mdl.

The function always sets the EstimationPeriod property of IncrementalMdl to 0. The incremental model uses the Mu and Sigma values of Mdl to standardize the predictor data. If Mu and Sigma are empty, the predictor data is not standardized.

When you create Mdl, the model is warm when MetricsWarmupPeriod is 0 and either of the following is true:

Solver is "freerex"
Solver is "minibatch-lbfgs" and Mdl.TrainingOptions.TuningPeriod is 0.

You can specify Solver and TuningPeriod using the TrainingOptions name-value argument.

More About

collapse all

Incremental Learning

Incremental learning, or online learning, is a branch of machine learning concerned with processing incoming data from a data stream, possibly given little to no knowledge of the distribution of the predictor variables, aspects of the prediction or objective function (including tuning parameter values), or whether the observations are labeled. Incremental learning differs from traditional machine learning, where enough labeled data is available to fit to a model, perform cross-validation to tune hyperparameters, and infer the predictor distribution.

Given incoming observations, an incremental learning model processes data in any of the following ways, but usually in this order:

Predict labels.
Measure the predictive performance.
Check for structural breaks or drift in the model.
Fit the model to the incoming observations.

For more details, see Incremental Learning Overview.

Incremental Training Periods

When you train an incremental neural network model with the incremental fitting functions fit and updateMetricsAndFit, then depending on the model's properties, up to three incremental training periods can occur in the following order: the estimation period, the solver tuning period, and the metrics warm-up period. Following these periods, the incremental model is warm and the incremental fitting functions track model performance metrics from new data.

Estimation Period

During the estimation period, fit does not fit the model, and updateMetricsAndFit does not fit the model or update the performance metrics. The incremental fitting functions use the first incoming EstimationPeriod observations to estimate the predictor means and standard deviation hyperparameters required to standardize the data during incremental training. The fitting functions store the hyperparameter estimates in the Mu and Sigma properties of Mdl.

The hyperparameters are estimated when both of these conditions apply:

Incremental fitting functions are configured to standardize predictor data (see Standardize Data).
Mu and Sigma are empty arrays [].

When you create the model object using the incrementalLearner function, EstimationPeriod is always 0.

Solver Tuning Period

During the solver tuning period, the incremental fitting functions use Mdl.TrainingOptions.TuningPeriod observations to tune the parameters of the mini-batch LBFGS solver (the default solver). There is no solver turning period for the FreeREX solver. You can select the solver algorithm and the length of the solver tuning period using the TrainingOptions name-value argument when you create the model object. For more information, see the Limited-Memory BFGS and FreeRex sections of the incrementalTrainingOptions reference page.

Metrics Warm-Up Period

During the metrics warm-up period, the incremental fitting functions fit the incremental model.

An incrementalClassificationNeuralNetwork model object is warm and tracks the performance metrics in its Metrics property after the incremental fitting functions process MetricsWarmupPeriod observations and fit at least one observation from each expected class (see the MaxNumClasses and ClassNames arguments of incrementalClassificationNeuralNetwork).
An incrementalRegressionNeuralNetwork model object is warm after the incremental fitting functions process MetricsWarmupPeriod observations.

Performance Metrics

The updateMetrics and updateMetricsAndFit functions track model performance metrics from new data only when the incremental model is warm (IsWarm property is true).
The Metrics property of the incremental model stores two forms of each performance metric as variables (columns) of a table, Cumulative and Window, with individual metrics in rows. When the incremental model is warm, updateMetrics and updateMetricsAndFit update the metrics at the following frequencies:
- Cumulative — The functions compute cumulative metrics since the start of model performance tracking. The functions update metrics every time you call the functions and base the calculation on the entire supplied data set.
- Window — The functions compute metrics based on all observations within a window determined by the MetricsWindowSize name-value argument. MetricsWindowSize also determines the frequency at which the software updates Window metrics. For example, if MetricsWindowSize is 20, the functions compute metrics based on the last 20 observations in the supplied data (X((end – 20 + 1):end,:) and Y((end – 20 + 1):end)).
  Incremental functions that track performance metrics within a window use the following process:
  1. Store a buffer of length MetricsWindowSize for each specified metric, and store a buffer of observation weights.
  2. Populate elements of the metrics buffer with the model performance based on batches of incoming observations, and store corresponding observation weights in the weights buffer.
  3. When the buffer is full, overwrite Mdl.Metrics.Window with the weighted average performance in the metrics window. If the buffer overfills when the function processes a batch of observations, the latest incoming MetricsWindowSize observations enter the buffer, and the earliest observations are removed from the buffer. For example, suppose MetricsWindowSize is 20, the metrics buffer has 10 values from a previously processed batch, and 15 values are incoming. To compose the length 20 window, the functions use the measurements from the 15 incoming observations and the latest 5 measurements from the previous batch.

The incremental fitting functions omit an observation with a NaN score when computing the Cumulative and Window performance metric values.

Version History

Introduced in R2026b

incrementalLearner

Syntax

Description

Examples

Convert Traditionally Trained Model to Incremental Learner

Configure Performance Metric Options

Input Arguments

`Mdl` — Traditionally trained neural network regression model
`RegressionNeuralNetwork` model object

Name-Value Arguments

`Metrics` — Model performance metrics to track during incremental learning
`"mse"` (default) | function handle | cell vector | structure array | ...

`MetricsWarmupPeriod` — Number of observations to fit during warm-up period
`0` (default) | nonnegative integer

`MetricsWindowSize` — Number of observations to use to compute window performance metrics
`200` (default) | positive integer

`TrainingOptions` — Solver training options
`TrainingOptionsMiniBatchLBFGS` object | `TrainingOptionsFREEREX` object

Output Arguments

`IncrementalMdl` — Neural network regression model for incremental learning
`incrementalRegressionNeuralNetwork` model object

More About

Incremental Learning

Incremental Training Periods

Performance Metrics

Version History

See Also

Objects

Functions

Topics

incrementalLearner

Syntax

Description

Examples

Convert Traditionally Trained Model to Incremental Learner

Configure Performance Metric Options

Input Arguments

Mdl — Traditionally trained neural network regression model RegressionNeuralNetwork model object

Name-Value Arguments

Metrics — Model performance metrics to track during incremental learning "mse" (default) | function handle | cell vector | structure array | ...

MetricsWarmupPeriod — Number of observations to fit during warm-up period 0 (default) | nonnegative integer

MetricsWindowSize — Number of observations to use to compute window performance metrics 200 (default) | positive integer

TrainingOptions — Solver training options TrainingOptionsMiniBatchLBFGS object | TrainingOptionsFREEREX object

Output Arguments

IncrementalMdl — Neural network regression model for incremental learning incrementalRegressionNeuralNetwork model object

More About

Incremental Learning

Incremental Training Periods

Performance Metrics

Version History

See Also

Objects

Functions

Topics

`Mdl` — Traditionally trained neural network regression model
`RegressionNeuralNetwork` model object

`Metrics` — Model performance metrics to track during incremental learning
`"mse"` (default) | function handle | cell vector | structure array | ...

`MetricsWarmupPeriod` — Number of observations to fit during warm-up period
`0` (default) | nonnegative integer

`MetricsWindowSize` — Number of observations to use to compute window performance metrics
`200` (default) | positive integer

`TrainingOptions` — Solver training options
`TrainingOptionsMiniBatchLBFGS` object | `TrainingOptionsFREEREX` object

`IncrementalMdl` — Neural network regression model for incremental learning
`incrementalRegressionNeuralNetwork` model object