Main Content

activations

Compute deep learning network layer activations

Description

You can compute deep learning network layer activations on either a CPU or GPU. Using a GPU requires a Parallel Computing Toolbox™ license and a supported GPU device. For information about supported devices, see GPU Computing Requirements (Parallel Computing Toolbox). Specify the hardware requirements using the ExecutionEnvironment name-value argument.

To compute activations using a trained SeriesNetwork or DAGNetwork, use the activations function. To compute activations of a dlnetwork objects, use the forward or predict function and specify the Outputs option.

act = activations(net,images,layer) returns the network activations for the layer with name or number layer using the specified images.

act = activations(net,sequences,layer) returns the network activations for the layer using the specified sequences.

act = activations(net,features,layer) returns the network activations for the layer using the specified feature data.

act = activations(net,X1,...,XN,layer) returns the network activations for the layer using the data in the numeric or cell arrays X1, …, XN for the multi-input network net. The input Xi corresponds to the network input net.InputNames(i).

act = activations(net,mixed,layer) returns the network activations for the layer using the trained network net with multiple inputs of mixed data types.

example

act = activations(___,Name=Value) returns network activations with additional options specified by one or more name-value pair arguments. For example, OutputAs="rows" specifies the activation output format as "rows". Use this syntax with any of the input arguments in previous syntaxes. Specify name-value arguments after all other input arguments.

Examples

collapse all

This example shows how to extract learned image features from a pretrained convolutional neural network and use those features to train an image classifier.

Feature extraction is the easiest and fastest way to use the representational power of pretrained deep networks. For example, you can train a support vector machine (SVM) using fitcecoc (Statistics and Machine Learning Toolbox™) on the extracted features. Because feature extraction requires only a single pass through the data, it is a good starting point if you do not have a GPU to accelerate network training with.

Load Data

Unzip and load the sample images as an image datastore. imageDatastore automatically labels the images based on folder names and stores the data as an ImageDatastore object. An image datastore lets you store large image data, including data that does not fit in memory. Split the data into 70% training and 30% test data.

unzip("MerchData.zip");

imds = imageDatastore("MerchData", ...
    IncludeSubfolders=true, ...
    LabelSource="foldernames");

[imdsTrain,imdsTest] = splitEachLabel(imds,0.7,"randomized");

This very small data set now has 55 training images and 20 validation images. Display some sample images.

numImagesTrain = numel(imdsTrain.Labels);
idx = randperm(numImagesTrain,16);

I = imtile(imds,"Frames",idx);

figure
imshow(I)

Load Pretrained Network

Load a pretrained SqueezeNet network. SqueezeNet is trained on more than a million images and can classify images into 1000 object categories, for example, keyboard, mouse, pencil, and many animals. As a result, the model has learned rich feature representations for a wide range of images.

net = squeezenet;

Analyze the network architecture.

analyzeNetwork(net)

2022-01-07_16-31-30.png

The first layer, the image input layer, requires input images of size 227-by-227-by-3, where 3 is the number of color channels.

inputSize = net.Layers(1).InputSize
inputSize = 1×3

   227   227     3

Extract Image Features

The network constructs a hierarchical representation of input images. Deeper layers contain higher level features, constructed using the lower level features of earlier layers. To get the feature representations of the training and test images, use activations on the global average pooling layer "pool10". To get a lower level representation of the images, use an earlier layer in the network.

The network requires input images of size 227-by-227-by-3, but the images in the image datastores have different sizes. To automatically resize the training and test images before inputting them to the network, create augmented image datastores, specify the desired image size, and use these datastores as input arguments to activations.

augimdsTrain = augmentedImageDatastore(inputSize(1:2),imdsTrain);
augimdsTest = augmentedImageDatastore(inputSize(1:2),imdsTest);

layer = "pool10";
featuresTrain = activations(net,augimdsTrain,layer,OutputAs="rows");
featuresTest = activations(net,augimdsTest,layer,OutputAs="rows");

Extract the class labels from the training and test data.

TTrain = imdsTrain.Labels;
TTest = imdsTest.Labels;

Fit Image Classifier

Use the features extracted from the training images as predictor variables and fit a multiclass support vector machine (SVM) using fitcecoc (Statistics and Machine Learning Toolbox).

