Time Series Anomaly Detector

Interactively create, train, test, and tune detectors for detecting anomalous behavior in time series

Since R2026a

Description

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

The Time Series Anomaly Detector app provides an interactive environment for developing anomaly detectors that can detect anomalous behavior in time series.

Using this app, you can:

• Import historical or simulated data

• Select from a variety of detector families, including detectors based on machine learning, deep learning, and statistical process control.

• Train detectors on data with normal behavior, and test the trained detectors on data with anomalous behavior.

• Visualize the source data and the detected anomalies, and view performance metrics.

• Tune your detectors and retrain them in order to improve performance

• Export the detectors you want to keep into your MATLAB^® workspace.

To get started with the app, you must have at least one data set that represents normal behavior data in your MATLAB workspace. Once you have trained the detector, to test your detector, you must have at least one data set that represents anomalous behavior.

For more information about the detector development workflow, see Detecting Anomalies in Time Series.

Open the Time Series Anomaly Detector App

• MATLAB toolstrip: on the Apps tab, under Deep Learning and Machine Learning, click the app icon.

  

• MATLAB command prompt: enter timeSeriesAnomalyDetector.

Examples

• Develop Time Series Anomaly Detector in Time Series Anomaly Detector App
• Prepare Data for Time Series Anomaly Detector Training and Validation
• Interpret Evaluation Metrics for Time Series Anomaly Detectors
• Detecting Anomalies in Time Series

Parameters

Anomaly Detector Tab

New Session — Open a new app session and initiate data importation

button

Open a new app session by clicking New Session. The app opens a data importation window that allows you to load training and testing data from your MATLAB workspace.

Your data can be in the form of matrices, tables, cell arrays of matrices, or cell arrays of tables. All the data items must have the same number of channels, represented by columns. The rows represent the members, and all rows within a data item must be entirely either normal class or anomalous class. Labels are not required but they can be included for more granular metrics.

Training data (normal data) is data that exhibits what you would define as normal behavior. The training data need not be completely clean, and it may contain minor anomalies. However, any anomalies within the training data will be undetectable, as they are classified during training normal behavior.

