TimeSeriesLOFDetector

Detect subsequence anomalies in time series using a local outlier factor algorithm

Since R2026a

expand all in page

Description

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

The TimeSeriesLOFDetector object implements a local outlier factor algorithm within a detector model capable of being trained to detect subsequence anomalies in time series data using only nominal data.

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

Creating a TimeSeriesLOFDetector 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 local outlier algorithm on which TimeSeriesLOFDetector is based, see the "More About" section in LocalOutlierFactor in Statistics and Machine Learning Toolbox.

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

Creation

Create a TimeSeriesLOFDetector object by using the timeSeriesLofAD function.

Properties

expand all

Input

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

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

This property is read-only after object creation.

Stride length of sliding window in training stage, specified as a positive integer.

This property is read-only after object creation.

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 timeSeriesLofAD, 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.

Method for computing the detection threshold, represented as one of these.

  • "kSigma" — Sigma-based standard deviation of the normalized anomaly scores, calculated as mean + k + standard deviation. The parameter k determines how many standard deviations above the mean the threshold is set. 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 the updateDetector function.

Feature Extraction

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.

Local Outlier Factor Options

Nearest neighbor search method, represented as "kdtree" or "exhaustive".

  • "kdtree" — This method uses the Kd-tree algorithm to find nearest neighbors. This option is valid when the distance metric (Distance) is one of the following:

    • "euclidean" — Euclidean distance

    • "cityblock" — City block distance

    • "minkowski" — Minkowski distance

    • "chebychev" — Chebychev distance

  • "exhaustive" — This method uses the"exhaustive" search algorithm to find nearest neighbors. This method finds nearest neighbors by computing the distance values from all points in the time series to each point in the neighborhood.

This property is read-only after object creation.

Number of nearest neighbors when SearchMethod is "kdtree", represented as a positive integer.

This property is read-only after object creation.

Distance metric, represented as a string, with possible values listed here.

ValueDescription
"euclidean"

Euclidean distance

"fasteuclidean"

Euclidean distance using an algorithm that usually saves time when the number of elements in a data point exceeds 10. "fasteuclidean" applies only to the "exhaustive" SearchMethod.

"mahalanobis"

Mahalanobis distance — You can specify the covariance matrix for the Mahalanobis distance by using the Cov name-value argument.

"minkowski"

Minkowski distance — You can specify the exponent of the Minkowski distance by using the Exponent name-value argument.

"chebychev"

Chebychev distance (maximum coordinate difference)

"cityblock"

City block distance

"correlation"

One minus the sample correlation between observations (treated as sequences of values)

"cosine"

One minus the cosine of the included angle between observations (treated as vectors)

"spearman"

One minus the sample Spearman's rank correlation between observations (treated as sequences of values)

If you want to use the Kd-tree algorithm (SearchMethod="kdtree"), then Distance must be "euclidean", "cityblock", "minkowski", or "chebychev".

For more information on the various distance metrics, see Distance Metrics.

Example: Distance="fasteuclidean"

This property is read-only after object creation.

Minkowski distance exponent, represented as a positive scalar value. This argument is valid only when Distance is "minkowski".

Example: Exponent=3

This property is read-only after object creation.

Tie inclusion flag indicating whether the software includes all the neighbors whose distance values are equal to the kth smallest distance, represented as logical 0 (false) or 1 (true). If IncludeTies is true, the software includes all of these neighbors. Otherwise, the software includes exactly k neighbors.

Example: IncludeTies=true

Maximum number of data points in the leaf node of the Kd-tree, represented as a positive integer value. This argument is valid only when SearchMethod is "kdtree".

Example: BucketSize=40

This property is read-only after object creation.

Size of the Gram matrix in megabytes, represented as a positive scalar or "maximal". For information about the Gram matrix, see the Algorithms section of lof. The TimeSeriesLOFDetector function can use a Gram matrix when the Distance name-value argument is "fasteuclidean".

When CacheSize is "maximal", TimeSeriesLOFDetector attempts to allocate enough memory for an entire intermediate matrix whose size is MX-by-MX, where MX is the number of rows of the input data, X or Tbl. CacheSize does not have to be large enough for an entire intermediate matrix, but must be at least large enough to hold an MX-by-1 vector. Otherwise, timeSeriesLofAD uses the "euclidean" distance.

If Distance is "fasteuclidean" and CacheSize is too large or "maximal", TimeSeriesLOFDetector might attempt to allocate a Gram matrix that exceeds the available memory. In this case, MATLAB® issues an error.

Example: CacheSize="maximal"

This property is read-only after object creation.

Covariance matrix, represented as a positive definite matrix of scalar values representing the covariance matrix when the function computes the Mahalanobis distance. This argument is valid only when Distance is "mahalanobis".

This property is read-only after object creation.

Normalization

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

This property is read-only.

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

Object Functions

trainTrain time series machine learning anomaly detector and obtain detection threshold
detectDetect anomalies in time series using a trained time series machine learning detector model
plotPlot detected anomalies and anomaly scores generated from trained machine learning anomaly detectors
plotHistogramPlot histogram of anomaly scores and detection threshold for trained machine learning anomaly detector
updateDetectorUpdate settings of a trained time series machine learning anomaly detector and recompute detection threshold

Version History

Introduced in R2026a

See Also

|

Topics