timeSeriesAnomalyMetrics

Compute specialized evaluation metrics for time series anomaly detection

Since R2026a

Syntax

evalmetrics = timeSeriesAnomalyMetrics(Predictions,[],Scores)

evalmetrics = timeSeriesAnomalyMetrics(Predictions,Labels)

evalmetrics = timeSeriesAnomalyMetrics(___,Name=Value)

Description

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

Time-series anomaly detection metrics evaluate subsequence anomalies, where the anomalous behavior occurs over a series of consecutive points, rather than at a single point. These evaluation metrics provide additional granularity and insight into the performance of a detector.

The function handles both supervised and unsupervised evaluation.

• Unsupervised means that the time series data is not labeled to reflect ground truth.

• Supervised means that the time series data does contain labels that provide ground truth.

evalmetrics = timeSeriesAnomalyMetrics(Predictions,[],Scores) computes unsupervised evaluation metrics without incorporating knowledge of ground truth.

Use this syntax when you have no labeled data ground truth data. The [] element in the syntax indicates that there are no values in Labels.

evalmetrics = timeSeriesAnomalyMetrics(Predictions,Labels) uses supervised evaluation metrics for detection results that incorporate the ground truth that Labels contains.

evalmetrics = timeSeriesAnomalyMetrics(___,Name=Value) specifies additional options using name-value arguments. You can specify these options with any of the previous input-argument combinations.

Input Arguments

Predictions — Predicted anomaly labels

logical vector | cell array of logical vectors

Predicted anomaly labels, specified as a logical vector or cell array of logical vectors indicating predicted anomalies.

• A label of 0 indicates no anomaly.

• A label of 1 indicates an anomaly.

When you test a detector using detect, the function returns a results table that includes window anomaly labels that you can use for Predictions.

Labels — ground-truth anomaly labels

[] | vector | cell array of vectors | cell array of logical vectors

Ground-truth anomaly labels, specified as [], a vector, or a cell array of vectors. The NormalClassLabel name-value argument defines what label value represents normal data. Typically, but not always, that value is 0

• A label corresponding to NormalClassLabel indicates no anomaly.

• A label with any other value than NormalClassLabel indicates an anomaly.

If you are using unsupervised metrics, and therefore are not using ground truth labels, you must set Labels to [] in the calling syntax.

Scores — Anomaly scores

numeric vector | cell array of numeric vectors

Anomaly scores to use when computing unsupervised metrics, specified as a vector or a cell array of vectors. These scores can be an output of the detect function that you use to assess the detection accuracy of an anomaly detector after you train it.

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: For example, to change the evaluation method for unsupervised evaluation from standard to point-adjusted, useevalmetrics = timeSeriesAnomalyMetrics(predictions,[],Scores,Method="point-adjusted")

NormalClassLabel — Label or labels representing normal (non-anomaly) class

0 (default) | scalar | vector

Label or labels representing the normal (non-anomaly) class, specified as a scalar or vector of numeric values or strings. The software uses this value to classify predicted labels and ground truth labels when computing evaluation metrics. Any label that does not match an element in NormalClassLabel represents an anomaly.

Method — Evaluation method

"standard" (default) | "point-adjusted"

Evaluation method, specified as "standard" or "point-adjusted".

• When Method is "standard", the method evaluates each data point individually, rather than as a subsequence.

• When Method is "point-adjusted", the method evaluates data points as a sequence when the number of points that are anomalous exceeds the limit in MinAnomalyFraction in the period of time bounded by DetectionDelay.

MinAnomalyFraction — Minimum anomaly fraction

0 (default) | numeric scalar between [0 1]

Minimum fraction of points in a subsequence that must be detected as anomalies for the point-adjusted method to label the entire subsequence as anomalous, specified as 0 or a numeric scalar that is between [0 1]. When MinAnomalyFraction is 0, any single-point anomaly detection is sufficient to label the subsequence as anomalous.

DetectionDelay — Maximum allowed detection delay

inf (no limit) (default) | positive numeric scalar

Maximum allowed detection delay when using the point-adjusted method. If you do not set this argument, there is no limit to allowed detection delay.

Aggregation — Option to aggregate metrics across multiple time series

false (default) | true

Option to aggregate metrics across multiple time series, specified as false or true.

This argument is used for cell array inputs, where each cell contains data for one time series.

• When Aggregation is false, the function computes metrics separately for each time series.

• When Aggregation is true, the function concatenates the time series and evaluates the metrics on the concatenated data.

Output Arguments

evalmetrics — Detector evaluation metrics

table

Detector evaluation metrics, returned as an n-by-m table, where n is the number of input channels and the m is the number of metric types.

For unsupervised evaluation, the table contains these metrics.

Unsupervised Evaluation Metrics
FractionofAnomalies	Fraction of points predicted as anomalies
KLdivergence	KL divergence between normal and anomaly score
AvgAnomalySeparation	Average separation between anomaly and normal
NormalScoresRange	Range of scores for normal data points

For unsupervised evaluation, the table contains these metrics.

Supervised Evaluation Metrics
Accuracy	Overall classification accuracy
Precision	Precision of anomaly detection
Recall	Recall (sensitivity) of anomaly detection
F1Score	Range of scores for normal data points
FalsePositiveRate	Harmonic mean of precision and recall
ConfusionMatrix	Confusion matrix for classification results
AccuracyPerSubClass	Per-class accuracy

For more information on how to interpret these metrics, see Interpret Evaluation Metrics for Time Series Anomaly Detectors.

References

[1] Kim, Siwon, Kukjin Choi, Hyun-Soo Choi, Byunghan Lee, and Sungroh Yoon. “Towards a Rigorous Evaluation of Time-Series Anomaly Detection.” Proceedings of the AAAI Conference on Artificial Intelligence 36, no. 7 (2022): 7194–201. https://doi.org/10.1609/aaai.v36i7.20680.

Version History

Introduced in R2026a