LongShortTermMemoryNetwork

class dtaianomaly.anomaly_detection.LongShortTermMemoryNetwork(window_size: int | Literal['fft', 'acf', 'mwf', 'suss'], error_metric: Literal['mean-absolute-error', 'mean-squared-error'] = 'mean-absolute-error', forecast_length: int = 1, hidden_units: int = 8, num_lstm_layers: int = 1, bias: bool = True, dropout_rate: float = 0.0, stride: int = 1, standard_scaling: bool = True, batch_size: int = 32, data_loader_kwargs: dict[str, any] = None, optimizer: Literal['adam', 'sgd'] = 'adam', learning_rate: float = 0.001, compile_model: bool = False, compile_mode: Literal['default', 'reduce-overhead', 'max-autotune', 'max-autotune-no-cudagraphs'] = 'default', n_epochs: int = 10, loss_function: Literal['mse', 'l1', 'huber'] = 'mse', device: str = 'cpu', seed: int = None)

Use an LSTM to detect anomalies [23].

The Long-Short Term Memory (LSTM) anomaly detector combines a decoder with LSTM layers with a liner layer to forecast the time series, given a subsequence. The anomalies are then detected by measuring the deviation between the forecasted values and the actual observations. The LSTM- decoder reads each subsequence sequentially, and constructs a hidden representation at each time point. The hidden representation at each time step is based on the observations at that time step, but also on the hidden state at the previous step. The LSTM units include learnable gates, which guide the information flow to avoid issues with gradients as faced in RNN networks. Once the complete sequence is processed, the output is fed to a linear layer, which will forecast the data.

The architecture of the LSTM consists of 2 blocks: (1) an LSTM-decoder consisting of one or more LST-layers with multiple LSTM-units, and (2) a single linear layer.

Parameters:

window_sizeint or str

The window size to use for extracting sliding windows from the time series. This value will be passed to compute_window_size().

error_metric{“mean-absolute-error”, “mean-squared-error”}, default=”mean-absolute-error”

The error measure between the reconstructed window and the original window.

forecast_lengthint default=1

The number of time steps the neural network must forecast.

hidden_unitsint, default=8

The number of hidden unit in each LSTM layer.

num_lstm_layersint, default=1

The number of LSTM layers in the LSTM-block.

biasbool, default=True

Whether to use bias weights in each layer of the LSTM block.

