TimeSeriesRRCForestDetector

Detect subsequence anomalies in time series using a robust random cut forest algorithm

Since R2026a

Description

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

The TimeSeriesRRCForestDetector object implements robust random cut forest algorithm to implement a detector model capable of being trained to detect subsequence anomalies in time series data using only nominal data.

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

Creating a TimeSeriesRRCForestDetector 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 functions this workflow uses, see Object Functions.

Creation

Create a timeSeriesRRCForestDetector object by using the timeSeriesRrcforestAD function.

Properties

Input

NumChannels — Number of input channels

positive integer

Number of input channels in each time series, represented as a 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 do not specify DetectionStride when you created the detector, the software sets the stride length to the value of detectionWindowLength to create non-overlapping windows.

This property is read-only after object creation.

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.

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.

Robust Random Cut Forest Model Options

NumLearners — Number of trees in the forest

100 (default)

Number of trees in the robust random cut forest, represented as a positive integer.

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

NumObservationsPerLearner — Number of observation for each robust random cut 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 robust random cut tree, represented as a positive integer greater than or equal to 3.

The robust random cut 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.

CollusiveDisplacement — Collusive displacement calculation method

"maximal" (default) | "average"

Collusive displacement calculation method, represented as "maximal" or "average".

The detector finds the maximum change ("maximal") or the average change ("average") in model complexity for each tree, and computes the collusive displacement (anomaly score) for each observation.

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] Guha, Sudipto, N. Mishra, G. Roy, and O. Schrijvers. "Robust Random Cut Forest Based Anomaly Detection on Streams," Proceedings of The 33rd International Conference on Machine Learning 48 (June 2016): 2712–21.

[2] Bartos, Matthew D., A. Mullapudi, and S. C. Troutman. "rrcf: Implementation of the Robust Random Cut Forest Algorithm for Anomaly Detection on Streams." Journal of Open Source Software 4, no. 35 (2019): 1336.

Version History

Introduced in R2026a