ClassificationECOCCoderConfigurer - Coder configurer for multiclass model using binary learners - MATLAB (original) (raw)

Coder configurer for multiclass model using binary learners

Description

A ClassificationECOCCoderConfigurer object is a coder configurer of a multiclass error-correcting output codes (ECOC) classification model (ClassificationECOC or CompactClassificationECOC) that uses support vector machine (SVM) or linear binary learners.

A coder configurer offers convenient features to configure code generation options, generate C/C++ code, and update model parameters in the generated code.

• Configure code generation options and specify the coder attributes of model parameters by using object properties.
• Generate C/C++ code for the predict and update functions of the ECOC model by using generateCode. Generating C/C++ code requires MATLAB® Coder™.
• Update model parameters in the generated C/C++ code without having to regenerate the code. This feature reduces the effort required to regenerate, redeploy, and reverify C/C++ code when you retrain the model with new data or settings. Before updating model parameters, use validatedUpdateInputs to validate and extract the model parameters to update.

This flow chart shows the code generation workflow using a coder configurer.

For the code generation usage notes and limitations of a multiclass ECOC classification model, see the Code Generation sections of CompactClassificationECOC, predict, and update.

Creation

After training a multiclass ECOC classification model with SVM or linear binary learners by using fitcecoc, create a coder configurer for the model by using learnerCoderConfigurer. Use the properties of a coder configurer to specify the coder attributes of predict and update arguments. Then, use generateCode to generate C/C++ code based on the specified coder attributes.

Properties

expand all

Other Configurer Options

File name of the generated C/C++ code, specified as a character vector.

The object function generateCode ofClassificationECOCCoderConfigurer generates C/C++ code using this file name.

The file name must not contain spaces because they can lead to code generation failures in certain operating system configurations. Also, the name must be a valid MATLAB function name.

After creating the coder configurer configurer, you can specify the file name by using dot notation.

configurer.OutputFileName = 'myModel';

Data Types: char

Verbosity level, specified as true (logical 1) orfalse (logical 0). The verbosity level controls the display of notification messages at the command line.

To enable updating machine learning model parameters in the generated code, you need to configure the coder attributes of the parameters before generating code. The coder attributes of parameters are dependent on each other, so the software stores the dependencies as configuration constraints. If you modify the coder attributes of a parameter by using a coder configurer, and the modification requires subsequent changes to other dependent parameters to satisfy configuration constraints, then the software changes the coder attributes of the dependent parameters. The verbosity level determines whether or not the software displays notification messages for these subsequent changes.

After creating the coder configurer configurer, you can modify the verbosity level by using dot notation.

configurer.Verbose = false;

Data Types: logical

Options for Code Generation Customization

To customize the code generation workflow, use the generateFiles function and the following three properties with codegen (MATLAB Coder), instead of using the generateCode function.

After generating the two entry-point function files (predict.m andupdate.m) by using the generateFiles function, you can modify these files according to your code generation workflow. For example, you can modify the predict.m file to include data preprocessing, or you can add these entry-point functions to another code generation project. Then, you can generate C/C++ code by using the codegen (MATLAB Coder) function and thecodegen arguments appropriate for the modified entry-point functions or code generation project. Use the three properties described in this section as a starting point to set the codegen arguments.

This property is read-only.

Data Types: cell

This property is read-only.

Data Types: cell

This property is read-only.

Data Types: cell

Object Functions

Examples

collapse all

Train a machine learning model, and then generate code for the predict and update functions of the model by using a coder configurer.

Load Fisher's iris data set and train a multiclass ECOC model using SVM binary learners.

load fisheriris X = meas; Y = species; Mdl = fitcecoc(X,Y);

Mdl is a ClassificationECOC object.

Create a coder configurer for the ClassificationECOC model by using learnerCoderConfigurer. Specify the predictor data X. The learnerCoderConfigurer function uses the input X to configure the coder attributes of the predict function input.

configurer = learnerCoderConfigurer(Mdl,X)

configurer = ClassificationECOCCoderConfigurer with properties:

Update Inputs: BinaryLearners: [1×1 ClassificationSVMCoderConfigurer] Prior: [1×1 LearnerCoderInput] Cost: [1×1 LearnerCoderInput]

Predict Inputs: X: [1×1 LearnerCoderInput]

Code Generation Parameters: NumOutputs: 1 OutputFileName: 'ClassificationECOCModel'

Properties, Methods

configurer is a ClassificationECOCCoderConfigurer object, which is a coder configurer of a ClassificationECOC object.

To generate C/C++ code, you must have access to a C/C++ compiler that is configured properly. MATLAB Coder locates and uses a supported, installed compiler. You can use mex -setup to view and change the default compiler. For more details, see Change Default Compiler.

Generate code for the predict and update functions of the ECOC classification model (Mdl) with default settings.

generateCode creates these files in output folder: 'initialize.m', 'predict.m', 'update.m', 'ClassificationECOCModel.mat' Code generation successful.

The generateCode function completes these actions:

• Generate the MATLAB files required to generate code, including the two entry-point functions predict.m and update.m for the predict and update functions of Mdl, respectively.
• Create a MEX function named ClassificationECOCModel for the two entry-point functions.
• Create the code for the MEX function in the codegen\mex\ClassificationECOCModel folder.
• Copy the MEX function to the current folder.

Display the contents of the predict.m, update.m, and initialize.m files by using the type function.

function varargout = predict(X,varargin) %#codegen % Autogenerated by MATLAB, 02-Feb-2025 03:54:35 [varargout{1:nargout}] = initialize('predict',X,varargin{:}); end

function update(varargin) %#codegen % Autogenerated by MATLAB, 02-Feb-2025 03:54:35 initialize('update',varargin{:}); end

function [varargout] = initialize(command,varargin) %#codegen % Autogenerated by MATLAB, 02-Feb-2025 03:54:35 coder.inline('always') persistent model if isempty(model) model = loadLearnerForCoder('ClassificationECOCModel.mat'); end switch(command) case 'update' % Update struct fields: BinaryLearners % Prior % Cost model = update(model,varargin{:}); case 'predict' % Predict Inputs: X X = varargin{1}; if nargin == 2 [varargout{1:nargout}] = predict(model,X); else PVPairs = cell(1,nargin-2); for i = 1:nargin-2 PVPairs{1,i} = varargin{i+1}; end [varargout{1:nargout}] = predict(model,X,PVPairs{:}); end end end

Train an error-correcting output codes (ECOC) model using SVM binary learners and create a coder configurer for the model. Use the properties of the coder configurer to specify coder attributes of the ECOC model parameters. Use the object function of the coder configurer to generate C code that predicts labels for new predictor data. Then retrain the model using different settings, and update parameters in the generated code without regenerating the code.

Train Model

Load Fisher's iris data set.

load fisheriris X = meas; Y = species;

Create an SVM binary learner template to use a Gaussian kernel function and to standardize predictor data.

t = templateSVM('KernelFunction','gaussian','Standardize',true);

Train a multiclass ECOC model using the template t.

Mdl = fitcecoc(X,Y,'Learners',t);

Mdl is a ClassificationECOC object.

Create Coder Configurer

Create a coder configurer for the ClassificationECOC model by using learnerCoderConfigurer. Specify the predictor data X. The learnerCoderConfigurer function uses the input X to configure the coder attributes of the predict function input. Also, set the number of outputs to 2 so that the generated code returns the first two outputs of the predict function, which are the predicted labels and negated average binary losses.

configurer = learnerCoderConfigurer(Mdl,X,'NumOutputs',2)

configurer = ClassificationECOCCoderConfigurer with properties:

Update Inputs: BinaryLearners: [1×1 ClassificationSVMCoderConfigurer] Prior: [1×1 LearnerCoderInput] Cost: [1×1 LearnerCoderInput]

Predict Inputs: X: [1×1 LearnerCoderInput]

Code Generation Parameters: NumOutputs: 2 OutputFileName: 'ClassificationECOCModel'

Properties, Methods

configurer is a ClassificationECOCCoderConfigurer object, which is a coder configurer of a ClassificationECOC object. The display shows the tunable input arguments of predict and update: X, BinaryLearners, Prior, and Cost.

Specify Coder Attributes of Parameters

Specify the coder attributes of predict arguments (predictor data and the name-value pair arguments 'Decoding' and 'BinaryLoss') and update arguments (support vectors of the SVM learners) so that you can use these arguments as the input arguments of predict and update in the generated code.

First, specify the coder attributes of X so that the generated code accepts any number of observations. Modify the SizeVector and VariableDimensions attributes. The SizeVector attribute specifies the upper bound of the predictor data size, and the VariableDimensions attribute specifies whether each dimension of the predictor data has a variable size or fixed size.

