importKerasLayers

Import layers from Keras network

Syntax

layers = importKerasLayers(modelfile)

layers = importKerasLayers(modelfile,Name,Value)

Description

layers = importKerasLayers(modelfile) imports the layers of a TensorFlow™-Keras network from a model file. The function returns the layers defined in the HDF5 (.h5) or JSON (.json) file given by the file name modelfile.

This function requires the Deep Learning Toolbox™ Importer for TensorFlow-Keras Models support package. If this support package is not installed, then the function provides a download link.

layers = importKerasLayers(modelfile,Name,Value) imports the layers from a TensorFlow-Keras network with additional options specified by one or more name-value pair arguments.

For example, importKerasLayers(modelfile,'ImportWeights',true) imports the network layers and the weights from the model file modelfile.

Examples

Download and Install Deep Learning Toolbox Importer for TensorFlow-Keras Models Support Package

Download and install Deep Learning Toolbox Importer for TensorFlow-Keras Models support package.

Type importKerasLayers at the command line.

importKerasLayers

If Deep Learning Toolbox Importer for TensorFlow-Keras Models support package is not installed, then the function provides a link to the required support package in the Add-On Explorer. To install the support package, click the link, and then click Install. Check that the installation is successful by importing the layers from the model file 'digitsDAGnet.h5' at the command line.

modelfile = 'digitsDAGnet.h5';
layers = importKerasLayers(modelfile)

layers = 

  LayerGraph with properties:

         Layers: [13×1 nnet.cnn.layer.Layer]
    Connections: [13×2 table]

If the required support package is installed, then the function returns a LayerGraph object.

Import Layers from Keras Network and Plot Architecture

Import the network layers from the model file digitsDAGnet.h5.

modelfile = 'digitsDAGnet.h5';
layers = importKerasLayers(modelfile) 

layers = 
  LayerGraph with properties:

         Layers: [13×1 nnet.cnn.layer.Layer]
    Connections: [13×2 table]

Plot the network architecture.

figure
plot(layers)

Import Keras Network Layers and Train Network

Specify the network file to import.

modelfile = 'digitsDAGnet.h5';

Import network layers.

layers = importKerasLayers(modelfile)

layers = 
  LayerGraph with properties:

         Layers: [13×1 nnet.cnn.layer.Layer]
    Connections: [13×2 table]

Load a data set for training a classifier to recognize new digits.

folder = fullfile(toolboxdir('nnet'),'nndemos','nndatasets','DigitDataset');
imds = imageDatastore(folder, ...
    'IncludeSubfolders',true, ...
    'LabelSource','foldernames');

Partition the dataset into training and test sets.

numTrainFiles = 750;
[imdsTrain,imdsTest] = splitEachLabel(imds,numTrainFiles,'randomize');

Set the training options.

options = trainingOptions('sgdm', ...
    'MaxEpochs',10, ...
    'InitialLearnRate',0.001);

Train network using training data.

net = trainNetwork(imdsTrain,layers,options);

Training on single GPU.
|========================================================================================|
|  Epoch  |  Iteration  |  Time Elapsed  |  Mini-batch  |  Mini-batch  |  Base Learning  |
|         |             |   (hh:mm:ss)   |   Accuracy   |     Loss     |      Rate       |
|========================================================================================|
|       1 |           1 |       00:00:00 |        5.47% |       6.4266 |          0.0010 |
|       1 |          50 |       00:00:05 |       81.25% |       0.6227 |          0.0010 |
|       2 |         100 |       00:00:08 |       92.19% |       0.2386 |          0.0010 |
|       3 |         150 |       00:00:12 |       96.88% |       0.0726 |          0.0010 |
|       4 |         200 |       00:00:16 |       97.66% |       0.0871 |          0.0010 |
|       5 |         250 |       00:00:19 |       99.22% |       0.0415 |          0.0010 |
|       6 |         300 |       00:00:23 |       97.66% |       0.0725 |          0.0010 |
|       7 |         350 |       00:00:27 |      100.00% |       0.0291 |          0.0010 |
|       7 |         400 |       00:00:30 |       99.22% |       0.0230 |          0.0010 |
|       8 |         450 |       00:00:34 |       99.22% |       0.0337 |          0.0010 |
|       9 |         500 |       00:00:38 |       99.22% |       0.0120 |          0.0010 |
|      10 |         550 |       00:00:41 |      100.00% |       0.0036 |          0.0010 |
|      10 |         580 |       00:00:44 |      100.00% |       0.0059 |          0.0010 |
|========================================================================================|

