このページの翻訳は最新ではありません。ここをクリックして、英語の最新版を参照してください。

generateLearnerDataTypeFcn

固定小数点コードの生成用のデータ型を定義する関数を生成

R2019b 以降

構文

generateLearnerDataTypeFcn(filename,X)

generateLearnerDataTypeFcn(filename,X,Name,Value)

説明

機械学習モデルの関数 predict の固定小数点の C/C++ コードを生成するには、generateLearnerDataTypeFcn、saveLearnerForCoder、loadLearnerForCoder および codegen (MATLAB Coder) を使用します。

• 機械学習モデルに学習させた後で、saveLearnerForCoder を使用してモデルを保存します。

• generateLearnerDataTypeFcn から生成される関数を使用して、固定小数点データ型を定義する構造体を作成します。

• loadLearnerForCoder と構造体の両方を使用してモデルを読み込み、関数 predict を呼び出すエントリポイント関数を定義します。

• codegen を使用してコードを生成し、生成されたコードを確認します。

関数 generateLearnerDataTypeFcn には Fixed-Point Designer™ が必要であり、固定小数点の C/C++ コードの生成には MATLAB^® Coder™ および Fixed-Point Designer が必要です。

次のフロー チャートは、機械学習モデルの関数 predict の固定小数点のコード生成ワークフローを示します。強調表示されているステップで generateLearnerDataTypeFcn を使用します。

generateLearnerDataTypeFcn(filename,X) は、機械学習モデルの予測用の固定小数点の C/C++ コードの生成に必要な変数の固定小数点データ型を定義するデータ型関数を生成します。filename は機械学習モデルを格納し、X にはモデルの関数 predict の予測子データが含まれます。

生成された関数を使用して、固定小数点データ型を定義する構造体を作成します。この場合、loadLearnerForCoder の入力引数 T として構造体を使用します。

generateLearnerDataTypeFcn(filename,X,Name,Value) では、1 つ以上の名前と値のペアの引数を使用して追加オプションを指定します。たとえば、固定小数点データ型で 32 ビットのワード長を使用するには、'WordLength',32 を指定します。

例

予測用の固定小数点の C/C++ コードの生成

機械学習モデルに学習させた後で、saveLearnerForCoder を使用してモデルを保存します。固定小数点のコード生成の場合、generateLearnerDataTypeFcnによって生成されるデータ型関数を使用して、予測に必要な変数の固定小数点データ型を指定します。次に、loadLearnerForCoder および指定した固定小数点データ型の両方を使用してモデルを読み込んでからモデルの関数 predict を呼び出す、エントリポイント関数を定義します。codegen (MATLAB Coder)を使用してエントリポイント関数の固定小数点の C/C++ コードを生成し、生成されたコードを確認します。

codegen を使用してコードを生成する前に、buildInstrumentedMex (Fixed-Point Designer)とshowInstrumentationResults (Fixed-Point Designer)を使用して固定小数点データ型を最適化し、固定小数点コードのパフォーマンスを向上させることができます。buildInstrumentedMex を使用して、予測用の名前付きの内部変数の最小値と最大値を記録します。showInstrumentationResults を使用して計測結果を表示します。次に、その結果に基づいて、変数の固定小数点データ型のプロパティを調整します。このオプション手順の詳細については、SVM の予測用の固定小数点コード生成を参照してください。

モデルの学習

ionosphere データセットを読み込み、バイナリ SVM 分類モデルに学習をさせます。

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

Mdl は ClassificationSVM モデルです。

モデルの保存

saveLearnerForCoder を使用して、SVM 分類モデルを myMdl.mat というファイルに保存します。

saveLearnerForCoder(Mdl,'myMdl');

固定小数点データ型の定義

generateLearnerDataTypeFcn を使用して、SVM モデルの予測に必要な変数の固定小数点データ型を定義する関数を生成します。

generateLearnerDataTypeFcn('myMdl',X)

