TimeSeriesIForestDetector

Detect subsequence anomalies in time series using an isolation forest algorithm

Since R2026a

Description

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

The TimeSeriesIForestDetector object implements an isolation forest algorithm within a detector model capable of being trained to detect subsequence anomalies in time series data using only nominal data.

TimeSeriesIForestDetector provides a time series version, for outlier point and subsequence detection, of the IsolationForest detector in Statistics and Machine Learning Toolbox™.

Creating a TimeSeriesIForestDetector model is the first step in a workflow that includes training the detector with normal data, testing the detector with anomalous data, and validating the model by visualizing detection effectiveness on anomalous data using plotting functions. To improve detection performance, you can use updateDetector to change certain properties, such as threshold properties, by updating the trained model without retraining. To change other properties, you must create a new detector object and specify the new properties using name-value arguments. You cannot modify detector properties using dot notation.

For more information on the Isolation Forest algorithm on which TimeSeriesIForestDetector is based, see Anomaly Detection with Isolation Forest.

For more information on the functions this workflow uses, see Object Functions.

Creation

Create a TimeSeriesIForestDetector object by using the timeSeriesIforestAD function.

Properties

Input

NumChannels — Number of input channels

positive integer

Number of input channels in each time series, represented as positive integer. All time series inputs must have the same number of channels.

This property is read-only after object creation.

Window

WindowLength — Length of detection window

10 (default) | positive integer scalar

Window length of each time series segment, represented as a positive integer scalar.

This property is read-only after object creation.

TrainingStride — Stride length

positive integer

Stride length of sliding window in detection stage, represented as a positive integer. TrainingStride controls the number of overlapped samples during training. If you do not specify TrainingStride, the software sets the stride length to the value of DetectionStride to create non-overlapping windows.

This property is read-only after object creation.

DetectionStride — Detection Stride length

positive integer

Stride length of sliding window in detection stage, represented as a positive integer. DetectionStride controls the number of overlapped samples. If you did not specify DetectionStride when creating the detector using timeSeriesIforestAD, the detection stride length is equal to the value of detectionWindowLength, resulting in non-overlapping windows.

This property can be set only during object creation and, after training, by using updateDetector.

Threshold

ThresholdMethod — Method to compute detection threshold

"kSigma" (default) | "contaminationFraction" | "max" | "mean" | "median" | "manual" | "customFunction"

Method to compute the detection threshold, represented as one of these values, each of which correspond to what the detection threshold is based on:

• "kSigma" — Standard deviation of the normalized anomaly scores. The parameter k determines the threshold within the standard deviation levels that identifies an anomaly. The value of k is specified by ThresholdParameter.

• "contaminationFraction" — Percentage of anomalies within a specified fraction of windows, measured over the entire training set. The fraction value is specified by ThresholdParameter.

• "max" — Maximum window loss measured over the entire training data set and multiplied by ThresholdParameter

• "mean" — Mean window loss measured over the entire training data set and multiplied by ThresholdParameter

• "median" — Median window loss measured over the entire training data set and multiplied by ThresholdParameter

• "manual" — Manual detection threshold value based on Threshold.

• "customFunction" — Custom detection threshold method based on ThresholdFunction.

If you specify ThresholdMethod, you can also specify ThresholdParameter, Threshold, or ThresholdParameter. The available threshold parameter depends on the specified detection method.

This property can be set only during object creation and, after training, by using updateDetector.

Threshold — Anomaly score used to detect anomalies

1 (default) | positive scalar

Anomaly score used to detect anomalies, represented as a positive scalar. The source of the Threshold value depends on the setting of ThresholdMethod.

• If ThresholdMethod is "manual", you set the value.

• If ThresholdMethod is "customFunction", the function represented as in ThresholdFunction computes the value.

• For other values of ThresholdMethod, use ThresholdParameter to specify the detection threshold.

This property can be set only during object creation and, after training, by using updateDetector.

ThresholdParameter — Parameter used for determining threshold

numeric scalar

Parameter used for determining the detection threshold, represented as a numeric scalar.

The way you specify ThresholdParameter depends on the specified value for ThresholdMethod. The following list describes the specification of ThresholdParameter for each possible value of ThresholdMethod

• "kSigma" — Specify ThresholdParameter as a positive numeric scalar. If you do not specify ThresholdParameter, the detector sets the threshold to 3.

• "contaminationFraction"— Specify ThresholdParameter as a as a nonnegative scalar less than 0.5. For example, if you specify "contaminationFraction" as 0.05, then the threshold is set to identify the top 5% of the anomaly scores as anomalous. If you do not specify ThresholdParameter, the detector sets the threshold to 0.01.

• "max", "mean", or "median" — Specify ThresholdParameter as a positive numeric scalar. If you do not specify ThresholdParameter, the detector sets the threshold to 1.