Testing data (anomalous data contains the type of anomalies that you want your detector to be able to detect. You use this data only for testing and not for training.

You are likely to have much more normal data than anomalous data available.

For more information on formatting your data, see Prepare Data for Time Series Anomaly Detector Training and Validation.

Import Data — Import data into the app

button

Click Import Data to initiate the import process. Doing so opens a dialog box that shows all the compatible data sets in your workspace.

You must import your normal data first. The app uses your first import for performing all the training during your session. When you select your normal data, the Select a data set to import lets you select the columns, or channels that you want to import. When you import training data, you can also specify the validation holdback percentage for training. If your data has labels, you can also specify which column contains your label variable.

Use Add more data sets to create a list of additional data variables. The dialog box lets you specify multiple individually configured data sets. The dialog box also allows you to import the same data set twice. If you do so, the app creates a separate copy of the data variable.

Plot Data — Plot a selected data set

button

Plot an imported data set that is listed in the Data Sets pane. First, select a data set in Data Sets. You can select only one data set at a time. Then, select Plot Data. Doing so results in the opening of the following items, from top to bottom.

• The Plot tab opens in the top toolstrip. This tab lets you select the member to plot and set the normalization method.

• A plot of the data set with plotted using default options

• A Plot Options pane that lets you plot one or more channels of the data set member that appears in the Data section of the Plot tab. If you have labeled anomalies in your data set, Plot Options lets you choose to show these as well.

Detectors — Select and configure detectors to develop

gallery

The Detectors section of the Anomaly Detector tab provides a gallery of detector types to choose from.

• A good starting point is the All Quick-to-Train option, which adds all the detectors that can be trained quickly to the list.

• If you know what detector you want to explore first, find that detector in the gallery.

• Choose a family of detectors. For example, to focus on machine learning detectors, select All ML Detectors.

• Select All to create an instance of every detector

Selecting a detector adds the detector to the detectors pane, but does not automatically trigger the training process. The Draft indicator on a detector indicates that the detector has not yet been trained.

To get more information about a detector, select it. The app provides an overview on the detection technique, what the detector is best suited for, and tuning tips for improving performance.

Selecting a detector also opens the Train results in a Configurations pane that you return to once you have you move forward to training that particular detector.

Train — Train a specific detector model

button

You can initiate the training process whenever you select a detector, although you do not have to. When you select a detector, as described in Detectors, the Train tab opens in the top toolstrip. When this tab is open, you can view the training data set, in the Data and Detector section, and customize the training and model configurations that are adjacent to the detector information pane.

The training configurations differ from detector to detector. Typically, the more intensive the training, the better the performance will be. For more information about the training parameters for a particular detector, see the corresponding function reference page linked in Time Series Anomaly Detectors.

The Model Configurations pane lets you configure key model parameters. For example, if you are configuring a machine learning model, you can set Feature Extraction to true or false. When this parameter is enabled, the app extracts statistical features to use during training. Extracted features are generally cleaner and more meaningful than raw data, but the extraction process can lengthen the training time required.

Once your configuration is complete, in the Train tab, click Train. The app performs the training, and shows the following information.

• The trained detector in the Detectors pane now shows a status of Trained instead of Draft.

• The Train: window shows a histogram of the anomaly score distribution for the detector validation using the training validation data. This is the data that you specified for holdback when you imported the training data. This histogram illustrates the range of anomaly scores associated with normal data. The computed threshold value should bound the histogram on the right.

• A Validation Metrics table shows the evaluation scores, which should all be nominal, that is, 1 for desirable metrics like Precision and 0 for undesirable metrics, like False Positive Rate.

• A confusion chart that shows the predicted vs true class. For training, the only populated quadrant should be the normal/normal quadrant. That is, all the predictions should match the true class.

• A Per Member Metrics shows metrics for each member of the training data set. These should all be nominal.

For more information about the validation metrics and what they represent, see timeSeriesAnomalyMetrics

Detect — Detect anomalies with a trained detector

button

Once you have trained and validated the detector with normal data, you can test the detector to see how it performs against anomalous data. To activate the detection process, in the Detect section of the Train tab, click Detect. This opens the Detect tab.

When the Detect tab is open, first, in the Data and Detector section, you must specify the detection data set (anomalous data) if you have one. If you have just performed training, the data set specification still retains the training data set name (normal data) until you change the name to another data set.

The next step is to click the green Detect button. When you do so, the app tests the detector against the anomalous data and provides a similar output to the training validation, but with the addition of the anomaly detection.

• A histogram of the anomaly score distribution for the detector calculations with the anomalous data. For detection, you expect to see anomaly score bars beyond the threshold.

• A Detection Metrics table shows the evaluation metrics. If no anomalies were detected for a particular member, some of the metrics will be NaNs.

• A confusion chart that shows the predicted vs true class if your data has ground truth labels. .

• A table of detected anomaly locations

• Plots of the detected anomalies for each member, where the detections are highlighted in color.

• Plot of the anomaly scores with an overlay of the threshold values.

Duplicate Detector — Create a copy of existing detector

button

Click Duplicate Detector to create a copy of a current detector and add to the Detectors pane.

Use Duplicate Detector when you want to preserve the current configuration on a detector that you have but continue to experiment with and develop the detector. You can access this button from either the Train tab or the Detect tab. If the detector has been trained, the duplicate retains the training.

Use Add more data sets to create a list of additional data variables. The dialog box lets you specify multiple individually configured data sets. The dialog box also allows you to import the same data set twice. If you do so, the app creates a separate copy of the data variable.

Retrain Detector — Retrain a detector with modified configuration

button

Retrain the detector with different parameters.

Export Detector — Export detector to MATLAB workspace

button

Export the detector to your MATLAB workspace. There you can continue to develop it or integrate it into an anomaly detection scenario.

Programmatic Use

timeSeriesAnomalyDetector opens the Time Series Anomaly Detector app.

Version History

Introduced in R2026a