diff --git a/deepod/models/time_series/devnet.py b/deepod/models/time_series/devnet.py index ab0db0c..2331e9f 100644 --- a/deepod/models/time_series/devnet.py +++ b/deepod/models/time_series/devnet.py @@ -19,71 +19,84 @@ class DevNetTS(BaseDeepAD): Deviation Networks for Weakly-supervised Anomaly Detection (KDD'19) :cite:`pang2019deep` - Parameters - ---------- - epochs: int, optional (default=100) - Number of training epochs - - batch_size: int, optional (default=64) - Number of samples in a mini-batch - - lr: float, optional (default=1e-3) - Learning rate - - rep_dim: int, optional (default=128) - it is for consistency, unused in this model - - hidden_dims: list, str or int, optional (default='100,50') - Number of neural units in hidden layers + Deviation Networks (DevNet) designed for weakly-supervised anomaly detection. + This implementation is based on the architecture presented in the KDD'19 paper: + "Deviation Networks for Weakly-supervised Anomaly Detection" by Pang et al. + + Args: + + hidden_dims (Union[list, str, int], optional): + The dimensions for the hidden layers. Can be a list of integers, a string of comma-separated integers, or a single integer. - If list, each item is a layer - If str, neural units of hidden layers are split by comma - If int, number of neural units of single hidden layer - - act: str, optional (default='ReLU') - activation layer name - choice = ['ReLU', 'LeakyReLU', 'Sigmoid', 'Tanh'] - - bias: bool, optional (default=False) - Additive bias in linear layer - - n_heads: int, optional(default=8): - number of head in multi-head attention - used when network='transformer', deprecated in other networks - - d_model: int, optional (default=64) - number of dimensions in Transformer - used when network='transformer', deprecated in other networks - - pos_encoding: str, optional (default='fixed') - manner of positional encoding, deprecated in other networks - choice = ['fixed', 'learnable'] - - norm: str, optional (default='BatchNorm') - manner of norm in Transformer, deprecated in other networks - choice = ['LayerNorm', 'BatchNorm'] - - margin: float, optional (default=5.) - margin value used in the deviation loss function - - l: int, optional (default=5000.) - the size of samples of the Gaussian distribution used in the deviation loss function - - epoch_steps: int, optional (default=-1) - Maximum steps in an epoch - - If -1, all the batches will be processed - - prt_steps: int, optional (default=10) - Number of epoch intervals per printing - - device: str, optional (default='cuda') - torch device, - - verbose: int, optional (default=1) - Verbosity mode - - random_state： int, optional (default=42) - the seed used by the random + - Defaults to '100,50'. + + act (str, optional): + Activation function to use. Choices include 'ReLU', 'LeakyReLU', 'Sigmoid', 'Tanh'. Default is 'ReLU'. + + bias (bool, optional): + Whether to include a bias term in the linear layers. Default is False. + + n_heads (int, optional): + Number of heads in multi-head attention. Only used when network is 'transformer'. Default is 8. + + pos_encoding (str, optional): + The type of positional encoding to use. Only relevant when network is 'transformer'. Choices are 'fixed' or 'learnable'. Default is 'fixed'. + + norm (str, optional): + Normalization method in the Transformer. Only relevant when network is 'transformer'. Choices are 'LayerNorm' or 'BatchNorm'. Default is 'LayerNorm'. + + epochs (int, optional): + Number of training epochs. Default is 100. + + batch_size (int, optional): + Batch size for training. Default is 64. + + lr (float, optional): + Learning rate for the optimizer. Default is 1e-3. + + network (str, optional): + Type of network architecture to use. Default is 'Transformer'. + + seq_len (int, optional): + Length of input sequences for models that require it. Default is 100. + + stride (int, optional): + Stride of the convolutional layers. Default is 1. + + rep_dim (int, optional): + The representation dimension. Unused in this model but kept for consistency. Default is 128. + + d_model (int, optional): + The number of expected features in the transformer model. Only used when network is 'transformer'. Default is 512. + + attn (str, optional): + Type of attention to use. Only used when network is 'transformer'. Default is 'self_attn'. + + margin (float, optional): + Margin for the deviation loss function. Default is 5. + + l (int, optional): + The size of the sample for the Gaussian distribution in the deviation loss function. Default is 5000. + + epoch_steps (int, optional): + Maximum number of steps per epoch. If -1, all batches will be processed. Default is -1. + + prt_steps (int, optional): + Number of epoch intervals for printing during training. Default is 10. + + device (str, optional): + The device to use for training ('cuda' or 'cpu'). Default is 'cuda'. + + verbose (int, optional): + Verbosity mode. 0 = silent, 1 = progress bar, 2 = one line per epoch. Default is 2. + + random_state (int, optional): + Seed for the random number generator for reproducibility. Default is 42. + """ + def __init__(self, epochs=100, batch_size=64, lr=1e-3, network='Transformer', seq_len=100, stride=1, rep_dim=128, hidden_dims='100,50', act='ReLU', bias=False, @@ -91,6 +104,9 @@ def __init__(self, epochs=100, batch_size=64, lr=1e-3, margin=5., l=5000, epoch_steps=-1, prt_steps=10, device='cuda', verbose=2, random_state=42): + """ + Initialize the DevNetTS. + """ super(DevNetTS, self).__init__( data_type='ts', model_name='DevNet', epochs=epochs, batch_size=batch_size, lr=lr, network=network, seq_len=seq_len, stride=stride, @@ -115,6 +131,31 @@ def __init__(self, epochs=100, batch_size=64, lr=1e-3, return def training_prepare(self, X, y): + """ + Prepares the data and model for training by creating a balanced data loader, + initializing the network, and setting up the loss criterion. + + Args: + + X (np.ndarray): + The input features for training. + + y (np.ndarray): + The target labels for training, where 1 indicates an anomaly. + + Returns: + + train_loader (DataLoader): + A DataLoader with balanced mini-batches for training. + + net (nn.Module): + The initialized neural network model. + + criterion (Loss): + The loss function used during training. + + """ + # loader: balanced loader, a mini-batch contains a half of normal data and a half of anomalies n_anom = np.where(y == 1)[0].shape[0] n_norm = self.n_samples - n_anom @@ -153,12 +194,47 @@ def training_prepare(self, X, y): return train_loader, net, criterion def inference_prepare(self, X): + """ + Prepares the data for inference. + + Args: + + X (Tensor): + The input features for inference. + + Returns: + + test_loader (DataLoader): + A DataLoader for inference. + + """ + test_loader = DataLoader(X, batch_size=self.batch_size, drop_last=False, shuffle=False) self.criterion.reduction = 'none' return test_loader def training_forward(self, batch_x, net, criterion): + """ + Performs a forward pass during training. + + Args: + + batch_x (tuple): + A batch of input features and target labels. + + net (nn.Module): + The neural network model. + + criterion (Loss): + The loss function used during training. + + Returns: + + loss (Tensor): + The computed loss for the batch. + """ + batch_x, batch_y = batch_x batch_x = batch_x.float().to(self.device) batch_y = batch_y.to(self.device) @@ -167,6 +243,30 @@ def training_forward(self, batch_x, net, criterion): return loss def inference_forward(self, batch_x, net, criterion): + """ + Performs a forward pass during inference. + + Args: + + batch_x (Tensor): + A batch of input features. + + net (nn.Module): + The neural network model. + + criterion (Loss): + The loss function used during training. Not used. + + Returns: + + batch_z (Tensor): + The batch of input features (unmodified). + + s (Tensor): + The computed scores for the batch. + + """ + batch_x = batch_x.float().to(self.device) s = net(batch_x) s = s.view(-1) diff --git a/deepod/models/time_series/dif.py b/deepod/models/time_series/dif.py index eec4a08..b037b48 100644 --- a/deepod/models/time_series/dif.py +++ b/deepod/models/time_series/dif.py @@ -20,7 +20,63 @@ class DeepIsolationForestTS(BaseDeepAD): """ Deep isolation forest for anomaly detection (TKDE'23) + + Implementation of a Deep Isolation Forest model for time-series anomaly detection, as described in TKDE'23. + This model combines deep learning methods for dimensionality reduction with the traditional Isolation Forest + algorithm to detect anomalies in time-series data. + + Args: + + epochs (int, optional): + Number of training epochs. Default is 100. + + batch_size (int, optional): + Batch size for training. Default is 1000. + + lr (float, optional): + Learning rate for the optimizer. Default is 1e-3. + + seq_len (int, optional): + Length of the input sequences. Default is 100. + + stride (int, optional): + Stride of the sliding window over the time series. Default is 1. + + hidden_dims (str, optional): + String representation of the hidden layer dimensions, separated by commas. + + bias (bool, optional): + If True, adds a bias term to the layers of the neural network. Default is False. + + n_ensemble (int, optional): + Number of ensemble models to train. + + n_estimators (int, optional): + Number of base estimators in the Isolation Forest. Default is 6. + + max_samples (int, optional): + Maximum number of samples to draw to train each base estimator. Default is 256. + + n_jobs (int, optional): + Number of jobs to run in parallel for Isolation Forest training. Default is 1. + + epoch_steps (int, optional): + Number of steps per epoch. If -1, all batches will be processed. + + prt_steps (int, optional): + Interval of epochs at which to print progress updates. + + device (str, optional): + Device to use for training ('cuda' or 'cpu'). Default is 'cuda'. + + verbose (int, optional): + Verbosity mode. 0 = silent, 1 = progress bar, 2 = one line per epoch. + + random_state (int, optional): + Seed for random number generation for reproducibility. Default is 42. + """ + def __init__(self, epochs=100, batch_size=1000, lr=1e-3, seq_len=100, stride=1, @@ -29,6 +85,10 @@ def __init__(self, max_samples=256, n_jobs=1, epoch_steps=-1, prt_steps=10, device='cuda', verbose=2, random_state=42): + """ + Initializes the Deep Isolation Forest Time-Series model with the specified hyperparameters. + """ + super(DeepIsolationForestTS, self).__init__( model_name='DIF', data_type='ts', network='DilatedConv', epochs=epochs, batch_size=batch_size, lr=lr, @@ -54,23 +114,23 @@ def __init__(self, def fit(self, X, y=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 - - Returns - ------- - self : object - Fitted estimator. + Fits the Deep Isolation Forest model on the provided time-series data. + + Args: + + X (np.ndarray): + The input samples of shape (n_samples, n_features). + + y (np.ndarray, optional): + Target values of shape (n_samples, ) (ignored in unsupervised training). + + Returns: + + self: + The fitted estimator. + """ - + X_seqs = get_sub_seqs(X, seq_len=self.seq_len, stride=self.stride) y_seqs = get_sub_seqs(y, seq_len=self.seq_len, stride=self.stride) if y is not None else None self.train_data = X_seqs @@ -119,22 +179,23 @@ def fit(self, X, y=None): return self def decision_function(self, X): - """Predict raw anomaly scores of X using the fitted detector. + """ + Predict raw anomaly scores of X using the fitted detector. The anomaly score of an input sample is computed based on the fitted detector. For consistency, outliers are assigned with higher anomaly scores. - Parameters - ---------- - X : numpy array of shape (n_samples, n_features) - The input samples. Sparse matrices are accepted only - if they are supported by the base estimator. + Args: + + X (np.ndarray): + The input samples of shape (n_samples, n_features). Sparse matrices are accepted only if they are supported by the base estimator. + + Returns: + + anomaly_scores (np.ndarray): + The anomaly score of the input samples with the shape of (n_samples,). - Returns - ------- - anomaly_scores : numpy array of shape (n_samples,) - The anomaly score of the input samples. """ if self.verbose >= 1: @@ -164,6 +225,30 @@ def decision_function(self, X): @staticmethod def _deep_transfer(X, net, batch_size, device): + """ + Transfers the input data through the network to obtain reduced representations. + + Args: + + X (np.ndarray): + The input samples to be reduced. + + net (nn.Module): + The neural network model for dimensionality reduction. + + batch_size (int): + Batch size for processing. + + device (str): + The device on which to perform computations. + + Returns: + + x_reduced (np.ndarray): + The reduced representation of the input samples. + + """ + x_reduced = [] loader = DataLoader(dataset=X, batch_size=batch_size, drop_last=False, pin_memory=True, shuffle=False) for batch_x in loader: diff --git a/deepod/models/time_series/dsad.py b/deepod/models/time_series/dsad.py index 8888f55..643ed24 100644 --- a/deepod/models/time_series/dsad.py +++ b/deepod/models/time_series/dsad.py @@ -18,71 +18,71 @@ class DeepSADTS(BaseDeepAD): """ Deep Semi-supervised Anomaly Detection (ICLR'20) :cite:`ruff2020dsad` - - Parameters - ---------- - data_type: str, optional (default='tabular') - Data type - - epochs: int, optional (default=100) - Number of training epochs - - batch_size: int, optional (default=64) - Number of samples in a mini-batch - - lr: float, optional (default=1e-3) - Learning rate - - network: str, optional (default='MLP') - network structure for different data structures - - rep_dim: int, optional (default=128) - Dimensionality of the representation space - - hidden_dims: list, str or int, optional (default='100,50') - Number of neural units in hidden layers - - If list, each item is a layer - - If str, neural units of hidden layers are split by comma - - If int, number of neural units of single hidden layer - - act: str, optional (default='ReLU') - activation layer name - choice = ['ReLU', 'LeakyReLU', 'Sigmoid', 'Tanh'] - - bias: bool, optional (default=False) - Additive bias in linear layer - - n_heads: int, optional(default=8): - number of head in multi-head attention - used when network='transformer', deprecated in other networks - - d_model: int, optional (default=64) - number of dimensions in Transformer - used when network='transformer', deprecated in other networks - - pos_encoding: str, optional (default='fixed') - manner of positional encoding, deprecated in other networks - choice = ['fixed', 'learnable'] - - norm: str, optional (default='BatchNorm') - manner of norm in Transformer, deprecated in other networks - choice = ['LayerNorm', 'BatchNorm'] - - epoch_steps: int, optional (default=-1) - Maximum steps in an epoch - - If -1, all the batches will be processed - - prt_steps: int, optional (default=10) - Number of epoch intervals per printing - - device: str, optional (default='cuda') - torch device, - - verbose: int, optional (default=1) - Verbosity mode - - random_state： int, optional (default=42) - the seed used by the random + + This model extends the semi-supervised anomaly detection framework to time-series datasets, aiming + to detect anomalies by learning a representation of the data in a lower-dimensional hypersphere. + + Args: + + data_type (str, optional): + The type of data, here it's defaulted to 'ts' (time-series). + + epochs (int, optional): + The number of epochs for training, default is 100. + + batch_size (int, optional): + The size of the mini-batch for training, default is 64. + + lr (float, optional): + The learning rate for the optimizer, default is 1e-3. + + network (str, optional): + The type of network architecture to use, default is 'TCN'. + + rep_dim (int, optional): + The size of the representation dimension, default is 128. + + hidden_dims (Union[list, str, int], optional): + The dimensions for hidden layers. It can be a list, a comma-separated string, or a single integer. Default is '100,50'. + - If list, each item is a layer + - If str, neural units of hidden layers are split by comma + - If int, number of neural units of single hidden layer + + act (str, optional): + The activation function to use. Possible values are 'ReLU', 'LeakyReLU', 'Sigmoid', 'Tanh', default is 'ReLU'. + + bias (bool, optional): + Whether to include a bias term in the layers, default is False. + + n_heads (int, optional): + The number of heads in a multi-head attention mechanism, default is 8. + + d_model (int, optional): + The number of dimensions in the transformer model, default is 512. + + attn (str, optional): + The type of attention mechanism used, default is 'self_attn'. + + pos_encoding (str, optional): + The type of positional encoding used in the transformer model, default is 'fixed'. + + norm (str, optional): + The type of normalization used in the transformer model, default is 'LayerNorm'. + + epoch_steps (int, optional): + The maximum number of steps per epoch, default is -1, indicating that all batches will be processed. + + prt_steps (int, optional): + The number of epoch intervals for printing progress, default is 10. + + device (str, optional): + The device to use for training and inference, default is 'cuda'. + + verbose (int, optional): + The verbosity mode, default is 2. + + random_state (int, optional): + The seed for the random number generator, default is 42. """ @@ -92,6 +92,10 @@ def __init__(self, epochs=100, batch_size=64, lr=1e-3, n_heads=8, d_model=512, attn='self_attn', pos_encoding='fixed', norm='LayerNorm', epoch_steps=-1, prt_steps=10, device='cuda', verbose=2, random_state=42): + """ + Initializes the DeepSADTS model with the provided parameters. + """ + super(DeepSADTS, self).__init__( data_type='ts', model_name='DeepSAD', epochs=epochs, batch_size=batch_size, lr=lr, network=network, seq_len=seq_len, stride=stride, @@ -116,6 +120,30 @@ def __init__(self, epochs=100, batch_size=64, lr=1e-3, return def training_prepare(self, X, y): + """ + Prepares the model for training by setting up data loaders, initializing the network, and defining the loss criterion. + + Args: + + X (np.ndarray): + The input feature matrix for training. + + y (np.ndarray): + The target labels where 1 indicates known anomalies. + + Returns: + + train_loader (DataLoader): + The data loader for training. + + net (nn.Module): + The neural network for feature extraction. + + criterion (Loss): + The loss function used for training. + + """ + # By following the original paper, # use -1 to denote known anomalies, and 1 to denote known inliers known_anom_id = np.where(y == 1) @@ -166,12 +194,48 @@ def training_prepare(self, X, y): return train_loader, net, criterion def inference_prepare(self, X): + """ + Prepares the model for inference by setting up data loaders. + + Args: + + X (np.ndarray): + The input feature matrix for inference. + + Returns: + + test_loader (DataLoader): + The data loader for inference. + + """ + test_loader = DataLoader(X, batch_size=self.batch_size, drop_last=False, shuffle=False) self.criterion.reduction = 'none' return test_loader def training_forward(self, batch_x, net, criterion): + """ + Performs a forward training pass. + + Args: + + batch_x (tuple): + A batch of input data and labels. + + net (nn.Module): + The neural network model. + + criterion (Loss): + The loss function. + + Returns: + + loss (torch.Tensor): + The computed loss for the batch. + + """ + batch_x, batch_y = batch_x # from collections import Counter @@ -186,13 +250,57 @@ def training_forward(self, batch_x, net, criterion): return loss def inference_forward(self, batch_x, net, criterion): + """ + Performs a forward inference pass. + + Args: + + batch_x (torch.Tensor): + A batch of input data. + + net (nn.Module): + The neural network model. + + criterion (Loss): + The loss function used to calculate the anomaly score. + + Returns: + + batch_z (torch.Tensor): + The encoded batch of data in the feature space. + + s (torch.Tensor): + The anomaly scores for the batch. + + """ + batch_x = batch_x.float().to(self.device) batch_z = net(batch_x) s = criterion(batch_z) return batch_z, s def _set_c(self, net, dataloader, eps=0.1): - """Initializing the center for the hypersphere""" + """ + Initializes the center 'c' for the hypersphere. + + Args: + + net (nn.Module): + The neural network model. + + dataloader (DataLoader): + The data loader to compute the center from. + + eps (float): + A small value to ensure 'c' is away from zero, default is 0.1. + + Returns: + + c (torch.Tensor): + The initialized center of the hypersphere. + + """ + net.eval() z_ = [] with torch.no_grad(): diff --git a/deepod/models/time_series/dsvdd.py b/deepod/models/time_series/dsvdd.py index 96076fd..fc3b065 100644 --- a/deepod/models/time_series/dsvdd.py +++ b/deepod/models/time_series/dsvdd.py @@ -14,68 +14,86 @@ class DeepSVDDTS(BaseDeepAD): """ Deep One-class Classification for Anomaly Detection (ICML'18) :cite:`ruff2018deepsvdd` + - Parameters - ---------- - epochs: int, optional (default=100) - Number of training epochs - - batch_size: int, optional (default=64) - Number of samples in a mini-batch - - lr: float, optional (default=1e-3) - Learning rate - - network: str, optional (default='MLP') - network structure for different data structures - - seq_len: int, optional (default=100) - Size of window used to create subsequences from the data - deprecated when handling tabular data (network=='MLP') - - stride: int, optional (default=1) - number of time points the window will move between two subsequences - deprecated when handling tabular data (network=='MLP') - - rep_dim: int, optional (default=128) - Dimensionality of the representation space - - hidden_dims: list, str or int, optional (default='100,50') - Number of neural units in hidden layers - - If list, each item is a layer - - If str, neural units of hidden layers are split by comma - - If int, number of neural units of single hidden layer - - act: str, optional (default='ReLU') - activation layer name - choice = ['ReLU', 'LeakyReLU', 'Sigmoid', 'Tanh'] - - bias: bool, optional (default=False) - Additive bias in linear layer - - epoch_steps: int, optional (default=-1) - Maximum steps in an epoch - - If -1, all the batches will be processed - - prt_steps: int, optional (default=10) - Number of epoch intervals per printing - - device: str, optional (default='cuda') - torch device, - - verbose: int, optional (default=1) - Verbosity mode - - random_state： int, optional (default=42) - the seed used by the random + Args: + epochs (int, optional): + Number of training epochs. Default is 100. + + + batch_size (int, optional): + Number of samples in a mini-batch. Default is 64. + + lr (float, optional): + Learning rate. Default is 1e-5. + + network (str, optional): + Network structure for different data structures. Default is 'Transformer'. + + seq_len (int, optional): + Size of window used to create subsequences from the data. Default is 30. + + stride (int, optional): + Number of time points the window moves between subsequences. Default is 10. + + rep_dim (int, optional): + Dimensionality of the representation space. Default is 64. + + hidden_dims (Union[list, str, int], optional): + Dimensions for hidden layers. Default is '512'. + - If list, each item is a layer + - If str, neural units of hidden layers are split by comma + - If int, number of neural units of single hidden layer + + act (str, optional): + Activation layer name. Choices are ['ReLU', 'LeakyReLU', 'Sigmoid', 'Tanh']. Default is 'GELU'. + + bias (bool, optional): + Whether to add a bias term in linear layers. Default is False. + + n_heads (int, optional): + Number of heads in multi-head attention. Default is 8. + + d_model (int, optional): + Number of dimensions in Transformer model. Default is 512. + + attn (str, optional): + Type of attention mechanism. Default is 'self_attn'. + + pos_encoding (str, optional): + Manner of positional encoding. Default is 'fixed'. + + norm (str, optional): + Manner of normalization in Transformer. Default is 'LayerNorm'. + + epoch_steps (int, optional): + Maximum steps in an epoch. Default is -1. + + prt_steps (int, optional): + Number of epoch intervals per printing. Default is 10. + + device (str, optional): + Torch device. Default is 'cuda'. + + verbose (int, optional): + Verbosity mode. Default is 2. + + random_state (int, optional): + Seed used by the random number generator. Default is 42. + """ + def __init__(self, epochs=100, batch_size=64, lr=1e-5, network='Transformer', seq_len=30, stride=10, rep_dim=64, hidden_dims='512', act='GELU', bias=False, n_heads=8, d_model=512, attn='self_attn', pos_encoding='fixed', norm='LayerNorm', epoch_steps=-1, prt_steps=10, device='cuda', verbose=2, random_state=42): + """ + Initializes the DeepSVDDTS model with the specified parameters. + """ + super(DeepSVDDTS, self).__init__( model_name='DeepSVDD', data_type='ts', epochs=epochs, batch_size=batch_size, lr=lr, network=network, seq_len=seq_len, stride=stride, @@ -99,6 +117,30 @@ def __init__(self, epochs=100, batch_size=64, lr=1e-5, return def training_prepare(self, X, y): + """ + Prepares the training process by setting up data loaders and initializing the network and loss criterion. + + Args: + + X (torch.Tensor): + Input tensor of the features. + + y (torch.Tensor): + Input tensor of the labels. + + Returns: + + train_loader (DataLoader): + DataLoader for the training data. + + net (nn.Module): + Initialized neural network model. + + criterion (DSVDDLoss): + Loss function for DeepSVDD. + + """ + train_loader = DataLoader(X, batch_size=self.batch_size, shuffle=True) network_params = { @@ -131,25 +173,104 @@ def training_prepare(self, X, y): return train_loader, net, criterion def inference_prepare(self, X): + """ + Prepares the model for inference by setting up data loaders. + + Args: + + X (torch.Tensor): + Input tensor of the features for inference. + + Returns: + + test_loader (DataLoader): + DataLoader for inference. + + """ + test_loader = DataLoader(X, batch_size=self.batch_size, drop_last=False, shuffle=False) self.criterion.reduction = 'none' return test_loader def training_forward(self, batch_x, net, criterion): + """ + Performs a forward pass during training. + + Args: + + batch_x (torch.Tensor): + Batch of input data. + + net (nn.Module): + The neural network model. + + criterion (DSVDDLoss): + Loss function for DeepSVDD. + + Returns: + + loss (torch.Tensor): + Computed loss for the batch. + + """ + batch_x = batch_x.float().to(self.device) z = net(batch_x) loss = criterion(z) return loss def inference_forward(self, batch_x, net, criterion): + """ + Performs a forward pass during inference. + + Args: + + batch_x (torch.Tensor): + Batch of input data. + + net (nn.Module): + The neural network model. + + criterion (DSVDDLoss): + Loss function for DeepSVDD to calculate anomaly score. + + Returns: + + batch_z (torch.Tensor): + The encoded batch of data in the feature space. + + s (torch.Tensor): + The anomaly scores for the batch. + """ + batch_x = batch_x.float().to(self.device) batch_z = net(batch_x) s = criterion(batch_z) return batch_z, s def _set_c(self, net, dataloader, eps=0.1): - """Initializing the center for the hypersphere""" + """ + Initializes the center 'c' for the hypersphere in the representation space. + + Args: + + net (nn.Module): + The neural network model. + + dataloader (DataLoader): + DataLoader for the data to compute the center from. + + eps (float, optional): + Small value to ensure 'c' is away from zero. Default is 0.1. + + Returns: + + c (torch.Tensor): + The initialized center of the hypersphere. + + """ + net.eval() z_ = [] with torch.no_grad(): @@ -167,25 +288,52 @@ def _set_c(self, net, dataloader, eps=0.1): class DSVDDLoss(torch.nn.Module): """ - Parameters - ---------- - c: torch.Tensor - Center of the pre-defined hyper-sphere in the representation space - - reduction: str, optional (default='mean') - choice = [``'none'`` | ``'mean'`` | ``'sum'``] - - If ``'none'``: no reduction will be applied; - - If ``'mean'``: the sum of the output will be divided by the number of - elements in the output; - - If ``'sum'``: the output will be summed + Custom loss function for Deep Support Vector Data Description (Deep SVDD). + + This loss function computes the distance between each data point in the representation + space and the center of the hypersphere and aims to minimize this distance for normal data points. + + Args: + + c (torch.Tensor): + The center of the hypersphere in the representation space. + + reduction (str, optional): + Specifies the reduction to apply to the output. Choices are 'none', 'mean', 'sum'. Default is 'mean'. + - If ``'none'``: no reduction will be applied; + - If ``'mean'``: the sum of the output will be divided by the number of elements in the output; + - If ``'sum'``: the output will be summed """ + def __init__(self, c, reduction='mean'): + """ + Initializes the DSVDDLoss with the hypersphere center and reduction method. + """ + super(DSVDDLoss, self).__init__() self.c = c self.reduction = reduction def forward(self, rep, reduction=None): + """ + Calculates the Deep SVDD loss for a batch of representations. + + Args: + + rep (torch.Tensor): + The representation of the batch of data. + + reduction (str, optional): + The reduction method to apply. If None, will use the specified 'reduction' attribute. Default is None. + + Returns: + + loss (torch.Tensor): + The calculated loss based on the representations and the center 'c'. + + """ + loss = torch.sum((rep - self.c) ** 2, dim=1) if reduction is None: