Main Content

UsadDetector

Detect time series anomalies using unsupervised dual-encoder network

Since R2025a

Description

The UsadDetector object uses a deep learning network architecture with dual encoders 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 usAD function.

By comparing reconstructed values with observed data within a detection window, the USAD detector identifies anomalies as significant deviations from expected patterns. You can control the sensitivity of the detector by modifying a set of threshold properties. You can also adjust two sensitivity parameters associated with the dual encoders.

Creating a UsadDetector object is the first step in a design workflow that includes creating, 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 UsadDetector object by using the usAD 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 scalar.

Setting the value of ObservationWindowLength also sets the value of the detection window length.

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 ObservationWindowLength to create nonoverlapping windows.

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 ObservationWindowLength 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

Sensitivity coefficient for the first autoencoder, specified as a positive scalar. This parameter balances the reconstruction loss of the first autoencoder and, in doing so, influences the sensitivity to anomalies.

Sensitivity coefficient for the second autoencoder, specified as a positive scalar. This parameter balances the reconstruction loss of the second autoencoder and, in doing so, refines anomaly detection by capturing subtle deviations.

Normalization

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

Read-Only

This property is read-only.

Length of the detection window for each time series segment, represented as the same value as ObservationWindowLength.

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.

This property is read-only.

Output size, represented as the vector [128 64 32]. The output size indicates the number of neurons in the fully connected layers for the encoder. The decoder uses the reverse order, [32 64 128], to reconstruct the data.

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] Audibert, Julien, Pietro Michiardi, Frédéric Guyard, Sébastien Marti, and Maria A. Zuluaga. “USAD: UnSupervised Anomaly Detection on Multivariate Time Series.” In Proceedings of the 26th ACM SIGKDD International Conference on Knowledge Discovery & Data Mining, 3395–3404. Virtual Event CA USA: ACM, 2020. https://doi.org/10.1145/3394486.3403392.

Version History

Introduced in R2025a