deepod.models.DCdetector
- class deepod.models.DCdetector(seq_len=100, stride=1, lr=0.0001, epochs=5, batch_size=128, epoch_steps=20, prt_steps=1, device='cuda', n_heads=1, d_model=256, e_layers=3, patch_size=None, verbose=2, random_state=42, threshold_=1)[source]
DCdetector: Dual Attention Contrastive Representation Learning for Time Series Anomaly Detection (KDD’23)
This class implements the DCdetector model. It uses a dual attention mechanism and contrastive representation learning to detect anomalies. The model is trained to learn representations of normal time series and then uses these representations to detect anomalies in new time series. The dual attention mechanism allows the model to focus on different parts of the time series at different times, which can help it detect a wider range of anomalies. The contrastive representation learning encourages the model to learn representations that are similar for normal time series and different for anomalous time series.
- Parameters:
seq_len (int, optional) – The length of the sequence. This parameter determines the length of the time series that the model will consider at a time. Default is 100.
stride (int, optional) – The stride. This parameter determines the step size when moving the sliding window across the time series. Default is 1.
lr (float, optional) – The learning rate. This parameter determines the step size that the model will take when updating its parameters during training. Default is 0.0001.
epochs (int, optional) – The number of epochs. This parameter determines the number of times the model will iterate over the entire dataset during training. Default is 5.
batch_size (int, optional) – The batch size. This parameter determines the number of samples that the model will process at a time during training. Default is 128.
epoch_steps (int, optional) – The number of epoch steps. This parameter determines the number of steps that the model will take in each epoch. Default is 20.
prt_steps (int, optional) – The number of prt steps. This parameter determines the number of steps that the model will take before printing the training progress. Default is 1.
device (str, optional) – The device to use. This parameter determines the device (CPU or GPU) that the model will use for computation. Default is ‘cuda’.
n_heads (int, optional) – The number of heads. This parameter determines the number of attention heads in the dual attention mechanism. Default is 1.
d_model (int, optional) – The model dimension. This parameter determines the dimensionality of the model’s output space. Default is 256.
e_layers (int, optional) – The number of e layers. This parameter determines the number of encoder layers in the model. Default is 3.
patch_size (list, optional) – The size of the patch. This parameter determines the size of the patches that the model will extract from the time series. Default is [5].
verbose (int, optional) – The verbosity level. This parameter determines the amount of information the model will print during training. Default is 2.
random_state (int, optional) – The random state. This parameter determines the seed for the random number generator. Default is 42.
threshold (int, optional) – The threshold. This parameter determines the threshold for anomaly detection. Default is 1.
Methods
__init__([seq_len, stride, lr, epochs, ...])Initialize the DCdetector.
decision_function(X[, return_rep])Compute the anomaly scores or representations for the input data using the trained DCdetector model.
decision_function_update(z, scores)for any updating operation after decision function
for any updating operation after each training epoch
fit(X[, y])Fit the model to the input data.
fit_auto_hyper(X[, y, X_test, y_test, ...])Fit detector.
inference(dataloader)Perform inference on the data provided by the DataLoader.
inference_forward(batch_x, net, criterion)define forward step in inference
define test_loader
load_model(path)load_ray_checkpoint(best_config, best_checkpoint)predict(X[, return_confidence])Predict whether each sequence in the input data is an anomaly or not.
save_model(path)set_seed(seed)set_tuned_net(config)set_tuned_params()training(dataloader)Train the model for one epoch using the provided DataLoader.
training_forward(batch_x, net, criterion)define forward step in training
training_prepare(X, y)define train_loader, net, and criterion
- decision_function(X, return_rep=False)[source]
Compute the anomaly scores or representations for the input data using the trained DCdetector model.
- Parameters:
X (numpy.ndarray) – The input data to compute the decision function for. It should have the same number of features as the data used to fit the model.
return_rep (bool, optional) – A flag that determines whether to return the raw anomaly scores (False) or the learned representations (True). Default is False.
- Returns:
An array of anomaly scores. The shape is (n_samples,), where ‘n_samples’ is the number of input sequences.
- Return type:
numpy.ndarray
- decision_function_update(z, scores)
for any updating operation after decision function
- epoch_update()
for any updating operation after each training epoch
- fit(X, y=None)[source]
Fit the model to the input data. This method is responsible for training the DCdetector model on the provided time series data. The training process involves extracting subsequences from the time series, constructing a model, and optimizing it over a number of epochs.
The ‘X’ parameter is the only required input as this is an unsupervised model, meaning it does not require target labels for training. The method involves setting up a DataLoader for the training sequences, defining an optimizer and a learning rate scheduler, and iterating over the dataset for a specified number of epochs to train the model.
- Parameters:
X (numpy.ndarray) – The input data for training. It is a numpy array of shape (n_samples, n_features), where ‘n_samples’ is the number of time series segments, and ‘n_features’ is the number of observations per time step.
y (numpy.ndarray, optional) – The target data is not used in this unsupervised training method. It is present to maintain consistency with supervised learning interfaces. Default is None.
- fit_auto_hyper(X, y=None, X_test=None, y_test=None, n_ray_samples=5, time_budget_s=None)
Fit detector. y is ignored in unsupervised methods.
- Parameters:
X (numpy array of shape (n_samples, n_features)) – The input samples.
y (numpy array of shape (n_samples, )) – Not used in unsupervised methods, present for API consistency by convention. used in (semi-/weakly-) supervised methods
X_test (numpy array of shape (n_samples, n_features), default=None) – The input testing samples for hyper-parameter tuning.
y_test (numpy array of shape (n_samples, ), default=None) – Label of input testing samples for hyper-parameter tuning.
n_ray_samples (int, default=5) – Number of times to sample from the hyperparameter space
time_budget_s (int, default=None) – Global time budget in seconds after which all trials of Ray are stopped.
- Returns:
config – tuned hyper-parameter
- Return type:
- inference(dataloader)[source]
Perform inference on the data provided by the DataLoader. It processes the data through the trained model to compute losses, which are then combined to generate anomaly scores.
The method uses a temperature parameter to scale the losses and applies a softmax to obtain a probability distribution over the anomaly scores, which can be used to rank the inputs by their likelihood of being anomalies.
- Parameters:
dataloader (torch.utils.data.DataLoader) – The DataLoader that provides batches of data for inference.
- Returns:
A tuple containing two elements:
- numpy.ndarray:
An array of anomaly scores for each sequence in the data.
- list:
An empty list, as placeholders for any additional outputs.
- Return type:
- predict(X, return_confidence=True)[source]
Predict whether each sequence in the input data is an anomaly or not. The method computes anomaly scores using the trained model and compares them to a threshold, classifying sequences as normal or anomalous.
The threshold is determined by the percentile of anomaly scores on the test set, which is a hyperparameter that can be tuned. Additionally, the method can return confidence scores, which represent the model’s certainty in its predictions.
- Parameters:
X (numpy.ndarray) – The input data sequences.
return_confidence (bool, optional) – Whether to return confidence scores along with predictions. Default is True.
- Returns:
If return_confidence is False, returns an array of binary predictions (0 for normal, 1 for anomaly). If True, returns a tuple with the array of predictions and an array of confidence scores.
- Return type:
numpy.ndarray or tuple
- training(dataloader)[source]
Train the model for one epoch using the provided DataLoader. It iterates over the dataset, calculates losses for each batch, and updates the model parameters using backpropagation.
The method calculates two types of losses, which represent the model’s performance in terms of its contrastive learning objective. These losses are combined to form the final loss used for backpropagation.
- Parameters:
dataloader (torch.utils.data.DataLoader) – The DataLoader that provides batches of data for training the model.
- Returns:
The average loss for the epoch, computed over all batches.
- Return type: