Main Content

learnerCoderConfigurer

機械学習モデルのコーダー コンフィギュアラーの作成

説明

機械学習モデルに学習をさせた後で、learnerCoderConfigurer を使用してモデルのコーダー コンフィギュアラーを作成します。コンフィギュアラーのプロパティとオブジェクト関数を使用することにより、コード生成オプションを指定し、機械学習モデルの関数 predict および update に対する C/C++ コードを生成します。C/C++ コードの生成には MATLAB® Coder™ が必要です。

次のフロー チャートは、コーダー コンフィギュアラーを使用するコード生成のワークフローを示します。強調表示されているステップで learnerCoderConfigurer を使用します。

Two code generation workflows: the first after training a model, and the second after retraining the same model. First workflow, Step 1 (highlighted): Create a coder configurer. Step 2: Generate code. Step 3: Verify the generated code. Second workflow, Step 1: Check if the update is valid. If yes, go to Step 2; if no, go to the first step of the first workflow. Step 2: Update the model parameters in the generated code.

configurer = learnerCoderConfigurer(Mdl,X) は、機械学習モデル Mdl のコーダー コンフィギュアラー configurer を返します。Mdl の関数 predict のための予測子データ X を指定します。

configurer = learnerCoderConfigurer(Mdl,X,Name,Value) は、1 つ以上の名前と値のペアの引数で指定された追加オプションを使用して、コーダー コンフィギュアラーを返します。たとえば、関数 predict の出力引数の個数、生成される C/C++ のファイル名、およびコーダー コンフィギュアラーの詳細レベルを指定できます。

すべて折りたたむ

機械学習モデルに学習させてから、コーダー コンフィギュアラーを使用して、このモデルの関数 predict および update に対してコードを生成します。

carsmall データ セットを読み込み、サポート ベクター マシン (SVM) 回帰モデルに学習をさせます。

load carsmall
X = [Horsepower,Weight];
Y = MPG;
Mdl = fitrsvm(X,Y);

Mdl は、線形 SVM モデルであるRegressionSVMオブジェクトです。線形 SVM モデルでは、新しい観測値の応答を予測するための十分な情報が予測子の係数によって提供されます。サポート ベクターを削除することで、生成コードのメモリ使用量が少なくなります。関数discardSupportVectorsを使用して線形 SVM モデルからサポート ベクターを削除します。

Mdl = discardSupportVectors(Mdl);

learnerCoderConfigurer を使用して、RegressionSVM モデルについてコーダー コンフィギュアラーを作成します。予測子データ X を指定します。関数 learnerCoderConfigurer は、入力 X を使用して、関数 predict の入力のコーダー属性を設定します。

configurer = learnerCoderConfigurer(Mdl,X)
Warning: Default response is removed to support learnerCoderConfigurer. The model will predict NaNs for observations with missing values.
configurer = 
  RegressionSVMCoderConfigurer with properties:

   Update Inputs:
              Beta: [1x1 LearnerCoderInput]
             Scale: [1x1 LearnerCoderInput]
              Bias: [1x1 LearnerCoderInput]

   Predict Inputs:
                 X: [1x1 LearnerCoderInput]

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


configurer は、RegressionSVM オブジェクトのコーダー コンフィギュアラーである RegressionSVMCoderConfigurer オブジェクトです。

C/C++ コードを生成するには、適切に設定されている C/C++ コンパイラにアクセスできなければなりません。MATLAB Coder は、サポートされているインストール済みのコンパイラを探して使用します。mex -setup を使用すると、既定のコンパイラを表示および変更できます。詳細は、既定のコンパイラの変更を参照してください。

既定の設定を使用して、SVM 回帰モデル (Mdl) の関数 predict および update に対するコードを生成します。

generateCode(configurer)
generateCode creates these files in output folder:
'initialize.m', 'predict.m', 'update.m', 'RegressionSVMModel.mat'
Code generation successful.

関数 generateCode は、以下の処理を実行します。

  • コードを生成するために必要な MATLAB ファイルを生成する。これには、Mdl の関数 predict および update にそれぞれ対応する 2 つのエントリポイント関数 predict.m および update.m が含まれます。

  • 2 つのエントリポイント関数に対して、RegressionSVMModel という名前の MEX 関数を作成する。

  • MEX 関数のコードを codegen\mex\RegressionSVMModel フォルダーに作成する。

  • MEX 関数を現在のフォルダーにコピーする。

