functionLayer

関数層

R2021b 以降

説明

関数層は、指定された関数を層の入力に適用します。

タスクに必要な層が Deep Learning Toolbox™ に用意されていない場合、functionLayer を使用して関数層を作成することで、新しい層を定義することができます。関数層は、追加のプロパティ、学習可能なパラメーター、または状態を必要としない演算のみをサポートします。この機能を必要とする層については、層をカスタム層として定義してください。詳細については、カスタム深層学習層の定義を参照してください。

作成

構文

layer = functionLayer(fun)

layer = functionLayer(fun,Name=Value)

説明

layer = functionLayer(fun) は、関数層を作成し、PredictFcn プロパティを設定します。

layer = functionLayer(fun,Name=Value) は、1 つ以上の名前と値の引数を使用して、オプションのプロパティを設定します。たとえば、functionLayer(fun,NumInputs=2,NumOutputs=3) は、ネットワークに 2 つの入力と 3 つの出力があることを指定します。複数の名前と値の引数を指定できます。

入力引数

fun — 層の入力に適用する関数

関数ハンドル

層の入力に適用する関数。構文 [Y1,...,YM] = fun(X1,...,XN) をもつ関数ハンドルとして指定します。ここで、入力と出力は dlarray オブジェクトで、M と N はそれぞれ NumOutputs と NumInputs に対応します。この構文では、入力 X1, …, XN は、InputNames で与えられた名前をもつ層入力に対応します。出力 Y1, …, YM は、OutputNames で与えられた名前をもつ層出力に対応します。

ヒント

層の使用時には、指定した関数に必ずアクセスできるようにしなければなりません。たとえば、複数のライブ スクリプトで層を必ず再利用できるようにするには、関数を個別のファイルに保存します。

層の作成時、指定した関数にアクセスできない場合、NumInputs 引数および NumOutputs 引数を指定しなければなりません。

予測関数の入力と出力は複素数値にすることができます。 (R2024a 以降)層が複素数値データを出力する場合、ニューラル ネットワークで層を使用するときに、後続の層または損失関数が複素数値入力をサポートしていることを確認しなければなりません。

R2024a より前: 予測関数の入力と出力は複素数であってはなりません。層の予測関数に複素数が含まれる場合は、すべての出力を実数値に変換してから返します。

dlarray 入力をサポートしている関数の一覧については、dlarray をサポートする関数の一覧を参照してください。

この引数は PredictFcn プロパティを設定します。

データ型: function_handle

名前と値の引数

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

例: functionLayer(fun,NumInputs=2,NumOutputs=3) は、層に 2 つの入力と 3 つの出力があることを指定します。

Formattable — 形式を整えたデータと形式を整えていないデータの処理のカスタマイズを有効にするフラグ

0 (false) (既定値) | 1 (true)

形式を整えたデータと形式を整えていないデータの処理のカスタマイズを有効にするフラグ。0 (false) または 1 (true) として指定します。

次の表は、ソフトウェアが functionLayer オブジェクトの形式を整えたデータと形式を整えていないデータを処理する方法を示しています。

Formattable の値	入力データの処理	出力データの処理
1 (true)	ソフトウェアは層入力を層関数に直接渡します。 層が形式を整えたデータを受け取った場合、ソフトウェアは形式を整えたデータを層関数に渡す。 層が形式を整えていないデータを受け取った場合、ソフトウェアは形式を整えていないデータを層関数に渡す。	ソフトウェアは層関数の出力を後続の層に直接渡します。 層関数が形式を整えたデータを返す場合、ソフトウェアは形式を整えたデータを後続の層に渡す。 層が形式を整えたデータを受け取り、層関数が形式を整えていないデータを出力する場合、ソフトウェアは入力データの形式を出力データに自動的に適用し、形式を整えたデータを後続の層に渡す。 層が形式を整えていないデータを受け取り、層関数が形式を整えていないデータを返す場合、ソフトウェアは形式を整えていないデータを後続の層に渡す。 警告 Formattable 引数が 1 (true) に設定された functionLayer オブジェクトにおいて、形式を整えていないデータの形式を自動的に整える機能は、将来のリリースで削除される予定です。代わりに、必ず層が形式を整えたデータを出力するようにしてください。従来の動作を再現するには、層の関数でコマンド Y = dlarray(Y,dims(X)); を使用します。ここで、X と Y はそれぞれ層の入力と出力です。
0 (false)	ソフトウェアは形式を整えた入力から形式を削除し、形式を整えていないデータを層関数に渡します。 層が形式を整えたデータを受け取った場合、ソフトウェアは形式を削除し、形式を整えていないデータを層関数に渡す。 層が形式を整えていないデータを受け取った場合、形式を整えていないデータを層関数に直接渡す。 (R2024b 以降) R2024b より前: Formattable が 0 (false) である場合、層入力の形式を整えなければならない。	出力データの形式は整っていてはなりません。ソフトウェアは、形式を整えていない層関数の出力に層入力の形式を適用し、その結果を後続の層に渡します。 層が形式を整えていないデータを受け取り、層関数が形式を整えていないデータを出力する場合、ソフトウェアは形式を整えていないデータを後続の層に渡す。 層が形式を整えたデータを受け取り、層関数が形式を整えていないデータを出力する場合、ソフトウェアは層入力の形式を自動的に適用し、形式を整えたデータを後続の層に渡す。

