updateDetector

Update settings of a trained anomaly detector and recompute detection threshold

Since R2025a

collapse all in page

Syntax

detector = updateDetector(detector,data)
detector = updateDetector(detector,data,Name=Value)

Description

detector = updateDetector(detector,data) recomputes the threshold of the trained detector detector using the data in data, as long as detector.Threshold is not set to "manual".

Use this syntax when you want to recompute the detection threshold while maintaining the current training and other threshold-related settings. The data data that you use must consist only of only normal data, that is, that contains no known anomalies or anomalous data.

For an example of using train as part of the detector development workflow, see Train and Test TCN Anomaly Detector.

detector = updateDetector(detector,data,Name=Value) sets additional options using one or more Name=Value arguments. These options set the corresponding properties of detector, include thresholding and execution-related properties. The options you can set depend on the detector model you are updating.

The relationship among settings for threshold-related properties are the same as when you first create a detector object. So, for example, if the original detector threshold has been computed statistically and you want to set it manually instead to the value TH, you must specify both ThresholdMethod and Threshold using a command such as detector = updateDetector(detector,data,ThresholdMethod="manual",Threshold=TH).

Input Arguments

collapse all

Trained anomaly detector model, specified as a TcnDetector, DeepantDetector, UsadDetector, or VaelstmDetector object.

Time series data to be used for updating the threshold, specified as a matrix, a cell array, or a timetable. data must consist of only normal data, with no known anomalies or anomalous data.

When data contains m sets of signals, each of which contain n = detector.NumChannels channels, the possible formats are these:

  • n-column matrix that consists of a single multichannel signal (m=1).

  • Cell array with m cells that each contain a matrix that has NumChannels columns.

  • Timetable that contains a single multichannel signal , arranged in one of two possible ways.

    • The n channels are distributed in the columns of a matrix that the timetable contains in a single variable

    • The n channels are represented by n timetable variables that each contain a vector.

    In either case, the timetable must contain finite, increasing, and uniformly sampled time values.

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 = updateDetector(detector,data,ThresholdMethod="manual",Threshold=TH) replaces the computed threshold value for detector to the manual threshold TH.

All Detectors

expand all

Method to compute the detection threshold, specified as one of these values, each of which correspond to what the detection threshold is based on:

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

Anomaly score used to detect anomalies, 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, use ThresholdParameter to specify the detection threshold.

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

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

The way you specify ThresholdParameter depends on the specified value for ThresholdMethod. The following 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 updateDetector.

Function to compute 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 detectionStrides 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 updateDetector.

Stride length of sliding window in detection stage, specified as a positive integer. DetectionStride controls the number of overlapped samples.

Mini-batch size, specified as a positive integer scalar for network detection computations.

TCN and DeepAnt Detector Models Only

expand all

Execution environment that determines what hardware resources the software uses to run the network, specified as "auto", "gpu", or "cpu".

  • "auto" — Use the GPU if it is available, or if not, the CPU.

  • "gpu" — Use the GPU.

  • "cpu" — Use the CPU.

USAD Detector Models Only

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.

Version History

Introduced in R2025a

See Also

| | | | | | |

Topics