mdl = fitcecoc(featuresTrain,TTrain);

Classify Test Images

Classify the test images using the trained SVM model and the features extracted from the test images.

YPred = predict(mdl,featuresTest);

Display four sample test images with their predicted labels.

idx = [1 5 10 15];
figure
for i = 1:numel(idx)
    subplot(2,2,i)
    I = readimage(imdsTest,idx(i));
    label = YPred(idx(i));
    
    imshow(I)
    title(label)
end

Calculate the classification accuracy on the test set. Accuracy is the fraction of labels that the network predicts correctly.

accuracy = mean(YPred == TTest)
accuracy = 0.9500

This SVM has high accuracy. If the accuracy is not high enough using feature extraction, then try transfer learning instead.

Input Arguments

collapse all

Trained network, specified as a SeriesNetwork or a DAGNetwork object. You can get a trained network by importing a pretrained network (for example, by using the googlenet function) or by training your own network using trainNetwork.

Image data, specified as one of the following.

Data TypeDescriptionExample Usage
DatastoreImageDatastoreDatastore of images saved on disk

Make predictions with images saved on disk, where the images are the same size.

When the images are different sizes, use an AugmentedImageDatastore object.

AugmentedImageDatastoreDatastore that applies random affine geometric transformations, including resizing, rotation, reflection, shear, and translation

Make predictions with images saved on disk, where the images are different sizes.

TransformedDatastoreDatastore that transforms batches of data read from an underlying datastore using a custom transformation function

  • Transform datastores with outputs not supported by activations.

  • Apply custom transformations to datastore output.

CombinedDatastoreDatastore that reads from two or more underlying datastores

  • Make predictions using networks with multiple inputs.

  • Combine predictors from different data sources.

Custom mini-batch datastoreCustom datastore that returns mini-batches of data

Make predictions using data in a format that other datastores do not support.

For details, see Develop Custom Mini-Batch Datastore.

Numeric arrayImages specified as a numeric arrayMake predictions using data that fits in memory and does not require additional processing like resizing.
TableImages specified as a tableMake predictions using data stored in a table.

When you use a datastore with networks with multiple inputs, the datastore must be a TransformedDatastore or CombinedDatastore object.

Tip

For sequences of images, for example, video data, use the sequences input argument.

Datastore

Datastores read mini-batches of images and responses. Use datastores when you have data that does not fit in memory or when you want to resize the input data.

These datastores are directly compatible with activations for image data.:

Tip

Use augmentedImageDatastore for efficient preprocessing of images for deep learning, including image resizing. Do not use the ReadFcn option of ImageDatastore objects.

ImageDatastore allows batch reading of JPG or PNG image files using prefetching. If you set the ReadFcn option to a custom function, then ImageDatastore does not prefetch and is usually significantly slower.

You can use other built-in datastores for making predictions by using the transform and combine functions. These functions can convert the data read from datastores to the format required by classify.

The required format of the datastore output depends on the network architecture.

Network ArchitectureDatastore OutputExample Output
Single input

Table or cell array, where the first column specifies the predictors.

Table elements must be scalars, row vectors, or 1-by-1 cell arrays containing a numeric array.

Custom datastores must output tables.

data = read(ds)
data =

  4×1 table

        Predictors    
    __________________

    {224×224×3 double}
    {224×224×3 double}
    {224×224×3 double}
    {224×224×3 double}
data = read(ds)
data =

  4×1 cell array

    {224×224×3 double}
    {224×224×3 double}
    {224×224×3 double}
    {224×224×3 double}
Multiple input

Cell array with at least numInputs columns, where numInputs is the number of network inputs.

The first numInputs columns specify the predictors for each input.

The order of inputs is given by the InputNames property of the network.

data = read(ds)
data =

  4×2 cell array

    {224×224×3 double}    {128×128×3 double}
    {224×224×3 double}    {128×128×3 double}
    {224×224×3 double}    {128×128×3 double}
    {224×224×3 double}    {128×128×3 double}

The format of the predictors depends on the type of data.

DataFormat
2-D images

h-by-w-by-c numeric array, where h, w, and c are the height, width, and number of channels of the images, respectively

3-D imagesh-by-w-by-d-by-c numeric array, where h, w, d, and c are the height, width, depth, and number of channels of the images, respectively