• "customFunction" or "manual" — ThresholdParameter does not apply.

This property can be set only during object creation and, after training, by using updateDetector.

ThresholdFunction — Function to compute detection threshold

function handle

Function to compute custom detection threshold, represented as a function handle. This argument applies only when ThresholdMethod is represented as "customFunction".

• The function must have one input and one output.

  • The input must be the vector of the anomaly scores.

  • The output must contain a positive scalar corresponding to the detection threshold.

This property can be set only during object creation and, after training, by using updateDetector.

NumObservationsPerLearner — Number of observation for each isolation tree

min(N,256), where N is the number of training observations (default) | positive integer greater than or equal to 3

Number of observations to draw from the training data, without replacement, for each isolation tree, represented as a positive integer greater than or equal to 3.

The isolation forest algorithm performs well with a small value for NumObservationsPerLearner, because using a small sample size helps to detect dense anomalies and anomalies close to normal points. However, you need to experiment with the sample size if N, the number of training observations, is small.

Feature Extraction

FeatureExtraction — Enable feature extraction

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

Enable feature extraction option, represented as 1(true) or 0(false).

• When FeatureExtraction is enabled, the software extracts statistical features to use during training. Extracted features are generally cleaner and more meaningful than raw data, but the extraction process can be computationally expensive.

• When FeatureExtraction is disabled, the training process uses only raw data points that are combined into a single flattened vector. Raw data is likely to be noisier and include random disturbances. However, if you have a relatively small number of signals and they already represent useful features, then the computational cost FeatureExtraction may not be worth the benefit.

This property can be set only during object creation.

Isolation Forest Model Options

NumLearners — Number of trees in the forest

100 (default)

Number of trees in the isolation forest, specified as a positive integer.

The average path lengths used by the isolation forest algorithm to compute anomaly scores usually converge well before growing 100 isolation trees for both normal points and anomalies.

NumObservationsPerLearner — Number of observation for each isolation tree

min(N,256), where N is the number of training observations (default) | positive integer greater than or equal to 3

Number of observations to draw from the training data, without replacement, for each isolation tree, specified as a positive integer greater than or equal to 3.

The isolation forest algorithm performs well with a small value for NumObservationsPerLearner, because using a small sample size helps to detect dense anomalies and anomalies close to normal points. However, you need to experiment with the sample size if N, the number of training observations, is small.

NumLearners — Number of trees in the forest

100 (default)

Number of trees in the isolation forest, specified as a positive integer.

The average path lengths used by the isolation forest algorithm to compute anomaly scores usually converge well before growing 100 isolation trees for both normal points and anomalies.

NumObservationsPerLearner — Number of observation for each isolation tree

min(N,256), where N is the number of training observations (default) | positive integer greater than or equal to 3

Number of observations to draw from the training data, without replacement, for each isolation tree, specified as a positive integer greater than or equal to 3.

The isolation forest algorithm performs well with a small value for NumObservationsPerLearner, because using a small sample size helps to detect dense anomalies and anomalies close to normal points. However, you need to experiment with the sample size if N, the number of training observations, is small.

Normalization

Normalization — Normalization technique

"zscore" (default) | "range" | "off"

Normalization technique for training and testing, represented as "zscore", "range", or "off".

• "range" — Rescale the data range to [0,1].

• "zscore" — Distance from a data point to the mean in terms of standard deviation

• "off" — Do not normalize the data.

The data to which Normalization is applied depends whether FeatureExtraction is enabled.

• If FeatureExtraction is enabled, then normalization is applied to the features.

• If FeatureExtraction is disabled, then normalization is applied to the raw data.

If all the input data values are the same (the data is constant), then normalization returns zeros. For example, if X is a vector containing all equal values, then normalize(X) returns a vector of the same size that contains all zeros.

For more information on normalization methods, see normalize.

This property is read-only after object creation.

Read-Only Properties

IsTrained — Training status

Read-only: 0 (false) | 1 (true)

This property is read-only.

Training status, represented as 0 (false) or 1 (true). Once you train the detector, IsTrained is equal to 1.

Object Functions

train	Train time series machine learning anomaly detector and obtain detection threshold
detect	Detect anomalies in time series using a trained time series machine learning detector model
plot	Plot detected anomalies and anomaly scores generated from trained machine learning anomaly detectors
plotHistogram	Plot histogram of anomaly scores and detection threshold for trained machine learning anomaly detector
updateDetector	Update settings of a trained time series machine learning anomaly detector and recompute detection threshold

References

[1] Liu, F. T., K. M. Ting, and Z. Zhou. "Isolation Forest," 2008 Eighth IEEE International Conference on Data Mining. Pisa, Italy, 2008, pp. 413-422.

Version History

Introduced in R2026a