train

Train deep learning anomaly detector and obtain detection threshold

Since R2025a

Syntax

detector = train(detector,trainData)

detector = train(detector,trainData,Name=Value)

Description

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

The train function trains deep learning anomaly detectors as part of the time series anomaly detection workflow.

The deep learning anomaly detectors use either training options from the option set in trainingOptions (Deep Learning Toolbox) that Deep Learning Toolbox™ provides or standalone name-value options in train that reproduce the essential functionality of the corresponding trainingOptions options. These options include items like Solver, MaxEpochs and Verbose, as well as GPU and parallel CPU processing.

detector = train(detector,trainData) trains the anomaly detector detector with a training data set trainData that contains only normal data, and not any anomalous data. This syntax uses default options.

When the ThresholdMethod property for detector is set to any method but "manual", train also obtains the detection threshold that the detector uses to identify an anomaly.

You can use train to train a newly created detector or continue the training of a previously trained detector.

For an example of using train as part of the detector development workflow, see Train and Test TCN Anomaly Detector.

For training deep learning detectors, this function requires Deep Learning Toolbox.

detector = train(detector,trainData,Name=Value) specifies the training options explicitly, rather than through trainingOptions. The options you can set depend on the detector model you are training.

• TcnDetector and DeepantDetector accept only a trainingOptions (Deep Learning Toolbox) option set that you configure separately.

• UsadDetector accepts certain training options as individual name-value arguments.

• VaelstmDetector accepts both a TrainingOptions set and individual name-value arguments.

Input Arguments

All Deep Learning Detectors

detector — Anomaly detector model

TcnDetector object | DeepantDetector object | UsadDetector object | VaelstmDetector object

Anomaly detector model, specified as a TcnDetector, DeepantDetector, UsadDetector, or VaelstmDetector object.

trainData — Training dataset

matrix | timetable | cell array

Training data set used to train the detector model within a detector object, specified as a matrix, a cell array, or a timetable. trainData must contain only normal data, and not any anomalous data.

When trainData contains m sets of signals, each of which contain n 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: detectorUs = train(detectorUs,MaxEpochs=100) sets the value of MaxEpochs to 100 when training the UsadDetector model detectorUs.

Note: in the value summaries below, all default values correspond to the TrainingOptionsADAM (Deep Learning Toolbox) default values. If you choose an alternative solver, see TrainingOptionsRMSProp (Deep Learning Toolbox) or TrainingOptionsSGDM (Deep Learning Toolbox) for default values.

Models that Use Deep Learning Training Options

TrainingOpts — Training options

TrainingOptionsADAM object (default) | TrainingOptionsSGDM object | TrainingOptionsRMSProp object

Training options, specified as a TrainingOptionsADAM (Deep Learning Toolbox), TrainingOptionsRMSProp (Deep Learning Toolbox), or TrainingOptionsSGDM (Deep Learning Toolbox) object returned by the trainingOptions (Deep Learning Toolbox) function.

This option is valid for TCN, DeepAnT, and the LSTM section of VAE-LSTM detector models only. For the VAE section of VAE-LSTM models, see VAE-MaxEpochs and VAE-InitialLearnRate.

The detector uses the following options within the training options set. The default values depend on the solver you specify when you first create the option set.

• Solver

• MiniBatchSize

• MaxEpochs

• InitialLearnRate

• Verbose

• Plots

• ExecutionEnvironment

To perform the modifications, specify them in the trainingOptions command. For example, to create a TrainingOptionsADAM option set, change the maximum number of epochs, MaxEpochs, from 30 to 100, and use a GPU if one is available, use the following commands.

trainopts = trainingOptions("adam", MaxEpochs=100,ExecutionEnvironment="auto")
detectorTcn = train(detector_tcn,trainData,trainingOpts=trainopts)

If you do not specify trainingOpts, the software uses the default TrainingOptionsADAM (Deep Learning Toolbox) option set, but with the LearnRateSchedule option set to "piecewise".

Models that Use Standalone Training Options (USAD Only)

MiniBatchSize — Size of mini-batch

128 (default) | positive integer

Size of the mini-batch to use for each training iteration, specified as a positive integer. A mini-batch is a subset of the training set that is used to evaluate the gradient of the loss function and update the weights. For more information, see the 'MiniBatchSize' description in trainingOptions (Deep Learning Toolbox)

MaxEpochs — Maximum number of epochs

30 (default) | positive integer

Maximum number of epochs (full passes of the data) to use for training, specified as a positive integer.

InitialLearnRate — Initial learning rate

positive scalar

Initial learning rate used for training, specified as a positive scalar.

If the learning rate is too low, then training can take a long time. If the learning rate is too high, then training might reach a suboptimal result or diverge.

Verbose — Flag to display training progress information

1 (true) (default) | 0 (false)

Flag to display training progress information, specified as 1 (true) or 0 (false).

The content of the verbose output depends on the solver that you use. For more information, see the 'Verbose' description in trainingOptions (Deep Learning Toolbox).

Plots — Plots to display during detector model training

"none (default) | "training-progress

Plots to display during detector model training, specified as one of these values:

• "none" — Do not display plots during training.

• "training-progress" — Plot training progress.

The contents of the plot depends on the solver that you use. For more information, see the 'Plots' description in trainingOptions (Deep Learning Toolbox).

ExecutionEnvironment — Option for using CPU and GPU

"auto" (default) | "cpu" | "gpu" | "multi-gpu"

Option for using GPU and CPU, specified as "auto", "cpu", "gpu", or "multi-gpu".

This argument is similar to the ExecutionEnvironment argument in trainingOptions (Deep Learning Toolbox).

• "auto" — Use the GPU if one is available, or if not, the CPU.

• "cpu" — Use the CPU.

• "gpu" — Use the GPU.

• "multi-gpu" — Use parallel processing on the GPU array.

Example: detectorUsad = train(detectorUsad,trainData,ExecutionEnvironment="cpu") uses the CPU regardless of whether a GPU is available.

Models That Use Both Deep Learning and Standalone Training Options (VAE-LSTM)

VaeMaxEpochs — Maximum number of epochs for VAE training

10 (default) | positive integer

Maximum number of epochs (full passes of the data) to use for VAE-model training, specified as a positive integer.

VaeInitialLearnRate — Initial learning rate for VAE training

positive scalar

Initial learning rate used for VAE training, specified as a positive scalar.

If the learning rate is too low, then training can take a long time. If the learning rate is too high, then training might reach a suboptimal result or diverge.

The LSTM portion of VAE-LSTM Models uses Deep Learning TrainingOpts.

Output Arguments

detector — Trained deep learning anomaly detector

TcnDetector object | DeepantDetector object | UsadDetector object | VaelstmDetector object

Trained deep learning anomaly detector, returned as a trained TcnDetector, DeepantDetector, UsadDetector, or VaelstmDetector object.

Extended Capabilities

Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The train function supports GPU arrays when you train any deep learning detector model. To specify GPU processing, see ExecutionEnvironment (USAD model) or TrainingOpts (TCN, VAE-LSTM, or DeepAnt model)

You cannot use GPU processing for machine learning detector models.

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox)

Version History

Introduced in R2025a

R2026a: GPU capability available for all deep learning time series anomaly detector models

GPU capability added for UsadDetector and VaelstmDetector detectors.

R2026a: Functionality moved to support package

Functionality moved to Time Series Anomaly Detection for MATLAB^® support package.