Main Content

classifyAndUpdateState

(Not recommended) Classify data using a trained recurrent neural network and update the network state

collapse all in page

classifyAndUpdateState is not recommended. Instead, use the predict function and use the state output to update the State property of the neural network. To convert classification scores to labels, use the scores2label function. For more information, see Version History.

Syntax

[updatedNet,Y] = classifyAndUpdateState(recNet,sequences)
[updatedNet,Y] = classifyAndUpdateState(recNet,X1,...,XN)
[updatedNet,Y] = classifyAndUpdateState(recNet,mixed)
[updatedNet,Y,scores] = classifyAndUpdateState(___)
___ = classifyAndUpdateState(___,Name=Value)

Description

You can make predictions using a trained deep learning network 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.

[updatedNet,Y] = classifyAndUpdateState(recNet,sequences) classifies the data in sequences using the trained recurrent neural network recNet and updates the network state.

This function supports recurrent neural networks only. The input recNet must have at least one recurrent layer such as an LSTM layer or a custom layer with state parameters.

example

[updatedNet,Y] = classifyAndUpdateState(recNet,X1,...,XN) predicts the class labels for the data in the numeric arrays or cell arrays X1, …, XN for the multi-input network recNet. The input Xi corresponds to the network input recNet.InputNames(i).

[updatedNet,Y] = classifyAndUpdateState(recNet,mixed) predicts the class labels for the multi-input network recNet with data of mixed data types.

[updatedNet,Y,scores] = classifyAndUpdateState(___) also returns the classification scores corresponding to the class labels using any of the previous syntaxes.

___ = classifyAndUpdateState(___,Name=Value) predicts class labels with additional options specified by one or more name-value arguments using any of the previous syntaxes. For example, MiniBatchSize=27 classifies data using mini-batches of size 27.

Tip

When you make predictions with sequences of different lengths, the mini-batch size can impact the amount of padding added to the input data, which can result in different predicted values. Try using different values to see which works best with your network. To specify mini-batch size and padding options, use the MiniBatchSize and SequenceLength options, respectively.

Classify and Update Network State

Examples

collapse all

Classify data using a recurrent neural network and update the network state.

Suppose you have a long short-term memory (LSTM) network net that was trained on the Japanese Vowels data set as described in [1] and [2]. Suppose the network was trained on the sequences sorted by sequence length with a mini-batch size of 27.

View the network architecture.

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

     1   'sequenceinput'   Sequence Input          Sequence input with 12 dimensions
     2   'lstm'            LSTM                    LSTM with 100 hidden units
     3   'fc'              Fully Connected         9 fully connected layer
     4   'softmax'         Softmax                 softmax
     5   'classoutput'     Classification Output   crossentropyex with '1' and 8 other classes

Suppose you have a test data set XTest, where XTest is a cell array of sequences of varying lengths. Each sequence has 12 features.

Loop over the time steps in one of the sequences. Classify each time step and update the network state.

X = XTest{94};
numTimeSteps = size(X,2);
for i = 1:numTimeSteps
    v = X(:,i);
    [net,label,score] = classifyAndUpdateState(net,v);
    labels(i) = label;
end

Plot the predicted labels in a stair plot. The plot shows how the predictions change between time steps.

figure
stairs(labels,"-o")
xlim([1 numTimeSteps])
xlabel("Time Step")
ylabel("Predicted Class")
title("Classification Over Time Steps")

Compare the predictions with the true label. 

trueLabel = TTest(94)
trueLabel = categorical
     3

Plot a horizontal line showing the true label of the observation.

hold on
line([1 numTimeSteps],[trueLabel trueLabel], ...
    Color="red", ...
    LineStyle="--")
legend(["Prediction" "True Label"])

Figure contains an axes object. The axes object with title Classification Over Time Steps, xlabel Time Step, ylabel Predicted Class contains 2 objects of type stair, line. These objects represent Prediction, True Label.

Input Arguments

collapse all

Trained recurrent neural network, specified as a SeriesNetwork or a DAGNetwork object. You can get a trained network by importing a pretrained network or by training your own network using the trainNetwork function.

recNet is a recurrent neural network. It must have at least one recurrent layer (for example, an LSTM network).

Sequence or time series data, specified as an N-by-1 cell array of numeric arrays, where N is the number of observations, a numeric array representing a single sequence, or a datastore.

For cell array or numeric array input, the dimensions of the numeric arrays containing the sequences depend on the type of 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.

For datastore input, the datastore must return data as a cell array of sequences or a table whose first column contains sequences. The dimensions of the sequence data must correspond to the table above.

Tip

This argument supports complex-valued predictors. To input complex-valued data into a SeriesNetwork or DAGNetwork object, the SplitComplexInputs option of the input layer must be 1 (true).

Numeric or cell arrays for networks with multiple inputs.

For sequence predictor input, the input must be a numeric array representing a single sequence or a cell array of sequences, where the format of the predictors match the formats described in the sequences argument description. For image and feature predictor input, the input must be a numeric array and the format of the predictors must match the one of the following:

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.
Feature data

