ClassificationSVMCoderConfigurer

Coder configurer for support vector machine (SVM) for one-class and binary classification

expand all in page

Description

A ClassificationSVMCoderConfigurer object is a coder configurer of an SVM classification model (ClassificationSVM or CompactClassificationSVM).

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 SVM model parameters by using object properties.

  • Generate C/C++ code for the predict and update functions of the SVM classification 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 SVM 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 an SVM classification model, see the Code Generation sections of CompactClassificationSVM, predict, and update.

Creation

After training an SVM classification model by using fitcsvm, 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

predict Arguments

The properties listed in this section specify the coder attributes of the predict function arguments in the generated code.

Coder attributes of predictor data to pass to the generated C/C++ code for the predict function of the SVM classification model, specified as a LearnerCoderInput object.

When you create a coder configurer by using the learnerCoderConfigurer function, the input argument X determines the default values of the LearnerCoderInput coder attributes:

  • SizeVector — The default value is the array size of the input X.

  • VariableDimensions — This value is [0 0](default) or [1 0].

    • [0 0] indicates that the array size is fixed as specified in SizeVector.

    • [1 0] indicates that the array has variable-size rows and fixed-size columns. In this case, the first value of SizeVector is the upper bound for the number of rows, and the second value of SizeVector is the number of columns.

  • DataType — This value is single or double. The default data type depends on the data type of the input X.

  • Tunability — This value must be true, meaning that predict in the generated C/C++ code always includes predictor data as an input.

You can modify the coder attributes by using dot notation. For example, to generate C/C++ code that accepts predictor data with 100 observations of three predictor variables, specify these coder attributes of X for the coder configurer configurer:

configurer.X.SizeVector = [100 3];
configurer.X.DataType = 'double';
configurer.X.VariableDimensions = [0 0];
[0 0] indicates that the first and second dimensions of X (number of observations and number of predictor variables, respectively) have fixed sizes.

To allow the generated C/C++ code to accept predictor data with up to 100 observations, specify these coder attributes of X:

configurer.X.SizeVector = [100 3];
configurer.X.DataType = 'double';
configurer.X.VariableDimensions = [1 0];
[1 0] indicates that the first dimension of X (number of observations) has a variable size and the second dimension of X (number of predictor variables) has a fixed size. The specified number of observations, 100 in this example, becomes the maximum allowed number of observations in the generated C/C++ code. To allow any number of observations, specify the bound as Inf.

Number of output arguments to return from the generated C/C++ code for the predict function of the SVM classification model, specified as 1 or 2.

The output arguments of predict are label (predicted class labels) and score (scores or posterior probabilities) in the order of listed. predict in the generated C/C++ code returns the first n outputs of the predict function, where n is the NumOutputs value.

After creating the coder configurer configurer, you can specify the number of outputs by using dot notation.

configurer.NumOutputs = 2;

The NumOutputs property is equivalent to the '-nargout' compiler option of codegen (MATLAB Coder). This option specifies the number of output arguments in the entry-point function of code generation. The object function generateCode generates two entry-point functions—predict.m and update.m for the predict and update functions of an SVM classification model, respectively—and generates C/C++ code for the two entry-point functions. The specified value for the NumOutputs property corresponds to the number of output arguments in the entry-point function predict.m.

Data Types: double

update Arguments

The properties listed in this section specify the coder attributes of the update function arguments in the generated code. The update function takes a trained model and new model parameters as input arguments, and returns an updated version of the model that contains the new parameters. To enable updating the parameters in the generated code, you need to specify the coder attributes of the parameters before generating code. Use a LearnerCoderInput object to specify the coder attributes of each parameter. The default attribute values are based on the model parameters in the input argument Mdl of learnerCoderConfigurer.