For more information, see Datastores for Deep Learning.

Numeric Array

For data that fits in memory and does not require additional processing like augmentation, you can specify a data set of images as a numeric array.

The size and shape of the numeric array depends on the type of image data.

DataFormat
2-D images

h-by-w-by-c-by-N numeric array, where h, w, and c are the height, width, and number of channels of the images, respectively, and N is the number of images

3-D imagesh-by-w-by-d-by-c-by-N numeric array, where h, w, d, and c are the height, width, depth, and number of channels of the images, respectively, and N is the number of images

Table

As an alternative to datastores or numeric arrays, you can also specify images in a table.

When you specify images in a table, each row in the table corresponds to an observation.

For image input, the predictors must be in the first column of the table, specified as one of the following:

  • Absolute or relative file path to an image, specified as a character vector

  • 1-by-1 cell array containing a h-by-w-by-c numeric array representing a 2-D image, where h, w, and c correspond to the height, width, and number of channels of the image, respectively

Tip

To input complex-valued data into a neural network, the SplitComplexInputs option of the input layer must be 1.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | table
Complex Number Support: Yes

Sequence or time series data, specified as one of the following.

Data TypeDescriptionExample Usage
DatastoreTransformedDatastoreDatastore that transforms batches of data read from an underlying datastore using a custom transformation function

  • Transform datastores with outputs not supported by activations.

  • Apply custom transformations to datastore output.

CombinedDatastoreDatastore that reads from two or more underlying datastores

  • Make predictions using networks with multiple inputs.

  • Combine predictors from different data sources.

Custom mini-batch datastoreCustom datastore that returns mini-batches of data

Make predictions using data in a format that other datastores do not support.

For details, see Develop Custom Mini-Batch Datastore.

Numeric or cell arrayA single sequence specified as a numeric array or a data set of sequences specified as cell array of numeric arraysMake predictions using data that fits in memory and does not require additional processing like custom transformations.

Datastore

Datastores read mini-batches of sequences and responses. Use datastores when you have data that does not fit in memory or when you want to apply transformations to the data.

These datastores are directly compatible with activations for sequence data:

You can use other built-in datastores for making predictions by using the transform and combine functions. These functions can convert the data read from datastores to the table or cell array format required by activations. For example, you can transform and combine data read from in-memory arrays and CSV files using an ArrayDatastore and an TabularTextDatastore object, respectively.

The datastore must return data in a table or cell array. Custom mini-batch datastores must output tables.

Datastore OutputExample Output
Table
data = read(ds)
data =

  4×2 table

        Predictors    
    __________________

    {12×50 double}
    {12×50 double}
    {12×50 double}
    {12×50 double}
Cell array
data = read(ds)
data =

  4×2 cell array

    {12×50 double}
    {12×50 double}
    {12×50 double}
    {12×50 double}

The format of the predictors depends on the type of data.

DataFormat of Predictors
Vector sequence

c-by-s matrix, where c is the number of features of the sequence and s is the sequence length

1-D image sequence

h-by-c-by-s array, where h and c correspond to the height and number of channels of the image, respectively, and s is the sequence length.

Each sequence in the mini-batch must have the same sequence length.

2-D image sequence

h-by-w-by-c-by-s array, where h, w, and c correspond to the height, width, and number of channels of the image, respectively, and s is the sequence length.

Each sequence in the mini-batch must have the same sequence length.

3-D image sequence

h-by-w-by-d-by-c-by-s array, where h, w, d, and c correspond to the height, width, depth, and number of channels of the image, respectively, and s is the sequence length.

Each sequence in the mini-batch must have the same sequence length.

For predictors returned in tables, the elements must contain a numeric scalar, a numeric row vector, or a 1-by-1 cell array containing a numeric array.

For more information, see Datastores for Deep Learning.

Numeric or Cell Array

For data that fits in memory and does not require additional processing like custom transformations, you can specify a single sequence as a numeric array or a data set of sequences as a cell array of numeric arrays.

For cell array input, the cell array must be an N-by-1 cell array of numeric arrays, where N is the number of observations. The size and shape of the numeric array representing a sequence depends on the type of sequence data.

