loadLearnerForCoder

Reconstruct model object from saved model for code generation

Syntax

Mdl = loadLearnerForCoder(filename)

Mdl = loadLearnerForCoder(filename,'DataType','single')

Mdl = loadLearnerForCoder(filename,'DataType',T)

Description

To generate C/C++ code for the object functions of machine learning models (including predict, random, knnsearch, rangesearch, and incremental learning functions) , use saveLearnerForCoder, loadLearnerForCoder, and codegen (MATLAB Coder). After training a machine learning model, save the model by using saveLearnerForCoder. Define an entry-point function that loads the model by using loadLearnerForCoder and calls an object function. Then use codegen or the MATLAB^® Coder™ app to generate C/C++ code. Generating C/C++ code requires MATLAB Coder.

For functions that support single-precision C/C++ code generation, use saveLearnerForCoder, loadLearnerForCoder, and codegen (MATLAB Coder); specify the name-value argument 'DataType','single' when you call the loadLearnerForCoder function.

This flow chart shows the code generation workflow for the object functions of machine learning models. Use loadLearnerForCoder for the highlighted step.

Fixed-point C/C++ code generation requires an additional step that defines the fixed-point data types of the variables required for prediction. Create a fixed-point data type structure by using the data type function generated by generateLearnerDataTypeFcn, and use the structure as an input argument of loadLearnerForCoder in an entry-point function. Generating fixed-point C/C++ code requires MATLAB Coder and Fixed-Point Designer™.

This flow chart shows the fixed-point code generation workflow for the predict function of a machine learning model. Use loadLearnerForCoder for the highlighted step.

Mdl = loadLearnerForCoder(filename) reconstructs a classification model, regression model, or nearest neighbor searcher (Mdl) from the model stored in the MATLAB formatted binary file (MAT-file) named filename. You must create the filename file by using saveLearnerForCoder.

Mdl = loadLearnerForCoder(filename,'DataType','single') reconstructs a single-precision classification or regression model (Mdl) from the model stored in the MATLAB formatted binary file (MAT-file) named filename.

Mdl = loadLearnerForCoder(filename,'DataType',T) returns a fixed-point version of the model stored in filename. The structure T contains the fields that specify the fixed-point data types for the variables required to use the predict function of the model. Create T using the function generated by generateLearnerDataTypeFcn.

Use this syntax in an entry-point function, and use codegen to generate fixed-point code for the entry-point function. You can use this syntax only when generating code.

Examples

Generate C/C++ Code for Prediction

After training a machine learning model, save the model by using saveLearnerForCoder. Define an entry-point function that loads the model by using loadLearnerForCoder and calls the predict function of the trained model. Then use codegen (MATLAB Coder) to generate C/C++ code.

This example briefly explains the code generation workflow for the prediction of machine learning models at the command line. For more details, see Code Generation for Prediction of Machine Learning Model at Command Line. You can also generate code using the MATLAB Coder app. See Code Generation for Prediction of Machine Learning Model Using MATLAB Coder App for details. To learn about the code generation for finding nearest neighbors using a nearest neighbor searcher model, see Code Generation for Nearest Neighbor Searcher.

Train Model

Load Fisher's iris data set. Remove all observed setosa irises data so that X and Y contain data for two classes only.

load fisheriris
inds = ~strcmp(species,'setosa');
X = meas(inds,:);
Y = species(inds);

Train a support vector machine (SVM) classification model using the processed data set.

Mdl = fitcsvm(X,Y);

Mdl is a ClassificationSVM model.

Save Model

Save the SVM classification model to the file SVMIris.mat by using saveLearnerForCoder.

saveLearnerForCoder(Mdl,'SVMIris');

Define Entry-Point Function

Define an entry-point function named classifyIris that does the following:

• Accept iris flower measurements with columns corresponding to meas, and return predicted labels.

• Load a trained SVM classification model.

• Predict labels using the loaded classification model for the iris flower measurements.

type classifyIris.m % Display contents of classifyIris.m file

function label = classifyIris(X) %#codegen
%CLASSIFYIRIS Classify iris species using SVM Model
%   CLASSIFYIRIS classifies the iris flower measurements in X using the SVM
%   model in the file SVMIris.mat, and then returns class labels in label.
Mdl = loadLearnerForCoder('SVMIris');
label = predict(Mdl,X);
end