generateLearnerDataTypeFcn は関数 myMdl_datatype を生成します。

myMdl_datatype を使用して、固定小数点データ型を定義する構造体 T を作成します。

T = myMdl_datatype('Fixed')

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

構造体 T には、関数 predict の実行に必要な名前付きの内部変数に対するフィールドが含まれています。各フィールドには、fi (Fixed-Point Designer)で返される固定小数点オブジェクトが含まれています。固定小数点オブジェクトは、語長や小数部の長さなどの固定小数点データ型のプロパティを指定します。たとえば、予測子データの固定小数点データ型プロパティを表示します。

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

エントリポイント関数の定義

以下を行う myFixedPointPredict という名前のエントリポイント関数を定義します。

• 予測子データ X および固定小数点データ型構造体 T を受け入れる。

• loadLearnerForCoder および構造体 T の両方を使用して、学習済み SVM 分類モデルの固定小数点バージョンを読み込みます。

• 読み込まれたモデルを使用してラベルとスコアを予測する。

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

メモ: この例の右上にあるボタンをクリックして MATLAB® で例を開くと、MATLAB は例のフォルダーを開きます。このフォルダーには、エントリポイント関数のファイルが含まれています。

コードの生成

構造体 T の XDataType フィールドは予測子データの固定小数点データ型を指定します。関数cast (Fixed-Point Designer)を使用して X を T.XDataType で指定された型に変換します。

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

codegen を使用して、エントリポイント関数のコードを生成します。X_fx と定数畳み込みされた T をエントリポイント関数の入力引数として指定します。

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

Code generation successful.

codegen は、プラットフォームに依存する拡張子をもつ MEX 関数 myFixedPointPredict_mex を生成します。

生成されたコードの確認

予測子データを predict と myFixedPointPredict_mex に渡し、出力を比較します。

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

predict と myFixedPointPredict_mex からの出力を比較します。

verify_labels = isequal(labels,labels_fx)

verify_labels = logical
   1

isequalは、logical 1 (true) を返します。これは labels と labels_fx が等しいことを意味します。ラベルが等しくない場合、不正に分類されたラベルの割合を次のように計算できます。

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

ans = 0

スコア出力間の相対的な差分の最大値を求めます。

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

relDiff_scores = 0.0055

比較結果に満足せず、生成されたコードの精度を向上させる場合、固定小数点データ型を調整し、コードを再生成できます。詳細については、generateLearnerDataTypeFcn のヒント、データ型関数およびSVM の予測用の固定小数点コード生成を参照してください。

入力引数

filename — モデル オブジェクトを表す構造体配列が格納されている MAT ファイルの名前

文字ベクトル | string スカラー

モデル オブジェクトを表す構造体配列が格納されている MATLAB 形式のバイナリ ファイル (MAT ファイル) の名前。文字ベクトルまたは string スカラーを指定します。

filename ファイルは saveLearnerForCoder を使用して作成しなければならず、filename 内のモデルは次のいずれかとすることができます。

• 分類モデル

  • 決定木 (CompactClassificationTree)

  • 決定木のアンサンブル (CompactClassificationEnsemble、ClassificationBaggedEnsemble)

  • SVM (サポート ベクター マシン) (CompactClassificationSVM)

• 回帰モデル

  • 決定木 (CompactRegressionTree)

  • 決定木のアンサンブル (CompactRegressionEnsemble、RegressionBaggedEnsemble)

  • SVM (CompactRegressionSVM)

filename ファイルの拡張子は .mat でなければなりません。filename に拡張子がない場合、generateLearnerDataTypeFcn は .mat を追加します。

filename に絶対パスが含まれていない場合、generateLearnerDataTypeFcn は現在のフォルダーからファイルを読み込みます。

例: 'myMdl'

データ型: char | string

X — 予測子データ

数値行列

filename に格納されているモデルの関数 predict の予測子データ。n 行 p 列の数値行列を指定します。n は観測値の個数、p は予測子変数の個数です。

