dlarray - Deep learning array for customization - MATLAB (original) (raw)

Deep learning array for customization

Description

A deep learning array stores data with optional data format labels for custom training loops, and enables functions to compute and use derivatives through automatic differentiation.

Tip

For most deep learning tasks, you can use a pretrained neural network and adapt it to your own data. For an example showing how to use transfer learning to retrain a convolutional neural network to classify a new set of images, see Retrain Neural Network to Classify New Images. Alternatively, you can create and train neural networks from scratch using the trainnet andtrainingOptions functions.

If the trainingOptions function does not provide the training options that you need for your task, then you can create a custom training loop using automatic differentiation. To learn more, see Train Network Using Custom Training Loop.

If the trainnet function does not provide the loss function that you need for your task, then you can specify a custom loss function to the trainnet as a function handle. For loss functions that require more inputs than the predictions and targets (for example, loss functions that require access to the neural network or additional inputs), train the model using a custom training loop. To learn more, see Train Network Using Custom Training Loop.

If Deep Learning Toolbox™ does not provide the layers you need for your task, then you can create a custom layer. To learn more, see Define Custom Deep Learning Layers. For models that cannot be specified as networks of layers, you can define the model as a function. To learn more, see Train Network Using Model Function.

For more information about which training method to use for which task, see Train Deep Learning Model in MATLAB.

Creation

Syntax

Description

[dlX](#mw%5Fc0a56618-0967-42ec-961d-dc49b83510e4) = dlarray([X](#mw%5F5a844837-dcd2-4dcc-9e4a-c3229e1f9e01)) returns a dlarray object representing X. IfX is a dlarray, dlX is a copy of X.

example

[dlX](#mw%5Fc0a56618-0967-42ec-961d-dc49b83510e4) = dlarray([X](#mw%5F5a844837-dcd2-4dcc-9e4a-c3229e1f9e01),[fmt](#mw%5Fe439e5de-77e9-4399-a2e8-2cc62d2ab575)) formats the data in dlX with dimension labels according to the data format in fmt. Dimension labels help in passing deep learning data between functions. For more information on dimension labels, see Usage. If X is a formatted dlarray, then fmt replaces the existing format.

example

[dlX](#mw%5Fc0a56618-0967-42ec-961d-dc49b83510e4) = dlarray([v](#mw%5F9c6aecd2-e53c-4282-96f4-0a5fc927b4a1),[dim](#mw%5F629a1f3a-675f-4567-8e9c-7fe74795f961)) accepts a vector v and a single character formatdim, and returns a column vector dlarray. The first dimension of dlX has the dimension label dim, and the second (singleton) dimension has the dimension label 'U'.

example

Input Arguments

expand all

X — Data array

numeric array of data type double or single | logical array | gpuArray object | dlarray object

Data array, specified as a numeric array of data type double orsingle, a logical array, a gpuArray object, or a dlarray object. X must be full, not sparse.

Example: rand(31*23,23)

Data Types: single | double | logical
Complex Number Support: Yes

fmt — Data format

character vector | string scalar

Data format, specified as a string scalar or a character vector. Each character in the string must be one of the following dimension labels:

You can specify multiple dimensions labeled "S" or "U". You can use the labels "C", "B", and"T" once each, at most. The software ignores singleton trailing"U" dimensions after the second dimension.

When you create a formatted dlarray object, the software automatically permutes the dimensions such that the format has dimensions in this order:

For example, if you specify a format of "TCB" (time, channel, batch), then the software automatically permutes the dimensions so that it has format"CBT" (channel, batch, time).

fmt must contain at least the same number of dimension labels as the number of dimensions of the input data. If you specify more than that number of dimension labels, dlarray creates empty (singleton) dimensions for the additional labels.

The following table indicates recommended data formats for common types of data.

Data Example
Shape Data Format
2-D images _h_-by-_w_-by-_c_-by-n numeric array, where h, w,c and n are the height, width, number of channels of the images, and number of observations, respectively. "SSCB"
3-D images _h_-by-_w_-by-_d_-by-_c_-by-n numeric array, where h, w,d, c and n are the height, width, depth, number of channels of the images, and number of image observations, respectively. "SSSCB"
Vector sequences _c_-by-s_-by-n matrix, where c is the number of features of the sequence, s is the sequence length, and_n is the number of sequence observations. "CTB"
2-D image sequences _h_-by-_w_-by-_c_-by-s_-by-n array, where h, w, and_c correspond to the height, width, and number of channels of the image, respectively, s is the sequence length, and n is the number of image sequence observations. "SSCTB"
3-D image sequences _h_-by-_w_-by-_d_-by-_c_-by-_s_-by-n array, where h, w,d, and c correspond to the height, width, depth, and number of channels of the image, respectively,s is the sequence length, and n is the number of image sequence observations. "SSSCTB"
Features c_-by-n array, where_c is the number of features, and n is the number of observations. "CB"

v — Data vector

numeric vector of data type double or single | logical vector | dlarray vector object

Data vector, specified as a numeric vector of data type double or single, logical vector, or dlarray vector object. Here, "vector" means any array with exactly one nonsingleton dimension.

Example: rand(100,1)

dim — Dimension label

single character

Dimension label, specified as a single character of the type allowed forfmt.

Example: "S"

Example: 'S'

Output Arguments

expand all

dlX — Deep learning array

dlarray object

Deep learning array, returned as a dlarray object.dlX enables automatic differentiation usingdlgradient and dlfeval. If you supply thefmt argument, dlX has labels.

Usage

dlarray data formats enable you to execute the functions in the following table with assurance that the data has the appropriate shape.

Function Operation Validates Input Dimension Affects Size of Input Dimension
avgpool Compute the average of the input data over moving rectangular (or cuboidal) spatial ('S') regions defined by a pool size parameter. 'S' 'S'
batchnorm Normalize the values contained in each channel ('C') of the input data. 'C'
crossentropy Compute the cross-entropy between estimates and target values, averaged by the size of the batch ('B') dimension. 'S', 'C', 'B','T', 'U' (Estimates and target arrays must have the same sizes.) 'S', 'C', 'B','T', 'U' (Output is an unformatted scalar.)
dlconv Compute the deep learning convolution of the input data using an array of filters, matching the number of spatial ('S') and (a function of the) channel ('C') dimensions of the input, and adding a constant bias. 'S', 'C' 'S', 'C'
dltranspconv Compute the deep learning transposed convolution of the input data using an array of filters, matching the number of spatial ('S') and (a function of the) channel ('C') dimensions of the input, and adding a constant bias. 'S', 'C' 'S', 'C'
fullyconnect Compute a weighted sum of the input data and apply a bias for each batch ('B') and time ('T') dimension. 'S', 'C', 'U' 'S', 'C', 'B','T', 'U' (Output always has data format'CB', 'CT', or'CTB'.)
gru Apply a gated recurrent unit calculation to the input data. 'S', 'C', 'T' 'C'
lstm Apply a long short-term memory calculation to the input data. 'S', 'C', 'T' 'C'
maxpool Compute the maximum of the input data over moving rectangular spatial ('S') regions defined by a pool size parameter. 'S' 'S'
maxunpool Compute the unpooling operation over the spatial ('S') dimensions. 'S' 'S'
mse Compute the half mean squared error between estimates and target values, averaged by the size of the batch ('B') dimension. 'S', 'C', 'B','T', 'U' (Estimates and target arrays must have the same sizes.) 'S', 'C', 'B','T', 'U' (Output is an unformatted scalar.)
softmax Apply the softmax activation to each channel ('C') of the input data. 'C'

These functions require each dimension to have a label. You can specify the dimension label format by providing the first input as a formatted dlarray, or by using the 'DataFormat' name-value argument of the function.

dlarray enforces the dimension label ordering of'SCBTU'. This enforcement eliminates ambiguous semantics in operations which implicitly match labels between inputs. dlarray also enforces that the dimension labels 'C', 'B', and 'T' can each appear at most once. The functions that use these dimension labels accept at most one dimension for each label.

dlarray provides functions for obtaining the data format associated with a dlarray (dims), removing the data format (stripdims), and obtaining the dimensions associated with specific dimension labels (finddim).

For more information on how a dlarray behaves with formats, see Notable dlarray Behaviors.

Object Functions

avgpool Pool data to average values over spatial dimensions
batchnorm Normalize data across all observations for each channel independently
crossentropy Cross-entropy loss for classification tasks
indexcrossentropy Index cross-entropy loss for classification tasks
dims Data format of dlarray object
dlconv Deep learning convolution
dldivergence Divergence of deep learning data
dlgradient Compute gradients for custom training loops using automatic differentiation
dljacobian Jacobian matrix deep learning operation
dllaplacian Laplacian of deep learning data
dltranspconv Deep learning transposed convolution
extractdata Extract data from dlarray
finddim Find dimensions with specified label
fullyconnect Sum all weighted input data and apply a bias
gru Gated recurrent unit
leakyrelu Apply leaky rectified linear unit activation
lstm Long short-term memory
maxpool Pool data to maximum value
maxunpool Unpool the output of a maximum pooling operation
mse Half mean squared error
relu Apply rectified linear unit activation
sigmoid Apply sigmoid activation
softmax Apply softmax activation to channel dimension
stripdims Remove dlarray data format

A dlarray also allows functions for numeric, matrix, and other operations. See the full list in List of Functions with dlarray Support.

Examples

collapse all

Create Unformatted dlarray

Create an unformatted dlarray from a matrix.

X = randn(3,5); dlX = dlarray(X)

dlX = 3x5 dlarray

0.5377    0.8622   -0.4336    2.7694    0.7254
1.8339    0.3188    0.3426   -1.3499   -0.0631

-2.2588 -1.3077 3.5784 3.0349 0.7147

Create Formatted dlarray

Create a dlarray that has a data format containing the dimension labels 'S' and 'C'.

X = randn(3,5); dlX = dlarray(X,'SC')

dlX = 3(S) x 5(C) dlarray

0.5377    0.8622   -0.4336    2.7694    0.7254
1.8339    0.3188    0.3426   -1.3499   -0.0631

-2.2588 -1.3077 3.5784 3.0349 0.7147

If you specify the dimension labels in the opposite order, dlarray implicitly reorders the underlying data.

dlX = 5(S) x 3(C) dlarray

0.5377    1.8339   -2.2588
0.8622    0.3188   -1.3077

-0.4336 0.3426 3.5784 2.7694 -1.3499 3.0349 0.7254 -0.0631 0.7147

Create Formatted dlarray Vector

Create a dlarray vector with the first dimension label 'T'. The second dimension label, which dlarray creates automatically, is 'U'.

X = randn(6,1); dlX = dlarray(X,'T')

dlX = 6(T) x 1(U) dlarray

0.5377
1.8339

-2.2588 0.8622 0.3188 -1.3077

If you specify a row vector for X, dlarray implicitly reorders the result to be a column vector.

X = X'; dlX = dlarray(X,'T')

dlX = 6(T) x 1(U) dlarray

0.5377
1.8339

-2.2588 0.8622 0.3188 -1.3077

Tips

Extended Capabilities

Version History

Introduced in R2019b

expand all

R2022b: Code generation behavior change for dlarray inputs and outputs

In R2022b, the generated code creates structures for the dlarray inputs and outputs of entry-point functions. Data is a public field that you can directly access.

In previous releases, the generated code uses class to represent thedlarray inputs and outputs of entry-point functions. In these releases, you use the initializing function init to access theData field.