次の表は、ソフトウェアが functionLayer オブジェクトの形式を整えたデータと形式を整えていないデータを処理する方法を示しています。

Formattable の値	入力データの処理	出力データの処理
1 (true)	ソフトウェアは層入力を層関数に直接渡します。 層が形式を整えたデータを受け取った場合、ソフトウェアは形式を整えたデータを層関数に渡す。 層が形式を整えていないデータを受け取った場合、ソフトウェアは形式を整えていないデータを層関数に渡す。	ソフトウェアは層関数の出力を後続の層に直接渡します。 層関数が形式を整えたデータを返す場合、ソフトウェアは形式を整えたデータを後続の層に渡す。 層が形式を整えたデータを受け取り、層関数が形式を整えていないデータを出力する場合、ソフトウェアは入力データの形式を出力データに自動的に適用し、形式を整えたデータを後続の層に渡す。 層が形式を整えていないデータを受け取り、層関数が形式を整えていないデータを返す場合、ソフトウェアは形式を整えていないデータを後続の層に渡す。 警告 Formattable 引数が 1 (true) に設定された functionLayer オブジェクトにおいて、形式を整えていないデータの形式を自動的に整える機能は、将来のリリースで削除される予定です。代わりに、必ず層が形式を整えたデータを出力するようにしてください。従来の動作を再現するには、層の関数でコマンド Y = dlarray(Y,dims(X)); を使用します。ここで、X と Y はそれぞれ層の入力と出力です。
0 (false)	ソフトウェアは形式を整えた入力から形式を削除し、形式を整えていないデータを層関数に渡します。 層が形式を整えたデータを受け取った場合、ソフトウェアは形式を削除し、形式を整えていないデータを層関数に渡す。 層が形式を整えていないデータを受け取った場合、形式を整えていないデータを層関数に直接渡す。 (R2024b 以降) R2024b より前: Formattable が 0 (false) である場合、層入力の形式を整えなければならない。	出力データの形式は整っていてはなりません。ソフトウェアは、形式を整えていない層関数の出力に層入力の形式を適用し、その結果を後続の層に渡します。 層が形式を整えていないデータを受け取り、層関数が形式を整えていないデータを出力する場合、ソフトウェアは形式を整えていないデータを後続の層に渡す。 層が形式を整えたデータを受け取り、層関数が形式を整えていないデータを出力する場合、ソフトウェアは層入力の形式を自動的に適用し、形式を整えたデータを後続の層に渡す。

この引数は Formattable プロパティを設定します。

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Acceleratable — 関数が高速化をサポートするかどうかを表すフラグ

0 (false) (既定値) | 1 (true)

層の関数が dlaccelerate 関数による高速化をサポートするかどうかを表すフラグ。0 (false) または 1 (true) として指定します。

この引数は Acceleratable プロパティを設定します。

データ型: logical

NumInputs — 入力の数

正の整数

入力の数。正の整数として指定します。

層の入力の数は固定でなければなりません。PredictFcn が varargin による可変個の入力引数をサポートしている場合、NumInputs または InputNames を使用して層の入力の数を指定しなければなりません。

fun の入力数が固定されている場合、既定値は nargin(fun) になります。

この引数は NumInputs プロパティを設定します。

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

InputNames — 入力名

string 配列 | 文字ベクトルの cell 配列

層の入力名。string 配列または文字ベクトルの cell 配列として指定します。

層の入力の数は固定でなければなりません。PredictFcn が varargin による可変個の入力引数をサポートしている場合、NumInputs または InputNames を使用して層の入力の数を指定しなければなりません。