データ型: single | double

名前と値の引数

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

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

例: generateLearnerDataTypeFcn(filename,X,'OutputFunctionName','myDataTypeFcn','WordLength',32) は、各変数の固定小数点データ型を定義するときに、語長に 32 ビットを使用する myDataTypeFcn という名前のデータ型関数を生成します。

OutputFunctionName — 生成された関数の名前

filename + _datatype (既定値) | 文字ベクトル | string スカラー

生成された関数の名前。'OutputFunctionName' と文字ベクトルまたは string スカラーから構成されるコンマ区切りのペアとして指定します。'OutputFunctionName' 値は有効な MATLAB 関数名でなければなりません。

既定の関数名は、filename 内のファイル名に _datatype を追加した名前です。たとえば、filename が myMdl である場合、既定の関数名は myMdl_datatype です。

例: 'OutputFunctionName','myDataTypeFcn'

データ型: char | string

WordLength — ビット単位の語長

16 (既定値) | 数値スカラー

ビット単位の語長。'WordLength' と数値スカラーで構成されるコンマ区切りのペアとして指定します。

生成されたデータ型関数は、指定された 'WordLength' 値を使用して各変数の固定小数点オブジェクトを定義します。より長い語長が必要な変数の場合、その変数の語長は倍の長さになります。

最適な語長は、ターゲット ハードウェアのプロパティに依存します。指定された語長がターゲット ハードウェアの最長ワード サイズより長い場合、生成されたコードにはマルチワード処理が含まれます。

詳細については、固定小数点データ型 (Fixed-Point Designer)を参照してください。

例: 'WordLength',32

データ型: single | double

OutputRange — predict の出力の範囲

X を使用してシミュレートされた範囲 (既定値) | 2 つの要素の数値ベクトル

関数 predict の出力引数の範囲。'OutputRange' と 2 つの要素の数値ベクトル (出力の最小値と最大値) から構成されるコンマ区切りのペアとして指定します。

'OutputRange' 値は、分類モデルについて予測されるクラス スコアの範囲、および回帰モデルについて予測される応答の範囲を指定します。次の表は、名前と値のペアの引数 'OutputRange' を使用して範囲を指定できる出力引数の一覧です。

分類モデル

モデル	モデルの関数 predict	出力引数
決定木	predict	score
決定木のアンサンブル	predict	score
SVM	predict	score

回帰モデル

モデル	モデルの関数 predict	出力引数
決定木	predict	Yfit
決定木のアンサンブル	predict	Yfit
SVM	predict	yfit

X に大量の観測値が含まれていて、出力引数の範囲がわかっている場合、'OutputRange' 値を指定して計算量を削減します。

'OutputRange' の値を指定しない場合、予測子データ X と関数 predict を使用して出力範囲をシミュレートします。

'OutputRange' 値と 'PercentSafetyMargin' 値を使用して、固定小数点データが表現できる数の範囲が決定されます。

例: 'OutputRange',[0,1]

データ型: single | double

PercentSafetyMargin — 安全余裕のパーセンテージ

10 (既定値) | 数値スカラー

安全余裕のパーセンテージ。'PercentSafetyMargin' と数値スカラーで構成されるコンマ区切りのペアとして指定します。

変数ごとに変数の範囲をシミュレートし、指定された安全余裕が追加されることで、固定小数点データが表現できる数の範囲が決定されます。この場合、オーバーフローを発生させない最大の小数部の長さが提案されます。

'PercentSafetyMargin' の値を使用する場合は注意してください。変数の範囲が大きいと、指定の語長を使用してより大きい範囲を表すために小数部の長さが削減されるため、安全余裕を増やすことでアンダーフローが発生する場合があります。

例: 'PercentSafetyMargin',15

データ型: single | double

詳細

データ型関数

generateLearnerDataTypeFcn によって生成されるデータ型関数を使用して、機械学習モデルの予測用の固定小数点の C/C++ コードの生成に必要な変数の固定小数点データ型を定義する構造体を作成します。データ型関数の出力構造体を loadLearnerForCoder の入力引数 T として使用します。