関数typeを使用して、predict.mupdate.m および initialize.m ファイルの内容を表示します。

type predict.m
function varargout = predict(X,varargin) %#codegen
% Autogenerated by MATLAB, 20-Jul-2024 17:19:44
[varargout{1:nargout}] = initialize('predict',X,varargin{:});
end
type update.m
function update(varargin) %#codegen
% Autogenerated by MATLAB, 20-Jul-2024 17:19:44
initialize('update',varargin{:});
end
type initialize.m
function [varargout] = initialize(command,varargin) %#codegen
% Autogenerated by MATLAB, 20-Jul-2024 17:19:44
coder.inline('always')
persistent model
if isempty(model)
    model = loadLearnerForCoder('RegressionSVMModel.mat');
end
switch(command)
    case 'update'
        % Update struct fields: Beta
        %                       Scale
        %                       Bias
        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

データ セットの一部を使用して SVM モデルに学習させ、モデルについてコーダー コンフィギュアラーを作成します。コーダー コンフィギュアラーのプロパティを使用して、SVM モデル パラメーターのコーダー属性を指定します。コーダー コンフィギュアラーのオブジェクト関数を使用して、新しい予測子データについてラベルを予測する C コードを生成します。その後、データ セット全体を使用してモデルに再学習をさせ、コードを再生成せずに、生成されたコードのパラメーターを更新します。

モデルの学習

ionosphere データ セットを読み込みます。このデータ セットには、レーダー反射についての 34 個の予測子と、不良 ('b') または良好 ('g') という 351 個の二項反応が含まれています。

load ionosphere

最初の 50 個の観測値と自動カーネル スケールのガウス カーネル関数を使用してバイナリ SVM 分類モデルに学習させます。

Mdl = fitcsvm(X(1:50,:),Y(1:50), ...
    'KernelFunction','gaussian','KernelScale','auto');

Mdl は、ClassificationSVM オブジェクトです。

コーダー コンフィギュアラーの作成

learnerCoderConfigurer を使用して、ClassificationSVM モデルについてコーダー コンフィギュアラーを作成します。予測子データ X を行列の形式で指定します。関数 learnerCoderConfigurer では table の形式の予測子データはサポートされないことに注意してください。関数 learnerCoderConfigurer は、入力 X を使用して、関数 predict の入力のコーダー属性を設定します。また、生成されるコードが予測ラベルおよびスコアを返すようにするため、出力の個数を 2 に設定します。

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

configurer は、ClassificationSVM オブジェクトのコーダー コンフィギュアラーである ClassificationSVMCoderConfigurer オブジェクトです。

パラメーターのコーダー属性の指定

生成されたコードのパラメーターをモデルの再学習後に更新できるようにするため、SVM 分類モデルのパラメーターのコーダー属性を指定します。この例では、生成されたコードに渡す予測子データのコーダー属性と、SVM モデルのサポート ベクターのコーダー属性を指定します。

はじめに、生成されたコードが任意の個数の観測値を受け入れるように、X のコーダー属性を指定します。属性 SizeVector および VariableDimensions を変更します。属性 SizeVector は、予測子データのサイズの上限を指定し、属性 VariableDimensions は、予測子データの各次元が可変サイズと固定サイズのどちらであるかを指定します。

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

1 番目の次元のサイズは、観測値の個数です。このケースでは、サイズの上限が Inf であり、サイズが可変、つまり X の観測値の個数が任意であることを指定します。この指定は、コードを生成するときに観測値の個数が不明である場合に便利です。

2 番目の次元のサイズは、予測子変数の個数です。この値は、機械学習モデルに対し固定でなければなりません。X には 34 個の予測子が含まれているので、属性 SizeVector の値は 34、属性 VariableDimensions の値は false でなければなりません。

新しいデータまたは異なる設定を使用して SVM モデルに再学習をさせた場合、サポート ベクターの個数が変化する可能性があります。したがって、生成されたコードのサポート ベクターを更新できるように SupportVectors のコーダー属性を指定します。

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.

