usAD

Create anomaly detector model that uses unsupervised dual-encoder network to detect anomalies in time series

Since R2025a

collapse all in page

Syntax

detector = usAD(numChannels)
detector = usAD(numChannels,Name=Value)

Description

detector = usAD(numChannels) creates a UsadDetector model with numChannels channels for each time series input to the detector.

After you create the detector model, you can train, test, and modify it to obtain the level of performance you require. For more information about the anomaly detector workflow, see Detecting Anomalies in Time Series Using Deep Learning Detector Models.

detector = usAD(numChannels,Name=Value) sets additional options using one or more name-value arguments.

For example, detector = usAD(3,alpha=0.8) creates a detector model for data containing three input channels and sets the alpha sensitivity value to 0.8.

Input Arguments

collapse all

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

Name-Value Arguments

expand all

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.

Example: detector = usAD(3,alpha=0.8) sets the alpha sensitivity value to 0.8.

Window

expand all

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

expand all

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.

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.

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 you specify 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.

Function for computing a custom detection threshold, specified as a function handle. This argument 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.

Model

expand all

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

expand all

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

Output Arguments

collapse all

Anomaly detector model, returned as a UsadDetector object.

Version History

Introduced in R2025a

See Also

| | | | |

Topics