NumInputs が 1 である場合、既定値は "in" になります。NumInputs が 1 より大きい場合、既定値は ["in1" "in2" ... "inN"] になります。ここで、N は入力の数です。

この引数は InputNames プロパティを設定します。

データ型: string | cell

NumOutputs — 出力の数

1 (既定値) | 正の整数

層の出力の数。正の整数として指定します。

層の出力の数は固定でなければなりません。PredictFcn が varargout を使用した可変個の出力引数をサポートしている場合、NumOutputs または OutputNames を使用して層の出力の数を指定しなければなりません。

fun の出力数が固定されている場合、既定値は nargout(fun) になります。

この引数は NumOutputs プロパティを設定します。

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

OutputNames — 出力名

string 配列 | 文字ベクトルの cell 配列

層の出力の名前。文字ベクトルの string 配列または cell 配列として指定します。

層の出力の数は固定でなければなりません。PredictFcn が varargout を使用した可変個の出力引数をサポートしている場合、NumOutputs または OutputNames を使用して層の出力の数を指定しなければなりません。

NumOutputs が 1 である場合、既定値は "out" になります。NumOutputs が 1 より大きい場合、既定は ["out1" "out2" ... "outM"} になります。ここで、M は出力の数です。

この引数は OutputNames プロパティを設定します。

データ型: string | cell

Name — 層の名前

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

層の名前。文字ベクトルまたは string スカラーとして指定します。Layer 配列入力の場合、関数 trainnet および関数 dlnetwork は、名前が "" の層に自動的に名前を割り当てます。

この引数は Name プロパティを設定します。

データ型: char | string

Description — 層についての 1 行の説明

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

層についての 1 行の説明。string スカラーまたは文字ベクトルとして指定します。この説明は、Layer 配列を表示するとき、および analyzeNetwork 関数を使用するときに表示されます。

層の説明を指定しない場合、ソフトウェアは層の演算を使用します。

データ型: char | string

プロパティ

関数

PredictFcn — 層の入力に適用する関数

関数ハンドル

このプロパティは、作成後、読み取り専用になります。

層の入力に適用する関数。構文 [Y1,...,YM] = fun(X1,...,XN) をもつ関数ハンドルとして指定します。ここで、入力と出力は dlarray オブジェクトで、M と N はそれぞれ NumOutputs と NumInputs に対応します。この構文では、入力 X1, …, XN は、InputNames で与えられた名前をもつ層入力に対応します。出力 Y1, …, YM は、OutputNames で与えられた名前をもつ層出力に対応します。

ヒント

層の使用時には、指定した関数に必ずアクセスできるようにしなければなりません。たとえば、複数のライブ スクリプトで層を必ず再利用できるようにするには、関数を個別のファイルに保存します。

データ型: function_handle

Formattable — 形式を整えたデータと形式を整えていないデータの処理のカスタマイズを有効にするフラグ

0 (false) (既定値) | 1 (true)

このプロパティは、作成後、読み取り専用になります。

形式を整えたデータと形式を整えていないデータの処理のカスタマイズを有効にするフラグ。0 (false) または 1 (true) として指定します。

次の表は、ソフトウェアが functionLayer オブジェクトの形式を整えたデータと形式を整えていないデータを処理する方法を示しています。

Formattable の値	入力データの処理	出力データの処理
1 (true)	ソフトウェアは層入力を層関数に直接渡します。 層が形式を整えたデータを受け取った場合、ソフトウェアは形式を整えたデータを層関数に渡す。 層が形式を整えていないデータを受け取った場合、ソフトウェアは形式を整えていないデータを層関数に渡す。	ソフトウェアは層関数の出力を後続の層に直接渡します。 層関数が形式を整えたデータを返す場合、ソフトウェアは形式を整えたデータを後続の層に渡す。 層が形式を整えたデータを受け取り、層関数が形式を整えていないデータを出力する場合、ソフトウェアは入力データの形式を出力データに自動的に適用し、形式を整えたデータを後続の層に渡す。 層が形式を整えていないデータを受け取り、層関数が形式を整えていないデータを返す場合、ソフトウェアは形式を整えていないデータを後続の層に渡す。 警告 Formattable 引数が 1 (true) に設定された functionLayer オブジェクトにおいて、形式を整えていないデータの形式を自動的に整える機能は、将来のリリースで削除される予定です。代わりに、必ず層が形式を整えたデータを出力するようにしてください。従来の動作を再現するには、層の関数でコマンド Y = dlarray(Y,dims(X)); を使用します。ここで、X と Y はそれぞれ層の入力と出力です。
0 (false)	ソフトウェアは形式を整えた入力から形式を削除し、形式を整えていないデータを層関数に渡します。 層が形式を整えたデータを受け取った場合、ソフトウェアは形式を削除し、形式を整えていないデータを層関数に渡す。 層が形式を整えていないデータを受け取った場合、形式を整えていないデータを層関数に直接渡す。 (R2024b 以降) R2024b より前: Formattable が 0 (false) である場合、層入力の形式を整えなければならない。	出力データの形式は整っていてはなりません。ソフトウェアは、形式を整えていない層関数の出力に層入力の形式を適用し、その結果を後続の層に渡します。 層が形式を整えていないデータを受け取り、層関数が形式を整えていないデータを出力する場合、ソフトウェアは形式を整えていないデータを後続の層に渡す。 層が形式を整えたデータを受け取り、層関数が形式を整えていないデータを出力する場合、ソフトウェアは層入力の形式を自動的に適用し、形式を整えたデータを後続の層に渡す。

