incrementalLearner

R2026b

Convert neural network classification model to incremental learner

Since R2026b

Syntax

IncrementalMdl = incrementalLearner(Mdl)

IncrementalMdl = incrementalLearner(Mdl,Name=Value)

Description

IncrementalMdl = incrementalLearner(Mdl) creates an incrementalClassificationNeuralNetwork model object for incremental learning, IncrementalMdl, using the hyperparameters and parameters of the traditionally trained neural classification model, Mdl. Because its property values reflect the knowledge gained from Mdl, IncrementalMdl can predict labels given new observations.

IncrementalMdl = incrementalLearner(Mdl,Name=Value) uses additional options specified by one or more name-value arguments. For example, incrementalLearner(Mdl,Metrics="hinge",MetricsWarmupPeriod=1000)specifies to track the hinge loss performance metric, and sets the metrics warm-up period to 1000 observations.

Examples

Convert Traditionally Trained Model to Incremental Learner

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

Load Data

Load the human activity data set.

load humanactivity

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

Train Model

Fit an incremental neural network classification model to the entire data set. Standardize the predictor data.

Mdl = fitcnet(feat,actid,Standardize=true)

Mdl = 
  ClassificationNeuralNetwork
             ResponseName: 'Y'
    CategoricalPredictors: []
               ClassNames: [1 2 3 4 5]
           ScoreTransform: 'none'
          NumObservations: 24075
               LayerSizes: 10
              Activations: 'relu'
    OutputLayerActivation: 'softmax'
                   Solver: 'LBFGS'
          ConvergenceInfo: [1×1 struct]
          TrainingHistory: [522×7 table]


  Properties, Methods

Mdl is a ClassificationNeuralNetwork model object representing a traditionally trained neural network classification model.

Convert Trained Model

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

IncrementalMdl = incrementalLearner(Mdl)

IncrementalMdl = 
  incrementalClassificationNeuralNetwork

                   IsWarm: 0
                  Metrics: [1×2 table]
               ClassNames: [1 2 3 4 5]
           ScoreTransform: 'none'
               LayerSizes: 10
              Activations: "relu"
    OutputLayerActivation: "softmax"
                   Solver: "minibatch-lbfgs"


  Properties, Methods

IncrementalMdl is an incrementalClassificationNeuralNetwork model object prepared for incremental learning.

• The incrementalLearner function initializes the incremental learner by passing the neural network architecture and model parameters to it, along with other information Mdl extracts from the training data.

• IncrementalMdl is not warm (IsWarm is 0), which means that incremental learning functions can make predictions but do not track performance metrics.

Predict Responses

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

Predict classification scores for all observations using both models.

[~,ttscores] = predict(Mdl,feat);
[~,ilscores] = predict(IncrementalMdl,feat);
compareScores = norm(ttscores - ilscores)

compareScores = 
0

The difference between the scores generated by the models is 0.

Configure Performance Metric Options

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

Load the human activity data set. Randomly shuffle the data

load humanactivity
n = numel(actid);
rng(0,"twister") % For reproducibility
idx = randsample(n,n);
X = feat(idx,:);
Y = actid(idx);

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

Randomly split the data in half: the first half for training a model traditionally, and the second half for incremental learning.

cvp = cvpartition(n,Holdout=0.5);
idxtt = training(cvp);
idxil = test(cvp);

% First half of data
Xtt = X(idxtt,:);
Ytt = Y(idxtt);

% Second half of data
Xil = X(idxil,:);
Yil = Y(idxil);

Fit a neural network classification model to the first half of the data.

Mdl = fitcnet(Xtt,Ytt);

Convert the traditionally trained neural network classification 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

• Track the classification error metric

IncrementalMdl = incrementalLearner(Mdl, ...
    MetricsWarmupPeriod=2000,MetricsWindowSize=500, ...
    Metrics="classiferror");
IncrementalMdl.IsWarm

ans = logical
   0

IncrementalMdl is an incrementalClassificationNeuralNetwork model object and is not warm, indicating that the object does not yet track performance metrics.

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

• Simulate a data stream by processing 20 observations at a time.

• Overwrite the previous incremental model with a new one fitted to the incoming observations.

• Store the mean bias of the second layer, the cumulative metrics, and the window metrics to see how they evolve during incremental learning.

% Preallocation
nil = numel(Yil);
numObsPerChunk = 20;
nchunk = ceil(nil/numObsPerChunk);
ce = array2table(zeros(nchunk,2),VariableNames=["Cumulative","Window"]);
lb2 = zeros(nchunk,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));
    ce{j,:} = IncrementalMdl.Metrics{"ClassificationError",:};
    lb2(j) = mean(IncrementalMdl.LayerBiases{2});
end

IncrementalMdl is an incrementalClassificationNeuralNetwork 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.

To see how the performance metrics and the mean bias of the second layer evolve during training, plot them on separate tiles.

t = tiledlayout(2,1);
nexttile
plot(lb2)
ylabel("Mean Layer 2 Bias")
xlim([0 nchunk]);
xline(IncrementalMdl.TrainingOptions.TuningPeriod/numObsPerChunk,"b--");
xline((IncrementalMdl.TrainingOptions.TuningPeriod + ...
    IncrementalMdl.MetricsWarmupPeriod)/numObsPerChunk,"r-.");
nexttile
plot(ce.Variables);
xlim([0 nchunk]);
ylabel("Classification Error")
xline(IncrementalMdl.TrainingOptions.TuningPeriod/numObsPerChunk,"b--");
xline((IncrementalMdl.TrainingOptions.TuningPeriod + ...
    IncrementalMdl.MetricsWarmupPeriod)/numObsPerChunk,"r-.");
legend(ce.Properties.VariableNames,Location="best")
xlabel(t,"Iteration")

The plots indicate that updateMetricsAndFit performs the following actions:

• Fit the layer biases after the solver tuning period (blue vertical line) only.

• Compute the performance metrics after the metrics warm-up period (red vertical line) only.

• Compute the cumulative metrics during each iteration.

• Compute the window metrics after processing 500 observations (25 iterations).

The classification error slowly increases as the function processes more observations.

Input Arguments

Mdl — Traditionally trained neural network classification model

ClassificationNeuralNetwork model object

Traditionally trained neural network classification model, specified as a ClassificationNeuralNetwork model object returned by fitcnet. The model object cannot be trained on a layer array or a dlnetwork (Deep Learning Toolbox) object (Mdl.ModelParameters.Network property must be empty).

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

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,Metrics="classiferror") specifies to track the classification error.

Metrics — Model performance metrics to track during incremental learning

"mincost" (default) | string vector | function handle | cell vector | structure array | "classiferror" | "hinge" | "logit" | "quadratic" | "exponential" | "binodeviance" | "crossentropy"

Model performance metrics to track during incremental learning with the updateMetrics and updateMetricsAndFit function, specified as a built-in loss function name, string vector of names, function handle (@metricName), structure array of function handles, or cell vector of names, function handles, or structure arrays. The minimum expected misclassification cost ("mincost") metric is always tracked.

The following table lists the built-in loss function names. You can specify more than one by using a string vector.

Name	Description
"binodeviance"	Binomial deviance
"classiferror"	Classification error
"crossentropy"	Cross-entropy loss
"exponential"	Exponential loss
"hinge"	Hinge loss
"logit"	Logistic loss
"mincost" (default)	Minimum expected misclassification cost
"quadratic"	Quadratic loss

For more details on the built-in loss functions, see loss.

Example: Metrics=["classiferror","crossentropy"]

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

metric = customMetric(C,S,Cost)

• 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 (here, customMetric).

• C is an n-by-K logical matrix with rows indicating the class to which the corresponding observation belongs, where K is the number of classes. The column order corresponds to the class order in the ClassNames property. Create C by setting C(p,q) = 1, if observation p is in class q, for each observation in the specified data. Set the other element in row p to 0.

• S is an n-by-K numeric matrix of predicted classification scores. S is similar to the Score output of predict, where rows correspond to observations in the data and the column order corresponds to the class order in the ClassNames property. S(p,q) is the classification score of observation p being classified in class q.

• Cost is a K-by-K numeric matrix of misclassification costs. See the Cost name-value argument.

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,"logit",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
String or character vector	Name of corresponding built-in metric	Row name for "classiferror" is "ClassificationError"
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 @(C,S)customMetric(C,S)... is CustomMetric_1

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 Limited-Memory BFGS and FreeRex sections of the incrementalTrainingOptions reference page.

Example: TrainingOptions=incrementalTrainingOptions("freerex")

Output Arguments

IncrementalMdl — Neural network classification model for incremental learning

incrementalClassificationNeuralNetwork model object

Neural network classification model for incremental learning, returned as an incrementalClassificationNeuralNetwork 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
ClassNames	Class labels for classification
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)
Prior	Prior class label distribution
Lambda	Regularization term strength (stored in Mdl.ModelParameters and passed to IncrementalMdl.L2Regularization)
Cost	Misclassification cost matrix

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

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