c-by-1 column vectors, where c is the number of features.

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

Tip

To input complex-valued data into a DAGNetwork or SeriesNetwork object, 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 classifyAndUpdateState 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 classifyAndUpdateState. 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

    {12×50 double}    {28×1 double}
    {12×50 double}    {28×1 double}
    {12×50 double}    {28×1 double}
    {12×50 double}    {28×1 double}

For sequence predictor input, the input must be a numeric array representing a single sequence or a cell array of sequences, where the format of the predictors match the formats described in the sequences argument description. For image and feature predictor input, the input must be a numeric array and the format of the predictors must match the one of the following:

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.
Feature data

c-by-1 column vectors, where c is the number of features.

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.

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: [updatedNet,Y] = classifyAndUpdateState(recNet,C,MiniBatchSize=27) classifies data using mini-batches of size 27.

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.

When you make predictions with sequences of different lengths, the mini-batch size can impact the amount of padding added to the input data, which can result in different predicted values. Try using different values to see which works best with your network. To specify mini-batch size and padding options, use the MiniBatchSize and SequenceLength options, respectively.

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

Performance optimization, specified as one of the following:

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

  • "none" — Disable all acceleration.

Using the Acceleration option "auto" 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.

Hardware resource, specified as one of these values:

  • "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.

Option to pad, truncate, or split sequences, specified as one of these values:

  • "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 and truncating sequences, see Sequence Padding and Truncation.

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

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 and truncating sequences, see Sequence Padding and Truncation.

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

Output Arguments

collapse all

Updated network. updatedNet is the same type of network as the input network.

Predicted class labels, returned as a categorical vector, or a cell array of categorical vectors. The format of Y depends on the type of problem.

The following table describes the format of Y.

TaskFormat
Sequence-to-label classificationN-by-1 categorical vector of labels, where N is the number of observations.
Sequence-to-sequence classification

N-by-1 cell array of categorical sequences of labels, where N is the number of observations. Each sequence has the same number of time steps as the corresponding input sequence after applying the SequenceLength option to each mini-batch independently.

For sequence-to-sequence classification problems with one observation, sequences can be a matrix. In this case, YPred is a categorical sequence of labels.

Predicted class scores, returned as a matrix or a cell array of matrices. The format of scores depends on the type of problem.

The following table describes the format of scores.

TaskFormat
Sequence-to-label classificationN-by-K matrix, where N is the number of observations, and K is the number of classes.
Sequence-to-sequence classification

N-by-1 cell array of matrices, where N is the number of observations. The sequences are matrices with K rows, where K is the number of classes. Each sequence has the same number of time steps as the corresponding input sequence after applying the SequenceLength option to each mini-batch independently.

For sequence-to-sequence classification problems with one observation, sequences can be a matrix. In this case, scores is a matrix of predicted class scores.

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.

Alternatives

To classify data using a recurrent neural network with multiple output layers and update the network state, use the predictAndUpdateState function and set the ReturnCategorical option to 1 (true).

To compute the predicted classification scores and update the network state of a recurrent neural network, you can also use the predictAndUpdateState function.

To compute the activations of a network layer, use the activations function. The activations function does not update the network state.

To make predictions without updating the network state, use the classify function or the predict function.

References

[1] M. Kudo, J. Toyama, and M. Shimbo. "Multidimensional Curve Classification Using Passing-Through Regions." Pattern Recognition Letters. Vol. 20, No. 11–13, pages 1103–1111.

[2] UCI Machine Learning Repository: Japanese Vowels Dataset. https://archive.ics.uci.edu/ml/datasets/Japanese+Vowels

Extended Capabilities

Version History

Introduced in R2017b

expand all

R2024a: Not recommended

Starting in R2024a, DAGNetwork and SeriesNetwork objects are not recommended, use dlnetwork objects instead. This recommendation means that the classifyAndUpdateState function is also not recommended. Instead, use the predict function and use the state output to update the State property of the neural network. To convert classification scores to labels, use the scores2label function.

There are no plans to remove support for DAGNetwork and SeriesNetwork objects. However, dlnetwork objects have these advantages and are recommended instead:

  • dlnetwork objects are a unified data type that supports network building, prediction, built-in training, visualization, compression, verification, and custom training loops.

  • dlnetwork objects support a wider range of network architectures that you can create or import from external platforms.

  • The trainnet function supports dlnetwork objects, which enables you to easily specify loss functions. You can select from built-in loss functions or specify a custom loss function.

  • Training and prediction with dlnetwork objects is typically faster than LayerGraph and trainNetwork workflows.

To convert a trained DAGNetwork or SeriesNetwork object to a dlnetwork object, use the dag2dlnetwork function.

This table shows a typical usage of the classifyAndUpdateState function and how to update your code to use dlnetwork objects instead.

Not RecommendedRecommended
[net,Y] = classifyAndUpdateState(net,X);
 
[scores,state] = predict(net,X);
net.State = state;
Y = scores2label(scores,classNames);

See Also

| | | | | | |

Topics