filename が 'myMdl' である場合、generateLearnerDataTypeFcn は myMdl_datatype という名前のデータ型関数を生成します。関数 myMdl_datatype は次の構文をサポートします。

T = myMdl_datatype(dt)

T = myMdl_datatype(dt) は、機械学習モデルの予測用の固定小数点の C/C++ コードの生成に必要な変数のデータ型を定義するデータ型構造体を返します。

T の各フィールドには、fi (Fixed-Point Designer) で返される固定小数点オブジェクトが含まれています。入力引数 dt は、固定小数点オブジェクトの DataType プロパティを指定します。

• 固定小数点コードの生成の場合、dt には 'Fixed' (既定値) を指定します。

• dt に 'Double' を指定すると、固定小数点コードの浮動小数点動作をシミュレートできます。

出力構造体 T を loadLearnerForCoder の 2 番目の入力引数として使用します。

構造体 T は、次の表のフィールドを含みます。これらのフィールドは、モデルの精度に直接影響する変数のデータ型を定義します。これらの変数は、他の名前付きの内部変数と共にモデルの関数 predict を実行するために必要です。

説明	フィールド
分類用の共通フィールド	XDataType (入力) ScoreDataType (出力または内部変数) および TransformedScoreDataType (出力) 'none' または 'identity' の既定値 'ScoreTransform' を使用してモデルに学習させる (つまり、予測されたスコアを変換しない) 場合、ScoreDataType フィールドは出力スコアの適合率に影響を与えます。 'none' または 'identity' 以外の 'ScoreTransform' の値を使用してモデルに学習させる (つまり、予測されたスコアを変換する) 場合、ScoreDataType フィールドは内部未変換スコアの適合率に影響を与えます。TransformedScoreDataType フィールドは、変換された出力スコアの適合率に影響を与えます。
回帰用の共通フィールド	XDataType (入力) YFitDataType (出力)
決定木のアンサンブル用の追加フィールド	WeakLearnerOutputDataType (内部変数) — 弱学習器からの出力に関するデータ型。 AggregatedLearnerWeightsDataType (内部変数) — 弱学習器からの出力の重み付き集計に関するデータ型。バギング ('Method','bag') を使用してモデルの学習を行う場合のみ適用可能です。ソフトウェアは、学習器の重みの和で集計を除算することによって、予測されるスコア (ScoreDataType) を計算します。
SVM 用の追加フィールド	XnormDataType (内部変数) ('Standardize' または 'KernelScale' を使用してモデルの学習を行う場合のみ適用可能) InnerProductDataType (内部変数)

各変数について、既定の語長 (16) と安全余裕 (10%) に基づいて、オーバーフローを発生させない最大の小数部の長さが提案されます。

filename が 'myMdl' であり、filename ファイル内のモデルが SVM 分類器である場合、次のコードは、generateLearnerDataTypeFcn によって生成されたデータ型関数 myMdl_datatype を示します。

function T = myMdl_datatype(dt)

if nargin < 1
	dt = 'Fixed';
end

% Set fixed-point math settings
fm = fimath('RoundingMethod','Floor', ...
    'OverflowAction','Wrap', ...
    'ProductMode','FullPrecision', ...
    'MaxProductWordLength',128, ...
    'SumMode','FullPrecision', ...
    'MaxSumWordLength',128);

% Data type for predictor data
T.XDataType = fi([],true,16,14,fm,'DataType',dt);

% Data type for output score
T.ScoreDataType = fi([],true,16,14,fm,'DataType',dt);

% Internal variables
% Data type of the squared distance dist = (x-sv)^2 for the Gaussian kernel G(x,sv) = exp(-dist),
% where x is the predictor data for an observation and sv is a support vector
T.InnerProductDataType = fi([],true,16,6,fm,'DataType',dt);

end