dropout_ratefloat in interval [0, 1[, default=0.0

The dropout rate to put on each layer in the LSTM block.

strideint, default=1

The stride, i.e., the step size for extracting sliding windows from the time series.

standard_scalingbool, default=True

Whether to standard scale each window independently, before feeding it to the network.

batch_sizeint, default=32

The size of the batches to feed to the network.

data_loader_kwargsdictionary, default=None

Additional kwargs to be passed to the data loader. For more information, see: https://docs.pytorch.org/docs/stable/data.html.

optimizer{“adam”, “sgd”} or callable default=”adam”

The optimizer to use for learning the weights. If “adam” is given, then the torch.optim.Adam optimizer will be used. If “sgd” is given, then the torch.optim.SGD optimizer will be used. Otherwise, a callable should be given, which takes as input the network parameters, and then creates an optimizer.

learning_ratefloat, default=1e-3

The learning rate to use for training the network. Has no effect if optimize is a callable.

compile_modelbool, default=False

Whether the network architecture should be compiled or not before training the weights. For more information, see: https://docs.pytorch.org/docs/stable/generated/torch.compile.html.

compile_mode{“default”, “reduce-overhead”, “max-autotune”, “max-autotune-no-cudagraphs”}, default=”default”

Method to compile the architecture. For more information, see: https://docs.pytorch.org/docs/stable/generated/torch.compile.html.

n_epochsint, default=10

The number of epochs for which the neural network should be trained.

loss_function{“mse”, “l1”, “huber} or torch.nn.Module, default=”mse”

The loss function to use for updating the weights. Valid options are:

• 'mse': Use the Mean Squared Error loss.

• 'l1': Use the L1-loss or the mean absolute error.

• 'huber': Use the huber loss, which smoothly combines the MSE-loss with the L1-loss.

• torch.nn.Module: a custom torch module to use for the loss function.

devicestr, default=”cpu”

The device on which te neural network should be trained. For more information, see: https://docs.pytorch.org/docs/stable/tensor_attributes.html#torch-device.

seedint, default=None

The seed used for training the model. This seed will update the torch and numpy seed at the beginning of the fit method.

Attributes:

window_size_int

The effectively used window size for this anomaly detector.

optimizer_torch.optim.Optimizer

The optimizer used for learning the weights of the network.

neural_network_torch.nn.Module

The PyTorch network architecture.

See also

BaseNeuralForecastingDetector

Use a neural network to forecast the time series, and detect anomalies by measuring the difference with the actual observations.

Examples

>>> from dtaianomaly.anomaly_detection import LongShortTermMemoryNetwork
>>> from dtaianomaly.data import demonstration_time_series
>>> x, y = demonstration_time_series()
>>> lstm = LongShortTermMemoryNetwork(10, seed=0).fit(x)
>>> lstm.decision_function(x)
array([0.354334  , 0.354334  , 0.28025536, ..., 0.61675562, 0.90525854,
       0.39284754]...)

check_is_fitted() → None

Raise an error if this object is not fitted.

Check whether this object is fitted, and if it is not fitted, an exception is thrown.

Raises:

NotFittedError

If this object is not fitted.

decision_function(X: ndarray) → array

Compute anomaly scores.

Compute the anomaly scores for the given time series using this detector.

Parameters:

Xarray-like of shape (n_samples, n_attributes)

Input time series.

Returns:

array-like of shape (n_samples)

The computed anomaly scores.

fit(X: ndarray, y: ndarray = None, **kwargs) → BaseDetector

Fit this detector.

Fit this detector to the given data.

Parameters:

Xarray-like of shape (n_samples, n_attributes)

Input time series.

yarray-like, default=None

Ground-truth information.

**kwargs

Additional parameters to be used to fit the anomaly detector.

Returns:

BaseDetector

Returns the instance itself.

is_fitted() → bool

Check whether this object is fitted.

Check whether all the attributes of this object that end with an underscore (‘_’) has been initialized.

Returns:

bool

True if and only if all the attributes of this object ending with ‘_’ are initialized.

predict_confidence(X: ndarray, X_train: ndarray = None, contamination: float = 0.05, decision_scores_given: bool = False)

Predict the confidence of the anomaly scores on the test given test data [26].

This method implements ExCeeD (Example-wise Confidence of anomaly Detectors) to estimate the confidence. ExCeed transforms the predicted decision scores to probability estimates using a Bayesian approach, which enables to assign a confidence score to each prediction which captures the uncertainty of the anomaly detector in that prediction.

Parameters:

Xarray-like of shape (n_samples, n_attributes)

The test time series for which the confidence of anomaly scores should be predicted.

X_trainarray-like of shape (n_samples_train, n_attributes), default=None

The training time series, which can be used as reference. If X_train=None, the test set is used as reference set.

contaminationfloat, default=0.05

The (estimated) contamination rate for the data, i.e., the expected percentage of anomalies.

decision_scores_givenbool, default=False

Whether the given X and X_train represent time series data or decision scores. If decision_scores_given=False (default), then the given arrays are interpreted as time series. Otherwise, they are interpreted as decision scores, as computed by decision_function().

Returns:

array-like of shape (n_samples)

The confidence of this anomaly detector in each prediction in the given test time series.

predict_proba(X: ndarray) → ndarray

Predict anomaly probabilities.

Estimate the probability of a sample of X being anomalous, based on the anomaly scores obtained from decision_function by rescaling them to the range of [0, 1] via min-max scaling.

Parameters:

Xarray-like of shape (n_samples, n_attributes)

Input time series.

Returns:

array-like of shape (n_samples)

1D array with the same length as X, with values in the interval [0, 1], in which a higher value implies that the instance is more likely to be anomalous.

Raises:

ValueError

If scores is not a valid array.

ValueError

If the prediction scores from ‘decision_function’ are constant, but not in the interval [0, 1], because these values can not unambiguously be transformed to an anomaly probability.

requires_fitting() → bool

Check whether this object requires fitting.

Check whether any of the attributes of this object ends with an underscore (‘_’), which indicates that the attribute is set when the object is fitted. Note that this method does not check whether the object is fitted, i.e., whether the attributes have been set.

Returns:

bool

True if and only if this object has attributes that end with ‘_’.

save(path: str | Path) → None

Save this detector.

Save detector to disk as a pickle file with extension .dtai. If the given path consists of multiple subdirectories, then the not existing subdirectories are created.

Parameters:

pathstr or Path

Location where to store the detector.