Run the trained network on the test set that was not used to train the network and predict the image labels (digits).

YPred = classify(net,imdsTest);
YTest = imdsTest.Labels;

Calculate the accuracy.

accuracy = sum(YPred == YTest)/numel(YTest)

accuracy = 0.9828

Import Keras Network Architecture and Weights from Same File

Specify the network file to import layers and weights from.

modelfile = 'digitsDAGnet.h5';

Import the network architecture and weights from the files you specified. To import the layer weights, specify 'ImportWeights' to be true. The function also imports the layers with their weights from the same HDF5 file.

layers = importKerasLayers(modelfile,'ImportWeights',true)

layers = 
  LayerGraph with properties:

         Layers: [13×1 nnet.cnn.layer.Layer]
    Connections: [13×2 table]

View the size of the weights in the second layer.

weights = layers.Layers(2).Weights;
size(weights)

ans = 1×4

     7     7     1    20

The function has imported the weights so the layer weights are non-empty.

Import Keras Network Architecture and Weights from Separate Files

Specify the network file to import layers from and the file containing weights.

modelfile = 'digitsDAGnet.json';
weights = 'digitsDAGnet.weights.h5';

Import the network architecture and weights from the files you specified. The .json file does not include an output layer. Specify the output layer, so that importKerasLayers adds an output layer at the end of the networks architecture.

layers = importKerasLayers(modelfile, ...
    'ImportWeights',true, ...
    'WeightFile',weights, ...
    'OutputLayerType','classification')

layers = 
  LayerGraph with properties:

         Layers: [13×1 nnet.cnn.layer.Layer]
    Connections: [13×2 table]

Assemble Network from Pretrained Keras Layers

This example shows how to import the layers from a pretrained Keras network, replace the unsupported layers with custom layers, and assemble the layers into a network ready for prediction.

Import Keras Network

Import the layers from a Keras network model. The network in 'digitsDAGnetwithnoise.h5' classifies images of digits.

filename = 'digitsDAGnetwithnoise.h5';
lgraph = importKerasLayers(filename,'ImportWeights',true);

Warning: Unable to import some Keras layers, because they are not yet supported by the Deep Learning Toolbox. They have been replaced by placeholder layers. To find these layers, call the function findPlaceholderLayers on the returned object.

The Keras network contains some layers that are not supported by Deep Learning Toolbox. The importKerasLayers function displays a warning and replaces the unsupported layers with placeholder layers.

Plot the layer graph using plot.

figure
plot(lgraph)
title("Imported Network")

Replace Placeholder Layers

To replace the placeholder layers, first identify the names of the layers to replace. Find the placeholder layers using findPlaceholderLayers.

placeholderLayers = findPlaceholderLayers(lgraph)

placeholderLayers = 
  2x1 PlaceholderLayer array with layers:

     1   'gaussian_noise_1'   PLACEHOLDER LAYER   Placeholder for 'GaussianNoise' Keras layer
     2   'gaussian_noise_2'   PLACEHOLDER LAYER   Placeholder for 'GaussianNoise' Keras layer

Display the Keras configurations of these layers.

placeholderLayers.KerasConfiguration

ans = struct with fields:
    trainable: 1
         name: 'gaussian_noise_1'
       stddev: 1.5000

ans = struct with fields:
    trainable: 1
         name: 'gaussian_noise_2'
       stddev: 0.7000

Define a custom Gaussian noise layer. To create this layer, save the file gaussianNoiseLayer.m in the current folder. Then, create two Gaussian noise layers with the same configurations as the imported Keras layers.

gnLayer1 = gaussianNoiseLayer(1.5,'new_gaussian_noise_1');
gnLayer2 = gaussianNoiseLayer(0.7,'new_gaussian_noise_2');

