trainNetwork - (Not recommended) Train neural network - MATLAB (original) (raw)

Main Content

(Not recommended) Train neural network

Syntax

Description

[net](#bu6sn4c-trainedNet) = trainNetwork([images](#mw%5F199f8be9-53f8-4bac-acdf-2846778f5904),[layers](#bu6sn4c%5Fsep%5Fmw%5Fa4be7938-74e9-410c-8d2d-98ae715a53af),[options](#bu6sn4c-options)) trains the neural network specified by layers for image classification and regression tasks using the images and responses specified byimages and the training options defined byoptions.

[net](#bu6sn4c-trainedNet) = trainNetwork([images](#mw%5F199f8be9-53f8-4bac-acdf-2846778f5904),[responses](#mw%5Fd0b3a2e4-09a0-42f9-a273-2bb25956fe66),[layers](#bu6sn4c%5Fsep%5Fmw%5Fa4be7938-74e9-410c-8d2d-98ae715a53af),[options](#bu6sn4c-options)) trains using the images specified by images and responses specified by responses.

[net](#bu6sn4c-trainedNet) = trainNetwork([sequences](#mw%5F36a68d96-8505-4b8d-b338-44e1efa9cc5e),[layers](#bu6sn4c%5Fsep%5Fmw%5Fa4be7938-74e9-410c-8d2d-98ae715a53af),[options](#bu6sn4c-options)) trains a neural network for sequence or time-series classification and regression tasks (for example, an LSTM or GRU neural network) using the sequences and responses specified by sequences.

[net](#bu6sn4c-trainedNet) = trainNetwork([sequences](#mw%5F36a68d96-8505-4b8d-b338-44e1efa9cc5e),[responses](#mw%5Fd0b3a2e4-09a0-42f9-a273-2bb25956fe66),[layers](#bu6sn4c%5Fsep%5Fmw%5Fa4be7938-74e9-410c-8d2d-98ae715a53af),[options](#bu6sn4c-options)) trains using the sequences specified by sequences and responses specified by responses.

example

[net](#bu6sn4c-trainedNet) = trainNetwork([features](#mw%5F9d0e11fb-fed4-441b-a0c6-05d8274571e1),[layers](#bu6sn4c%5Fsep%5Fmw%5Fa4be7938-74e9-410c-8d2d-98ae715a53af),[options](#bu6sn4c-options)) trains a neural network for feature classification or regression tasks (for example, a multilayer perceptron (MLP) neural network) using the feature data and responses specified by features.

[net](#bu6sn4c-trainedNet) = trainNetwork([features](#mw%5F9d0e11fb-fed4-441b-a0c6-05d8274571e1),[responses](#mw%5Fd0b3a2e4-09a0-42f9-a273-2bb25956fe66),[layers](#bu6sn4c%5Fsep%5Fmw%5Fa4be7938-74e9-410c-8d2d-98ae715a53af),[options](#bu6sn4c-options)) trains using the feature data specified by features and responses specified by responses.

[net](#bu6sn4c-trainedNet) = trainNetwork([mixed](#mw%5F9717db9c-a40f-41b1-aceb-29019274a2d0),[layers](#bu6sn4c%5Fsep%5Fmw%5Fa4be7938-74e9-410c-8d2d-98ae715a53af),[options](#bu6sn4c-options)) trains a neural network with multiple inputs with mixed data types with the data and responses specified by mixed.

[[net](#bu6sn4c-trainedNet),[info](#bu6sn4c-traininfo)] = trainNetwork(___) also returns information on the training using any of the previous syntaxes.

Examples

collapse all

Train Network for Sequence Classification

Train a deep learning LSTM network for sequence-to-label classification.

Load the example data from WaveformData.mat. The data is a numObservations-by-1 cell array of sequences, wherenumObservations is the number of sequences. Each sequence is anumChannels-by-numTimeSteps numeric array, where numChannels is the number of channels of the sequence and numTimeSteps is the number of time steps of the sequence.

Visualize some of the sequences in a plot.

numChannels = size(data{1},1);

idx = [3 4 5 12]; figure tiledlayout(2,2) for i = 1:4 nexttile stackedplot(data{idx(i)}', ... DisplayLabels="Channel " + string(1:numChannels))

xlabel("Time Step")
title("Class: " + string(labels(idx(i))))

end

Set aside data for testing. Partition the data into a training set containing 90% of the data and a test set containing the remaining 10% of the data. To partition the data, use thetrainingPartitions function, attached to this example as a supporting file. To access this file, open the example as a live script.

numObservations = numel(data); [idxTrain,idxTest] = trainingPartitions(numObservations, [0.9 0.1]); XTrain = data(idxTrain); TTrain = labels(idxTrain);

XTest = data(idxTest); TTest = labels(idxTest);

Define the LSTM network architecture. Specify the input size as the number of channels of the input data. Specify an LSTM layer to have 120 hidden units and to output the last element of the sequence. Finally, include a fully connected with an output size that matches the number of classes, followed by a softmax layer and a classification layer.

numHiddenUnits = 120; numClasses = numel(categories(TTrain));

layers = [ ... sequenceInputLayer(numChannels) lstmLayer(numHiddenUnits,OutputMode="last") fullyConnectedLayer(numClasses) softmaxLayer classificationLayer]

layers = 5×1 Layer array with layers:

 1   ''   Sequence Input          Sequence input with 3 dimensions
 2   ''   LSTM                    LSTM with 120 hidden units
 3   ''   Fully Connected         4 fully connected layer
 4   ''   Softmax                 softmax
 5   ''   Classification Output   crossentropyex

Specify the training options. Train using the Adam solver with a learn rate of 0.01 and a gradient threshold of 1. Set the maximum number of epochs to 150 and shuffle every epoch. The software, by default, trains on a GPU if one is available. Using a GPU requires Parallel Computing Toolbox™ and a supported GPU device. For information on supported devices, see GPU Computing Requirements (Parallel Computing Toolbox).

options = trainingOptions("adam", ... MaxEpochs=150, ... InitialLearnRate=0.01,... Shuffle="every-epoch", ... GradientThreshold=1, ... Verbose=false, ... Plots="training-progress");

Train the LSTM network with the specified training options.

net = trainNetwork(XTrain,TTrain,layers,options);

Classify the test data. Specify the same mini-batch size used for training.

YTest = classify(net,XTest);

Calculate the classification accuracy of the predictions.

acc = mean(YTest == TTest)

Display the classification results in a confusion chart.

figure confusionchart(TTest,YTest)

Input Arguments

collapse all

images — Image data

datastore | numeric array | table

Image data, specified as one of the following:

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

Tip

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

Datastore

Datastores read mini-batches of images and responses. Datastores are best suited when you have data that does not fit in memory or when you want to apply augmentations or transformations to the data.

The list below lists the datastores that are directly compatible withtrainNetwork for image data.

• ImageDatastore
• AugmentedImageDatastore
• CombinedDatastore
• TransformedDatastore
• PixelLabelImageDatastore (Computer Vision Toolbox)
• RandomPatchExtractionDatastore (Image Processing Toolbox)
• DenoisingImageDatastore (Image Processing Toolbox)
• Custom mini-batch datastore. For details, see Develop Custom Mini-Batch Datastore.

For example, you can create an image datastore using the imageDatastore function and use the names of the folders containing the images as labels by setting the 'LabelSource' option to'foldernames'. Alternatively, you can specify the labels manually using the Labels property of the image datastore.

Tip

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

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

You can use other built-in datastores for training deep learning neural networks by using the transform and combine functions. These functions can convert the data read from datastores to the format required bytrainNetwork.

For neural networks with multiple inputs, the datastore must be aTransformedDatastore or CombinedDatastore object.

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

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

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

The format of the responses depends on the type of task.

For responses returned in tables, the elements must be a categorical scalar, 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 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. If you specify images as a numeric array, then you must also specify the responses argument.

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

Table

As an alternative to datastores or numeric arrays, you can also specify images and responses in a table. If you specify images as a table, then you can also specify which columns contain the responses using the responses argument.

When specifying images and responses 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.

The format of the responses depends on the type of task.

For neural networks with image input, if you do not specifyresponses, then the function, by default, uses the first column of tbl for the predictors and the subsequent columns as responses.

Tip

• If the predictors or the responses containsNaNs, then they are propagated through the neural network during training. In these cases, the training usually fails to converge.
• For regression tasks, normalizing the responses often helps to stabilize and speed up training of neural networks for regression. For more information, see Train Convolutional Neural Network for Regression.
• This argument supports complex-valued predictors. To train a network with complex-valued predictors using thetrainNetwork function, theSplitComplexInputs option of the input layer must be 1 (true).

sequences — Sequence or time series data

datastore | cell array of numeric arrays | numeric array

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

Datastore

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

The list below lists the datastores that are directly compatible withtrainNetwork for sequence data.

• CombinedDatastore
• TransformedDatastore
• Custom mini-batch datastore. For details, see Develop Custom Mini-Batch Datastore.

You can use other built-in datastores for training deep learning neural networks by using the transform and combine functions. These functions can convert the data read from datastores to the table or cell array format required bytrainNetwork. For example, you can transform and combine data read from in-memory arrays and CSV files usingArrayDatastore andTabularTextDatastore objects, respectively.

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

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

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.

The format of the responses depends on the type of task.

For responses returned in tables, the elements must be a categorical scalar, 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. If you specify sequences as a cell or numeric array, then you must also specify the responses argument.

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.

The trainNetwork function supports neural networks with at most one sequence input layer.

Tip

• If the predictors or the responses containsNaNs, then they are propagated through the neural network during training. In these cases, the training usually fails to converge.
• For regression tasks, normalizing the responses often helps to stabilize and speed up training. For more information, see Train Convolutional Neural Network for Regression.
• This argument supports complex-valued predictors. To train a network with complex-valued predictors using thetrainNetwork function, theSplitComplexInputs option of the input layer must be 1 (true).

features — Feature data

datastore | numeric array | table

Feature data, specified as one of the following:

Datastore

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

The list below lists the datastores that are directly compatible withtrainNetwork for feature data.

• CombinedDatastore
• TransformedDatastore
• Custom mini-batch datastore. For details, see Develop Custom Mini-Batch Datastore.

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

For neural networks with multiple inputs, the datastore must be aTransformedDatastore 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 neural network architecture.

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

The format of the responses depends on the type of task.

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 and responses in the table columns depends on the type of task.

For classification neural networks with feature input, if you do not specify the responses argument, then the function, by default, uses the first (numColumns - 1) columns of tbl for the predictors and the last column for the labels, where numFeatures is the number of features in the input data.

For regression neural networks with feature input, if you do not specify the responseNames argument, then the function, by default, uses the first numFeatures columns for the predictors and the subsequent columns for the responses, where numFeatures is the number of features in the input data.

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. If you specify feature data as a numeric array, then you must also specify the responses argument.

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

Tip

• Normalizing the responses often helps to stabilize and speed up training of neural networks for regression. For more information, see Train Convolutional Neural Network for Regression.
• Responses must not contain NaNs. If the predictor data contains NaNs, then they are propagated through the training. However, in most cases, the training fails to converge.
• This argument supports complex-valued predictors. To train a network with complex-valued predictors using thetrainNetwork function, theSplitComplexInputs option of the input layer must be 1 (true).

mixed — Mixed data

datastore

Mixed data and responses, specified as one of the following:

You can use other built-in datastores for training deep learning neural networks by using the transform and combine functions. These functions can convert the data read from datastores to the table or cell array format required bytrainNetwork. 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 neural network architecture.

For image, sequence, and feature predictor input, the format of the predictors must match the formats described in theimages, sequences, orfeatures argument descriptions, respectively. Similarly, the format of the responses must match the formats described in the images, sequences, orfeatures argument descriptions that corresponds to the type of task.

The trainNetwork function supports neural networks with at most one sequence input layer.

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

Tip

• To convert a numeric array to a datastore, useArrayDatastore.
• When combining layers in a neural network with mixed types of data, you may need to reformat the data before passing it to a combination layer (such as a concatenation or an addition layer). To reformat the data, you can use a flatten layer to flatten the spatial dimensions into the channel dimension, or create a FunctionLayer object or custom layer that reformats and reshapes.
• This argument supports complex-valued predictors. To train a network with complex-valued predictors using thetrainNetwork function, theSplitComplexInputs option of the input layer must be 1 (true).

responses — Responses

categorical vector | numeric array | cell array of sequences | character vector | cell array of character vectors | string array

Responses.

When the input data is a numeric array or a cell array, specify the responses as one of the following.

• categorical vector of labels
• numeric array of numeric responses
• cell array of categorical or numeric sequences

When the input data is a table, you can optionally specify which columns of the table contains the responses as one of the following:

• character vector
• cell array of character vectors
• string array

When the input data is a numeric array or a cell array, then the format of the responses depends on the type of task.

Tip

Responses must not contain NaNs. If the predictor data contains NaNs, then they are propagated through the training. However, in most cases, the training fails to converge.

layers — Neural network layers

Layer array | LayerGraph object

Neural network layers, specified as a Layer array or a LayerGraph object.

To create a neural network with all layers connected sequentially, you can use aLayer array as the input argument. In this case, the returned neural network is a SeriesNetwork object.

A directed acyclic graph (DAG) neural network has a complex structure in which layers can have multiple inputs and outputs. To create a DAG neural network, specify the neural network architecture as a LayerGraph object and then use that layer graph as the input argument totrainNetwork.

The trainNetwork function supports neural networks with at most one sequence input layer.

For a list of built-in layers, see List of Deep Learning Layers.

options — Training options

TrainingOptionsSGDM | TrainingOptionsRMSProp | TrainingOptionsADAM

Training options, specified as a TrainingOptionsSGDM,TrainingOptionsRMSProp, orTrainingOptionsADAM object returned by the trainingOptions function.

Output Arguments

collapse all

net — Trained neural network

SeriesNetwork object | DAGNetwork object

Trained neural network, returned as a SeriesNetwork object or a DAGNetwork object.

If you train the neural network using a Layer array, thennet is a SeriesNetwork object. If you train the neural network using a LayerGraph object, then net is aDAGNetwork object.

info — Training information

structure

Training information, returned as a structure, where each field is a scalar or a numeric vector with one element per training iteration.

For classification tasks, info contains the following fields:

• TrainingLoss — Loss function values
• TrainingAccuracy — Training accuracies
• ValidationLoss — Loss function values
• ValidationAccuracy — Validation accuracies
• BaseLearnRate — Learning rates
• FinalValidationLoss — Validation loss of returned neural network
• FinalValidationAccuracy — Validation accuracy of returned neural network
• OutputNetworkIteration — Iteration number of returned neural network

For regression tasks, info contains the following fields:

• TrainingLoss — Loss function values
• TrainingRMSE — Training RMSE values
• ValidationLoss — Loss function values
• ValidationRMSE — Validation RMSE values
• BaseLearnRate — Learning rates
• FinalValidationLoss — Validation loss of returned neural network
• FinalValidationRMSE — Validation RMSE of returned neural network
• OutputNetworkIteration — Iteration number of returned neural network

The structure only contains the fields ValidationLoss,ValidationAccuracy, ValidationRMSE , FinalValidationLoss ,FinalValidationAccuracy, andFinalValidationRMSE when options specifies validation data. The ValidationFrequency training option determines which iterations the software calculates validation metrics. The final validation metrics are scalar. The other fields of the structure are row vectors, where each element corresponds to a training iteration. For iterations when the software does not calculate validation metrics, the corresponding values in the structure areNaN.

For neural networks containing batch normalization layers, if theBatchNormalizationStatistics training option is'population' then the final validation metrics are often different from the validation metrics evaluated during training. This is because batch normalization layers in the final neural network perform different operations than during training. For more information, see batchNormalizationLayer.

More About

collapse all

Save Checkpoint Neural Networks and Resume Training

Deep Learning Toolbox™ enables you to save neural networks as .mat files during training. This periodic saving is especially useful when you have a large neural network or a large data set, and training takes a long time. If the training is interrupted for some reason, you can resume training from the last saved checkpoint neural network. If you want the trainNetwork function to save checkpoint neural networks, then you must specify the name of the path by using theCheckpointPath option oftrainingOptions. If the path that you specify does not exist, then trainingOptions returns an error.

The software automatically assigns unique names to checkpoint neural network files. In the example name,net_checkpoint__351__2018_04_12__18_09_52.mat, 351 is the iteration number, 2018_04_12 is the date, and18_09_52 is the time at which the software saves the neural network. You can load a checkpoint neural network file by double-clicking it or using the load command at the command line. For example:

load net_checkpoint__351__2018_04_12__18_09_52.mat

You can then resume training by using the layers of the neural network as an input argument to trainNetwork. For example:

trainNetwork(XTrain,TTrain,net.Layers,options)

You must manually specify the training options and the input data, because the checkpoint neural network does not contain this information.

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

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

To run computation in parallel, set the ExecutionEnvironment training option to "multi-gpu" or "parallel".

Use trainingOptions to set theExecutionEnvironment training option and supply the options to trainNetwork. If you do not setExecutionEnvironment, then trainNetwork runs on a GPU if available.

For details, see Scale Up Deep Learning in Parallel, on GPUs, and in the Cloud.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

• To prevent out-of-memory errors, recommended practice is not to move large sets of training data onto the GPU. Instead, train your neural network on a GPU by using trainingOptions to set theExecutionEnvironment to "auto" or"gpu" and supply the options totrainNetwork.
• The ExecutionEnvironment option must be"auto" or "gpu" when the input data is:
  • A gpuArray
  • A cell array containing gpuArray objects
  • A table containing gpuArray objects
  • A datastore that outputs cell arrays containinggpuArray objects
  • A datastore that outputs tables containinggpuArray objects

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2016a

expand all

R2024a: Not recommended

Starting in R2024a, the trainNetwork function is not recommended, use the trainnet function instead.

There are no plans to remove support for the trainNetwork function. However, the trainnet function has these advantages and is recommended instead:

• trainnet supports dlnetwork objects, which support a wider range of network architectures that you can create or import from external platforms.
• trainnet enables you to easily specify loss functions. You can select from built-in loss functions or specify a custom loss function.
• trainnet outputs a dlnetwork object, which is a unified data type that supports network building, prediction, built-in training, visualization, compression, verification, and custom training loops.
• trainnet is typically faster than trainNetwork.

This table shows some typical usages of the trainNetwork function and how to update your code to use the trainnet function instead.

Instead of using an output layer, specify a loss function usinglossFcn.

R2022b: trainNetwork pads mini-batches to length of longest sequence before splitting when you specify SequenceLength training option as an integer

Starting in R2022b, when you train a neural network with sequence data using the trainNetwork function and the SequenceLength option is an integer, the software pads sequences to the length of the longest sequence in each mini-batch and then splits the sequences into mini-batches with the specified sequence length. If SequenceLength does not evenly divide the sequence length of the mini-batch, then the last split mini-batch has a length shorter than SequenceLength. This behavior prevents the neural network training on time steps that contain only padding values.

In previous releases, the software pads mini-batches of sequences to have a length matching the nearest multiple of SequenceLength that is greater than or equal to the mini-batch length and then splits the data. To reproduce this behavior, use a custom training loop and implement this behavior when you preprocess mini-batches of data.

R2021b: trainNetwork automatically stops training when loss is NaN

When you train a neural network using the trainNetwork function, training automatically stops when the loss is NaN. Usually, a loss value of NaN introduces NaN values to the neural network learnable parameters, which in turn can cause the neural network to fail to train or to make valid predictions. This change helps identify issues with the neural network before training completes.

In previous releases, the neural network continues to train when the loss isNaN.

R2021a: Support for specifying tables of MAT file paths will be removed

When specifying sequence data for the trainNetwork function, support for specifying tables of MAT file paths will be removed in a future release.

To train neural networks with sequences that do not fit in memory, use a datastore. You can use any datastore to read your data and then use thetransform function to transform the datastore output to the format the trainNetwork function requires. For example, you can read data using a FileDatastore orTabularTextDatastore object then transform the output using thetransform function.