detect

R2026b

Detect anomalies in time series using a trained time series machine learning detector model

Since R2026a

collapse all in page

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 machine learning 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. You can specify whether detectionResults returns these labels at the sample, window, or member level.

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

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

Input Arguments

collapse all

All Detectors

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. Each individual time series within data represents an independent member of the data file.

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

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

All Machine Learning Detectors

expand all

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

  • When Resolution is specified as "window", detect applies anomaly labels only at the window level and returns them in a cell array.

  • When Resolution is specified as "sample", detect uses the option specified in LabelConversionMethod to perform anomaly labeling at the sample level and returned in a cell array of tables.

  • When Resolution is specified as "member", detect performs anomaly labeling at the member level — that is, on the set of time-series data within one cell element of data, and returns the results in a table that contains a row for each member. Member-level resolution provides a single score for each member of the detection data, concisely indicating which members detect considers normal and which members detect flags as anomalous.

    If, for example, the member contains the time-series data for a specific machine within a set of machines, that machine is labeled as performing anomalously.

    Use the name-value argument AnomalousWindowPercentage to set the sensitivity of the member-level detection to the percentage of anomalous windows within the member.

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 an 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 an 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.

Minimum percentage level for flagging member-level anomalies, specified as a numeric percent value from 0 to 100. detect uses AnomalousWindowPercentage only when Resolution is equal to "member".

The value of AnomalousWindowPercentage controls the sensitivity of detect to the number of anomalous windows. A value of 0 is the most sensitive, and a value of 100 is the least sensitive.

The following list describes the relationship between each of a selection of possible percentage settings and its impact on sensitivity of the anomaly reporting.

  • 0 — A single anomalous window score within the member. This is the most sensitive setting.

  • 10 — At least 10% of windows must be anomalous. This value is the default setting. It provides robustness to sporadic false positives.

  • 50 — At least 50% of windows must be anomalous. With this setting, detect flags member-level anomalies only in the presence of sustained high window scores.

  • 100 — All windows must be anomalous.

Dependencies

detect uses AnomalousWindowPercentage only when Resolution is equal to "member".

Output Arguments

collapse all

Detection results that contain the anomaly labels, anomaly scores, and start indices for detections, returned as one of these:

  • If Resolution is set to "sample", an m-by-1 cell array, where m is the number of test anomaly members. Each cell contains an s -by- 3 table, where s is the number of samples.

  • If Resolution is set to "window", an m-by-1 cell array where each cell contains a w -by-3 table, where w is the number of windows.

  • If Resolution is set to "member", an m-by-3 table that contains the detection results at the member level.

Version History

Introduced in R2026a

expand all

See Also

| | |

Topics