Main Content

VaelstmDetector

Detect anomalies in time series using combined variational autoencoder (VAE) and long short-term memory (LSTM) networks

Since R2025a

Description

The VaelstmDetector object uses a deep learning network architecture that contains both VAE and LSTM networks to implement a detector model capable of being trained to detect anomalies in time series data using only normal data. You create this object with the vaelstmAD function.

By comparing forecasted values with measured data within a detection window, the detector identifies anomalies as significant differences between forecasted and measured observations. You can control the sensitivity of the detector by modifying a set of threshold and window-sizing properties.

Creating a VaelstmDetector object is the first step in a workflow that includes creation, training, testing, assessing, and, if necessary, modifying the detector. For information on the workflow for developing a Predictive Maintenance Toolbox™ anomaly detector, see Detecting Anomalies in Time Series Using Deep Learning Detector Models.

This anomaly detector model was inspired by the architecture proposed in the paper in [1] .

For more information on the functions this workflow uses, see Object Functions.

Creation

Create a VaelstmDetector object by using the vaelstmAD function.

Properties

expand all

Input

Number of input channels in each time series, specified as a positive integer. All time series inputs must have the same number of channels.

This property is read-only after object creation.

Window

Observation window length of each time series segment, specified as a positive integer.

The detector uses this value to divide each input time series into segments.

Training stride length of the sliding window in the training stage, specified as a positive integer.

This property controls the number of overlapping samples. If you do not specify TrainingStride, the software sets the stride length to the value of 1 to create nonoverlapping windows.

Detection window length of each time series segment, specified as a positive integer that is smaller than ObservationWindowLength. This value determines the length of the prediction segment that the model uses for detection.

Detection stride length of the sliding window in the detection stage, specified as a positive integer.

This property controls the number of overlapping samples. If you do not specify DetectionStride, the software sets the stride length to the value of DetectionWindowLength to create nonoverlapping windows.

Threshold

Method for computing the detection threshold, specified as one of these:

  • "kSigma" — Standard deviation of the normalized anomaly scores. The parameter k determines the threshold within the standard deviation levels that identifies an anomaly. The value of k is specified by ThresholdParameter.

  • "contaminationFraction" — Percentage of anomalies within a specified fraction of windows, measured over the entire training set. The fraction value is specified by ThresholdParameter.

  • "max" — Maximum window loss measured over the entire training data set and multiplied by ThresholdParameter.

  • "mean" — Mean window loss measured over the entire training data set and multiplied by ThresholdParameter.

  • "median" — Median window loss measured over the entire training data set and multiplied by ThresholdParameter.

  • "manual" — Manual detection threshold value based on Threshold.

  • "customFunction" — Custom detection threshold method based on ThresholdFunction.

If you specify ThresholdMethod, you can also specify ThresholdParameter, Threshold, or ThresholdParameter. The available threshold parameter depends on the specified detection method.

This property can be set only during object creation and, after training, by using the updateDetector function.

Detection threshold, specified as a positive scalar. The source of the Threshold value depends on the setting of ThresholdMethod.

  • If ThresholdMethod is "manual", you set the value.

  • If ThresholdMethod is "customFunction", the function specified in ThresholdFunction computes the value.

  • For other values of ThresholdMethod, specify ThresholdParameter as the input to the specified method. The software uses this method to compute the threshold value.

This property can be set only during object creation and, after training, by using the updateDetector function.

Parameter for determining the detection threshold, specified as a numeric scalar.

The way you specify ThresholdParameter depends on the specified value for ThresholdMethod. This list describes the specification of ThresholdParameter for each possible value of ThresholdMethod.

  • "kSigma" — Specify ThresholdParameter as a positive numeric scalar. If you do not specify ThresholdParameter, the detector sets the threshold to 3.

  • "contaminationFraction"— Specify ThresholdParameter as a as a nonnegative scalar less than 0.5. For example, if you specify "contaminationFraction" as 0.05, then the threshold is set to identify the top 5% of the anomaly scores as anomalous. If you do not specify ThresholdParameter, the detector sets the threshold to 0.01.

  • "max", "mean", or "median" — Specify ThresholdParameter as a positive numeric scalar. If you do not specify ThresholdParameter, the detector sets the threshold to 1.

  • "customFunction" or "manual"ThresholdParameter does not apply.

This property can be set only during object creation and, after training, by using the updateDetector function.

Function to compute custom detection threshold, specified as a function handle. This property applies only when ThresholdMethod is specified as "customFunction".

  • The function must have two inputs:

    • The first input is a vector of scalar window anomaly scores.

    • The second input is a vector representing all point-level anomalies.

    For example, suppose that the value of detectionWindowLength is 10, the value of detectionStride is set to be nonoverlapping, and the time series length is 10001. Then the first input vector has a length of 1000 and the second input vector has a length of 10000.

  • The function must return a positive scalar corresponding to the detection threshold.

This property can be set only during object creation and, after training, by using the updateDetector function.

Model

Number of convolutional layers in the downsampling section of the model, specified as a positive integer.

Filter size of each convolutional layer in the VAE network, specified as a positive integer or integer vector. The value of NumDownsampleLayers determines how many convolutional layers the network contains.

Number of filters in each convolutional layer for the VAE network, specified as a positive integer.

Dimensionality of the compressed representation of the input signal by the VAE model, specified as a positive integer. This value impacts the ability of the VAE model to capture the most important features when reconstructing the input data.

Number of hidden units in the LSTM layers, specified as an integer row vector. The length of this vector determines the number of LSTM layers in the LSTM model.

Dropout probability used to avoid overfitting, specified as a nonnegative numeric scalar less than 1. All convolution layers share the same dropout probability.

Normalization

Normalization technique for training and testing, specified as "zscore", "range", or "off".

Read-Only

This property is read-only.

Training status, represented as 0 (false) or 1 (true). After you train the detector, IsTrained is equal to 1.

This property is read-only.

Deep network layer structure, represented as a 1-by-3 cell array, with one structure for the encoder, and one structure for each of the two decoders.

This property is read-only.

Deep learning network, represented as a 1-by-3 cell array. Each cell contains a dlnetwork, with one network for the encoder and one network for each of two decoders.

Object Functions

trainTrain anomaly detector and obtain detection threshold
detectDetect anomalies in time series using trained detector model
plotPlot detected anomalies and anomaly scores in time series
plotHistogramPlot histogram of anomaly scores and detection threshold
updateDetectorUpdate settings of a trained anomaly detector and recompute detection threshold

References

[1] Lin, Shuyu, Ronald Clark, Robert Birke, Sandro Schonborn, Niki Trigoni, and Stephen Roberts. “Anomaly Detection for Time Series Using VAE-LSTM Hybrid Model.” In ICASSP 2020 - 2020 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP), 4322–26. Barcelona, Spain: IEEE, 2020. https://doi.org/10.1109/ICASSP40776.2020.9053558.

Version History

Introduced in R2025a