Main Content

dlarray

Deep learning array for custom training loops

expand all in page

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 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, seeTrain Deep Learning Network to Classify New Images. Alternatively, you can create and train networks from scratch usinglayerGraphobjects with thetrainNetworkandtrainingOptionsfunctions.

If thetrainingOptionsfunction 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, seeDefine Deep Learning Network for Custom Training Loops.

Creation

Syntax

dlX = dlarray(X)
dlX = dlarray(X,fmt)
dlX = dlarray(v,dim)

Description

example

dlX= dlarray(X)返回一个dlarrayobject representingX. IfXis adlarray,dlXis a copy ofX.

example

dlX= dlarray(X,fmt)formats the data indlXwith dimension labels according to the data format infmt. Dimension labels help in passing deep learning data between functions. For more information on dimension labels, seeUsage. IfXis a formatteddlarray, thenfmtreplaces the existing format.

example

dlX= dlarray(v,dim)accepts a vectorvand a single character formatdim, and returns a column vectordlarray. The first dimension ofdlXhas the dimension labeldim, and the second (singleton) dimension has the dimension label'U'.

Input Arguments

expand all

Data array, specified as a numeric array of data typedoubleorsingle, alogicalarray, agpuArrayobject, or adlarrayobject.Xmust be full, not sparse.

Example:rand(31*23,23)

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

数据格式, specified as a character vector or string scalar. Each character infmtmust be one of the following dimension labels:

  • S— Spatial

  • C— Channel

  • B— Batch observations

  • T— Time or sequence

  • U— Unspecified

You can specify any number ofSandUlabels. You can specify at most one of each of theC,B, andTlabels.

Each element offmtlabels the matching dimension of the input data. Iffmtis not in the listed order ('S'followed by'C'and so on), thendlarrayimplicitly permutes bothfmtand the data to match the order without changing the storage of the data.

fmtmust 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,dlarraycreates 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-nnumeric array, whereh,w,candnare 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-nnumeric array, whereh,w,d,candnare the height, width, depth, number of channels of the images, and number of image observations, respectively. "SSSCB"
Vector sequences

c-by-s-by-nmatrix, wherecis the number of features of the sequence,sis the sequence length, andnis the number of sequence observations.

 "CTB"
2-D image sequences

h-by-w-by-c-by-s-by-narray, whereh,w, andccorrespond to the height, width, and number of channels of the image, respectively,sis the sequence length, andnis the number of image sequence observations.

 "SSCTB"
3-D image sequences

h-by-w-by-d-by-c-by-s-by-narray, whereh,w,d, andccorrespond to the height, width, depth, and number of channels of the image, respectively,sis the sequence length, andnis the number of image sequence observations.

 "SSSCTB"
Features c-by-narray, wherecis the number of features, andnis the number of observations. "CB"

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

Example:rand(100,1)

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

Example:"S"

Example:'S'

Output Arguments

expand all

Deep learning array, returned as adlarrayobject.dlXenables automatic differentiation usingdlgradientanddlfeval. If you supply thefmtargument,dlXhas labels.

  • IfXis a numeric or logical array,dlXcontains its data, possibly reordered because of the data format infmt.

  • IfXis agpuArray, the data indlXis also on the GPU. Subsequent calculations usingdlXare performed on the GPU.

Usage

dlarraydata 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'

这些功能需要每个维度有label. You can specify the dimension label format by providing the first input as a formatteddlarray, or by using the'DataFormat'name-value argument of the function.

dlarrayenforces the dimension label ordering of'SCBTU'. This enforcement eliminates ambiguous semantics in operations which implicitly match labels between inputs.dlarrayalso 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.

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

For more information on how adlarraybehaves with formats, seeNotable 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
dims Dimension labels ofdlarray
dlconv Deep learning convolution
dlgradient Compute gradients for custom training loops using automatic differentiation
dltranspconv Deep learning transposed convolution
extractdata Extract data fromdlarray
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 Removedlarraydata format

Adlarrayalso allows functions for numeric, matrix, and other operations. See the full list inList of Functions with dlarray Support.

Examples

collapse all

Open Live Script

Create an unformatteddlarrayfrom 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
Open Live Script

Create adlarraythat 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,dlarrayimplicitly reorders the underlying data.

dlX = dlarray(X,'CS')
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
Open Live Script

Create adlarrayvector with the first dimension label'T'. The second dimension label, whichdlarraycreates 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 forX,dlarrayimplicitly 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

更小ion History

Introduced in R2019b

See Also

|||||

Topics