メインコンテンツ

UsadDetector

Detect time series anomalies using unsupervised dual-encoder network

Since R2025a

Description

Add-On Required: This feature requires the Time Series Anomaly Detection for MATLAB add-on.

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. This detector requires Deep Learning Toolbox™.

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.

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, represented 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, represented 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, represented 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, represented 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, represented as one of these.

  • "kSigma" — Sigma-based standard deviation of the normalized anomaly scores, calculated as mean + k + standard deviation. The parameter k determines how many standard deviations above the mean the threshold is set. 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 that separates the normal anomaly scores from the anomalous anomaly scores, specified as a scalar. During the detection process, the software assigns anomaly labels according to this threshold.

. 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, represented 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, represented as a function handle. This property applies only when ThresholdMethod is specified as "customFunction".

  • The function must have one input and one output.

    • The input must be the vector of the anomaly scores.

    • The output must contain a scalar corresponding to the detection threshold.

For more information about how the detector uses the threshold to detect anomalies, see 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, represented as a positive scalar less than 1. This parameter balances the reconstruction loss of the first autoencoder and, in doing so, influences the sensitivity to anomalies.

The sum of Alpha and Beta must be 1.

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

The sum of Alpha and Beta must be 1.

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

Normalization

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

  • "range" — Rescale the data range to [0,1].

  • "zscore" — Distance from a data point to the mean in terms of standard deviation

  • "off" — Do not normalize the data.

The data to which Normalization is applied depends whether FeatureExtraction is enabled.

  • If FeatureExtraction is enabled, then normalization is applied to the features.

  • If FeatureExtraction is disabled, then normalization is applied to the raw data.

If all the input data values are the same (the data is constant), then normalization returns zeros. For example, if X is a vector containing all equal values, then normalize(X) returns a vector of the same size that contains all zeros.

For more information on normalization methods, see normalize.

This property is read-only after object creation.

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.

Object Functions

trainTrain deep learning anomaly detector and obtain detection threshold
detectDetect anomalies in time series using trained deep learning detector model
plotPlot detected anomalies and anomaly scores generated from deep learning anomaly detectors
plotHistogramPlot histogram of anomaly scores and detection threshold for trained deep learning anomaly detector
updateDetectorUpdate settings of a trained deep learning 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

expand all