データ型: logical

Acceleratable — 関数が高速化をサポートするかどうかを表すフラグ

0 (false) (既定値) | 1 (true)

このプロパティは、作成後、読み取り専用になります。

層の関数が dlaccelerate 関数による高速化をサポートするかどうかを表すフラグ。0 (false) または 1 (true) として指定します。

データ型: logical

層

Name — 層の名前

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

層の名前。文字ベクトルまたは string スカラーとして指定します。Layer 配列入力の場合、trainnet 関数および dlnetwork 関数は、名前のない層に自動的に名前を割り当てます。

FunctionLayer オブジェクトは、このプロパティを文字ベクトルとして格納します。

データ型: char | string

Description — 層についての 1 行の説明

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

このプロパティは、作成後、読み取り専用になります。

層についての 1 行の説明。string スカラーまたは文字ベクトルとして指定します。この説明は、Layer 配列を表示するとき、および analyzeNetwork 関数を使用するときに表示されます。

データ型: char | string

NumInputs — 入力の数

正の整数

このプロパティは、作成後、読み取り専用になります。

入力の数。正の整数として指定します。

データ型: double

InputNames — 入力名

文字ベクトルの cell 配列

このプロパティは、作成後、読み取り専用になります。

層の入力名。文字ベクトルの cell 配列として保存されます。

データ型: cell

NumOutputs — 出力の数

1 (既定値) | 正の整数

このプロパティは、作成後、読み取り専用になります。

層の出力の数。正の整数として指定します。

データ型: double

OutputNames — 出力名

文字ベクトルの cell 配列

このプロパティは、作成後、読み取り専用になります。

層の出力名。文字ベクトルの cell 配列として保存されます。

データ型: cell

例

ソフトサイン層の関数層としての定義

入力にソフトサイン演算を適用する関数層オブジェクトを作成します。ソフトサイン演算は、関数 $\mathit{f}\left(\mathit{x}\right)=\frac{\mathit{x}}{1+\left|\mathit{x}\right|}$ で表されます。

layer = functionLayer(@(X) X./(1 + abs(X)))

関数層として指定されたソフトサイン層を層配列に含めます。この層に "softsign" という説明があることを指定します。

layers = [
    imageInputLayer([28 28 1])
    convolution2dLayer(5,20)
    functionLayer(@(X) X./(1 + abs(X)),Description="softsign")
    maxPooling2dLayer(2,Stride=2)
    fullyConnectedLayer(10)
    softmaxLayer]

関数層を使用したデータの再構築

"CB" (チャネル、バッチ) という形式の入力データを "SBC" (空間、バッチ、チャネル) という形式に再構築する関数層を作成します。形式を整えたデータに層が作用することを指定するには、Formattable オプションを true に設定します。層の関数が dlaccelerate による高速化をサポートすることを指定するには、Acceleratable オプションを true に設定します。

layer = functionLayer(@(X) dlarray(X,"SBC"),Formattable=true,Acceleratable=true)

layer = 
  FunctionLayer with properties:

             Name: ''
       PredictFcn: @(X)dlarray(X,"SBC")
      Formattable: 1
    Acceleratable: 1

   Learnable Parameters
    No properties.

   State Parameters
    No properties.

  Show all properties

"SB" という形式に入力を再構築する関数層を層配列に含めます。層の説明を "channel to spatial" に設定します。

layers = [
    featureInputLayer(10)
    functionLayer(@(X) dlarray(X,"SBC"),Formattable=true,Acceleratable=true,Description="channel to spatial")
    convolution1dLayer(3,16)]