InputDescription
Vector sequencesc-by-s matrices, where c is the number of features of the sequences and s is the sequence length
1-D image sequencesh-by-c-by-s arrays, where h and c correspond to the height and number of channels of the images, respectively, and s is the sequence length
2-D image sequencesh-by-w-by-c-by-s arrays, where h, w, and c correspond to the height, width, and number of channels of the images, respectively, and s is the sequence length
3-D image sequencesh-by-w-by-d-by-c-by-s, where h, w, d, and c correspond to the height, width, depth, and number of channels of the 3-D images, respectively, and s is the sequence length

Tip

To input complex-valued data into a neural network, the SplitComplexInputs option of the input layer must be 1.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | cell
Complex Number Support: Yes

Feature data, specified as one of the following.

Data TypeDescriptionExample Usage
DatastoreTransformedDatastoreDatastore that transforms batches of data read from an underlying datastore using a custom transformation function

  • Transform datastores with outputs not supported by activations.

  • Apply custom transformations to datastore output.

CombinedDatastoreDatastore that reads from two or more underlying datastores

  • Make predictions using networks with multiple inputs.

  • Combine predictors from different data sources.

Custom mini-batch datastoreCustom datastore that returns mini-batches of data

Make predictions using data in a format that other datastores do not support.

For details, see Develop Custom Mini-Batch Datastore.

TableFeature data specified as a tableMake predictions using data stored in a table.
Numeric arrayFeature data specified as numeric arrayMake predictions using data that fits in memory and does not require additional processing like custom transformations.

Datastore

Datastores read mini-batches of feature data and responses. Use datastores when you have data that does not fit in memory or when you want to apply transformations to the data.

These datastores are directly compatible with activations for feature data:

You can use other built-in datastores for making predictions by using the transform and combine functions. These functions can convert the data read from datastores to the table or cell array format required by activations. For more information, see Datastores for Deep Learning.

For networks with multiple inputs, the datastore must be a TransformedDatastore or CombinedDatastore object.

The datastore must return data in a table or a cell array. Custom mini-batch datastores must output tables. The format of the datastore output depends on the network architecture.

Network ArchitectureDatastore OutputExample Output
Single input layer

Table or cell array with at least one column, where the first column specifies the predictors.

Table elements must be scalars, row vectors, or 1-by-1 cell arrays containing a numeric array.

Custom mini-batch datastores must output tables.

Table for network with one input:

data = read(ds)
data =

  4×2 table

        Predictors    
    __________________

    {24×1 double}
    {24×1 double}
    {24×1 double}
    {24×1 double}

Cell array for network with one input:

data = read(ds)
data =

  4×1 cell array

    {24×1 double}
    {24×1 double}
    {24×1 double}
    {24×1 double}

Multiple input layers

Cell array with at least numInputs columns, where numInputs is the number of network inputs.

The first numInputs columns specify the predictors for each input.

The order of inputs is given by the InputNames property of the network.

Cell array for network with two inputs:

data = read(ds)
data =

  4×3 cell array

    {24×1 double}    {28×1 double}
    {24×1 double}    {28×1 double}
    {24×1 double}    {28×1 double}
    {24×1 double}    {28×1 double}

The predictors must be c-by-1 column vectors, where c is the number of features.

For more information, see Datastores for Deep Learning.

Table

For feature data that fits in memory and does not require additional processing like custom transformations, you can specify feature data and responses as a table.

Each row in the table corresponds to an observation. The arrangement of predictors in the table columns depends on the type of task.

TaskPredictors
Feature classification

Features specified in one or more columns as scalars.

Numeric Array

For feature data that fits in memory and does not require additional processing like custom transformations, you can specify feature data as a numeric array.

The numeric array must be an N-by-numFeatures numeric array, where N is the number of observations and numFeatures is the number of features of the input data.

Tip

To input complex-valued data into a neural network, the SplitComplexInputs option of the input layer must be 1.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | table
Complex Number Support: Yes

Numeric or cell arrays for networks with multiple inputs.

For image, sequence, and feature predictor input, the format of the predictors must match the formats described in the images, sequences, or features argument descriptions, respectively.

For an example showing how to train a network with multiple inputs, see Train Network on Image and Feature Data.

To input complex-valued data into a neural network, the SplitComplexInputs option of the input layer must be 1.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | cell
Complex Number Support: Yes

Mixed data, specified as one of the following.