Add the %#codegen compiler directive (or pragma) to the entry-point function after the function signature to indicate that you intend to generate code for the MATLAB algorithm. Adding this directive instructs the MATLAB Code Analyzer to help you diagnose and fix violations that would result in errors during code generation.

Note: If you click the button located in the upper-right section of this example and open this example in MATLAB®, then MATLAB® opens the example folder. This folder includes the entry-point function file.

Generate Code

Generate code for the entry-point function using codegen (MATLAB Coder). Because C and C++ are statically typed languages, you must determine the properties of all variables in the entry-point function at compile time. Pass X as the value of the -args option to specify that the generated code must accept an input that has the same data type and array size as the training data X. If the number of observations is unknown at compile time, you can also specify the input as variable-size by using coder.typeof (MATLAB Coder). For details, see Specify Variable-Size Arguments for Code Generation and Specify Properties of Entry-Point Function Inputs (MATLAB Coder).

codegen classifyIris -args {X}

Code generation successful.

codegen generates the MEX function classifyIris_mex with a platform-dependent extension.

Verify Generated Code

Compare the labels classified using predict, classifyIris, and classifyIris_mex.

label1 = predict(Mdl,X);
label2 = classifyIris(X);
label3 = classifyIris_mex(X);
verify_label = isequal(label1,label2,label3)

verify_label = logical
   1

isequal returns logical 1 (true), which means all the inputs are equal. The labels classified all three ways are the same.

Generate Single-Precision C/C++ Code for Prediction

After training a machine learning model, save the model by using saveLearnerForCoder. Define an entry-point function that loads the model by using loadLearnerForCoder and calls the predict function of the trained model. Then use codegen (MATLAB Coder) to generate C/C++ code.

This example briefly explains the single-precision code generation workflow for the prediction of machine learning models at the command line. For more details, see Code Generation for Prediction of Machine Learning Model at Command Line. You can also generate code using the MATLAB Coder app. See Code Generation for Prediction of Machine Learning Model Using MATLAB Coder App for details.

Train Model

Load the fisheriris data set. Create X as a numeric matrix that contains four petal measurements for 150 irises. Create Y as a cell array of character vectors that contains the corresponding iris species.

load fisheriris
X = meas;
Y = species;

Train a naive Bayes classifier using predictors X and class labels Y.

Mdl = fitcnb(X,Y);

Mdl is a trained ClassificationNaiveBayes classifier.

Save Model

Save the naive Bayes classification model to the file naiveBayesIris.mat by using saveLearnerForCoder.

saveLearnerForCoder(Mdl,'naiveBayesIris');

Define Entry-Point Function

Define an entry-point function named classifyIrisSingle that does the following:

• Accept iris flower measurements with columns corresponding to petal measurements, and return predicted labels.

• Load a trained naive Bayes classification model.

• Predict labels using the single-precision loaded classification model for the iris flower measurements.

type classifyIrisSingle.m

function label = classifyIrisSingle(X) %#codegen
% CLASSIFYIRISSINGLE Classify iris species using single-precision naive
% Bayes model
% CLASSIFYIRISSINGLE classifies the iris flower measurements in X using the
% single-precision naive Bayes model in the file naiveBayesIris.mat, and
% then returns the predicted labels in label.
Mdl = loadLearnerForCoder('naiveBayesIris','DataType','single');
label = predict(Mdl,X);
end

Add the %#codegen compiler directive (or pragma) to the entry-point function after the function signature to indicate that you intend to generate code for the MATLAB algorithm. Adding this directive instructs the MATLAB Code Analyzer to help you diagnose and fix violations that would result in errors during code generation.

Note: If you click the button located in the upper-right section of this example and open this example in MATLAB, then MATLAB opens the example folder. This folder includes the entry-point function file.

Generate Code

Generate code for the entry-point function using codegen (MATLAB Coder). Because C and C++ are statically typed languages, you must determine the properties of all variables in the entry-point function at compile time. Pass X as the value of the -args option to specify that the generated code must accept an input that has the same data type and array size as the training data X. If the number of observations is unknown at compile time, you can also specify the input as variable-size by using coder.typeof (MATLAB Coder). For details, see Specify Variable-Size Arguments for Code Generation and Specify Properties of Entry-Point Function Inputs (MATLAB Coder).

Xpred = single(X);
codegen classifyIrisSingle -args Xpred

Code generation successful.

codegen generates the MEX function classifyIrisSingle_mex with a platform-dependent extension.

Verify Generated Code

Compare the labels classified using predict, classifyIrisSingle, and classifyIrisSingle_mex.

label1 = predict(Mdl,X);
label2 = classifyIrisSingle(X);
label3 = classifyIrisSingle_mex(Xpred);
verify_label = isequal(label1,label2,label3)

verify_label = logical
   1

isequal returns logical 1 (true), which means all the inputs are equal. The labels classified all three ways are the same. If the generated MEX function classifyIrisSingle_mex and the function predict do not produce the same classification results, you can compute the percentage of incorrectly classified labels.

sum(strcmp(label3,label1)==0)/numel(label1)*100

ans = 0

Generate Fixed-Point C/C++ Code for Prediction

After training a machine learning model, save the model using saveLearnerForCoder. For fixed-point code generation, specify the fixed-point data types of the variables required for prediction by using the data type function generated by generateLearnerDataTypeFcn. Then, define an entry-point function that loads the model by using both loadLearnerForCoder and the specified fixed-point data types, and calls the predict function of the model. Use codegen (MATLAB Coder) to generate fixed-point C/C++ code for the entry-point function, and then verify the generated code.

Before generating code using codegen, you can use buildInstrumentedMex (Fixed-Point Designer) and showInstrumentationResults (Fixed-Point Designer) to optimize the fixed-point data types to improve the performance of the fixed-point code. Record minimum and maximum values of named and internal variables for prediction by using buildInstrumentedMex. View the instrumentation results using showInstrumentationResults; then, based on the results, tune the fixed-point data type properties of the variables. For details regarding this optional step, see Fixed-Point Code Generation for Prediction of SVM.

Train Model

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

load ionosphere
Mdl = fitcsvm(X,Y,'KernelFunction','gaussian');

Mdl is a ClassificationSVM model.

Save Model

Save the SVM classification model to the file myMdl.mat by using saveLearnerForCoder.

saveLearnerForCoder(Mdl,'myMdl');

Define Fixed-Point Data Types

Use generateLearnerDataTypeFcn to generate a function that defines the fixed-point data types of the variables required for prediction of the SVM model.

generateLearnerDataTypeFcn('myMdl',X)

generateLearnerDataTypeFcn generates the myMdl_datatype function.

Create a structure T that defines the fixed-point data types by using myMdl_datatype.

T = myMdl_datatype('Fixed')

T = struct with fields:
               XDataType: [0x0 embedded.fi]
           ScoreDataType: [0x0 embedded.fi]
    InnerProductDataType: [0x0 embedded.fi]

The structure T includes the fields for the named and internal variables required to run the predict function. Each field contains a fixed-point object, returned by fi (Fixed-Point Designer). The fixed-point object specifies fixed-point data type properties, such as word length and fraction length. For example, display the fixed-point data type properties of the predictor data.

T.XDataType

ans = 

[]

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 14

        RoundingMethod: Floor
        OverflowAction: Wrap
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128

Define Entry-Point Function

Define an entry-point function named myFixedPointPredict that does the following:

• Accept the predictor data X and the fixed-point data type structure T.

• Load a fixed-point version of a trained SVM classification model by using both loadLearnerForCoder and the structure T.

• Predict labels and scores using the loaded model.

type myFixedPointPredict.m % Display contents of myFixedPointPredict.m file

function [label,score] = myFixedPointPredict(X,T) %#codegen
Mdl = loadLearnerForCoder('myMdl','DataType',T);
[label,score] = predict(Mdl,X);
end

Note: If you click the button located in the upper-right section of this example and open the example in MATLAB®, then MATLAB opens the example folder. This folder includes the entry-point function file.

Generate Code

The XDataType field of the structure T specifies the fixed-point data type of the predictor data. Convert X to the type specified in T.XDataType by using the cast (Fixed-Point Designer) function.

X_fx = cast(X,'like',T.XDataType);

Generate code for the entry-point function using codegen. Specify X_fx and constant folded T as input arguments of the entry-point function.

codegen myFixedPointPredict -args {X_fx,coder.Constant(T)}

Code generation successful.

codegen generates the MEX function myFixedPointPredict_mex with a platform-dependent extension.

Verify Generated Code

Pass predictor data to predict and myFixedPointPredict_mex to compare the outputs.

[labels,scores] = predict(Mdl,X);
[labels_fx,scores_fx] = myFixedPointPredict_mex(X_fx,T);

Compare the outputs from predict and myFixedPointPredict_mex.

verify_labels = isequal(labels,labels_fx)

verify_labels = logical
   1

isequal returns logical 1 (true), which means labels and labels_fx are equal. If the labels are not equal, you can compute the percentage of incorrectly classified labels as follows.

sum(strcmp(labels_fx,labels)==0)/numel(labels_fx)*100

ans = 0

Find the maximum of the relative differences between the score outputs.

relDiff_scores = max(abs((scores_fx.double(:,1)-scores(:,1))./scores(:,1)))

relDiff_scores = 0.0055

If you are not satisfied with the comparison results and want to improve the precision of the generated code, you can tune the fixed-point data types and regenerate the code. For details, see Tips in generateLearnerDataTypeFcn, Data Type Function, and Fixed-Point Code Generation for Prediction of SVM.

Input Arguments

filename — Name of MAT-file that contains structure array representing a model object

character vector | string scalar

Name of the MAT-file that contains the structure array representing a model object, specified as a character vector or string scalar. You must create the filename file using saveLearnerForCoder. loadLearnerForCoder reconstructs the model stored in the filename file at compile time.

The extension of the filename file must be .mat. If filename has no extension, then loadLearnerForCoder appends .mat.

If filename does not include a full path, then loadLearnerForCoder loads the file from the current folder.

The following tables show the models you can save using saveLearnerForCoder and whether each model supports fixed-point and single-precision code generation.

• Classification Model Object

  Model	Full/Compact Model Objects	Fixed-Point Code Generation Support	Single-Precision Code Generation Support
  Discriminant analysis classification	ClassificationDiscriminant, CompactClassificationDiscriminant	No	Yes
  Multiclass model for support vector machines (SVMs) or other classifiers	ClassificationECOC, CompactClassificationECOC	No	Yes
  Ensemble classifier	ClassificationEnsemble, CompactClassificationEnsemble, ClassificationBaggedEnsemble	Yes (only for ensembles of decision trees)	Yes
  k-nearest neighbor classification	ClassificationKNN	No	Yes
  Linear model for binary classification of high-dimensional data	ClassificationLinear	No	Yes
  Naive Bayes classifier	ClassificationNaiveBayes, CompactClassificationNaiveBayes	No	Yes
  Neural network classifier	ClassificationNeuralNetwork, CompactClassificationNeuralNetwork	No	Yes
  SVM for one-class and binary classification	ClassificationSVM, CompactClassificationSVM	Yes	Yes
  Binary decision tree for classification	ClassificationTree, CompactClassificationTree	Yes	Yes
  Binary classification linear model for incremental learning	incrementalClassificationLinear	No	Yes

• Regression Model Object

  Model	Full/Compact Model Object	Fixed-Point Code Generation Support	Single-Precision Code Generation Support
  Generalized linear model	GeneralizedLinearModel, CompactGeneralizedLinearModel	No	No
  Linear regression model for incremental learning	incrementalRegressionLinear	No	Yes
  Linear regression model	LinearModel, CompactLinearModel	No	Yes
  Ensemble regression	RegressionEnsemble, CompactRegressionEnsemble, RegressionBaggedEnsemble	Yes	Yes
  Gaussian process regression	RegressionGP, CompactRegressionGP	No	Yes (see Tips)
  Linear regression for high-dimensional data	RegressionLinear	No	No
  Neural network regression	RegressionNeuralNetwork, CompactRegressionNeuralNetwork	No	Yes
  Regression tree	RegressionTree, CompactRegressionTree	Yes	Yes
  SVM regression	RegressionSVM, CompactRegressionSVM	Yes	Yes

• Nearest Neighbor Searcher Object

  Model	Model Object	Fixed-Point Code Generation Support	Single-Precision Code Generation Support
  Exhaustive nearest neighbor searcher	ExhaustiveSearcher	No	No
  Nearest neighbor searcher using Kd-tree	KDTreeSearcher	No	No

Example: 'Mdl'

Data Types: char | string

T — Fixed-point data types

structure

Fixed-point data types, specified as a structure. This argument is for fixed-point C/C++ code generation.

Create T using a function generated by generateLearnerDataTypeFcn. For details about the generated function and the structure T, see generateLearnerDataTypeFcn and Data Type Function.

You can use this argument when the model in the filename file is an SVM model, a decision tree model, and an ensemble of decision trees.

Data Types: struct

Output Arguments

Mdl — Machine learning model

model object

Machine learning model, returned as one of these model objects:

• Classification model object

  • ClassificationKNN

  • ClassificationLinear

  • CompactClassificationDiscriminant

  • CompactClassificationECOC

  • CompactClassificationEnsemble

  • CompactClassificationNaiveBayes

  • CompactClassificationNeuralNetwork

  • CompactClassificationSVM

  • CompactClassificationTree

  • incrementalClassificationLinear

• Regression model object

  • CompactGeneralizedLinearModel

  • CompactLinearModel

  • CompactRegressionEnsemble

  • CompactRegressionGP

  • CompactRegressionNeuralNetwork

  • CompactRegressionSVM

  • CompactRegressionTree

  • incrementalRegressionLinear

  • RegressionLinear

• Nearest neighbor searcher object

  • ExhaustiveSearcher

  • KDTreeSearcher

Limitations

• When Mdl is CompactLinearModel — Suppose you train a linear model by using fitlm and specifying 'RobustOpts' as a structure with an anonymous function handle for the RobustWgtFun field, use saveLearnerForCoder to save the model, and then use loadLearnerForCoder to load the model. In this case, loadLearnerForCoder cannot restore the Robust property into the MATLAB Workspace. However, loadLearnerForCoder can load the model at compile time within an entry-point function for code generation.

• When Mdl is CompactClassificationSVM or CompactClassificationECOC — If you use saveLearnerForCoder to save a model that is equipped to predict posterior probabilities, and use loadLearnerForCoder to load the model, then loadLearnerForCoder cannot restore the ScoreTransform property into the MATLAB Workspace. However, loadLearnerForCoder can load the model, including the ScoreTransform property, within an entry-point function at compile time for code generation.

Tips

• For single-precision code generation for a Gaussian process regression (GPR) model or a support vector machine (SVM) model, use standardized data by specifying 'Standardize',true when you train the model.

Algorithms

saveLearnerForCoder prepares a machine learning model (Mdl) for code generation. The function removes some unnecessary properties.

• For a model that has a corresponding compact model, the saveLearnerForCoder function applies the appropriate compact function to the model before saving it.

• For a model that does not have a corresponding compact model, such as ClassificationKNN, ClassificationLinear, RegressionLinear, ExhaustiveSearcher, and KDTreeSearcher, the saveLearnerForCoder function removes properties such as hyperparameter optimization properties, training solver information, and others.

loadLearnerForCoder loads the model saved by saveLearnerForCoder.

Alternative Functionality

• Use a coder configurer created by learnerCoderConfigurer for the models listed in this table.

  Model	Coder Configurer Object
  Binary decision tree for multiclass classification	ClassificationTreeCoderConfigurer
  SVM for one-class and binary classification	ClassificationSVMCoderConfigurer
  Linear model for binary classification	ClassificationLinearCoderConfigurer
  Multiclass model for SVMs and linear models	ClassificationECOCCoderConfigurer
  Binary decision tree for regression	RegressionTreeCoderConfigurer
  Support vector machine (SVM) regression	RegressionSVMCoderConfigurer
  Linear regression	RegressionLinearCoderConfigurer

  After training a machine learning model, create a coder configurer of the model. Use the object functions and properties of the configurer to configure code generation options and to generate code for the predict and update functions of the model. If you generate code using a coder configurer, you can update model parameters in the generated code without having to regenerate the code. For details, see Code Generation for Prediction and Update Using Coder Configurer.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• For fixed-point C/C++ code generation, the input argument T must be a compile-time constant. For an example, see Generate Fixed-Point C/C++ Code for Prediction.

For more information, see Introduction to Code Generation.

Version History

Introduced in R2019b