configurer.X.SizeVector = [Inf 4]; configurer.X.VariableDimensions = [true false];

The size of the first dimension is the number of observations. In this case, the code specifies that the upper bound of the size is Inf and the size is variable, meaning that X can have any number of observations. This specification is convenient if you do not know the number of observations when generating code.

The size of the second dimension is the number of predictor variables. This value must be fixed for a machine learning model. X contains 4 predictors, so the second value of the SizeVector attribute must be 4 and the second value of the VariableDimensions attribute must be false.

Next, modify the coder attributes of BinaryLoss and Decoding to use the 'BinaryLoss' and 'Decoding' name-value pair arguments in the generated code. Display the coder attributes of BinaryLoss.

ans = EnumeratedInput with properties:

         Value: 'hinge'
SelectedOption: 'Built-in'
BuiltInOptions: {'hamming'  'linear'  'quadratic'  'exponential'  'binodeviance'  'hinge'  'logit'}
    IsConstant: 1
    Tunability: 0

To use a nondefault value in the generated code, you must specify the value before generating the code. Specify the Value attribute of BinaryLoss as 'exponential'.

configurer.BinaryLoss.Value = 'exponential'; configurer.BinaryLoss

ans = EnumeratedInput with properties:

         Value: 'exponential'
SelectedOption: 'Built-in'
BuiltInOptions: {'hamming'  'linear'  'quadratic'  'exponential'  'binodeviance'  'hinge'  'logit'}
    IsConstant: 1
    Tunability: 1

If you modify attribute values when Tunability is false (logical 0), the software sets the Tunability to true (logical 1).

Display the coder attributes of Decoding.

ans = EnumeratedInput with properties:

         Value: 'lossweighted'
SelectedOption: 'Built-in'
BuiltInOptions: {'lossweighted'  'lossbased'}
    IsConstant: 1
    Tunability: 0

Specify the IsConstant attribute of Decoding as false so that you can use all available values in BuiltInOptions in the generated code.

configurer.Decoding.IsConstant = false; configurer.Decoding

ans = EnumeratedInput with properties:

         Value: [1×1 LearnerCoderInput]
SelectedOption: 'NonConstant'
BuiltInOptions: {'lossweighted'  'lossbased'}
    IsConstant: 0
    Tunability: 1

The software changes the Value attribute of Decoding to a LearnerCoderInput object so that you can use both 'lossweighted' and 'lossbased' as the value of 'Decoding'. Also, the software sets the SelectedOption to 'NonConstant' and the Tunability to true.

Finally, modify the coder attributes of SupportVectors in BinaryLearners. Display the coder attributes of SupportVectors.

configurer.BinaryLearners.SupportVectors

ans = LearnerCoderInput with properties:

        SizeVector: [54 4]
VariableDimensions: [1 0]
          DataType: 'double'
        Tunability: 1

The default value of VariableDimensions is [true false] because each learner has a different number of support vectors. If you retrain the ECOC model using new data or different settings, the number of support vectors in the SVM learners can vary. Therefore, increase the upper bound of the number of support vectors.

configurer.BinaryLearners.SupportVectors.SizeVector = [150 4];

SizeVector attribute for Alpha has been modified to satisfy configuration constraints. SizeVector attribute for SupportVectorLabels has been modified to satisfy configuration constraints.

If you modify the coder attributes of SupportVectors, then the software modifies the coder attributes of Alpha and SupportVectorLabels to satisfy configuration constraints. If the modification of the coder attributes of one parameter requires subsequent changes to other dependent parameters to satisfy configuration constraints, then the software changes the coder attributes of the dependent parameters.

Display the coder configurer.

configurer = ClassificationECOCCoderConfigurer with properties:

Update Inputs: BinaryLearners: [1×1 ClassificationSVMCoderConfigurer] Prior: [1×1 LearnerCoderInput] Cost: [1×1 LearnerCoderInput]

Predict Inputs: X: [1×1 LearnerCoderInput] BinaryLoss: [1×1 EnumeratedInput] Decoding: [1×1 EnumeratedInput]

Code Generation Parameters: NumOutputs: 2 OutputFileName: 'ClassificationECOCModel'

Properties, Methods

The display now includes BinaryLoss and Decoding as well.

Generate Code

To generate C/C++ code, you must have access to a C/C++ compiler that is configured properly. MATLAB Coder locates and uses a supported, installed compiler. You can use mex -setup to view and change the default compiler. For more details, see Change Default Compiler.

Generate code for the predict and update functions of the ECOC classification model (Mdl).

generateCode creates these files in output folder: 'initialize.m', 'predict.m', 'update.m', 'ClassificationECOCModel.mat' Code generation successful.

The generateCode function completes these actions:

• Generate the MATLAB files required to generate code, including the two entry-point functions predict.m and update.m for the predict and update functions of Mdl, respectively.
• Create a MEX function named ClassificationECOCModel for the two entry-point functions.
• Create the code for the MEX function in the codegen\mex\ClassificationECOCModel folder.
• Copy the MEX function to the current folder.

Verify Generated Code

Pass some predictor data to verify whether the predict function of Mdl and the predict function in the MEX function return the same labels. To call an entry-point function in a MEX function that has more than one entry point, specify the function name as the first input argument. Because you specified 'Decoding' as a tunable input argument by changing the IsConstant attribute before generating the code, you also need to specify it in the call to the MEX function, even though 'lossweighted' is the default value of 'Decoding'.

[label,NegLoss] = predict(Mdl,X,'BinaryLoss','exponential'); [label_mex,NegLoss_mex] = ClassificationECOCModel('predict',X,'BinaryLoss','exponential','Decoding','lossweighted');

Compare label to label_mex by using isequal.

isequal returns logical 1 (true) if all the inputs are equal. The comparison confirms that the predict function of Mdl and the predict function in the MEX function return the same labels.

NegLoss_mex might include round-off differences compared to NegLoss. In this case, compare NegLoss_mex to NegLoss, allowing a small tolerance.

find(abs(NegLoss-NegLoss_mex) > 1e-8)

ans =

0×1 empty double column vector

The comparison confirms that NegLoss and NegLoss_mex are equal within the tolerance 1e–8.

Retrain Model and Update Parameters in Generated Code

Retrain the model using a different setting. Specify 'KernelScale' as 'auto' so that the software selects an appropriate scale factor using a heuristic procedure.

t_new = templateSVM('KernelFunction','gaussian','Standardize',true,'KernelScale','auto'); retrainedMdl = fitcecoc(X,Y,'Learners',t_new);

Extract parameters to update by using validatedUpdateInputs. This function detects the modified model parameters in retrainedMdl and validates whether the modified parameter values satisfy the coder attributes of the parameters.

params = validatedUpdateInputs(configurer,retrainedMdl);

Update parameters in the generated code.

ClassificationECOCModel('update',params)

Verify Generated Code

Compare the outputs from the predict function of retrainedMdl to the outputs from the predict function in the updated MEX function.

[label,NegLoss] = predict(retrainedMdl,X,'BinaryLoss','exponential','Decoding','lossbased'); [label_mex,NegLoss_mex] = ClassificationECOCModel('predict',X,'BinaryLoss','exponential','Decoding','lossbased'); isequal(label,label_mex)

find(abs(NegLoss-NegLoss_mex) > 1e-8)

ans =

0×1 empty double column vector

The comparison confirms that label and label_mex are equal, and NegLoss and NegLoss_mex are equal within the tolerance.

More About

expand all

A coder configurer uses a LearnerCoderInput object to specify the coder attributes of predict and update input arguments.

A LearnerCoderInput object has the following attributes to specify the properties of an input argument array in the generated code.

After creating a coder configurer, you can modify the coder attributes by using dot notation. For example, specify the coder attributes of the coefficientsAlpha in BinaryLearners of the coder configurerconfigurer:

configurer.BinaryLearners.Alpha.SizeVector = [100 1]; configurer.BinaryLearners.Alpha.VariableDimensions = [1 0]; configurer.BinaryLearners.Alpha.DataType = 'double';

If you specify the verbosity level (Verbose) as true (default), then the software displays notification messages when you modify the coder attributes of a machine learning model parameter and the modification changes the coder attributes of other dependent parameters.

A coder configurer uses an EnumeratedInput object to specify the coder attributes of predict input arguments that have a finite set of available values.

An EnumeratedInput object has the following attributes to specify the properties of an input argument array in the generated code.

After creating a coder configurer, you can modify the coder attributes by using dot notation. For example, specify the coder attributes of BinaryLoss of the coder configurerconfigurer:

configurer.BinaryLoss.Value = 'linear';

Version History

Introduced in R2019a