incrementalNormalizer

Instantiate incremental data normalizer

Since R2026a

collapse all in page

Syntax

Normalizer = incrementalNormalizer("zscore")
Normalizer = incrementalNormalizer("exponentiallyweighted")
Normalizer = incrementalNormalizer("classweighted",ClassNames,Prior)
Normalizer = incrementalNormalizer(___,Name=Value)

Description

Use incrementalNormalizer to create an incremental data normalizer model that transforms streaming data into z-scores. To normalize nonstreaming data, use zscore or normalize.

Normalizer = incrementalNormalizer("zscore") creates a default ZScoreNormalizer model object for simple-weighted normalization of streaming data.

You can also create a default ZScoreNormalizer model object using Normalizer = incrementalNormalizer.

example

Normalizer = incrementalNormalizer("exponentiallyweighted") creates a default ExponentiallyWeightedNormalizer model object for exponentially weighted normalization of streaming data.

example

Normalizer = incrementalNormalizer("classweighted",ClassNames,Prior) creates a default ClassWeightedNormalizer model object for class-weighted normalization of streaming data, with the class names ClassNames and class priors Prior. You can use a ClassWeightedNormalizer object to normalize input data for supervised classification models.

example

Normalizer = incrementalNormalizer(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in the previous syntaxes (except Normalizer = incrementalNormalizer). For example, Normalizer=incrementalNormalizer("exponentiallyweighted",ForgettingFactor=0.9) creates an ExponentiallyWeightedNormalizer object that gives more weight to newer observations than older ones.

Examples

collapse all

Open Live Script

Create a default model for incremental normalization and display its properties.

Normalizer = incrementalNormalizer;
details(Normalizer)
  incremental.preprocessing.ZScoreNormalizer with properties:

               SumOfWeights: [1×0 double]
                  ScaleData: 1
                     Center: [1×0 double]
                      Scale: [1×0 double]
             PredictorNames: []
                     IsWarm: 1
    NumTrainingObservations: 0
              NumPredictors: 0
               WarmupPeriod: 0
             TrainingPeriod: Inf
            UpdateFrequency: 1
      CategoricalPredictors: []

  Methods, Superclasses

Normalizer is a ZScoreNormalizer model object. All its properties are read-only. The properties of Normalizer affect how the incremental fit function processes chunks of data as follows:

  • fit returns normalized data (IsWarm=true).

  • The ScaleData value is true, meaning that the normalized data is centered (mean = 0) and scaled (standard deviation = 1).

  • The UpdateFrequency value is 1, meaning that fit updates the Center (mean) and Scale (standard deviation) values of Normalizer each time it processes an observation.

  • The TrainingPeriod value is Inf, meaning that the Center and Scale values of Normalizer are never fixed.

  • Because NumPredictors=0, fit sets the NumPredictors value equal to the number of predictors in the input data.

Generate Simulated Data

Generate a data set X that contains 1000 observations of two simulated Gaussian noise signals. The first signal has zero mean and a standard deviation of 1, and the second signal has a mean of 2 and a standard deviation of 2.

rng(0,"twister"); % For reproducibility
n = 1000;
X = [randn(n,1),2*randn(n,1)+2];

Plot the data set.

plot(X)
xlabel("Observation")
ylabel("X",Rotation=0)
legend(["Signal 1","Signal 2"])

Figure contains an axes object. The axes object with xlabel Observation, ylabel X contains 2 objects of type line. These objects represent Signal 1, Signal 2.

Perform Incremental Learning

Fit the incremental model Normalizer to the data by using the fit function. To simulate a data stream, fit the model in chunks of 50 observations at a time. At each iteration:

  • Process 50 observations.

  • Call the incremental fit function to overwrite the previous incremental normalizer model Normalizer with a new one fitted to the incoming observations.

  • Store center, the fitted Center values of Normalizer, to see how the values evolve during incremental learning.

  • Store scale, the fitted Scale values of Normalizer, to see how the values evolve during incremental learning.

  • Store XNormalized, the normalized data chunk, to see how it evolves during incremental learning. 

numObsPerChunk = 50;
nchunk = floor(n/numObsPerChunk);
center = zeros(nchunk,2);
scale = zeros(nchunk,2); 
XNormalized = [];
% Incremental normalization
for j = 1:nchunk
    ibegin = min(n,numObsPerChunk*(j-1) + 1);
    iend = min(n,numObsPerChunk*j);
    idx = ibegin:iend;    
    [Normalizer,normalized] = fit(Normalizer,X(idx,:));
    center(j,:) = Normalizer.Center;
    scale(j,:) = Normalizer.Scale;
    XNormalized = [XNormalized;normalized];
end

Display the properties of the incremental normalizer model after the final iteration.

details(Normalizer)
  incremental.preprocessing.ZScoreNormalizer with properties:

               SumOfWeights: [1000 1000]
                  ScaleData: 1
                     Center: [-0.0326 2.0738]
                      Scale: [0.9985 1.9962]
             PredictorNames: ["x1"    "x2"]
                     IsWarm: 1
    NumTrainingObservations: 1000
              NumPredictors: 2
               WarmupPeriod: 0
             TrainingPeriod: Inf
            UpdateFrequency: 1
      CategoricalPredictors: []

  Methods, Superclasses

The model is trained on all the data in the stream. The Center and Scale values are approximately equal to the true means and standard deviations of the input signals.

Analyze Model During Incremental Learning

At the end of each iteration, the fit function updates the Center and Scale values of the model object using the observations in the data chunk. The function then returns a transformed version of the data chunk that is normalized using the updated values of Center and Scale.

To see how the Center and Scale values evolve during training, plot them on separate tiles.

figure
tiledlayout(2,1);
nexttile
plot(center,"o-")
xlabel("Iteration")
ylabel("Center")
nexttile
plot(scale,"o-")
xlabel("Iteration")
ylabel("Scale")

Figure contains 2 axes objects. Axes object 1 with xlabel Iteration, ylabel Center contains 2 objects of type line. Axes object 2 with xlabel Iteration, ylabel Scale contains 2 objects of type line.

The Center and Scale values approach the true means and standard deviations of the input signals after approximately 10 iterations.

Plot the normalized signal data, and then display the means and standard deviations.

figure
plot(XNormalized)
xlabel("Observation")
ylabel("XNormalized")
legend(["Signal 1","Signal 2"])

Figure contains an axes object. The axes object with xlabel Observation, ylabel XNormalized contains 2 objects of type line. These objects represent Signal 1, Signal 2.

display(mean(XNormalized))
   -0.0323   -0.0318

display(std(XNormalized))
    0.9576    0.9786

The normalized signals have means close to zero and standard deviations close to 1.

Compute the z-scores for the entire data set using the zscore function. Plot the absolute percentage difference between the normalized signal values and the z-scores.

zscores = zscore(X);
figure
plot(100*abs(XNormalized-zscores)/zscores)
xlabel("Observation")
ylabel("Absolute Percentage Difference")
legend(["Signal 1","Signal 2"])

Figure contains an axes object. The axes object with xlabel Observation, ylabel Absolute Percentage Difference contains 1000 objects of type line. These objects represent Signal 1, Signal 2.

The plot indicates that after the normalizer processes approximately 600 observations, the z-scores and the normalized signal values differ by less than one percent.

Open Live Script

Generate a data set X that contains 1000 observations of a simulated Gaussian noise signal with a standard deviation of 0.05. The signal has an initial mean of 1, which increases linearly after the 500th observation.

rng(0,"twister"); % For reproducibility
n = 1000;
m = 500;
initialMu = 1;
sigma = 0.05;
driftRate = 1/1000;
X = initialMu + sigma*randn(m,1);
t = (1:n-m)';
X = [X; initialMu + t*driftRate + sigma*randn(n-m,1)];

Plot the data set.

plot(X)
xlabel("Observation")
ylabel("X",Rotation=0)

Figure contains an axes object. The axes object with xlabel Observation, ylabel X contains an object of type line.

Create Incremental Normalization Model

Create an exponentially weighted incremental normalization model with an initial Center (mean) value of 1 and a Scale (standard deviation) value of 0.05, based on 10 prior observations. Display the properties of the model object. 

Normalizer = incrementalNormalizer("exponentiallyweighted", ...
    Center=1,Scale=0.05,NumObservations=10);
details(Normalizer)
  incremental.preprocessing.ExponentiallyWeightedNormalizer with properties:

               SumOfWeights: 10
           ForgettingFactor: 0.0500
                  ScaleData: 1
                     Center: 1
                      Scale: 0.0500
             PredictorNames: "x1"
                     IsWarm: 1
    NumTrainingObservations: 0
              NumPredictors: 1
               WarmupPeriod: 0
             TrainingPeriod: Inf
            UpdateFrequency: 1
      CategoricalPredictors: []

  Methods, Superclasses

Normalizer is an ExponentiallyWeightedNormalizer model object. All its properties are read-only. The properties of Normalizer affect how the software processes chunks of data as follows:

  • The incremental fit function returns normalized data (IsWarm=true).

  • The ScaleData value is true, meaning that the normalized data is centered (mean = 0) and scaled (standard deviation = 1).

  • fit updates the Center and Scale values of the model each time it processes an observation (UpdateFrequency=1).

  • The value of ForgettingFactor (0.05) is greater than zero, meaning that fit assigns higher weight to newer observations.

  • The TrainingPeriod value is Inf, meaning that the Center and Scale values of the model are never fixed.

Perform Incremental Fitting

To simulate a data stream, process the data in chunks of 50 observations at a time. At each iteration:

  • Process 50 observations.

  • If the mean of the data chunk is within one standard deviation of the signal's initial mean, transform the data chunk using the current model. Otherwise, overwrite the previous incremental model with a new one fitted to the incoming observations, and then transform the data chunk using the updated values of Center and Scale.

  • Store center, the fitted Center value of Normalizer, to see it evolves during incremental learning.

  • Store scale, the fitted Scale value of Normalizer, to see how it evolves during incremental learning.

  • Store XNormalized, the normalized data chunk, to see how it evolves during incremental learning. 

numObsPerChunk = 50;
nchunk = floor(n/numObsPerChunk);
center = zeros(nchunk,1);
scale = zeros(nchunk,1); 
XNormalized = [];
% Incremental normalization
for j = 1:nchunk
    ibegin = min(n,numObsPerChunk*(j-1) + 1);
    iend = min(n,numObsPerChunk*j);
    idx = ibegin:iend;
    chunkMu = mean(X(idx));
    if abs(chunkMu - initialMu) < sigma
        normalized = transform(Normalizer,X(idx));
    else
        [Normalizer,normalized] = fit(Normalizer,X(idx));
    end
    center(j) = Normalizer.Center;
    scale(j) = Normalizer.Scale;
    XNormalized = [XNormalized;normalized];
end

Analyze Incremental Model During Training

To see how the Center and Scale values evolve during training, plot them on separate tiles.

figure
tiledlayout(2,1);
nexttile
plot(center,"o-")
xlabel("Iteration")
ylabel("Center")
nexttile
plot(scale,"o-")
xlabel("Iteration")
ylabel("Scale")

Figure contains 2 axes objects. Axes object 1 with xlabel Iteration, ylabel Center contains an object of type line. Axes object 2 with xlabel Iteration, ylabel Scale contains an object of type line.

The Center and Scale values closely track the signal's mean and standard deviation values during the first 11 iterations. After the signal's mean starts to drift, the Center value continues to track the signal's mean, and the Scale value fluctuates slightly around the signal's standard deviation value.

Plot the normalized signal data, and then display its mean and standard deviation.

figure
plot(XNormalized)
xlabel("Observation")
ylabel("XNormalized")

Figure contains an axes object. The axes object with xlabel Observation, ylabel XNormalized contains an object of type line.

display(mean(XNormalized))
   -0.0180

display(std(XNormalized))
    0.9880

The normalized signal has a mean close to zero and a standard deviation close to 1.

Open Live Script

Load the human activity data set. The data set contains 24,075 observations of five physical human activities: sitting, standing, walking, running, and dancing. Each observation has 60 features extracted from acceleration data measured by smartphone accelerometer sensors.

rng(0,"twister") % For reproducibility
load humanactivity
n = numel(actid);
classes = unique(actid);

Display a bar chart of the feature means.

bar(mean(feat))
xlabel("Feature")
ylabel("Mean Value")

Figure contains an axes object. The axes object with xlabel Feature, ylabel Mean Value contains an object of type bar.

The plot shows that feature 56 has a significantly higher mean than the other features. This result suggests that it is useful to normalize the data prior to incremental learning by converting the data to z-scores, which have a mean of zero and a standard deviation of 1.

Create Incremental Learning Models

For the purposes of this example, perform incremental learning using three methods:

  • Normalize the incoming data using simple weighting, and then fit the normalized data using a classification ECOC model that does not perform normalization.

  • Normalize the incoming data using class weighting, and then fit the normalized data using a classification ECOC model that does not perform normalization.

  • Fit the incoming data using a classification ECOC model that performs normalization.

Create an incremental normalizer model named normalizerSW that uses simple weighting. 

normalizerSW = incrementalNormalizer("zscore");

Create an incremental normalizer model named normalizerCW that uses class-weighted normalization. Use the activity class numbers in actid as the class names, and assign prior probabilities based on the frequencies of the activity classes in the data.

frequencies = histcounts(feat, [classes; max(classes) + 1])/n;
normalizerCW = incrementalNormalizer("classweighted",classes,frequencies);

Create two incremental classification ECOC models for multiclass learning. First, configure binary learner properties by creating an incrementalClassificationLinear object. Set the linear classification model type (Learner) to logistic regression, use the sgd solver, and specify to not normalize the input data. 

binaryMdl = incrementalClassificationLinear(Learner="logistic", ...
    Standardize=false,Solver="sgd");

Configure the incremental ECOC models as follows:

  • Set the maximum number of classes equal to the number of activity states in the data.

  • Specify a metrics warm-up period of 5000 observations.

  • Specify a metrics window size of 500 observations.

  • Specify to use the binary learner binaryMdl for the learners.

mdlSW = incrementalClassificationECOC(MaxNumClasses=length(classes), ...
    MetricsWarmupPeriod=5000,MetricsWindowSize=500,Learners=binaryMdl);
mdlCW = incrementalClassificationECOC(MaxNumClasses=length(classes), ...
    MetricsWarmupPeriod=5000,MetricsWindowSize=500,Learners=binaryMdl);

Create a third incremental ECOC model that normalizes the input data and does not use binaryMdl.

mdl = incrementalClassificationECOC(MaxNumClasses=length(classes), ...
    MetricsWarmupPeriod=5000,MetricsWindowSize=500);

mdlSW, mdlCW, and mdl are incrementalClassificationECOC model objects configured for incremental learning. By default, incrementalClassificationECOC uses classification error loss to measure the performance of the model.

Perform Incremental Fitting

Fit the incremental models to the data by using the fit and updateMetricsAndFit functions. At each iteration:

  • Simulate a data stream by processing a chunk of 50 observations.

  • Call the updateMetricsAndFit function to overwrite the incremental ECOC model mdl with a new one fitted to the unnormalized data, and to update the performance metrics.

  • Call the incremental fit function to overwrite the previous simple-weighted incremental normalizer model NormalizerSW with a new one fitted to the incoming observations. Return the normalized data normalized.

  • Store the center (mean) and scale (standard deviation) values of NormalizerSW to see how they evolve during incremental learning.

  • Call the updateMetricsAndFit function to overwrite the previous incremental ECOC model mdlSW with a new one fitted to the normalized data, and to update the performance metrics.

  • Store the cumulative and window metrics of mdlSW to see how they evolve during incremental learning.

  • Repeat the previous four steps using the class-weighted incremental normalizer model NormalizerCW and the incremental ECOC model mdlCW.

During incremental learning, after each model is warmed up, updateMetricsAndFit checks the performance of the model on the incoming observations, and then fits the model to those observations.

% Preallocation
numObsPerChunk = 50;
nchunk = floor(n/numObsPerChunk);
ceSW = array2table(zeros(nchunk,2),VariableNames=["Cumulative","Window"]);
ceCW = array2table(zeros(nchunk,2),VariableNames=["Cumulative","Window"]);
ce = array2table(zeros(nchunk,2),VariableNames=["Cumulative","Window"]);
centerSW = zeros(nchunk,60);
scaleSW = zeros(nchunk,60);
centerCW = zeros(nchunk,60);
scaleCW = zeros(nchunk,60);

% Incremental fitting
for j = 1:nchunk
    ibegin = min(n,numObsPerChunk*(j-1) + 1);
    iend   = min(n,numObsPerChunk*j);
    idx = ibegin:iend; 
    
    mdl = updateMetricsAndFit(mdl,feat(idx,:),actid(idx));
    ce{j,:} = mdl.Metrics{"ClassificationError",:};

    [normalizerSW,normalized] = fit(normalizerSW, feat(idx,:));
    centerSW(j,:) = normalizerSW.Center;
    scaleSW(j,:) = normalizerSW.Scale;
    mdlSW = updateMetricsAndFit(mdlSW,normalized,actid(idx));
    ceSW{j,:} = mdlSW.Metrics{"ClassificationError",:};

    [normalizerCW,normalized] = fit(normalizerCW, feat(idx,:),actid(idx,:));
    centerCW(j,:) = normalizerCW.Center;
    scaleCW(j,:) = normalizerCW.Scale;
    mdlCW = updateMetricsAndFit(mdlCW,normalized,actid(idx));
    ceCW{j,:} = mdlCW.Metrics{"ClassificationError",:};
end

To see how the Center and Scale values of the incremental normalizer models for feature 56 evolve during training, plot them on separate tiles.

figure
t = tiledlayout(2,1);
nexttile
plot([centerSW(:,56) centerCW(:,56)])
ylabel("Center")
xlim([0 nchunk])
legend(["Simple weighted" "Class weighted"],Location="southeast")
nexttile
plot([scaleSW(:,56) scaleCW(:,56)])
ylabel("Scale")
xlim([0 nchunk])
legend(["Simple weighted" "Class weighted"],Location="southeast")
xlabel("Iteration")

Figure contains 2 axes objects. Axes object 1 with ylabel Center contains 2 objects of type line. These objects represent Simple weighted, Class weighted. Axes object 2 with xlabel Iteration, ylabel Scale contains 2 objects of type line. These objects represent Simple weighted, Class weighted.

The plots show that the Center and Scale values of feature 56 for both models rise sharply after the 55th iteration, and approach approximately constant values after the 350th iteration. The final values of Center and Scale are different for each model because they use different weighting schemes.

To see how the performance metrics of the incremental ECOC models evolve during training, plot them on separate tiles.

figure
t = tiledlayout(3,1);
nexttile
plot(ceSW.Variables)
ylabel("mdlSW Error")
xlim([0 nchunk])
xline(mdlSW.MetricsWarmupPeriod/numObsPerChunk,"--")
ylim([0 0.25])
legend(ceSW.Properties.VariableNames,Location="northwest")
text(310,0.2,"Simple-weighted normalization",FontSize=8)
nexttile
plot(ceCW.Variables)
xlim([0 nchunk])
ylim([0 0.25])
ylabel("mdlCW Error")
xline(mdlCW.MetricsWarmupPeriod/numObsPerChunk,"--")
legend(ceCW.Properties.VariableNames,Location="northwest")
text(310,0.2,"Class-weighted normalization",FontSize=8)
nexttile
plot(ce.Variables)
xlim([0 nchunk])
ylim([0 0.25])
ylabel("mdl Error")
xline(mdl.MetricsWarmupPeriod/numObsPerChunk,"--")
legend(ce.Properties.VariableNames,Location="northwest")
text(310,0.2,"ECOC model normalization",FontSize=8)
xlabel("Iteration")

Figure contains 3 axes objects. Axes object 1 with ylabel mdlSW Error contains 4 objects of type line, constantline, text. These objects represent Cumulative, Window. Axes object 2 with ylabel mdlCW Error contains 4 objects of type line, constantline, text. These objects represent Cumulative, Window. Axes object 3 with xlabel Iteration, ylabel mdl Error contains 4 objects of type line, constantline, text. These objects represent Cumulative, Window.

The plots indicate that updateMetricsAndFit performs the following actions:

  • Compute the performance metrics after the metrics warm-up period (dashed vertical line at 100th iteration) only.

  • Compute the cumulative metrics during each iteration.

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

A comparison of the plots indicates that, for this data set, the three incremental learning methods produce similar levels of classification error.

Input Arguments

collapse all

Class names, specified as a categorical, character, or string array, a logical or numeric vector, or a cell array of character vectors. ClassNames cannot be empty and must have the same number of elements as Prior.

You cannot specify ClassNames when creating a ZScoreNormalizer or ExponentiallyWeightedNormalizer model object. You must specify ClassNames when creating a ClassWeightedNormalizer model object.

Example: ["A" "B" "C"]

Data Types: categorical | char | string | logical | single | double | cell

Class prior probabilities, specified as a vector of positive scalar values or "uniform". The incrementalNormalizer function uses Prior (and Center, if specified) to set the initial Center values of Normalizer. The incremental fit function uses Prior to calculate and update the Center values (and Scale values, if ScaleData=true) of Normalizer.

You must specify Prior when creating a ClassWeightedNormalizer model object. You cannot specify Prior when creating aZScoreNormalizer or ExponentiallyWeightedNormalizer model object.

If you specify Prior as a vector of positive scalar values:

  • Prior must have the same number of elements as ClassNames.

  • The order of the elements in Prior corresponds to the order of the elements in ClassNames.

  • incrementalNormalizer normalizes the values of Normalizer.Prior, if necessary, so that their sum equals 1.

If you specify Prior as "uniform", then Normalizer.Prior has the same number of elements as ClassNames, and each element is equal to 1/length(ClassNames).

Example: [0.2 0.4 0.4]

Data Types: single | double | char | string

Name-Value Arguments

expand 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: Normalizer = incrementalNormalizer("zscore",WarmupPeriod=1000) creates a ZScoreNormalizer object that uses simple-weighted normalization and a warm-up period of 1000 observations.

General Options

expand all

Number of predictors, specified as a nonnegative integer.

When you specify NumPredictors, the following conditions apply:

  • incrementalNormalizer sets Normalizer.NumPredictors equal to NumPredictors.

  • If you specify Center, then NumPredictors must equal the number of columns in Center.

  • If you specify PredictorNames, then NumPredictors must equal the number of elements in PredictorNames.

When you do not specify NumPredictors, the following conditions apply:

  • If you specify Center, then Normalizer.NumPredictors equals the number of columns in Center.

  • If you specify PredictorNames, then Normalizer.NumPredictors equals the number of elements in PredictorNames.

  • If you do not specify Center or PredictorNames, then Normalizer.NumPredictors is 0.

When Normalizer.NumPredictors is 0:

  • You cannot call transform.

  • The software sets Normalizer.NumPredictors equal to the number of predictors in the training data when you call the incremental fit function.

Example: NumPredictors=10

Data Types: single | double

Predictor names, specified as a string array, cell array of character vectors, or character matrix. If you specify NumPredictors, then PredictorNames must contain NumPredictors elements. If you do not specify PredictorNames, then Normalizer.PredictorNames is ["x1" "x2" ... "xN"], where N is the value of NumPredictors.

Example: PredictorNames=["A" "B" "C"]

Data Types: char | string | cell

List of categorical predictors, specified as one of the values in this table.

ValueDescription
Vector of positive integers

Each entry in the vector is an index value corresponding to the column of the predictor data that contains a categorical variable. The index values must be between 1 and NumPredictors.

Logical vectorA true entry means that the corresponding column of predictor data is a categorical variable. The length of the vector must be equal to NumPredictors.
String arrayYou must specify PredictorNames, and each entry in CategoricalPredictors must be an element in PredictorNames.
Cell array of character vectorsYou must specify PredictorNames, and each entry in CategoricalPredictors must be an element in PredictorNames.
Character arrayYou must specify PredictorNames, and each entry in CategoricalPredictors must be an element in PredictorNames.

For categorical predictors:

  • The Center and Scale property values of Normalizer are NaN.

  • The incremental fit function returns unnormalized values.

Example: CategoricalPredictors=[1 2 4] and CategoricalPredictors=[true true false true] specify that the first, second, and fourth of four predictors are categorical.

Data Types: single | double | logical | char | string

Predictor means, specified as a numeric vector or numeric array.

When you specify Center, the following conditions apply:

  • You must specify NumObservations or SumOfWeights.

  • If you do not specify Scale, the default value of ScaleData is false, meaning the normalized predictor data returned by fit or transform is centered and not scaled.

  • If you are creating a ZScoreNormalizer or ExponentiallyWeightedNormalizer model object, then Center must be a numeric vector with NumPredictors elements.

  • If you are creating a ClassWeightedNormalizer model object, Center must be a numeric array of size k-by-NumPredictors, where k is the number of elements in ClassNames. The nth row of Center contains the predictor means for the nth class in ClassNames. incrementalNormalizer uses the values of Center and Prior to set the initial Center values of Normalizer.

If you do not specify Center, then Normalizer.Center is a 1-by-NumPredictors array of zeros.

Example: Center=[0 -2]

Data Types: single | double

Predictor standard deviations, specified as a numeric vector or numeric array.

When you specify Scale, the following conditions apply:

  • You must specify Center.

  • You must specify SumOfWeights or NumObservations.

  • incrementalNormalizer sets ScaleData=true. You cannot specify ScaleData=false.

  • If you are creating a ZScoreNormalizer or ExponentiallyWeightedNormalizer model object, then Scale must be a numeric vector with NumPredictors elements.

  • If you are creating a ClassWeightedNormalizer model object:

    • Scale must be a numeric array of size k-by-NumPredictors, where k is the number of elements in ClassNames. The nth row of Scale contains the predictor standard deviations for the nth class in ClassNames.

    • incrementalNormalizer uses the values of Prior, Center, and Scale to set the Scale property of Normalizer.

When you do not specify Scale, the following conditions apply:

  • If ScaleData is true, then Normalizer.Scale is a 1-by-NumPredictors array of zeros.

  • If ScaleData is false, then Normalizer.Scale is [].

Example: Scale=[1 1]

Data Types: single | double

Number of observations for the sum of weights calculation, specified as a positive integer. incrementalNormalizer uses NumObservations and NumPredictors to set Normalizer.SumOfWeights.

When you specify NumObservations, the following conditions apply:

  • You must specify Center.

  • You cannot specify SumOfWeights.

  • If you are creating a ZScoreNormalizer or ExponentiallyWeightedNormalizer model object, incrementalNormalizer assumes that the specified values of Center are derived from NumObservations observations of each predictor, and sets Normalizer.SumOfWeights equal to NumObservations*ones(1,size(Center,2)).

  • If you are creating a ClassWeightedNormalizer model object, incrementalNormalizer assumes that the specified values of Center are derived from NumObservations observations distributed uniformly across each class, and sets Normalizer.SumOfWeights equal to (NumObservations/k)*ones(k,size(Center,2)), where k is the number of elements in ClassNames.

Example: NumObservations=1000

Data Types: single | double

Sum of weights, specified as a positive scalar or a vector of positive scalar values. If you are creating a ClassWeightedNormalizer model object, you can also specify SumOfWeights as a k-by-NumPredictors array of positive scalar values, where k is the number of elements in ClassNames. The incremental fit function uses SumOfWeights to update Normalizer.Center (and Normalizer.Scale, if ScaleData=true).

When you specify SumOfWeights, the following conditions apply:

  • You must specify Center.

  • You cannot specify NumObservations.

  • When you are creating a ZScoreNormalizer or ExponentiallyWeightedNormalizer model object:

    • If SumOfWeights is a positive scalar, incrementalNormalizer sets Normalizer.SumOfWeights equal to SumOfWeights*ones(1,length(Center)).

    • If SumOfWeights is a vector, it must have the same length as Center.

  • When you are creating a ClassWeightedNormalizer model object, the following conditions apply:

    • If SumOfWeights is a scalar, incrementalNormalizer sets Normalizer.SumOfWeights equal to (SumOfWeights/k)*ones(k,size(Center,2)), where k is the number of elements in ClassNames.

    • If SumOfWeights is a vector, incrementalNormalizer sets Normalizer.SumOfWeights equal to repmat(SumOfWeights(:),1,size(Center,2)).

    • If SumOfWeights is an array, incrementalNormalizer sets Normalizer.SumOfWeights equal to SumOfWeights.

When you do not specify SumOfWeights, and specify Center, the following conditions apply:

  • Normalizer.SumOfWeights has the same dimensions as Center.

  • If Normalizer is a ZScoreNormalizer or ExponentiallyWeightedNormalizer model object, the values of Normalizer.SumOfWeights are equal to NumObservations.

  • If Normalizer is a ClassWeightedNormalizer model object, the values of Normalizer.SumOfWeights are equal to NumObservations/k, where k is the number of elements in ClassNames.

When you do not specify SumOfWeights or Center, the following conditions apply:

  • If you are creating a ZScoreNormalizer or ExponentiallyWeightedNormalizer model object, then SumOfWeights is a 1-by-NumPredictors array of zeros.

  • If you are creating a ClassWeightedNormalizer model object, then SumOfWeights is a NumPredictors-by-1 array of zeros.

Note

The Normalizer.SumOfWeights values that correspond to categorical predictors are NaN.

Example: SumOfWeights=100

Data Types: single | double

Training Options

expand all

Flag indicating whether to scale the predictor output, specified as a numeric or logical 0 (false) or 1 (true). The default value of ScaleData is true. However, if you specify Center and do not specify Scale, the default value of ScaleData is false.

If you specify Scale, you cannot specify ScaleData=false.

When ScaleData is false:

  • The normalized predictor data returned by fit or transform is centered and not scaled.

  • Normalizer.Scale is [].

  • fit does not update Normalizer.Scale.

Example: ScaleData=false

Data Types: logical

Warm-up period before the normalized predictor output, specified as a nonnegative integer. The WarmupPeriod value is the number of observations to which the incremental model must be fit before the incremental fit function returns normalized predictor values. If you specify WarmupPeriod and TrainingPeriod, then WarmupPeriod must be less than or equal to TrainingPeriod.

Example: WarmupPeriod=100

Data Types: single | double

Training period before the Center and Scale property values of Normalizer are fixed, specified as a positive integer or Inf. After the incremental fit function processes TrainingPeriod observations, the function no longer updates Normalizer.Center and Normalizer.Scale. If you specify TrainingPeriod and WarmupPeriod, then TrainingPeriod must be greater than or equal to WarmupPeriod.

Example: TrainingPeriod=500

Data Types: single | double

Update frequency for the Center and Scale property values of Normalizer, specified as a positive integer. The incremental fit function updates Normalizer.Center (and Normalizer.Scale, if ScaleData=true) each time the function processes UpdateFrequency observations.

Example: UpdateFrequency=100

Data Types: single | double

Forgetting factor for the Center and Scale values calculated by fit, specified as a scalar value from 0 to 1. A high ForgettingFactor value gives more weight to newer observations than older ones. A value of 0 indicates infinite memory, where all the previous observations have equal weight when fit updates Normalizer.Center (and Normalizer.Scale, if ScaleData is true).

You can specify ForgettingFactor only when creating an ExponentiallyWeightedNormalizer model object.

Example: ForgettingFactor=0.1

Data Types: double | single

Output Arguments

collapse all

Incremental normalizer model, returned as one of the model objects in this table.

ObjectDescription
ZScoreNormalizerSimple-weighted normalization of streaming data
ExponentiallyWeightedNormalizerExponentially weighted normalization of streaming data
ClassWeightedNormalizerClass-weighted normalization of streaming data

To reference properties of Normalizer, use dot notation. For example, to access or display the warm-up period, enter Normalizer.WarmupPeriod at the command line.

More About

collapse all

Algorithms

incrementalNormalizer and the incremental fit function normalize by n–1 when calculating the Scale values, where n is the number of observations.

When a value in Normalizer.Scale is 0 or [], the fit and transform functions compute the z-score values of the corresponding predictor using a standard deviation value of 1. This behavior matches the behavior of zscore, which computes z-score values using a standard deviation value of 1 when the input data consists of identical values. The normalize function always calculates z-scores using the standard deviation of the input data.

Version History

Introduced in R2026a

See Also

| | | | | | |