activations

Compute convolutional neural network layer activations

You can extract features using a trained convolutional neural network (ConvNet, CNN) on either a CPU or GPU. Using a GPU requires Parallel Computing Toolbox™ and a CUDA® enabled NVIDIA® GPU with compute capability 3.0 or higher. Specify the hardware requirements using the ExecutionEnvironment name-value pair argument.

Syntax

features = activations(net,X,layer)
features = activations(net,X,layer,Name,Value)

Description

example

features = activations(net,X,layer) returns network activations for a specific layer using the trained network net and the data in X.

The function only supports networks with an imageInputLayer or image3dInputLayer image input layer.

example

features = activations(net,X,layer,Name,Value) returns network activations for a specific layer with additional options specified by one or more name-value pair arguments. For example, 'OutputAs','rows' specifies the activation output format as 'rows'. Specify name-value pair 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 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 only requires 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');

There are now 55 training images and 20 validation images in this very small data set. Display some sample images.

numTrainImages = numel(imdsTrain.Labels);
idx = randperm(numTrainImages,16);
figure
for i = 1:16
    subplot(4,4,i)
    I = readimage(imdsTrain,idx(i));
    imshow(I)
end

Load Pretrained Network

Load a pretrained AlexNet network. If the Deep Learning Toolbox Model for AlexNet Network support package is not installed, then the software provides a download link. AlexNet 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 = alexnet;

Display the network architecture. The network has five convolutional layers and three fully connected layers.

net.Layers
ans = 
  25x1 Layer array with layers:

     1   'data'     Image Input                   227x227x3 images with 'zerocenter' normalization
     2   'conv1'    Convolution                   96 11x11x3 convolutions with stride [4  4] and padding [0  0  0  0]
     3   'relu1'    ReLU                          ReLU
     4   'norm1'    Cross Channel Normalization   cross channel normalization with 5 channels per element
     5   'pool1'    Max Pooling                   3x3 max pooling with stride [2  2] and padding [0  0  0  0]
     6   'conv2'    Grouped Convolution           2 groups of 128 5x5x48 convolutions with stride [1  1] and padding [2  2  2  2]
     7   'relu2'    ReLU                          ReLU
     8   'norm2'    Cross Channel Normalization   cross channel normalization with 5 channels per element
     9   'pool2'    Max Pooling                   3x3 max pooling with stride [2  2] and padding [0  0  0  0]
    10   'conv3'    Convolution                   384 3x3x256 convolutions with stride [1  1] and padding [1  1  1  1]
    11   'relu3'    ReLU                          ReLU
    12   'conv4'    Grouped Convolution           2 groups of 192 3x3x192 convolutions with stride [1  1] and padding [1  1  1  1]
    13   'relu4'    ReLU                          ReLU
    14   'conv5'    Grouped Convolution           2 groups of 128 3x3x192 convolutions with stride [1  1] and padding [1  1  1  1]
    15   'relu5'    ReLU                          ReLU
    16   'pool5'    Max Pooling                   3x3 max pooling with stride [2  2] and padding [0  0  0  0]
    17   'fc6'      Fully Connected               4096 fully connected layer
    18   'relu6'    ReLU                          ReLU
    19   'drop6'    Dropout                       50% dropout
    20   'fc7'      Fully Connected               4096 fully connected layer
    21   'relu7'    ReLU                          ReLU
    22   'drop7'    Dropout                       50% dropout
    23   'fc8'      Fully Connected               1000 fully connected layer
    24   'prob'     Softmax                       softmax
    25   'output'   Classification Output         crossentropyex with 'tench' and 999 other classes

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 fully connected layer 'fc7'. 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 they are input 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 = 'fc7';
featuresTrain = activations(net,augimdsTrain,layer,'OutputAs','rows');
featuresTest = activations(net,augimdsTest,layer,'OutputAs','rows');

Extract the class labels from the training and test data.

YTrain = imdsTrain.Labels;
YTest = 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).

classifier = fitcecoc(featuresTrain,YTrain);

Classify Test Images

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

