injectAnomaly

Inject anomalies defined by one or more anomaly models into a univariate time series

Since R2026a

Syntax

[outTS,outLabels] = injectAnomaly(synthAnom,inTS)

[outTS,labelsOut] = injectAnomaly(___,Name=Value)

Description

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

[outTS,outLabels] = injectAnomaly(synthAnom,inTS) inserts the anomaly or set of anomalies defined by synthAnom. The software injects each anomaly in a separate 10-sample window that starts at a random location within the time series.

Use injectAnomaly, in conjunction with the anomaly models you create with syntheticAnomaly, to provide various types of anomalous data that you can use to validate anomaly detection models.

[outTS,labelsOut] = injectAnomaly(___,Name=Value) sets additional options using name-value arguments. For example, use the following command to set the start of the window to 300 samples and length of the window to 15.

[outTS] = injectAnomaly(synthAnom,inTS,WindowStart=300,WindowLength=15)

Examples

Create and Inject Synthetic Anomaly Models

Create a NoiseAnomaly model that models white noise that has a standard deviation and a mean of 3.0.

noiseanom = syntheticAnomaly("Noise",Type="White",Std=3,Mean = 3.0);

Create a "StuckAtConstant" model that sticks at a custom constant of 1.5.

sacanom = syntheticAnomaly("StuckAtConstant",Type="Custom",Value=1.5);

Combine the anomalies into a vector so that they can be injected together into a time series.

anomvec = [noiseanom sacanom]

anomvec = 
1×2 AnomalyTypes:

 NoiseAnomaly, StuckAtConstantAnomaly

Load and plot the healthy single-variable time series channel1, which serves as the injection target.

load HealthySineWaveU channel1

Plot the time series.

plot(channel1)
title("Healthy Time Series")

Inject the anomalies into channel1. For example repeatability, specify starting positions for the two anomalies.

[channel1_anom,labels] = injectAnomaly(anomvec,channel1,WindowStart=[185 1080]);

The resulting signal is channel1_anom. The labels output identifies where the anomalies are injected.

ianom = find(labels==1);
ianom(1:8)

ans = 8×1

   185
   186
   187
   188
   189
   190
   191
   192

plot(channel1_anom)

The anomalies appear where WindowStart specifies.

Input Arguments

synthAnom — Anomaly model

NoiseAnomaly | BiasAnomaly | DriftAnomaly | PointOutliersAnomaly | vector of anomaly models

Anomaly model that defines the anomaly type and its associated parameters, specified as one of the following objects or a vector that contains multiple objects:

• NoiseAnomaly

• BiasAnomaly

• DriftAnomaly

• PointOutliersAnomaly

If you specify a vector of anomalies and you also want to specify window requirements using the name-value arguments WindowStart and WindowLength, specify these values as vectors also, with each value corresponding to an anomaly model.

Example: [outTS] = injectAnomaly([noiseanom driftanom,inTS) injects both the NoiseAnomaly model noiseanom and the DriftAnomaly model driftanom into the time series inTS.

inTS — input time series

column vector | timetable

Input time series, specified as either a column vector or a timetable.

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: outTS = injectAnomaly(noiseAnom,inTS,WindowStart=250) injects the noise anomaly model noiseAnom into the time series inTS with a window starting at 250 samples.

WindowStart — Sample index at start of injection window

"random" (default) | integer | integer vector

Sample index at start of injection window, specified as "random" or an integer that is less than the length of inTS. If a vector of anomaly models is being injected, then WindowStart is a vector of the start indices that correspond to each anomaly.

WindowLength — Anomaly window length

10 (default) | integer | integer vector

Anomaly window length in samples, specified as an integer. If a vector of anomaly models is being injected, then WindowLength is a vector of the start indices that correspond to each anomaly.

EdgeContinuity — Edge-smoothing option

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

Edge smoothing option on either side of the anomaly, specified as 0(false) or 1(true). When you set this argument, you can control the amount of smoothing with TransitionLength.

TransitionLength — Sample length for edge smoothing

5 (default) | positive integer

Sample length for edge smoothing, specified as a positive integer. When you specify TransitionLength, you must also set EdgeContinuity to 1 (true).

LabelAggregation — Label anomaly locations

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

Label anomaly locations, specified as 1 (true) or 0 (false). When this argument is true, the software records the locations where injected anomalies are present. This information is useful for determining whether anomaly detection identifies injected anomalies accurately.

UseParallel — Use parallel processing option

"off" (default) | "on"

Use parallel processing option, specified as "off" or "on".

Output Arguments

outTS — Output time series

column vector | timetable

Output time series that contains the injected anomaly, returned in the same form as inTS.

outLabels — Anomaly labels

column vector | timetable

Output time series that contains the injected anomaly, returned in the same form as inTS.

Version History

Introduced in R2026a