Data TypeDescriptionExample Usage
TransformedDatastoreDatastore that transforms batches of data read from an underlying datastore using a custom transformation function

  • Make predictions using networks with multiple inputs.

  • Transform outputs of datastores not supported by activations so they have the required format.

  • Apply custom transformations to datastore output.

CombinedDatastoreDatastore that reads from two or more underlying datastores

  • Make predictions using networks with multiple inputs.

  • Combine predictors from different data sources.

Custom mini-batch datastoreCustom datastore that returns mini-batches of data

Make predictions using data in a format that other datastores do not support.

For details, see Develop Custom Mini-Batch Datastore.

You can use other built-in datastores for making predictions by using the transform and combine functions. These functions can convert the data read from datastores to the table or cell array format required by activations. For more information, see Datastores for Deep Learning.

The datastore must return data in a table or a cell array. Custom mini-batch datastores must output tables. The format of the datastore output depends on the network architecture.

Datastore OutputExample Output

Cell array with numInputs columns, where numInputs is the number of network inputs.

The order of inputs is given by the InputNames property of the network.

data = read(ds)
data =

  4×3 cell array

    {24×1 double}    {28×1 double}
    {24×1 double}    {28×1 double}
    {24×1 double}    {28×1 double}
    {24×1 double}    {28×1 double}

For image, sequence, and feature predictor input, the format of the predictors must match the formats described in the images, sequences, or features argument descriptions, respectively.

For an example showing how to train a network with multiple inputs, see Train Network on Image and Feature Data.

Tip

To convert a numeric array to a datastore, use arrayDatastore.

Layer to extract activations from, specified as a numeric index or a character vector.

To compute the activations of a SeriesNetwork object, specify the layer using its numeric index, or as a character vector corresponding to the layer name.

To compute the activations of a DAGNetwork object, specify the layer as the character vector corresponding to the layer name. If the layer has multiple outputs, specify the layer and output as the layer name, followed by the character “/”, followed by the name of the layer output. That is, layer is of the form 'layerName/outputName'.

Example: 3

Example: 'conv1'

Example: 'mpool/out'

Name-Value Arguments

Specify optional pairs of arguments as Name1=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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: MiniBatchSize=256 specifies the mini-batch size as 256.

Format of output activations, specified as "channels", "rows", or "columns". For descriptions of the output formats, see act.

For image input, if the OutputAs option is "channels", then the images in the input data can be larger than the input size of the image input layer of the network. For other output formats, the images in the input must have the same size as the input size of the image input layer of the network.

Size of mini-batches to use for prediction, specified as a positive integer. Larger mini-batch sizes require more memory, but can lead to faster predictions.

Option to pad, truncate, or split input sequences, specified as one of the following:

  • "longest" — Pad sequences in each mini-batch to have the same length as the longest sequence. This option does not discard any data, though padding can introduce noise to the neural network.

  • "shortest" — Truncate sequences in each mini-batch to have the same length as the shortest sequence. This option ensures that no padding is added, at the cost of discarding data.

  • Positive integer — For each mini-batch, pad the sequences to the length of the longest sequence in the mini-batch, and then split the sequences into smaller sequences of the specified length. If splitting occurs, then the software creates extra mini-batches. If the specified sequence length does not evenly divide the sequence lengths of the data, then the mini-batches containing the ends those sequences have length shorter than the specified sequence length. Use this option if the full sequences do not fit in memory. Alternatively, try reducing the number of sequences per mini-batch by setting the MiniBatchSize option to a lower value.

To learn more about the effect of padding, truncating, and splitting the input sequences, see Sequence Padding, Truncation, and Splitting.

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

Value by which to pad input sequences, specified as a scalar.

Do not pad sequences with NaN, because doing so can propagate errors throughout the neural network.

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

Direction of padding or truncation, specified as one of the following:

  • "right" — Pad or truncate sequences on the right. The sequences start at the same time step and the software truncates or adds padding to the end of the sequences.

  • "left" — Pad or truncate sequences on the left. The software truncates or adds padding to the start of the sequences so that the sequences end at the same time step.

Because recurrent layers process sequence data one time step at a time, when the recurrent layer OutputMode property is "last", any padding in the final time steps can negatively influence the layer output. To pad or truncate sequence data on the left, set the SequencePaddingDirection option to "left".