SupportVectors のコーダー属性が変更されると、Alpha および SupportVectorLabels のコーダー属性が構成の制約を満たすように変更されます。あるパラメーターのコーダー属性の変更によって構成の制約を満たすために他の従属パラメーターの変更が必要になる場合、従属パラメーターのコーダー属性は変更されます。

コードの生成

C/C++ コードを生成するには、適切に設定されている C/C++ コンパイラにアクセスできなければなりません。MATLAB Coder は、サポートされているインストール済みのコンパイラを探して使用します。mex -setup を使用すると、既定のコンパイラを表示および変更できます。詳細は、既定のコンパイラの変更を参照してください。

generateCodeを使用して、SVM 分類モデル (Mdl) の関数 predict および update について、既定の設定でコードを生成します。

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

generateCode は、コードを生成するために必要な MATLAB ファイルを生成します。これには、Mdl の関数 predict および update にそれぞれ対応する 2 つのエントリポイント関数 predict.m および update.m が含まれます。次に generateCode は、2 つのエントリポイント関数に対して ClassificationSVMModel という名前の MEX 関数を codegen\mex\ClassificationSVMModel フォルダー内に作成し、この MEX 関数を現在のフォルダーにコピーします。

生成されたコードの確認

予測子データを渡して、Mdl の関数 predict と MEX 関数の関数 predict が同じラベルを返すかどうかを確認します。複数のエントリポイントがある MEX 関数内のエントリポイント関数を呼び出すため、1 番目の入力引数として関数名を指定します。

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

isequal を使用して、labellabel_mex を比較します。

isequal(label,label_mex)
ans = logical
   1

すべての入力が等しい場合、isequal は logical 1 (true) を返します。この比較により、同じラベルを Mdl の関数 predict と MEX 関数の関数 predict が返すことを確認します。

score と比較すると、score_mex には丸めによる差が含まれている場合があります。このような場合は、小さい誤差を許容して score_mexscore を比較します。

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

  0x1 empty double column vector

この比較により、許容誤差 1e–8 内で scorescore_mex が等しいことを確認します。

モデルの再学習と生成コード内のパラメーターの更新

データ セット全体を使用してモデルに再学習をさせます。

retrainedMdl = fitcsvm(X,Y, ...
    'KernelFunction','gaussian','KernelScale','auto');

validatedUpdateInputs を使用して、更新するパラメーターを抽出します。この関数は、retrainedMdl 内の修正されたモデル パラメーターを判別し、修正されたパラメーター値がパラメーターのコーダー属性を満たすかどうかを検証します。

params = validatedUpdateInputs(configurer,retrainedMdl);

生成されたコード内のパラメーターを更新します。

ClassificationSVMModel('update',params)

生成されたコードの確認

retrainedMdl の関数 predict の出力と、更新した MEX 関数の関数 predict の出力を比較します。