layers = 
  3×1 Layer array with layers:

     1   ''   Feature Input     10 features
     2   ''   Function          channel to spatial
     3   ''   1-D Convolution   16 3 convolutions with stride 1 and padding [0  0]

このネットワークでは、1 次元畳み込み層により、入力データの "S" (空間) 次元に沿って畳み込みが行われます。この演算は、ネットワークの入力データの "C" (チャネル) 次元に沿った畳み込みと同等です。

層配列を dlnetwork オブジェクトに変換し、"CB" という形式をもつデータのランダム配列を渡します。

dlnet = dlnetwork(layers);

X = rand(10,64);
dlX = dlarray(X,"CB");

dlY = forward(dlnet,dlX);

出力データのサイズと形式を表示します。

size(dlY)

ans = 1×3

     8    16    64

dims(dlY)

ans = 
'SCB'

アルゴリズム

層の入力形式と出力形式

層配列内または層グラフ内の層は、形式を整えた dlarray オブジェクトとして後続の層にデータを渡します。dlarray オブジェクトの形式は文字列で、各文字はデータ内の対応する次元を表します。この形式には次の文字が 1 つ以上含まれています。

• "S" — 空間

• "C" — チャネル

• "B" — バッチ

• "T" — 時間

• "U" — 指定なし

たとえば、4 次元配列として表された 2 次元イメージ データがあり、最初の 2 つの次元がイメージの空間次元に対応し、3 番目の次元がイメージのチャネルに対応し、4 番目の次元がバッチ次元に対応している場合、このイメージ データは "SSCB" (空間、空間、チャネル、バッチ) という形式で記述できます。

形式を整えた dlarray オブジェクトを層関数で使用することで、次元の並べ替え、追加、削除を行う層など、入力と出力の形式が異なる層を定義することもできます。たとえば、形式が "SSCB" (spatial、spatial、channel、batch) であるイメージのミニバッチを入力として受け取り、形式が "CBT" (channel、batch、time) であるシーケンスのミニバッチを出力する層を定義できます。形式を整えた dlarray オブジェクトを使用すると、入力形式が異なるデータの処理が可能な層を定義することもできます。たとえば、形式 "SSCB" (spatial、spatial、channel、batch) と "CBT" (channel、batch、time) の入力をサポートする層を定義できます。

Formattable 引数を設定することで、ソフトウェアが層とデータをやり取りする際に、形式を整えたデータや形式を整えていないデータをどのように処理するかを指定できます。

複素数値の入力と出力

FunctionLayer オブジェクトは、複素数値の入力と出力をサポートします。 (R2024a 以降)この層は、複素数値の入力に対して実数値の入力の場合と同じ forward 関数を適用し、結果が複素数となった場合は複素数値のデータを出力します。

拡張機能

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意および制限:

• 層の関数 fun は、パス上の名前付き関数でなければなりません。

• Formattable プロパティは 0 (false) でなければなりません。

GPU コード生成

GPU Coder™ を使用して NVIDIA® GPU のための CUDA® コードを生成します。

使用上の注意および制限:

• 層の関数 fun は、パス上の名前付き関数でなければなりません。

• Formattable プロパティは 0 (false) でなければなりません。

バージョン履歴

R2021b で導入

R2025a: 形式を整えていない層入力のサポート

関数層は、形式を整えていないデータを直接受け取れるようになりました。これらの層は、形式を整えていないデータを受け取ると、形式を整えていないデータを後続の層に渡します。

詳細については、Formattable 引数を参照してください。

R2025a: 出力の自動整形のサポートは削除予定

Formattable プロパティが 1 (true) に設定された functionLayer オブジェクトにおいて、形式を整えていないデータの形式を自動的に整える機能は、将来のリリースで削除される予定です。代わりに、必ず層が形式を整えたデータを出力するようにしてください。従来の動作を再現するには、層の forward 関数でコマンド Y = dlarray(Y,dims(X)); を使用します。ここで、X と Y はそれぞれ層の入力と出力です。

R2024a: 複素数値の入力と出力のサポート

FunctionLayer オブジェクトは、複素数値の入力と出力をサポートします。この層は、複素数値の入力に対して実数値の入力の場合と同じ forward 関数を適用し、結果が複素数となった場合は複素数値のデータを出力します。

参考

trainnet | trainingOptions | dlnetwork | findPlaceholderLayers | PlaceholderLayer | connectLayers | disconnectLayers | addLayers | removeLayers | replaceLayer

トピック

• MATLAB による深層学習
• カスタム深層学習層の定義