For sequence-to-sequence neural networks (when the OutputMode property is "sequence" for each recurrent layer), any padding in the first time steps can negatively influence the predictions for the earlier time steps. To pad or truncate sequence data on the right, set the SequencePaddingDirection option to "right".

To learn more about the effect of padding, truncating, and splitting the input sequences, see Sequence Padding, Truncation, and Splitting.

Performance optimization, specified as one of the following:

  • "auto" — Automatically apply a number of optimizations suitable for the input network and hardware resources.

  • "mex" — Compile and execute a MEX function. This option is available only when you use a GPU. Using a GPU requires a Parallel Computing Toolbox license and a supported GPU device. For information about supported devices, see GPU Computing Requirements (Parallel Computing Toolbox). If Parallel Computing Toolbox or a suitable GPU is not available, then the software returns an error.

  • "none" — Disable all acceleration.

If Acceleration is "auto", then MATLAB® applies a number of compatible optimizations and does not generate a MEX function.

The "auto" and "mex" options can offer performance benefits at the expense of an increased initial run time. Subsequent calls with compatible parameters are faster. Use performance optimization when you plan to call the function multiple times using new input data.

The "mex" option generates and executes a MEX function based on the network and parameters used in the function call. You can have several MEX functions associated with a single network at one time. Clearing the network variable also clears any MEX functions associated with that network.

The "mex" option supports networks that contain the layers listed on the Supported Layers (GPU Coder) page, except for sequenceInputLayer objects.

The "mex" option is available when you use a single GPU.

To use the "mex" option, you must have a C/C++ compiler installed and the GPU Coder™ Interface for Deep Learning support package. Install the support package using the Add-On Explorer in MATLAB. For setup instructions, see MEX Setup (GPU Coder). GPU Coder is not required.

For quantized networks, the "mex" option requires a CUDA® enabled NVIDIA® GPU with compute capability 6.1, 6.3, or higher.

MATLAB Compiler™ does not support deploying networks when you use the "mex" option.

Hardware resource, specified as one of the following:

  • "auto" — Use a GPU if one is available; otherwise, use the CPU.

  • "gpu" — Use the GPU. Using a GPU requires a Parallel Computing Toolbox license and a supported GPU device. For information about supported devices, see GPU Computing Requirements (Parallel Computing Toolbox). If Parallel Computing Toolbox or a suitable GPU is not available, then the software returns an error.

  • "cpu" — Use the CPU.

  • "multi-gpu" — Use multiple GPUs on one machine, using a local parallel pool based on your default cluster profile. If there is no current parallel pool, the software starts a parallel pool with pool size equal to the number of available GPUs.

  • "parallel" — Use a local or remote parallel pool based on your default cluster profile. If there is no current parallel pool, the software starts one using the default cluster profile. If the pool has access to GPUs, then only workers with a unique GPU perform computation. If the pool does not have GPUs, then computation takes place on all available CPU workers instead.

For more information on when to use the different execution environments, see Scale Up Deep Learning in Parallel, on GPUs, and in the Cloud.

The "gpu", "multi-gpu", and "parallel" options require Parallel Computing Toolbox. To use a GPU for deep learning, you must also have a supported GPU device. For information on supported devices, see GPU Computing Requirements (Parallel Computing Toolbox). If you choose one of these options and Parallel Computing Toolbox or a suitable GPU is not available, then the software returns an error.

To make predictions in parallel with networks with recurrent layers (by setting ExecutionEnvironment to either "multi-gpu" or "parallel"), the SequenceLength option must be "shortest" or "longest".

Networks with custom layers that contain State parameters do not support making predictions in parallel.

Output Arguments

collapse all

Activations from the network layer, returned as a numeric array or a cell array of numeric arrays. The format of act depends on the type of input data, the type of layer output, and the specified OutputAs option.

Image or Folded Sequence Output

If the layer outputs image or folded sequence data, then act is a numeric array.

OutputAsact
"channels"

For 2-D image output, act is an h-by-w-by-c-by-n array, where h, w, and c are the height, width, and number of channels for the output of the chosen layer, respectively, and n is the number of images. In this case, act(:,:,:,i) contains the activations for the ith image.