YPred = predict(classifier,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(char(label))
end

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

accuracy = mean(YPred == YTest)
accuracy = 1

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 DAGNetwork object. You can get a trained network by importing a pretrained network or by training your own network using the trainNetwork function. For more information about pretrained networks, see Pretrained Deep Neural Networks.

activations only supports networks with an imageInputLayer or image3dInputLayer image input layer.

Image data, specified as one of the following.

InputDescription
3-D arrayNumeric array that represents a single image. The array has size h-by-w-by-c, where h, w, and c correspond to the height, width, and the number of channels of the image, respectively.
4-D arrayNumeric array that represents a stack of images. The array has size h-by-w-by-c-by-N, where N is the number of images in the image stack.
Image datastore

ImageDatastore with categorical labels.

For more information, see the imds argument of trainNetwork.

Datastore

Datastore that returns data as a single image, a cell array of images, or a table whose first column contains images.

For more information, see Datastores for Deep Learning.

Table

The first column of the table contains either image paths or 3-D arrays representing images. Subsequent columns contain the responses.

If the 'OutputAs' value equals 'channels', then the images in the input data X can be larger than the input size of the image input layer of the network. For other output formats, the images in X must have the same size as the input size of the image input layer of the network.

Layer to extract features 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 on the form 'layerName/outputName'.

Example: 3

Example: 'conv1'

Example: 'mpool/out'

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: activations(net,X,layer,'OutputAs','rows')

Format of output activations, specified as the comma-separated pair consisting of 'OutputAs' and one of the following:

'OutputAs' valueFormat of output activations
'channels'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. n is the number of observations in X. Each h-by-w-by-c subarray is the output for a single observation.
'rows'n-by-m matrix, where n is the number of observations, and m is the number of output elements from the chosen layer.
'columns'm-by-n matrix, where m is the number of output elements from the chosen layer, and n is the number of observations. Each column of the matrix is the output for a single observation.

If the 'OutputAs' value equals 'channels', then the images in the input data X can be larger than the input size of the image input layer of the network. For other output formats, the images in X must have the same size as the input size of the image input layer of the network.

Example: 'OutputAs','rows'

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.

Example: 'MiniBatchSize',256

Performance optimization, specified as the comma-separated pair consisting of 'Acceleration' and one of the following:

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

  • 'mex' — Compile and execute a MEX function. This option is available when using a GPU only. Using a GPU requires Parallel Computing Toolbox and a CUDA enabled NVIDIA GPU with compute capability 3.0 or higher. If Parallel Computing Toolbox or a suitable GPU is not available, then the software returns an error.

  • 'none' — Disable all acceleration.

The default option is 'auto'. If 'auto' is specified, MATLAB® will apply a number of compatible optimizations. If you use the 'auto' option, MATLAB does not ever generate a MEX function.

Using the 'Acceleration' options 'auto' and 'mex' can offer performance benefits, but 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 is only available for input data specified as a numeric array, cell array of numeric arrays, table, or image datastore. No other types of datastore support the 'mex' option.

The 'mex' option is only available when you are using a GPU. You must also have a C/C++ compiler installed. For setup instructions, see MEX Setup (GPU Coder).

'mex' acceleration does not support all layers. For a list of supported layers, see Supported Layers (GPU Coder).

Example: 'Acceleration','mex'

Hardware resource, specified as the comma-separated pair consisting of 'ExecutionEnvironment' and one of the following:

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

  • 'gpu' — Use the GPU. Using a GPU requires Parallel Computing Toolbox and a CUDA enabled NVIDIA GPU with compute capability 3.0 or higher. If Parallel Computing Toolbox or a suitable GPU is not available, then the software returns an error.

  • 'cpu' — Use the CPU.

Example: 'ExecutionEnvironment','cpu'

Output Arguments

collapse all

Activations from a network layer, returned as one of the following, depending on the value of the 'OutputAs' name-value pair argument.

features'OutputAs' value
h-by-w-by-c-by-n array'channels'
n-by-m matrix'rows'
m-by-n matrix'columns'

Here h, w, and c are the height, width, and number of channels for the output of the chosen layer, n is the number of observations in X, and m = hwc is the total number of features.

Algorithms

All functions for deep learning training, prediction, and validation in Deep Learning Toolbox™ perform computations using single-precision, floating-point arithmetic. Functions for deep learning include trainNetwork, predict, classify, and activations. The software uses single-precision arithmetic when you train networks using both CPUs and GPUs.

Extended Capabilities

Introduced in R2016a