[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

この比較により、labelslabels_mex が等しく、スコアの値が許容誤差内で等しいことを確認します。

入力引数

すべて折りたたむ

機械学習モデル。完全またはコンパクトなモデル オブジェクトを指定します。サポートされるモデルは次の表に記載されています。

モデル完全/コンパクトなモデル オブジェクト学習関数
マルチクラス分類用の二分決定木ClassificationTree, CompactClassificationTreefitctree
1 クラスおよびバイナリ分類用の SVMClassificationSVM, CompactClassificationSVMfitcsvm
バイナリ分類用の線形モデルClassificationLinearfitclinear
SVM モデルおよび線形モデル用のマルチクラス モデルClassificationECOC, CompactClassificationECOCfitcecoc
回帰用の二分決定木RegressionTree, CompactRegressionTreefitrtree
サポート ベクター マシン (SVM) 回帰RegressionSVM, CompactRegressionSVMfitrsvm
線形回帰RegressionLinearfitrlinear

機械学習モデルのコード生成に関する使用上の注意および制限については、モデル オブジェクトのページの「コード生成」セクションを参照してください。

Mdl の関数 predict の予測子データ。np 列の数値行列を指定します。n は観測値の個数、p は予測子変数の個数です。代わりに X を観測値が列に対応する pn 列の行列として指定するには、名前と値のペアの引数 'ObservationsIn''columns' に設定します。このオプションが利用できるのは、線形バイナリ学習器を含む線形モデルと ECOC モデルのみです。

learnerCoderConfigurer では table データ形式の予測子データはサポートされないことに注意してください。

機械学習モデルの関数 predict は、分類の場合はラベルを、回帰の場合は応答を、与えられた予測子データに対して予測します。コーダー コンフィギュアラー configurer の作成後、関数 generateCode を使用して Mdl の関数 predict に対する C/C++ コードを生成できます。生成されるコードは、X と同じサイズおよびデータ型の予測子データを受け入れます。configurer の作成後、各次元のサイズを可変または固定のどちらにするかを指定できます。

たとえば、100 個の観測値と 3 つの予測子変数を使用してラベルを予測する C/C++ コードを生成する場合、X として zeros(100,3) を指定します。関数 learnerCoderConfigurer は、X の値ではなく、サイズおよびデータ型のみを使用します。したがって X は、特定のデータ型をもつ一連の値を表す MATLAB 式または予測子データにすることができます。出力 configurer には、configurerX プロパティ内の X のサイズおよびデータ型が格納されます。configurer の作成後、X のサイズおよびデータ型を変更できます。たとえば、観測値の個数を 200 に、データ型を single に変更します。

configurer.X.SizeVector = [200 3];
configurer.X.DataType = 'single';

生成される C/C++ コードが、最大 100 個の観測値がある予測子データを受け入れるようにするには、X として zeros(100,3) を指定し、VariableDimensions プロパティを変更します。

configurer.X.VariableDimensions = [1 0];
[1 0] は、X の 1 番目の次元 (観測値の個数) が可変サイズであり、X の 2 番目の次元 (予測子変数の個数) が固定サイズであることを示します。指定した観測値の個数 (この例では 100) は、生成される C/C++ コードで許容される観測値の最大数になります。任意の個数の観測値を可能にするには、上限として Inf を指定します。
configurer.X.SizeVector = [Inf 3];

データ型: single | double

名前と値の引数

オプションの引数のペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名、Value は対応する値です。名前と値の引数は他の引数の後に指定しなければなりませんが、ペアの順序は重要ではありません。

R2021a より前では、名前と値をそれぞれコンマを使って区切り、Name を引用符で囲みます。

例: configurer = learnerCoderConfigurer(Mdl,X,'NumOutputs',2,'OutputFileName','myModel') は、predict の出力の個数を 2 に設定し、生成される C/C++ コードのファイル名として 'myModel' を指定します。

機械学習モデル Mdl の関数 predict の出力引数の個数。'NumOutputs' と正の整数 n から構成されるコンマ区切りのペアとして指定します。

次の表は、各種のモデルにおける関数 predict の出力の一覧です。生成される C/C++ コードの predict は、「出力」列に示されている順序で関数 predict の最初の n 個の出力を返します。

モデルモデルの関数 predict出力
マルチクラス分類用の二分決定木predictlabel (予測クラス ラベル)、score (事後確率)、node (予測クラスのノード数)、cnum (予測ラベルのクラス数)
1 クラスおよびバイナリ分類用の SVMpredictlabel (予測されたクラス ラベル)、score (スコアまたは事後確率)
バイナリ分類用の線形モデルpredictLabel (予測されたクラス ラベル)、Score (分類スコア)
SVM モデルおよび線形モデル用のマルチクラス モデルpredictlabel (予測されたクラス ラベル)、NegLoss (符号を反転した平均バイナリ損失)、PBScore (陽性クラスのスコア)
回帰用の二分決定木predictYfit (予測された応答)、node (予測のノード数)
SVM 回帰predictyfit (予測された応答)
線形回帰predictYHat (予測された応答)

たとえば、SVM 分類モデルに対して 'NumOutputs',1 を指定した場合、predict は生成された C/C++ コードで予測クラス ラベルを返します。

コーダー コンフィギュアラー configurer を作成した後で、ドット表記を使用して出力の個数を変更できます。

configurer.NumOutputs = 2;

名前と値のペアの引数 'NumOutputs' は、codegen (MATLAB Coder) のコンパイラ オプション '-nargout' と等価です。このオプションは、コード生成のエントリポイント関数における出力引数の個数を指定します。コーダー コンフィギュアラーのオブジェクト関数 generateCode は、Mdl の関数 predict および update に対して predict.m および update.m という 2 つのエントリポイント関数をそれぞれ生成し、この 2 つのエントリポイント関数に対して C/C++ コードを生成します。'NumOutputs' について指定した値は、predict.m の出力引数の個数に対応します。

例: 'NumOutputs',2

データ型: single | double

生成される C/C++ コードのファイル名。'OutputFileName' と文字ベクトルまたは string スカラーから構成されるコンマ区切りのペアとして指定します。

コーダー コンフィギュアラーのオブジェクト関数 generateCode は、このファイル名を使用して C/C++ コードを生成します。

オペレーティング システムの構成によってはコード生成に失敗する可能性があるので、ファイル名には空白を含めないでください。また、名前は有効な MATLAB 関数名でなければなりません。

既定のファイル名は、Mdl のオブジェクト名に 'Model' を追加した名前です。たとえば、MdlCompactClassificationSVM または ClassificationSVM オブジェクトである場合、既定の名前は 'ClassificationSVMModel' です。

コーダー コンフィギュアラー configurer を作成した後で、ドット表記を使用してファイル名を変更できます。

configurer.OutputFileName = 'myModel';

例: 'OutputFileName','myModel'

データ型: char | string

詳細レベル。'Verbose'true (logical 1) または false (logical 0) のいずれかから構成されるコンマ区切りのペアとして指定します。詳細レベルは、コマンド ラインにおけるコーダー コンフィギュアラー configurer に関する通知メッセージの表示を制御します。

説明
true (logical 1)パラメーターのコーダー属性に対する変更によって他の従属するパラメーターが変化する場合、通知メッセージが表示されます。
false (logical 0)通知メッセージは表示されません。

生成コード内の機械学習のモデル パラメーターを更新できるようにするには、コード生成の前にパラメーターのコーダー属性を構成する必要があります。パラメーターのコーダー属性は互いに依存するので、依存関係が構成の制約として保存されます。コーダー コンフィギュアラーを使用してパラメーターのコーダー属性を変更するときに、構成の制約を満たすために他の従属するパラメーターも変更する必要がある場合、従属するパラメーターのコーダー属性が変更されます。詳細レベルは、これらの引き続いて起きた変更についてメッセージを表示するかどうかを決定します。

コーダー コンフィギュアラー configurer を作成した後で、ドット表記を使用して詳細レベルを変更できます。

configurer.Verbose = false;

例: 'Verbose',false

データ型: logical

予測子データにおける観測値の次元。'ObservationsIn' と、'rows' または 'columns' のいずれかから構成されるコンマ区切りのペアとして指定します。'ObservationsIn''columns' に設定すると、観測値が列に対応するように予測子データ X の方向を設定しなければなりません。

メモ

'columns' オプションが利用できるのは、線形バイナリ学習器を含む線形モデルと ECOC モデルのみです。

例: 'ObservationsIn','columns'

出力引数

すべて折りたたむ

機械学習モデルのコーダー コンフィギュアラー オブジェクト。次の表のいずれかのコーダー コンフィギュアラー オブジェクトとして返されます。

モデルコーダー コンフィギュアラー オブジェクト
マルチクラス分類用の二分決定木ClassificationTreeCoderConfigurer
1 クラスおよびバイナリ分類用の SVMClassificationSVMCoderConfigurer
バイナリ分類用の線形モデルClassificationLinearCoderConfigurer
SVM モデルおよび線形モデル用のマルチクラス モデルClassificationECOCCoderConfigurer
回帰用の二分決定木RegressionTreeCoderConfigurer
サポート ベクター マシン (SVM) 回帰RegressionSVMCoderConfigurer
線形回帰RegressionLinearCoderConfigurer

コーダー コンフィギュアラー オブジェクトのプロパティとオブジェクト関数を使用することにより、コード生成オプションを設定し、機械学習モデルの関数 predict および update に対する C/C++ コードを生成します。

バージョン履歴

R2018b で導入