Replace the placeholder layers with the custom layers using replaceLayer.

lgraph = replaceLayer(lgraph,'gaussian_noise_1',gnLayer1);
lgraph = replaceLayer(lgraph,'gaussian_noise_2',gnLayer2);

Plot the updated layer graph using plot.

figure
plot(lgraph)
title("Network with Replaced Layers")

Specify Class Names

If the imported classification layer does not contain the classes, then you must specify these before prediction. If you do not specify the classes, then the software automatically sets the classes to 1, 2, ..., N, where N is the number of classes.

Find the index of the classification layer by viewing the Layers property of the layer graph.

lgraph.Layers

ans = 
  15x1 Layer array with layers:

     1   'input_1'                            Image Input             28x28x1 images
     2   'conv2d_1'                           Convolution             20 7x7x1 convolutions with stride [1  1] and padding 'same'
     3   'conv2d_1_relu'                      ReLU                    ReLU
     4   'conv2d_2'                           Convolution             20 3x3x1 convolutions with stride [1  1] and padding 'same'
     5   'conv2d_2_relu'                      ReLU                    ReLU
     6   'new_gaussian_noise_1'               Gaussian Noise          Gaussian noise with standard deviation 1.5
     7   'new_gaussian_noise_2'               Gaussian Noise          Gaussian noise with standard deviation 0.7
     8   'max_pooling2d_1'                    Max Pooling             2x2 max pooling with stride [2  2] and padding 'same'
     9   'max_pooling2d_2'                    Max Pooling             2x2 max pooling with stride [2  2] and padding 'same'
    10   'flatten_1'                          Flatten C-style         Flatten activations into 1D assuming C-style (row-major) order
    11   'flatten_2'                          Flatten C-style         Flatten activations into 1D assuming C-style (row-major) order
    12   'concatenate_1'                      Depth concatenation     Depth concatenation of 2 inputs
    13   'dense_1'                            Fully Connected         10 fully connected layer
    14   'activation_1'                       Softmax                 softmax
    15   'ClassificationLayer_activation_1'   Classification Output   crossentropyex

The classification layer has the name 'ClassificationLayer_activation_1'. View the classification layer and check the Classes property.

cLayer = lgraph.Layers(end)

cLayer = 
  ClassificationOutputLayer with properties:

            Name: 'ClassificationLayer_activation_1'
         Classes: 'auto'
      OutputSize: 'auto'

   Hyperparameters
    LossFunction: 'crossentropyex'

Because the Classes property of the layer is 'auto', you must specify the classes manually. Set the classes to 0, 1, ..., 9, and then replace the imported classification layer with the new one.

cLayer.Classes = string(0:9)

cLayer = 
  ClassificationOutputLayer with properties:

            Name: 'ClassificationLayer_activation_1'
         Classes: [0    1    2    3    4    5    6    7    8    9]
      OutputSize: 10

   Hyperparameters
    LossFunction: 'crossentropyex'

lgraph = replaceLayer(lgraph,'ClassificationLayer_activation_1',cLayer);

Assemble Network

Assemble the layer graph using assembleNetwork. The function returns a DAGNetwork object that is ready to use for prediction.

net = assembleNetwork(lgraph)

net = 
  DAGNetwork with properties:

         Layers: [15×1 nnet.cnn.layer.Layer]
    Connections: [15×2 table]

Input Arguments

modelfile — Name of Keras model file

character vector | string scalar

Name of the model file containing the network architecture, and possibly the weights, specified as a character vector or a string scalar. The file must be in the current folder, in a folder on the MATLAB^® path, or you must include a full or relative path to the file.

If modelfile includes

• The network architecture and weights, then it must be in HDF5 (.h5) format.

• Only the network architecture, then it can be in HDF5 or JSON (.json) format.

If modelfile includes only the network architecture, then you can optionally supply the weights using the 'ImportWeights' and 'WeightFile' name-value pair arguments. If you supply the weights, then the weights file must be in HDF5 format.

Example: 'digitsnet.h5'

Data Types: char | string

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: importKerasLayers(modelfile,'OutputLayerType','classification') imports the network layers from the model file modelfile and adds an output layer for a classification problem at the end of the Keras layers.

