detect

Detect anomalies in time series using a trained time statistical process control (SPC) detector model

Since R2026a

Syntax

detectionResults = detect(detector,data)

detectionResults = detect(___,Name=Value)

Description

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

detectionResults = detect(detector,data) detects anomalies in the time series data using the trained time series statistical process control anomaly detector detector.

detect calculates the anomaly scores, labels anomalies using the threshold value in the property detector.Threshold, and returns these labels and scores, as well as the window start indices, in detectionResults. A label of 1 indicates an anomaly and a label of 0 indicates normal behavior.

For an example of using detect as part of the detector development workflow, see Train and Test Time Series Statistical Process Control Anomaly Detector.

detectionResults = detect(___,Name=Value) sets additional options using one or more Name=Value arguments. These options include execution-related specifications and the plotting of a histogram.

Input Arguments

detector — Statistical process control anomaly detector model

TimeSeriesSPCDetector object

Anomaly detector model, specified as a TimeSeriesSPCDetector object.

data — Time series data

matrix | timetable | cell array of matrices | cell array of timetables

Time series data to be evaluated for anomalies, specified as a matrix, a timetable, a cell array of matrices, or a cell array of timetables.

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 observation (m=1).

  A sufficiently long single observation can be as effective for training as multiple shorter observations.

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

• Timetable that contains a single multichannel signal observation, 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

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: detectResults = detect(detector,data,Resolution="sample") specifies that anomaly labeling be done at the sample level using the option specified in LabelConversionMethod.

Resolution — Level at which to label anomalies

"window" (default) | "sample"

Level at which to detect anomalies, specified as "window" or "sample".

• When Resolution is specified as "window", anomaly labels are applied only at the window level.

• When Resolution is specified as "sample", detect uses the option specified in LabelConversionMethod to perform anomaly labeling at the sample level.

LabelConversionMethod — Method for scoring and labeling samples

"majorityVoting" (default) | "anomalyPriority" | "normalPriority"

Method for assigning sample-level anomaly scores and for labeling individual samples as anomalous or normal. This option addresses the situation where a sample point is covered by multiple overlapping windows, and the set of windows themselves contain both anomalous and normal designations. This argument is used only when Resolution is set to "sample". The options are:

• "majorityVoting" — The majority vote of overlapping windows determines the label, and the average of the window anomaly scores determines the sample anomaly score. In the case of a voting tie, the method labels the sample as anomalous. This method balances false positives and false negatives.

  "majorityVoting" requires enough overlapping windows for the voting to be meaningful, which increases performance load.

• "anomalyPriority" — The presence of a even a single anomalous window determines that the sample be labeled anomalous and that the anomaly score be set to the maximum window anomaly score.

  This option minimizes false negatives, which represent undetected anomalies. However, it increases the number of false positives, that is, false alarms that must be investigated.

• "normalPriority" — The presence of a even a single normal window determines that the sample be labeled normal and the anomaly score to be set to the average of all overlapping window scores for the sample.

  This method minimizes false positives, but increases the risk of false negatives, that is undetected anomalies.

Output Arguments

detectionResults — Detection results

sample | table | cell array of tables

Detection information for each window or sample, returned as one of these:

• If Resolution is set to "sample", a table consisting of a column of tables that contain the results for each sample.

• If Resolution is set to "window", a table containing a column of tables, one table for each data channel.

  Each table within detectionResults contains the window anomaly labels, anomaly scores, and window start indices for the corresponding channel.

• If the input data is a cell array, a cell array of tables.

Version History

Introduced in R2026a