For 3-D image output, act is an h-by-w-by-d-by-c-by-n array, where h, w, d, and c are the height, width, depth, and number of channels for the output of the chosen layer, respectively, and n is the number of images. In this case, act(:,:,:,:,i) contains the activations for the ith image.

For folded 2-D image sequence output, act is an h-by-w-by-c-by-(n*s) array, where h, w, and c are the height, width, and number of channels for the output of the chosen layer, respectively, n is the number of sequences, and s is the sequence length. In this case, act(:,:,:,(t-1)*n+k) contains the activations for time step t of the kth sequence.

For folded 3-D image sequence output, act is an h-by-w-by-d-by-c-by-(n*s) array, where h, w, d, and c are the height, width, depth, and number of channels for the output of the chosen layer, respectively, n is the number of sequences, and s is the sequence length. In this case, act(:,:,:,:,(t-1)*n+k) contains the activations for time step t of the kth sequence.

"rows"

For 2-D and 3-D image output, act is an n-by-m matrix, where n is the number of images and m is the number of output elements from the layer. In this case, act(i,:) contains the activations for the ith image.

For folded 2-D and 3-D image sequence output, act is an (n*s)-by-m matrix, where n is the number of sequences, s is the sequence length, and m is the number of output elements from the layer. In this case, act((t-1)*n+k,:) contains the activations for time step t of the kth sequence.

"columns"

For 2-D and 3-D image output, act is an m-by-n matrix, where m is the number of output elements from the chosen layer and n is the number of images. In this case, act(:,i) contains the activations for the ith image.

For folded 2-D and 3-D image sequence output, act is an m-by-(n*s) matrix, where m is the number of output elements from the chosen layer, n is the number of sequences, and s is the sequence length. In this case, act(:,(t-1)*n+k) contains the activations for time step t of the kth sequence.

Sequence Output

If layer has sequence output (for example, LSTM layers with the output mode "sequence"), then act is a cell array. In this case, the "OutputAs" option must be "channels".

OutputAsact
"channels"

For vector sequence output, act is an n-by-1 cell array of c-by-s matrices, where n is the number of sequences, c is the number of features in the sequence, and s is the sequence length.

For 2-D image sequence output, act is an n-by-1 cell array of h-by-w-by-c-by-s matrices, where n is the number of sequences, h, w, and c are the height, width, and the number of channels of the images, respectively, and s is the sequence length.

For 3-D image sequence output, act is an n-by-1 cell array of h-by-w-by-c-by-d-by-s matrices, where n is the number of sequences, h, w, d, and c are the height, width, depth, and the number of channels of the images, respectively, and s is the sequence length.

In these cases, act{i} contains the activations of the ith sequence.

Feature Vector and Single Time Step Output

If layer outputs a feature vector or a single time step of a sequence (for example, an LSTM layer with the output mode "last"), then act is a numeric array.

OutputAsact
"channels"

For a feature vector or single time step containing vector data, act is a c-by-n matrix, where n is the number of observations and c is the number of features.

For a single time step containing 2-D image data, act is a h-by-w-by-c-by-n array, where n is the number of sequences and h, w, and c are the height, width, and the number of channels of the images, respectively.

For a single time step containing 3-D image data, act is a h-by-w-by-c-by-d-by-n array, where n is the number of sequences and h, w, d, and c are the height, width, depth, and the number of channels of the images, respectively.

"rows"n-by-m matrix, where n is the number of observations and m is the number of output elements from the chosen layer. In this case, act(i,:) contains the activations for the ith sequence.
"columns"m-by-n matrix, where m is the number of output elements from the chosen layer and n is the number of observations. In this case, act(:,i) contains the activations for the ith image.

Algorithms

collapse all

Floating-Point Arithmetic

When you train a neural network using the trainnet or trainNetwork functions, or when you use prediction or validation functions with DAGNetwork and SeriesNetwork objects, the software performs these computations using single-precision, floating-point arithmetic. Functions for prediction and validation include predict, classify, and activations. The software uses single-precision arithmetic when you train neural networks using both CPUs and GPUs.

Reproducibility

To provide the best performance, deep learning using a GPU in MATLAB is not guaranteed to be deterministic. Depending on your network architecture, under some conditions you might get different results when using a GPU to train two identical networks or make two predictions using the same network and data.

Extended Capabilities

Version History

Introduced in R2016a

expand all