Coder attributes of the trained classifier coefficients (Alpha of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — The default value is [s,1], where s is the number of support vectors in Mdl.

  • VariableDimensions — This value is [0 0](default) or [1 0].

    • [0 0] indicates that the array size is fixed as specified in SizeVector.

    • [1 0] indicates that the array has variable-size rows and fixed-size columns. In this case, the first value of SizeVector is the upper bound for the number of rows, and the second value of SizeVector is the number of columns.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — If you train a model with a linear kernel function, and the model stores the linear predictor coefficients (Beta) without the support vectors and related values, then this value must be false. Otherwise, this value must be true.

Coder attributes of the linear predictor coefficients (Beta of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — This value must be [p 1], where p is the number of predictors in Mdl.

  • VariableDimensions — This value must be [0 0], indicating that the array size is fixed as specified in SizeVector.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — If you train a model with a linear kernel function, and the model stores the linear predictor coefficients (Beta) without the support vectors and related values, then this value must be true. Otherwise, this value must be false.

Coder attributes of the bias term (Bias of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — This value must be [1 1].

  • VariableDimensions — This value must be [0 0], indicating that the array size is fixed as specified in SizeVector.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — This value must be true.

Coder attributes of the misclassification cost (Cost of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — For binary classification, this value must be [2 2]. For one-class classification, this value must be [1 1].

  • VariableDimensions — This value must be [0 0], indicating that the array size is fixed as specified in SizeVector.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — For binary classification, the default value is true. For one-class classification, this value must be false.

Coder attributes of the predictor means (Mu of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — If you train Mdl using standardized predictor data by specifying 'Standardize',true, this value must be [1,p], where p is the number of predictors in Mdl. Otherwise, this value must be [0,0].

  • VariableDimensions — This value must be [0 0], indicating that the array size is fixed as specified in SizeVector.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — If you train Mdl using standardized predictor data by specifying 'Standardize',true, the default value is true. Otherwise, this value must be false.

Coder attributes of the prior probabilities (Prior of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — For binary classification, this value must be [1 2]. For one-class classification, this value must be [1 1].

  • VariableDimensions — This value must be [0 0], indicating that the array size is fixed as specified in SizeVector.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — For binary classification, the default value is true. For one-class classification, this value must be false.

Coder attributes of the kernel scale parameter (KernelParameters.Scale of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — This value must be [1 1].

  • VariableDimensions — This value must be [0 0], indicating that the array size is fixed as specified in SizeVector.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — The default value is true.

Coder attributes of the predictor standard deviations (Sigma of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — If you train Mdl using standardized predictor data by specifying 'Standardize',true, this value must be [1,p], where p is the number of predictors in Mdl. Otherwise, this value must be [0,0].

  • VariableDimensions — This value must be [0 0], indicating that the array size is fixed as specified in SizeVector.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — If you train Mdl using standardized predictor data by specifying 'Standardize',true, the default value is true. Otherwise, this value must be false.

Coder attributes of the support vector class labels (SupportVectorLabels of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — The default value is [s,1], where s is the number of support vectors in Mdl.

  • VariableDimensions — This value is [0 0](default) or [1 0].

    • [0 0] indicates that the array size is fixed as specified in SizeVector.

    • [1 0] indicates that the array has variable-size rows and fixed-size columns. In this case, the first value of SizeVector is the upper bound for the number of rows, and the second value of SizeVector is the number of columns.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — If you train a model with a linear kernel function, and the model stores the linear predictor coefficients (Beta) without the support vectors and related values, then this value must be false. Otherwise, this value must be true.

Coder attributes of the support vectors (SupportVectors of an SVM classification model), specified as a LearnerCoderInput object.

The default attribute values of the LearnerCoderInput object are based on the input argument Mdl of learnerCoderConfigurer:

  • SizeVector — The default value is [s,p], where s is the number of support vectors, and p is the number of predictors in Mdl.

  • VariableDimensions — This value is [0 0](default) or [1 0].

    • [0 0] indicates that the array size is fixed as specified in SizeVector.

    • [1 0] indicates that the array has variable-size rows and fixed-size columns. In this case, the first value of SizeVector is the upper bound for the number of rows, and the second value of SizeVector is the number of columns.

  • DataType — This value is 'single' or 'double'. The default data type is consistent with the data type of the training data you use to train Mdl.

  • Tunability — If you train a model with a linear kernel function, and the model stores the linear predictor coefficients (Beta) without the support vectors and related values, then this value must be false. Otherwise, this value must be true.

Other Configurer Options

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

The object function generateCode of ClassificationSVMCoderConfigurer 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) or false (logical 0). The verbosity level controls the display of notification messages at the command line.

ValueDescription
true (logical 1)The software displays notification messages when your changes to the coder attributes of a parameter result in changes for other dependent parameters.
false (logical 0)The software does not display notification messages.

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 and update.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 the codegen 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.

codegen (MATLAB Coder) arguments, specified as a cell array.

This property enables you to customize the code generation workflow. Use the generateCode function if you do not need to customize your workflow.

Instead of using generateCode with the coder configurer configurer, you can generate C/C++ code as follows:

generateFiles(configurer)
cgArgs = configurer.CodeGenerationArguments;
codegen(cgArgs{:})
If you customize the code generation workflow, modify cgArgs accordingly before calling codegen.

If you modify other properties of configurer, the software updates the CodeGenerationArguments property accordingly.

Data Types: cell

This property is read-only.

Input argument of the entry-point function predict.m for code generation, specified as a cell array of a coder.PrimitiveType (MATLAB Coder) object. The coder.PrimitiveType object includes the coder attributes of the predictor data stored in the X property.

If you modify the coder attributes of the predictor data, then the software updates the coder.PrimitiveType object accordingly.

The coder.PrimitiveType object in PredictInputs is equivalent to configurer.CodeGenerationArguments{6} for the coder configurer configurer.

Data Types: cell

This property is read-only.

List of the tunable input arguments of the entry-point function update.m for code generation, specified as a cell array of a structure including coder.PrimitiveType (MATLAB Coder) objects. Each coder.PrimitiveType object includes the coder attributes of a tunable machine learning model parameter.

If you modify the coder attributes of a model parameter by using the coder configurer properties (update Arguments properties), then the software updates the corresponding coder.PrimitiveType object accordingly. If you specify the Tunability attribute of a machine learning model parameter as false, then the software removes the corresponding coder.PrimitiveType object from the UpdateInputs list.

The structure in UpdateInputs is equivalent to configurer.CodeGenerationArguments{3} for the coder configurer configurer.

Data Types: cell

Object Functions

generateCodeGenerate C/C++ code using coder configurer
generateFilesGenerate MATLAB files for code generation using coder configurer
validatedUpdateInputsValidate and extract machine learning model parameters to update

Examples

collapse all

This example uses:

Open Live Script

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

Load the ionosphere data set and train a binary SVM classification model. 

load ionosphere
Mdl = fitcsvm(X,Y);

Mdl is a ClassificationSVM object.

Create a coder configurer for the ClassificationSVM 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 = 
  ClassificationSVMCoderConfigurer with properties:

   Update Inputs:
                  Alpha: [1x1 LearnerCoderInput]
         SupportVectors: [1x1 LearnerCoderInput]
    SupportVectorLabels: [1x1 LearnerCoderInput]
                  Scale: [1x1 LearnerCoderInput]
                   Bias: [1x1 LearnerCoderInput]
                  Prior: [1x1 LearnerCoderInput]
                   Cost: [1x1 LearnerCoderInput]

   Predict Inputs:
                      X: [1x1 LearnerCoderInput]

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


  Properties, Methods

configurer is a ClassificationSVMCoderConfigurer object, which is a coder configurer of a ClassificationSVM 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 SVM classification model (Mdl) with default settings. 

generateCode(configurer)
generateCode creates these files in output folder:
'initialize.m', 'predict.m', 'update.m', 'ClassificationSVMModel.mat'

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 ClassificationSVMModel for the two entry-point functions.

  • Create the code for the MEX function in the codegen\mex\ClassificationSVMModel 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.

type predict.m
function varargout = predict(X,varargin) %#codegen
% Autogenerated by MATLAB, 20-Aug-2020 18:33:38
[varargout{1:nargout}] = initialize('predict',X,varargin{:});
end

type update.m
function update(varargin) %#codegen
% Autogenerated by MATLAB, 20-Aug-2020 18:33:38
initialize('update',varargin{:});
end

type initialize.m
function [varargout] = initialize(command,varargin) %#codegen
% Autogenerated by MATLAB, 20-Aug-2020 18:33:38
coder.inline('always')
persistent model
if isempty(model)
    model = loadLearnerForCoder('ClassificationSVMModel.mat');
end
switch(command)
    case 'update'
        % Update struct fields: Alpha
        %                       SupportVectors
        %                       SupportVectorLabels
        %                       Scale
        %                       Bias
        %                       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

This example uses:

Open Live Script

Train a SVM model using a partial data set and create a coder configurer for the model. Use the properties of the coder configurer to specify coder attributes of the SVM 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 the whole data set and update parameters in the generated code without regenerating the code.

Train Model

Load the ionosphere data set. This data set has 34 predictors and 351 binary responses for radar returns, either bad ('b') or good ('g'). Train a binary SVM classification model using the first 50 observations.

load ionosphere
Mdl = fitcsvm(X(1:50,:),Y(1:50));

Mdl is a ClassificationSVM object.

Create Coder Configurer

Create a coder configurer for the ClassificationSVM 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 predicted labels and scores.

configurer = learnerCoderConfigurer(Mdl,X(1:50,:),'NumOutputs',2);

configurer is a ClassificationSVMCoderConfigurer object, which is a coder configurer of a ClassificationSVM object.

Specify Coder Attributes of Parameters

Specify the coder attributes of the SVM classification model parameters so that you can update the parameters in the generated code after retraining the model. This example specifies the coder attributes of predictor data that you want to pass to the generated code and the coder attributes of the support vectors of the SVM model.

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 34];
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 34 predictors, so the value of the SizeVector attribute must be 34 and the value of the VariableDimensions attribute must be false.

If you retrain the SVM model using new data or different settings, the number of support vectors can vary. Therefore, specify the coder attributes of SupportVectors so that you can update the support vectors in the generated code. 

configurer.SupportVectors.SizeVector = [250 34];
SizeVector attribute for Alpha has been modified to satisfy configuration constraints.
SizeVector attribute for SupportVectorLabels has been modified to satisfy configuration constraints.

configurer.SupportVectors.VariableDimensions = [true false];
VariableDimensions attribute for Alpha has been modified to satisfy configuration constraints.
VariableDimensions 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.

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.

Use generateCode to generate code for the predict and update functions of the SVM classification model (Mdl) with default settings. 

generateCode(configurer)
generateCode creates these files in output folder:
'initialize.m', 'predict.m', 'update.m', 'ClassificationSVMModel.mat'

generateCode generates 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. Then generateCode creates a MEX function named ClassificationSVMModel for the two entry-point functions in the codegen\mex\ClassificationSVMModel folder and copies 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.

[label,score] = predict(Mdl,X);
[label_mex,score_mex] = ClassificationSVMModel('predict',X);

Compare label and label_mex by using isequal.

isequal(label,label_mex)
ans = logical
   1

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.

score_mex might include round-off differences compared with score. In this case, compare score_mex and score, allowing a small tolerance.

find(abs(score-score_mex) > 1e-8)
ans =

  0x1 empty double column vector

The comparison confirms that score and score_mex are equal within the tolerance 1e–8.

Retrain Model and Update Parameters in Generated Code

Retrain the model using the entire data set.

retrainedMdl = fitcsvm(X,Y);

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.

ClassificationSVMModel('update',params)

Verify Generated Code

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

[label,score] = predict(retrainedMdl,X);
[label_mex,score_mex] = ClassificationSVMModel('predict',X);
isequal(label,label_mex)
ans = logical
   1


find(abs(score-score_mex) > 1e-8)
ans =

  0x1 empty double column vector

The comparison confirms that labels and labels_mex are equal, and the score values are equal within the tolerance.

More About

expand all

See Also

| | | | |

Topics

Introduced in R2018b

Statistics and Machine Learning Toolbox Documentation

Support