ヒント

• 生成された固定小数点コードの精度を向上させるために、固定小数点データ型を調整できます。データ型関数 (myMdl_datatype) を更新して、新しい構造体を作成して固定小数点データ型を変更し、その新しい構造体を使用してコードを再生成します。次の 2 つの方法のいずれかで、関数 myMdl_datatype を更新できます。

  • generateLearnerDataTypeFcn とその名前と値のペアの引数を使用して、関数 myMdl_datatype を再生成します。

    • 名前と値のペアの引数 'WordLength' を使用して、語長を増やします。

    • 名前と値のペアの引数 'PercentSafetyMargin' を使用して、安全余裕を減らします。

    語長を増やしたり、安全余裕を減らしたりすると、より長い小数部の長さが提案され、したがって、指定のデータセットに基づいて生成されたコードの精度が向上します。

  • 関数ファイル (myMdl_datatype.m) の固定小数点データ型を手動で変更します。各変数について、語長と小数部の長さを調整し、fimath (Fixed-Point Designer) オブジェクトを使用して固定小数点の数学的設定を指定できます。

• 生成された固定小数点コードで、操作を大量に行ったり、変数範囲を大きくすると、対応する浮動小数点コードの精度と比較して精度が失われる可能性があります。SVM モデルの学習時は、次のヒントに注意して、生成された固定小数点コードの精度が失われないようにします。

  • データの標準化 ('Standardize') — SVM モデルのサポート ベクターのモデル プロパティの値がオーバーフローしないようにするために、予測子データを標準化できます。モデルを学習させるときに名前と値のペアの引数 'Standardize' を使用せず、データを近似関数と関数 predict に渡す前に予測子データを標準化し、固定小数点コードに標準化の操作が含まれないようにします。

  • カーネル関数 ('KernelFunction') — 多項式カーネルを使用するより、ガウス カーネルまたは線形カーネルを使用する方が適切です。多項式カーネルは、他のカーネルよりさらに多くの計算量が必要であり、多項式カーネル関数の出力は無制限です。

  • カーネル スケール ('KernelScale') — カーネル スケールを使用すると、'KernelScale' の値が 1 ではない場合に追加の操作が必要です。

  • 予測されたクラス スコアの値の範囲が大きい場合、1 クラス分類問題の予測の精度が失われる可能性があります。

バージョン履歴

R2019b で導入

R2020a: 変換されたスコアの適合率の変換前後における指定

R2019b では、既定ではないいくつかのスコア変換 ('ismax'、'sign'、'symmetric'、または 'symmetricismax') を使って固定小数点コードを生成するため、SVM 分類器に学習させることができました。関数 generateLearnerDataTypeFcn は、出力構造体に、スコアに関連するフィールドを 1 つだけ (ScoreDataType) 含むデータ型関数を生成しました。このフィールドは、変換前と変換後の両方で、出力スコアの適合率に影響を与えていました。

R2020a 以降については、'none' または 'identity' 以外のスコア変換で SVM 分類器に学習させる場合、関数 generateLearnerDataTypeFcn は、出力構造体 T に、スコアに関連するフィールドを 2 つ (ScoreDataType および TransformedScoreDataType) 含むデータ型関数を生成します。これらの各フィールドを使用することにより、変換前と変換後それぞれについて、出力スコアの適合率に影響を与えることができます。詳細は、データ型関数を参照してください。

コードを更新するには、関数 generateLearnerDataTypeFcn を再実行してから、出力構造体 T を再生成します。

参考

loadLearnerForCoder | saveLearnerForCoder | buildInstrumentedMex (Fixed-Point Designer) | showInstrumentationResults (Fixed-Point Designer) | codegen (MATLAB Coder) | fi (Fixed-Point Designer)

トピック

• SVM の予測用の固定小数点コード生成

×

例を開く

この例の変更されたバージョンがあります。編集された方の例を開きますか?

いいえ、変更されたバージョンを上書きします。 はい