deepod.models.COUTA
- class deepod.models.COUTA(seq_len=100, stride=1, epochs=40, batch_size=64, lr=0.0001, ss_type='FULL', hidden_dims=16, rep_dim=16, rep_hidden=16, pretext_hidden=16, kernel_size=2, dropout=0.0, bias=True, alpha=0.1, neg_batch_ratio=0.2, train_val_pc=0.25, epoch_steps=-1, prt_steps=1, device='cuda', verbose=2, random_state=42)[source]
Calibrated One-class classifier for Unsupervised Time series Anomaly detection (arXiv’22)
Calibrated One-class classifier for Unsupervised Time Series Anomaly detection (COUTA) is a neural network-based model for anomaly detection in time series. It operates unsupervised, meaning it doesn’t require labeled data for training. The model architecture and training process are designed to learn a representation of normal patterns in order to detect anomalies as deviations from these patterns.
- Parameters:
seq_len (int, optional) – The length of each time series segment that the model will ingest during training and inference. It determines how many time steps back the model looks when considering a point for anomaly detection. Default value is 100, which means the model looks at 100 time steps at a time.
stride (int, optional) – The step size for moving the window of seq_len across the time series data. A stride of 1 moves the window one time step at a time, resulting in high overlap between consecutive segments, which can be useful for detecting anomalies that require high temporal resolution. Default is 1.
epochs (int, optional) – The total number of complete passes through the entire training dataset. More epochs can potentially lead to better model performance but also a risk of overfitting. Default is 40.
batch_size (int, optional) – The number of time series segments processed together in one pass of gradient descent during training. Larger batch sizes can lead to faster training but may require more memory. Default is 64.
lr (float, optional) – The learning rate dictates the speed at which the model learns. Specifically, it determines the size of the steps taken during gradient descent optimization. A smaller learning rate can make learning more gradual and precise but may slow down convergence. Default is 1e-4.
ss_type (str, optional) – Specifies the type of subsequence to be used for model training. ‘FULL’ implies that entire sequences are used without alteration. Other types might involve partial sequences or modified segments to introduce certain types of anomalies during training. Default is ‘FULL’.
hidden_dims (int, optional) – Specifies the number of neurons in the hidden layers of the neural network. This parameter is crucial for determining the capacity and complexity of the model. Default is 16.
rep_dim (int, optional) – Dimensionality of the representations learned by the neural network. It reflects the size of the feature space in which the time series data is embedded. Default is 16.
rep_hidden (int, optional) – Size of the hidden layers specifically in the representation learning part of the network. This can affect the granularity of the learned representations. Default is 16.
pretext_hidden (int, optional) – Size of the hidden layers for a pretext task, which is a task designed to help the network learn useful representations without requiring labeled data. Default is 16.
kernel_size (int, optional) – Size of the convolutional filters if the model uses convolutional layers. It affects how many time steps are considered together at one time by each filter. Default is 2.
dropout (float, optional) – The dropout rate is a regularization technique where randomly selected neurons are ignored during training. It helps in preventing overfitting. Default is 0.0 (no dropout).
bias (bool, optional) – Indicates whether the neurons in the network layers include a bias term. Bias terms can help the model fit the data better. Default is True.
alpha (float, optional) – A weighting factor that balances different components of the loss function. Tweaking this value can significantly affect the training dynamics and model performance. Default is 0.1.
neg_batch_ratio (float, optional) – The proportion of negative samples in each batch. In the context of anomaly detection, negative samples might refer to examples that are considered normal. Default is 0.2.
train_val_pc (float, optional) – The fraction of the training data set aside for validation purposes. Validation data is used to tune hyperparameters and early stopping to avoid overfitting. Default is 0.25 (25% of the training data).
epoch_steps (int, optional) – Defines the number of mini-batch updates within each epoch. Setting this to -1 uses the full dataset for each epoch, which is the default.
prt_steps (int, optional) – Frequency of epochs at which to print out the training progress and loss metrics to monitor the training process. Default is 1, which means printing after every epoch.
device (str, optional) – The computing device to run the model on. ‘cuda’ for NVIDIA GPU (if available) or ‘cpu’ for the computer’s central processing unit. Default is ‘cuda’, which will train the model on GPU if available for faster performance.
verbose (int, optional) – The level of verbosity determines how much information the model outputs during training. Higher verbosity levels result in more detailed messages, which can be useful for debugging or detailed analysis. Default is 2, which typically includes progress bars and loss metrics.
random_state (int, optional) – A seed for the random number generator to ensure reproducibility of the results. Setting this to a fixed number ensures that the random processes within the model are repeatable. Default is 42, a common choice in machine learning.
Methods
__init__([seq_len, stride, epochs, ...])Initialize the COUTA model with the provided parameters
create_batch_neg(batch_seqs[, ...])Creates a batch of negative samples.
decision_function(X[, return_rep])Predict raw anomaly score of X using the fitted detector.
decision_function_update(z, scores)for any updating operation after decision function
for any updating operation after each training epoch
fit(X[, y])Fit detector.
fit_auto_hyper(X[, y, X_test, y_test, ...])Fit detector.
inference_forward(batch_x, net, criterion)define forward step in inference
define test_loader
load_model(path)load_ray_checkpoint(best_config, best_checkpoint)Loads the model and its parameters from the best checkpoint obtained from Ray Tune.
predict(X[, return_confidence])Predict if a particular sample is an outlier or not.
save_model(path)set_seed(seed)set_tuned_net(config)Initializes the network with the given configuration.
Defines the hyperparameter space for tuning the model.
train(net, train_seqs[, val_seqs])Internal method to train the network.
training_forward(batch_x, net, criterion)define forward step in training
training_prepare(X, y)define train_loader, net, and criterion
- static create_batch_neg(batch_seqs, max_cut_ratio=0.5, seed=0, return_mul_label=False, ss_type='FULL')[source]
Creates a batch of negative samples.
- Parameters:
batch_seqs (numpy.ndarray) – The batch of sequences.
max_cut_ratio (float, optional) – The maximum cut ratio. Default is 0.5.
seed (int, optional) – The seed for the random number generator. Default is 0.
return_mul_label (bool, optional) – Whether to return multiple labels. Default is False.
ss_type (str, optional) – The type of the subsequence. Default is ‘FULL’.
- Returns:
The batch of negative samples and their labels.
- Return type:
- decision_function(X, return_rep=False)[source]
Predict raw anomaly score of X using the fitted detector. For consistency, outliers are assigned with larger anomaly scores.
- Parameters:
X (numpy.ndarray) – The input dataset to compute anomaly scores for. numpy array of shape (n_samples, n_features) The input samples. Sparse matrices are accepted only if they are supported by the base estimator.
return_rep (bool, optional) – Flag to return the learned representations. default=False
- Returns:
The computed anomaly scores. numpy array of shape (n_samples,).
- 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 detector. In unsupervised anomaly detection, ‘y’ is not required and thus ignored, allowing the model to learn the normal patterns of the dataset autonomously. This method initiates the training process for the COUTA model on the given time series dataset.
- Parameters:
X (numpy.ndarray) – The input dataset for the model to train on. It is expected to be a 2D numpy array where each row corresponds to a sample in the time series, and each column represents a feature at a given time step. The shape of the array should be (n_samples, n_features), where ‘n_samples’ is the number of time series segments and ‘n_features’ is the number of observations at each time step.
y (numpy.ndarray, optional) – Labels for the input data. Although not utilized in the unsupervised version of the COUTA model, it is included in the method signature for compatibility with supervised or semi-supervised extensions of the model. In those cases, ‘y’ could provide additional context or labeling information that may be used for training purposes. It is a 1D array with a length of ‘n_samples’, where each entry is the label of the corresponding sample in ‘X’.
- Returns:
The fitted model instance. By returning ‘self’, the method allows for a fluent interface, enabling the chaining of method calls. After fitting, the model instance contains the learned parameters, and additional methods can be called on it, such as ‘decision_function’ to compute anomaly scores, or further training with additional data.
- Return type:
self
- 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:
- load_ray_checkpoint(best_config, best_checkpoint)[source]
Loads the model and its parameters from the best checkpoint obtained from Ray Tune.
- predict(X, return_confidence=False)
Predict if a particular sample is an outlier or not.
- Parameters:
X (numpy array of shape (n_samples, n_features)) – The input samples.
return_confidence (boolean, optional(default=False)) – If True, also return the confidence of prediction.
- Returns:
outlier_labels (numpy array of shape (n_samples,)) – For each observation, tells whether it should be considered as an outlier according to the fitted model. 0 stands for inliers and 1 for outliers.
confidence (numpy array of shape (n_samples,).) – Only if return_confidence is set to True.
- set_tuned_net(config)[source]
Initializes the network with the given configuration.
- Parameters:
config (dict) – A dictionary containing the hyperparameters for the model.
- Returns:
The initialized neural network.
- Return type:
_COUTANet
- static set_tuned_params()[source]
Defines the hyperparameter space for tuning the model.
- Returns:
A dictionary specifying the hyperparameter search space.
- Return type:
- train(net, train_seqs, val_seqs=None)[source]
Internal method to train the network.
- Parameters:
net (nn.Module) – The neural network to train.
train_seqs (numpy.ndarray) – The training sequences.
val_seqs (numpy.ndarray, optional) – The validation sequences. Default is None.
- Returns:
The trained neural network.
- Return type:
nn.Module