timesead.models.other.ncad

Classes

`TCNEncoder`	Encoder of a time series using a Temporal Convolution Network (TCN).
`ContrastiveClassifier`	Contrastive Classifier.
`NCAD`	Neural Contrastive Detection in Time Series
`NCADTrainer`
`NCADAnomalyDetector`	Base class for all neural network modules.
`LocalOutlierInjectionTransform`	Inject spikes based on local noise

Functions

`l2_distance`(→ torch.Tensor)
`coe_batch`(→ Tuple[torch.Tensor, torch.Tensor])	Contextual Outlier Exposure.
`mixup_batch`(→ Tuple[torch.Tensor, torch.Tensor])

Module Contents

class timesead.models.other.ncad.TCNEncoder(in_channels: int, out_channels: int, kernel_size: int, tcn_channels: int, tcn_layers: int, tcn_out_channels: int, maxpool_out_channels: int = 1, normalize_embedding: bool = True)

Bases: torch.nn.Module

Encoder of a time series using a Temporal Convolution Network (TCN). The computed representation is the output of a fully connected layer applied to the output of an adaptive max pooling layer applied on top of the TCN, which reduces the length of the time series to a fixed size. Takes as input a three-dimensional tensor (B, C_in, L) where B is the batch size, C_in is the number of input channels, and L is the length of the input. Outputs a two-dimensional tensor (B, C_out), C_in is the number of input channels C_in=tcn_channels*

Parameters:

in_channels (int) – Number of input channels.
out_channels (int) – Dimension of the output representation vector.
kernel_size (int) – Kernel size of the applied non-residual convolutions.
tcn_channels (int) – Number of channels manipulated in the causal CNN.
tcn_layers (int) – Depth of the causal CNN.
tcn_out_channels (int) – Number of channels produced by the TCN. The TCN outputs a tensor of shape (B, tcn_out_channels, T)
maxpool_out_channels (int) – Fixed length to which each channel of the TCN is reduced.
normalize_embedding (bool) – Normalize size of the embeddings

Initialize internal Module state, shared by both nn.Module and ScriptModule.

network

normalize_embedding = True

forward(x)

class timesead.models.other.ncad.ContrastiveClassifier(distance: Callable[[torch.Tensor, torch.Tensor], str] | torch.Tensor)

Bases: torch.nn.Module

Contrastive Classifier. Calculates the distance between two random vectors, and returns an exponential transformation of it, which can be interpreted as the logits for the two vectors being different. p : Probability of x1 and x2 being different p = 1 - exp( -dist(x1,x2) )

Parameters:: distance (Union[Callable[[torch.Tensor, torch.Tensor], str], torch.Tensor]) – A Function which takes two (batches of) vectors and returns a (batch of) positive number.

distance

eps = 1e-10

forward(x1: torch.Tensor, x2: torch.Tensor) → torch.Tensor

Parameters:

x1 (torch.Tensor)
x2 (torch.Tensor)

Return type:

torch.Tensor

timesead.models.other.ncad.l2_distance(x1: torch.Tensor, x2: torch.Tensor) → torch.Tensor

Parameters:

x1 (torch.Tensor)
x2 (torch.Tensor)

Return type:

torch.Tensor

class timesead.models.other.ncad.NCAD(ts_channels: int, suspect_window_length: int = 1, tcn_kernel_size: int = 7, tcn_layers: int = 8, tcn_out_channels: int = 20, tcn_maxpool_out_channels: int = 8, embedding_rep_dim: int = 120, normalize_embedding: bool = True, distance: Callable | str = l2_distance)

Bases: timesead.models.BaseModel

Neural Contrastive Detection in Time Series

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Parameters:

ts_channels (int)
suspect_window_length (int)
tcn_kernel_size (int)
tcn_layers (int)
tcn_out_channels (int)
tcn_maxpool_out_channels (int)
embedding_rep_dim (int)
normalize_embedding (bool)
distance (Union[Callable, str])

suspect_window_length = 1

encoder

classifier

forward(inputs: Tuple[torch.Tensor, Ellipsis]) → torch.Tensor

Parameters:: inputs (Tuple[torch.Tensor, Ellipsis])
Return type:: torch.Tensor

timesead.models.other.ncad.coe_batch(x: torch.Tensor, y: torch.Tensor, coe_rate: float, suspect_window_length: int) → Tuple[torch.Tensor, torch.Tensor]

Contextual Outlier Exposure.

Parameters:

x (torch.Tensor) – Tensor of shape (batch, time, D)
y (torch.Tensor) – Tensor of shape (batch, )
coe_rate (float) – Number of generated anomalies as proportion of the batch size.
suspect_window_length (int)

Return type:

Tuple[torch.Tensor, torch.Tensor]

timesead.models.other.ncad.mixup_batch(x: torch.Tensor, y: torch.Tensor, mixup_rate: float) → Tuple[torch.Tensor, torch.Tensor]

Parameters:

x (torch.Tensor) – Tensor of shape (batch, time, D)
y (torch.Tensor) – Tensor of shape (batch, )
mixup_rate (float) – Number of generated anomalies as proportion of the batch size.

Return type:

Tuple[torch.Tensor, torch.Tensor]

class timesead.models.other.ncad.NCADTrainer(*args, coe_rate: float = 1.116, mixup_rate: float = 1.96, **kwargs)

Bases: timesead.optim.trainer.Trainer

Parameters:

coe_rate (float)
mixup_rate (float)

coe_rate = 1.116

mixup_rate = 1.96

validate_batch(network: torch.nn.Module, val_metrics: Dict[str, Callable], b_inputs: Tuple[torch.Tensor, Ellipsis], b_targets: Tuple[torch.Tensor, Ellipsis], *args, **kwargs) → Dict[str, float]

Parameters:

network (torch.nn.Module)
val_metrics (Dict[str, Callable])
b_inputs (Tuple[torch.Tensor, Ellipsis])
b_targets (Tuple[torch.Tensor, Ellipsis])

Return type:

Dict[str, float]

train_batch(network: NCAD, losses: List[timesead.optim.loss.Loss], optimizers: List[torch.optim.Optimizer], epoch: int, num_epochs: int, b_inputs: Tuple[torch.Tensor, Ellipsis], b_targets: Tuple[torch.Tensor, Ellipsis]) → List[float]

Parameters:

network (NCAD)
losses (List[timesead.optim.loss.Loss])
optimizers (List[torch.optim.Optimizer])
epoch (int)
num_epochs (int)
b_inputs (Tuple[torch.Tensor, Ellipsis])
b_targets (Tuple[torch.Tensor, Ellipsis])

Return type:

List[float]

class timesead.models.other.ncad.NCADAnomalyDetector(model: NCAD)

Bases: timesead.models.common.AnomalyDetector

Base class for all neural network modules.

Your models should also subclass this class.

Modules can also contain other Modules, allowing them to be nested in a tree structure. You can assign the submodules as regular attributes:

import torch.nn as nn
import torch.nn.functional as F

class Model(nn.Module):
    def __init__(self) -> None:
        super().__init__()
        self.conv1 = nn.Conv2d(1, 20, 5)
        self.conv2 = nn.Conv2d(20, 20, 5)

    def forward(self, x):
        x = F.relu(self.conv1(x))
        return F.relu(self.conv2(x))

Submodules assigned in this way will be registered, and will also have their parameters converted when you call to(), etc.

Note

As per the example above, an __init__() call to the parent class must be made before assignment on the child.

Variables:: training (bool) – Boolean represents whether this module is in training or evaluation mode.
Parameters:: model (NCAD)

Initialize internal Module state, shared by both nn.Module and ScriptModule.

model

compute_online_anomaly_score(inputs: Tuple[torch.Tensor, Ellipsis]) → torch.Tensor

Compute the online anomaly score for a batch of inputs. The output tensor must have the same shape as the output of format_targets when called with the corresponding targets for this batch. This method expects a window (or a batch of windows) as its input and should return a score for the last point in the window.

Parameters:: inputs (Tuple[torch.Tensor, Ellipsis]) – tuple of input tensors
Returns:: Tensor of shape (B,) that contains the anomaly scores for this batch
Return type:: torch.Tensor

compute_offline_anomaly_score(inputs: Tuple[torch.Tensor, Ellipsis]) → torch.Tensor

Compute the offline anomaly score for a batch of inputs. The output tensor must have the same shape as the output of format_targets when called with the corresponding targets for this batch. This method expects a window (or a batch of windows) as its input and should return a score for the last point in the window.

Parameters:: inputs (Tuple[torch.Tensor, Ellipsis]) – tuple of input tensors
Returns:: Tensor of shape (N,) that contains the anomaly scores for this batch
Return type:: torch.Tensor

fit(dataset: torch.utils.data.DataLoader) → None

Fit this anomaly detector on a dataset. Note that we assume only normal data here.

Parameters:: dataset (torch.utils.data.DataLoader) – A dataset
Return type:: None

format_online_targets(targets: Tuple[torch.Tensor, Ellipsis]) → torch.Tensor

Format the labels for a batch of targets. The output tensor must have the same shape as the output of compute_online_anomaly_score when called with the corresponding inputs for this batch.

Parameters:: targets (Tuple[torch.Tensor, Ellipsis]) – tuple of target tensors
Returns:: Tensor of shape (B,) that contains the ground truth labels for this batch
Return type:: torch.Tensor

class timesead.models.other.ncad.LocalOutlierInjectionTransform(parent: timesead.data.transforms.Transform, max_duration_spike: int = 2, spike_multiplier_range: Tuple[float, float] = (0.5, 2.0), spike_value_range: Tuple[float, float] = (-np.inf, np.inf), area_radius: int = 100, num_spikes: int = 10)

Bases: timesead.data.transforms.Transform

Inject spikes based on local noise

Parameters:

parent (timesead.data.transforms.Transform)
max_duration_spike (int)
spike_multiplier_range (Tuple[float, float])
spike_value_range (Tuple[float, float])
area_radius (int)
num_spikes (int)

max_duration_spike = 2

spike_multiplier_range = (0.5, 2.0)

spike_value_range

area_radius = 100

num_spikes = 10