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.

The app allows you to specify a label variable with each data set that identifies whether that data represents normal or anomalous data. If your data sets include such labels, in Label variable, specify which column or channel contains them. Also, in Normal class label, specify the label value that represents your normal class, that is, data contains no anomalies. The app converts all labels to logical values during import, with false indicating normal data, and true indicating data that contains an anomaly.

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 an untrained detector, although you do not need 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.

Generally, you can train only detectors that have a status of draft, which Indicates an untrained detector. However, if you modify the parameters in the Configurations panel, you can rerun Train on that detector with the new parameters.

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

Train All — Train all untrained models in the detector list

button

Train all the untrained (draft status) detectors that are listed in the Detectors panel. When you click Train All, the app opens the Multi Detector Training dialog box. In the Detector Selection table, you can customize your list by modifying the selections. The selection list shows both draft and trained detectors, but you cannot select a detector that has already been trained without first modifying one or more of its training parameters.

Click Start to initiate the training. The dialog box displays the training status and, for deep learning detector models only, the loss plot.

Once the training is complete, you can view the results for each detector individually by selecting the detector in the Detectors list.

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 — Export detector and detection results to MATLAB workspace

button

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

The Export button provides two options:

1. Export the detector model.

2. Export the labeled predicted detection results for the detector and the detection data set. You can choose either sample-based or window-based resolution for the labels.

   If you have ground truth labels, you can also choose whether to include them in the export.

Programmatic Use

timeSeriesAnomalyDetector opens the Time Series Anomaly Detector app.

Version History

Introduced in R2026a