FunctionLayer - Function layer - MATLAB (original) (raw)

Function layer

Since R2021b

Description

A function layer applies a specified function to the layer input.

If Deep Learning Toolbox™ does not provide the layer that you need for your task, then you can define new layers by creating function layers using functionLayer. Function layers only support operations that do not require additional properties, learnable parameters, or states. For layers that require this functionality, define the layer as a custom layer. For more information, see Define Custom Deep Learning Layers.

Creation

Syntax

Description

`layer` = functionLayer([fun](#mw%5F395e8693-0862-4258-8f0a-dfeb9681e485)) creates a function layer and sets the PredictFcn property.

example

`layer` = functionLayer([fun](#mw%5F395e8693-0862-4258-8f0a-dfeb9681e485),[Name=Value](#namevaluepairarguments)) sets optional properties using one or more name-value arguments. For example,functionLayer(fun,NumInputs=2,NumOutputs=3) specifies that the layer has two inputs and three outputs. You can specify multiple name-value arguments.

example

Input Arguments

expand all

Function to apply to layer input, specified as a function handle with the syntax[Y1,...,YM] = fun(X1,...,XN), where the inputs and outputs aredlarray objects, and M and N correspond to NumOutputs and NumInputs, respectively. In this syntax, the inputs X1, …, XN correspond to the layer inputs with names given by InputNames. The outputs Y1, …, YM correspond to the layer outputs with names given by OutputNames.

Tip

When you use the layer, you must ensure that the specified function is accessible. For example, to ensure that the layer can be reused in multiple live scripts, save the function in its own separate file.

If the specified function is not accessible when you create the layer, then you must specify the NumInputs and NumOutputs arguments.

The inputs and outputs of the predict function can be complex-valued. (since R2024a) If the layer outputs complex-valued data, then when you use the layer in a neural network, you must ensure that the subsequent layers or loss function support complex-valued input.

Before R2024a: The inputs and outputs of the predict function must not be complex. If the predict function of the layer involves complex numbers, convert all outputs to real values before returning them.

For a list of functions that support dlarray input, see List of Functions with dlarray Support.

This argument sets the PredictFcn property.

Data Types: function_handle

Name-Value Arguments

expand all

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: functionLayer(fun,NumInputs=2,NumOutputs=3) specifies that the layer has two inputs and three outputs.

Flag to enable customization of processing of formatted and unformatted data, specified as0 (false) or 1 (true).

This table describes how the software processes formatted and unformatted data infunctionLayerobjects.

This table describes how the software processes formatted and unformatted data infunctionLayerobjects.

This argument sets the Formattable property.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Flag indicating whether the layer function supports acceleration using thedlaccelerate function, specified as 0 (false) or 1 (true).

This argument sets the Acceleratable property.

Data Types: logical

Number of inputs, specified as a positive integer.

The layer must have a fixed number of inputs. If PredictFcn supports a variable number of input arguments using varargin, then you must specify the number of layer inputs using NumInputs or InputNames.

If fun has a fixed number of inputs, then the default value is nargin(fun).

This argument sets the NumInputs property.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Input names of the layer, specified as a string array or a cell array of character vectors.

The layer must have a fixed number of inputs. If PredictFcn supports a variable number of input arguments using varargin, then you must specify the number of layer inputs using NumInputs or InputNames.

If NumInputs is 1, then the default value is "in". If NumInputs is greater than1, then the default value is ["in1" "in2" ... "inN"], where N is the number of inputs.

This argument sets the InputNames property.

Data Types: string | cell

Number of outputs of the layer, specified as a positive integer.

The layer must have a fixed number of outputs. If PredictFcn supports a variable number of output arguments using varargout, then you must specify the number of layer outputs using NumOutputs or OutputNames.

If fun has a fixed number of outputs, then the default value is nargout(fun).

This argument sets the NumOutputs property.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output names of the layer, specified as a string array or a cell array of character vectors.

The layer must have a fixed number of outputs. If PredictFcn supports a variable number of output arguments using varargout, then you must specify the number of layer outputs using NumOutputs or OutputNames.

If NumOutputs is 1, then the default value is "out". If NumOutputs is greater than 1, then the default is ["out1" "out2" ... "outM"}, where M is the number of outputs.

This argument sets the OutputNames property.

Data Types: string | cell

Layer name, specified as a character vector or a string scalar. For Layer array input, the trainnet and dlnetwork functions automatically assign names to layers with the name "".

This argument sets the Name property.

Data Types: char | string

One-line description of the layer, specified as a string scalar or a character vector. This description appears when you display a Layer array and when you use the analyzeNetwork function.

If you do not specify a layer description, then the software uses the layer operation.

Data Types: char | string

Properties

expand all

Function

This property is read-only after creation.

Function to apply to layer input, specified as a function handle with the syntax[Y1,...,YM] = fun(X1,...,XN), where the inputs and outputs aredlarray objects, and M and N correspond to NumOutputs and NumInputs, respectively. In this syntax, the inputs X1, …, XN correspond to the layer inputs with names given by InputNames. The outputs Y1, …, YM correspond to the layer outputs with names given by OutputNames.

Tip

When you use the layer, you must ensure that the specified function is accessible. For example, to ensure that the layer can be reused in multiple live scripts, save the function in its own separate file.

Data Types: function_handle

This property is read-only after creation.

Flag to enable customization of processing of formatted and unformatted data, specified as0 (false) or 1 (true).

This table describes how the software processes formatted and unformatted data infunctionLayerobjects.

Data Types: logical

This property is read-only after creation.

Flag indicating whether the layer function supports acceleration using thedlaccelerate function, specified as 0 (false) or 1 (true).

Data Types: logical

Layer

Data Types: char | string

This property is read-only after creation.

One-line description of the layer, specified as a string scalar or a character vector. This description appears when you display a Layer array and when you use the analyzeNetwork function.

Data Types: char | string

This property is read-only after creation.

Number of inputs, specified as a positive integer.

Data Types: double

This property is read-only after creation.

Input names of the layer, stored as a cell array of character vectors.

Data Types: cell

This property is read-only after creation.

Number of outputs of the layer, specified as a positive integer.

Data Types: double

This property is read-only after creation.

Output names of the layer, stored as a cell array of character vectors.

Data Types: cell

Examples

collapse all

Create a function layer object that applies the softsign operation to the input. The softsign operation is given by the function f(x)=x1+|x|.

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

Include a softsign layer, specified as a function layer, in a layer array. Specify that the layer has the description "softsign".

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

Create a function layer that reformats input data with the format "CB" (channel, batch) to have the format "SBC" (spatial, batch, channel). To specify that the layer operates on formatted data, set the Formattable option to true. To specify that the layer function supports acceleration using dlaccelerate, set the Acceleratable option to 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

Include a function layer that reformats the input to have the format "SB" in a layer array. Set the layer description to "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]

In this network, the 1-D convolution layer convolves over the "S" (spatial) dimension of its input data. This operation is equivalent to convolving over the "C" (channel) dimension of the network input data.

Convert the layer array to a dlnetwork object and pass a random array of data with the format "CB".

dlnet = dlnetwork(layers);

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

dlY = forward(dlnet,dlX);

View the size and format of the output data.

Algorithms

expand all

Layers in a layer array or layer graph pass data to subsequent layers as formatted dlarray objects. The format of a dlarray object is a string of characters in which each character describes the corresponding dimension of the data. The format consists of one or more of these characters:

• "S" — Spatial
• "C" — Channel
• "B" — Batch
• "T" — Time
• "U" — Unspecified

For example, you can describe 2-D image data that is represented as a 4-D array, where the first two dimensions correspond to the spatial dimensions of the images, the third dimension corresponds to the channels of the images, and the fourth dimension corresponds to the batch dimension, as having the format "SSCB" (spatial, spatial, channel, batch).

Using formatted dlarray objects in layers functions also allows you to define layers where the inputs and outputs have different formats, such as layers that permute, add, or remove dimensions. For example, you can define a layer that takes as input a mini-batch of images with the format "SSCB" (spatial, spatial, channel, batch) and output a mini-batch of sequences with the format"CBT" (channel, batch, time). Using formatteddlarray objects also allows you to define layers that can operate on data with different input formats, for example, layers that support inputs with the formats "SSCB" (spatial, spatial, channel, batch) and "CBT" (channel, batch, time).

You can specify how to processes formatted and unformatted data that the software passes to and from the layer by setting the Formattable argument.

FunctionLayer objects support complex-valued input and outputs. (since R2024a) The layer applies the same forward function to complex-valued input as it does to real-valued input and outputs complex-valued data where applicable.

Extended Capabilities

expand all

Usage notes and limitations:

• The layer function fun must be a named function on the path.
• The Formattable property must be 0 (false)

Usage notes and limitations:

• The layer function fun must be a named function on the path.
• The Formattable property must be 0 (false)

Version History

Introduced in R2021b

expand all

Function layers now support receiving unformatted data directly. When these layers receive unformatted data, they pass the unformatted data to subsequent layers.

For more information, see the Formattable argument.

For functionLayer objects with the Formattable property set to 1 (true), support for automatically formatting unformatted data will be removed in a future release. Instead, ensure that the layer outputs formatted data. To reproduce the previous behavior, use the command Y = dlarray(Y,dims(X)); in the layer forward functions, where X and Y are the layer input and output, respectively.

FunctionLayer objects support complex-valued input and outputs. The layer applies the same forward function to complex-valued input as it does to real-valued input and outputs complex-valued data where applicable.