Documentation

## Define Custom Regression Output Layer

### Tip

To create a regression output layer with mean squared error loss, use regressionLayer. If you want to use a different loss function for your regression problems, then you can define a custom regression output layer using this example as a guide.

This example shows how to create a custom regression output layer with the mean absolute error (MAE) loss.

To define a custom regression output layer, you can use the template provided in this example, which takes you through the following steps:

1. Name the layer – Give the layer a name so it can be used in MATLAB®.

2. Declare the layer properties – Specify the properties of the layer.

3. Create a constructor function (optional) – Specify how to construct the layer and initialize its properties. If you do not specify a constructor function, then the software initializes the properties with '' at creation.

4. Create a forward loss function – Specify the loss between the predictions and the training targets.

5. Create a backward loss function (optional) – Specify the derivative of the loss with respect to the predictions. If you do not specify a backward loss function, then the forward loss function must support dlarray objects.

A regression MAE layer computes the mean absolute error loss for regression problems. MAE loss is an error measure between two continuous random variables. For predictions Y and training targets T, the MAE loss between Y and T is given by

$L=\frac{1}{N}\sum _{n=1}^{N}\left(\frac{1}{R}\sum _{i=1}^{R}|{Y}_{ni}-{T}_{ni}|\right),$

where N is the number of observations and R is the number of responses.

### Regression Output Layer Template

Copy the regression output layer template into a new file in MATLAB. This template outlines the structure of a regression output layer and includes the functions that define the layer behavior.

classdef myRegressionLayer < nnet.layer.RegressionLayer

properties
% (Optional) Layer properties.

% Layer properties go here.
end

methods
function layer = myRegressionLayer()
% (Optional) Create a myRegressionLayer.

% Layer constructor function goes here.
end

function loss = forwardLoss(layer, Y, T)
% Return the loss between the predictions Y and the training
% targets T.
%
% Inputs:
%         layer - Output layer
%         Y     – Predictions made by network
%         T     – Training targets
%
% Output:
%         loss  - Loss between Y and T

% Layer forward loss function goes here.
end

function dLdY = backwardLoss(layer, Y, T)
% (Optional) Backward propagate the derivative of the loss
% function.
%
% Inputs:
%         layer - Output layer
%         Y     – Predictions made by network
%         T     – Training targets
%
% Output:
%         dLdY  - Derivative of the loss with respect to the
%                 predictions Y

% Layer backward loss function goes here.
end
end
end

### Name the Layer

First, give the layer a name. In the first line of the class file, replace the existing name myRegressionLayer with maeRegressionLayer.

classdef maeRegressionLayer < nnet.layer.RegressionLayer
...
end

Next, rename the myRegressionLayer constructor function (the first function in the methods section) so that it has the same name as the layer.

methods
function layer = maeRegressionLayer()
...
end

...
end

#### Save the Layer

Save the layer class file in a new file named maeRegressionLayer.m. The file name must match the layer name. To use the layer, you must save the file in the current folder or in a folder on the MATLAB path.

### Declare Layer Properties

Declare the layer properties in the properties section.

By default, custom output layers have the following properties:

• NameLayer name, specified as a character vector or a string scalar. To include a layer in a layer graph, you must specify a nonempty unique layer name. If you train a series network with the layer and Name is set to '', then the software automatically assigns a name to the layer at training time.

• Description – One-line description of the layer, specified as a character vector or a string scalar. This description appears when the layer is displayed in a Layer array. If you do not specify a layer description, then the software displays "Classification Output" or "Regression Output".

• Type – Type of the layer, specified as a character vector or a string scalar. The value of Type appears when the layer is displayed in a Layer array. If you do not specify a layer type, then the software displays the layer class name.

Custom classification layers also have the following property:

• ClassesClasses of the output layer, specified as a categorical vector, string array, cell array of character vectors, or 'auto'. If Classes is 'auto', then the software automatically sets the classes at training time. If you specify the string array or cell array of character vectors str, then the software sets the classes of the output layer to categorical(str,str). The default value is 'auto'.

Custom regression layers also have the following property:

• ResponseNamesNames of the responses, specified a cell array of character vectors or a string array. At training time, the software automatically sets the response names according to the training data. The default is {}.

If the layer has no other properties, then you can omit the properties section.

The layer does not require any additional properties, so you can remove the properties section.

### Create Constructor Function

Create the function that constructs the layer and initializes the layer properties. Specify any variables required to create the layer as inputs to the constructor function.

To initialize the Name property at creation, specify the input argument name. Add a comment to the top of the function that explains the syntax of the function.

function layer = maeRegressionLayer(name)
% layer = maeRegressionLayer(name) creates a
% mean-absolute-error regression layer and specifies the layer
% name.

...
end

#### Initialize Layer Properties

Replace the comment % Layer constructor function goes here with code that initializes the layer properties.

Give the layer a one-line description by setting the Description property of the layer. Set the Name property to the input argument name. Set the description to describe the type of layer and its size.

function layer = maeRegressionLayer(name)
% layer = maeRegressionLayer(name) creates a
% mean-absolute-error regression layer and specifies the layer
% name.

% Set layer name.
layer.Name = name;

% Set layer description.
layer.Description = 'Mean absolute error';
end

### Create Forward Loss Function

Create a function named forwardLoss that returns the MAE loss between the predictions made by the network and the training targets. The syntax for forwardLoss is loss = forwardLoss(layer, Y, T), where Y is the output of the previous layer and T contains the training targets.

For regression problems, the dimensions of T also depend on the type of problem.

2-D image regression1-by-1-by-R-by-N, where R is the number of responses and N is the number of observations.4
2-D Image-to-image regressionh-by-w-by-c-by-N, where h, w, and c are the height, width, and number of channels of the output respectively, and N is the number of observations.4
3-D image regression1-by-1-by-1-by-R-by-N, where R is the number of responses and N is the number of observations.5
3-D Image-to-image regressionh-by-w-by-d-by-c-by-N, where h, w, d, and c are the height, width, depth, and number of channels of the output respectively, and N is the number of observations.5
Sequence-to-one regressionR-by-N, where R is the number of responses and N is the number of observations.2
Sequence-to-sequence regressionR-by-N-by-S, where R is the number of responses, N is the number of observations, and S is the sequence length.2

For example, if the network defines an image regression network with one response and has mini-batches of size 50, then T is a 4-D array of size 1-by-1-by-1-by-50.

The size of Y depends on the output of the previous layer. To ensure that Y is the same size as T, you must include a layer that outputs the correct size before the output layer. For example, for image regression with R responses, to ensure that Y is a 4-D array of the correct size, you can include a fully connected layer of size R before the output layer.

A regression MAE layer computes the mean absolute error loss for regression problems. MAE loss is an error measure between two continuous random variables. For predictions Y and training targets T, the MAE loss between Y and T is given by

$L=\frac{1}{N}\sum _{n=1}^{N}\left(\frac{1}{R}\sum _{i=1}^{R}|{Y}_{ni}-{T}_{ni}|\right),$

where N is the number of observations and R is the number of responses.

The inputs Y and T correspond to Y and T in the equation, respectively. The output loss corresponds to L. To ensure that loss is scalar, output the mean loss over the mini-batch. Add a comment to the top of the function that explains the syntaxes of the function.

function loss = forwardLoss(layer, Y, T)
% loss = forwardLoss(layer, Y, T) returns the MAE loss between
% the predictions Y and the training targets T.

% Calculate MAE.
R = size(Y,3);
meanAbsoluteError = sum(abs(Y-T),3)/R;

% Take mean over mini-batch.
N = size(Y,4);
loss = sum(meanAbsoluteError)/N;
end

Because the forwardLoss function only uses functions that support dlarray objects, defining the backwardLoss function is optional. For a list of functions that support dlarray objects, see List of Functions with dlarray Support.

### Completed Layer

View the completed regression output layer class file.

classdef maeRegressionLayer < nnet.layer.RegressionLayer
% Example custom regression layer with mean-absolute-error loss.

methods
function layer = maeRegressionLayer(name)
% layer = maeRegressionLayer(name) creates a
% mean-absolute-error regression layer and specifies the layer
% name.

% Set layer name.
layer.Name = name;

% Set layer description.
layer.Description = 'Mean absolute error';
end

function loss = forwardLoss(layer, Y, T)
% loss = forwardLoss(layer, Y, T) returns the MAE loss between
% the predictions Y and the training targets T.

% Calculate MAE.
R = size(Y,3);
meanAbsoluteError = sum(abs(Y-T),3)/R;

% Take mean over mini-batch.
N = size(Y,4);
loss = sum(meanAbsoluteError)/N;
end
end
end

### GPU Compatibility

If the layer forward functions fully support dlarray objects, then the layer is GPU compatible. Otherwise, to be GPU compatible, the layer functions must support inputs and return outputs of type gpuArray.

Many MATLAB built-in functions support gpuArray and dlarray input arguments. For a list of functions that support dlarray objects, see List of Functions with dlarray Support. For a list of functions that execute on a GPU, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox). To use a GPU for deep learning, you must also have a CUDA® enabled NVIDIA® GPU with compute capability 3.0 or higher. For more information on working with GPUs in MATLAB, see GPU Computing in MATLAB (Parallel Computing Toolbox).

The MATLAB functions used in forwardLoss in maeRegressionLayer all support dlarray objects, so the layer is GPU compatible.

### Check Output Layer Validity

Check the layer validity of the custom classification output layer maeRegressionLayer.

Define a custom mean absolute error regression layer. To create this layer, save the file maeRegressionLayer.m in the current folder. Create an instance of the layer.

layer = maeRegressionLayer('mae');

Check the layer is valid using checkLayer. Specify the valid input size to be the size of a single observation of typical input to the layer. The layer expects a 1-by-1-by-R-by-N array inputs, where R is the number of responses, and N is the number of observations in the mini-batch.

validInputSize = [1 1 10];
checkLayer(layer,validInputSize,'ObservationDimension',4);
Running nnet.checklayer.TestOutputLayerWithoutBackward
..........
Done nnet.checklayer.TestOutputLayerWithoutBackward
__________

Test Summary:
10 Passed, 0 Failed, 0 Incomplete, 0 Skipped.
Time elapsed: 0.088094 seconds.

The test summary reports the number of passed, failed, incomplete, and skipped tests.

### Include Custom Regression Output Layer in Network

You can use a custom output layer in the same way as any other output layer in Deep Learning Toolbox. This section shows how to create and train a network for regression using the custom output layer you created earlier.

The example constructs a convolutional neural network architecture, trains a network, and uses the trained network to predict angles of rotated, handwritten digits. These predictions are useful for optical character recognition.

[XTrain,~,YTrain] = digitTrain4DArrayData;

Create a layer array including the regression output layer maeRegressionLayer.

layers = [
imageInputLayer([28 28 1])
convolution2dLayer(5,20)
batchNormalizationLayer
reluLayer
fullyConnectedLayer(1)
maeRegressionLayer('mae')]
layers =
6x1 Layer array with layers:

1   ''      Image Input           28x28x1 images with 'zerocenter' normalization
2   ''      Convolution           20 5x5 convolutions with stride [1  1] and padding [0  0  0  0]
3   ''      Batch Normalization   Batch normalization
4   ''      ReLU                  ReLU
5   ''      Fully Connected       1 fully connected layer
6   'mae'   Regression Output     Mean absolute error

Set the training options and train the network.

options = trainingOptions('sgdm');
net = trainNetwork(XTrain,YTrain,layers,options);
Training on single CPU.
Initializing input data normalization.
|========================================================================================|
|  Epoch  |  Iteration  |  Time Elapsed  |  Mini-batch  |  Mini-batch  |  Base Learning  |
|         |             |   (hh:mm:ss)   |     RMSE     |     Loss     |      Rate       |
|========================================================================================|
|       1 |           1 |       00:00:00 |        28.28 |         25.1 |          0.0100 |
|       2 |          50 |       00:00:05 |        14.27 |         11.3 |          0.0100 |
|       3 |         100 |       00:00:09 |        14.30 |         11.5 |          0.0100 |
|       4 |         150 |       00:00:13 |        10.07 |          7.7 |          0.0100 |
|       6 |         200 |       00:00:17 |         9.81 |          7.5 |          0.0100 |
|       7 |         250 |       00:00:21 |        10.20 |          7.5 |          0.0100 |
|       8 |         300 |       00:00:25 |         9.57 |          7.2 |          0.0100 |
|       9 |         350 |       00:00:29 |         8.61 |          6.5 |          0.0100 |
|      11 |         400 |       00:00:33 |         9.45 |          6.8 |          0.0100 |
|      12 |         450 |       00:00:37 |         8.26 |          6.0 |          0.0100 |
|      13 |         500 |       00:00:41 |         9.51 |          6.1 |          0.0100 |
|      15 |         550 |       00:00:45 |        10.00 |          7.7 |          0.0100 |
|      16 |         600 |       00:00:49 |         8.60 |          6.1 |          0.0100 |
|      17 |         650 |       00:00:53 |         7.18 |          5.4 |          0.0100 |
|      18 |         700 |       00:00:56 |         8.89 |          6.3 |          0.0100 |
|      20 |         750 |       00:01:00 |         7.76 |          5.9 |          0.0100 |
|      21 |         800 |       00:01:04 |         8.07 |          6.0 |          0.0100 |
|      22 |         850 |       00:01:07 |         7.38 |          5.6 |          0.0100 |
|      24 |         900 |       00:01:10 |         7.51 |          5.5 |          0.0100 |
|      25 |         950 |       00:01:14 |         6.88 |          4.9 |          0.0100 |
|      26 |        1000 |       00:01:17 |         6.83 |          4.7 |          0.0100 |
|      27 |        1050 |       00:01:23 |         6.70 |          4.8 |          0.0100 |
|      29 |        1100 |       00:01:28 |         6.57 |          4.8 |          0.0100 |
|      30 |        1150 |       00:01:33 |         6.87 |          4.9 |          0.0100 |
|      30 |        1170 |       00:01:35 |         7.75 |          6.2 |          0.0100 |
|========================================================================================|

Evaluate the network performance by calculating the prediction error between the predicted and actual angles of rotation.

[XTest,~,YTest] = digitTest4DArrayData;
YPred = predict(net,XTest);
predictionError = YTest - YPred;

Calculate the number of predictions within an acceptable error margin from the true angles. Set the threshold to be 10 degrees and calculate the percentage of predictions within this threshold.

thr = 10;
numCorrect = sum(abs(predictionError) < thr);
numTestImages = size(XTest,4);
accuracy = numCorrect/numTestImages
accuracy = 0.7524