'OutputLayerType' — Type of output layer

'classification' | 'regression' | 'pixelclassification'

Type of the output layer that the function appends to the end of the imported network architecture when modelfile does not specify a loss function, specified as 'classification', 'regression', or 'pixelclassification'. Appending a pixelClassificationLayer object requires Computer Vision Toolbox™.

Example: 'OutputLayerType','regression'

'ImageInputSize' — Size of input images

vector of two or three numerical values

Size of the input images for the network, specified as a vector of two or three numerical values corresponding to [height,width] for grayscale images and [height,width,channels] for color images, respectively. The network uses this information when the modelfile does not specify the input size.

Example: 'ImageInputSize',[28 28]

'ImportWeights' — Indicator to import weights

false (default) | true

Indicator to import weights as well as the network architecture, specified as either false or true.

• If 'ImportWeights' is true and modelfile includes the weights, then importKerasLayers imports the weights from modelfile, which must have HDF5 (.h5) format.

• If 'ImportWeights' is true and modelfile does not include the weights, then you must specify a separate file that includes weights, using the 'WeightFile' name-value pair argument.

Example: 'ImportWeights',true

Data Types: logical

'WeightFile' — Weight file name

character vector | string scalar

Weight file name, from which to import weights when modelfile does not include weights, specified as a character vector or a string scalar. To use this name-value pair argument, you also must set 'ImportWeights' to true.

Weight file must be in the current folder, in a folder on the MATLAB path, or you must include a full or relative path to the file.

Example: 'WeightFile','weights.h5'

Data Types: char | string

Output Arguments

layers — Network architecture

Layer array object | LayerGraph object

Network architecture, returned as a Layer array object when the Keras network is of type Sequential, or returned as a LayerGraph object when the Keras network is of type Model.

Tips

• importKerasLayers supports the following Keras layer types, with some limitations. If the network contains any other type of layer, then the software inserts a place holder layer in place of the unsupported layer. To find the names and indices of the unsupported layers in the network, use the findPlaceholderLayers function.

  Supported Keras Layers

  Keras Layer	Deep Learning Toolbox Layer
  Add	additionLayer
  Activation, with activation names: 'relu' 'linear' 'softmax' 'sigmoid' 'tanh'	Layers: reluLayer, clippedReluLayer None softmaxLayer nnet.keras.layer.SigmoidLayer nnet.cnn.layer.TanhLayer
  Advanced activations: Softmax ReLU LeakyReLU	Layers: softmaxLayer reluLayer, clippedReluLayer leakyReluLayer
  AveragePooling2D	averagePooling2dLayer
  BatchNormalization	batchNormalizationLayer
  Bidirectional(LSTM(__))	bilstmLayer
  Concatenate	depthConcatenationLayer
  Conv2D	convolution2dLayer
  Conv2DTranspose	transposedConv2dLayer
  DepthwiseConv2D	groupedConvolution2dLayer
  Dense	fullyConnectedLayer
  Dropout	dropoutLayer
  Embedding	wordEmbeddingLayer (Text Analytics Toolbox™)
  Flatten	nnet.keras.layer.FlattenCStyleLayer
  GlobalAveragePooling2D	nnet.cnn.layer.GlobalAveragePooling2DLayer
  Input	imageInputLayer
  LeakyReLU	leakyReluLayer
  LSTM	lstmLayer
  MaxPooling2D	maxPooling2dLayer
  SeparableConv2D	groupedConvolution2dLayer and convolution2dLayer
  ZeroPadding2D	nnet.keras.layer.ZeroPadding2DLayer

• You can replace a placeholder layer with a new layer that you define.

  • If the network is a series network, then replace the layer in the array directly. For example, layer(2) = newlayer;.

  • If the network is a DAG network, then replace the layer using replaceLayer. For an example, see Assemble Network from Pretrained Keras Layers.

• importKerasLayers supports the following Keras loss functions:

  • mean_squared_error

  • categorical_crossentropy

  • sparse_categorical_crossentropy

  • binary_crossentropy

References

[1] Keras: The Python Deep Learning library. https://keras.io.