ClassWeightedNormalizer

Class-weighted normalizer

Since R2026a

expand all in page

Description

A ClassWeightedNormalizer model object represents an incremental normalizer that weighs observations per class. After creating the object, you can use the fit object function to update the weighted Center (mean) and Scale (standard deviation) property values of the object based on new data. You can return normalized data by using the fit or transform function.

Creation

Create a class-weighted normalizer object using incrementalNormalizer.

Properties

expand all

This property is read-only.

List of categorical predictors, represented as a 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.

For categorical predictors:

Data Types: single | double

This property is read-only.

Class names, represented as a string array.

Data Types: char | string

This property is read-only.

Class prior probabilities, represented as a vector of positive scalar values. The incremental fit function uses Prior to calculate and update Center (and Scale, if ScaleData is true). The order of the elements in Prior corresponds to the order of the elements in ClassNames.

Data Types: single | double | char | string

This property is read-only.

Sum of weights, represented as a k-by-NumPredictors array of positive scalar values, where k is the number of elements in ClassNames. The SumOfWeights values that correspond to CategoricalPredictors are NaN. The incremental fit function uses SumOfWeights to update Center (and Scale, if ScaleData is true).

Data Types: single | double

This property is read-only.

Flag indicating whether the incremental fit function updates Scale, represented as a numeric or logical 0 (false) or 1 (true).

When ScaleData is false, Scale is [] and the normalized predictor data returned by fit or transform is centered and not scaled.

Data Types: logical

This property is read-only.

Predictor means, represented as a 1-by-NumPredictors numeric array. The Center values that correspond to CategoricalPredictors are NaN.

Data Types: single | double

This property is read-only.

Predictor standard deviations, represented as a 1-by-NumPredictors numeric array. The Scale values that correspond to CategoricalPredictors are NaN. If ScaleData is false, the Scale values that correspond to noncategorical predictors are 0.

Data Types: single | double

This property is read-only.

Predictor variable names, represented as a string array. If you do not specify PredictorNames when you create the object, then PredictorNames is ["x1" "x2" ... "xN"], where N is the value of NumPredictors.

Data Types: string

This property is read-only.

Number of predictor variables, represented as a nonnegative integer.

  • If Center is not empty, NumPredictors equals the number of elements in Center.

  • If PredictorNames is not empty, NumPredictors equals the number of elements in PredictorNames.

  • If NumPredictors is 0, when you call the incremental fit function, the software sets NumPredictors to the number of predictors in the training data.

Data Types: single | double

This property is read-only.

Flag indicating whether the incremental fit function returns normalized predictor values, represented as a numeric or logical 0 (false) or 1 (true). IsWarm becomes true after fit processes WarmupPeriod observations. If IsWarm is false, the normalized output of fit consists of NaN values.

Data Types: single | double | logical

This property is read-only.

Warm-up period before the normalized predictor output, represented 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. When processing observations, fit ignores observations that contain all NaN values and observations with a corresponding Weights value that is NaN.

Data Types: single | double

This property is read-only.

Training period before Center and Scale are fixed, represented as a positive integer. After the incremental fit function processes TrainingPeriod observations, the function no longer updates Center (and Scale, if ScaleData is true). When processing observations, fit ignores observations that contain all NaN values and observations with a corresponding Weights value that is NaN.

Data Types: single | double

This property is read-only.

Number of observations used for training, represented as a nonnegative integer. If NumTrainingObservations exceeds TrainingPeriod, the incremental fit function does not update Center and Scale.

Data Types: double

Update frequency, represented as a positive integer. The incremental fit function updates Center (and Scale, if ScaleData is true) each time the function processes UpdateFrequency observations. When processing observations, fit ignores observations that contain all NaN values and observations with a corresponding Weights value that is NaN.

Data Types: single | double

Object Functions

fitFit incremental normalizer model to streaming data
transformNormalize streaming data
resetReset incremental normalizer model

Examples

collapse all

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.

Version History

Introduced in R2026a

See Also

| |