DOCSEARCHbyAlgolia
Submit Docs

OmniAnomaly Documentation

repository·master·Indexed 21 days ago

https://github.com/netmanaiops/omnianomaly

A stochastic recurrent neural network for anomaly detection in multivariate time series, combining Gated Recurrent Units (GRU) and Variational Auto-encoders (VAE). It supports datasets including SMAP, MSL, and SMD, and utilizes reconstruction probability and the Peak Over Threshold (POT) algorithm for identifying anomalies. The project is designed for Python 3.5 or 3.6.

Tokens
2.4K
Snippets
7
Records
9
Agent score
26%

What's inside OmniAnomaly

  1. How OmniAnomaly processes data

    master

    When running main.py with default settings, the system follows this lifecycle:

    1. Training: Trains the model on the training set with periodic validation and default early stopping.
    2. Scoring: Tests the model on both the training and testing sets, saving the resulting anomaly scores to train_score.pkl and test_score.pkl.
    3. Evaluation: Identifies the best F1 score on the testing set and prints the results.
    4. Thresholding: Initializes a POT (Peak Over Threshold) model on train_score to determine the anomaly score threshold, then uses this threshold to make final predictions on the testing set.

  2. Run OmniAnomaly training and testing

    master

    Execute the main pipeline using python main.py. You can customize the execution by modifying the ExpConfig object within main.py or by passing command-line arguments to override settings like the dataset or maximum epochs.

    # Run with default configuration
python main.py

# Run with custom dataset and max_epoch
python main.py --dataset='MSL' --max_epoch=20

  3. Install OmniAnomaly

    master

    To use OmniAnomaly, clone the repository and install the required dependencies using pip. It is recommended to use a virtual environment. Note that the project is designed for Python 3.5 or 3.6.

    git clone https://github.com/smallcowbaby/OmniAnomaly && cd OmniAnomaly
pip install -r requirements.txt

  5. Download and prepare datasets

    master

    OmniAnomaly supports three datasets: SMAP, MSL, and SMD.

    1. SMD (Server Machine Dataset): Located in the ServerMachineDataset folder.
    2. SMAP and MSL: These NASA datasets can be downloaded using wget and unzip as shown below.

    After downloading, ensure you have the labeled_anomalies.csv file in the data directory.

    # Download SMAP and MSL
wget https://s3-us-west-2.amazonaws.com/telemanom/data.zip && unzip data.zip && rm data.zip

cd data && wget https://raw.githubusercontent.com/khundman/telemanom/master/labeled_anomalies.csv

  6. Run an OmniAnomaly experiment

    master

    The main() function orchestrates the full lifecycle of an anomaly detection experiment: data loading, model construction, training, prediction, and evaluation.

    To run the project, you typically instantiate ExpConfig, parse command-line arguments to override defaults, and then call main(). The execution flow is:

    1. Data Preparation: Uses get_data to load training and testing sets.
    2. Model Construction: Initializes OmniAnomaly within a TensorFlow variable_scope named 'model'.
    3. Training: Uses the Trainer class to fit the model to the training data.
    4. Prediction: Uses the Predictor class to generate scores for both training and testing sets.
    5. Evaluation: Performs threshold searching via bf_search and Peak-Over-Threshold (POT) evaluation via pot_eval.
    6. Persistence: Saves model variables to save_dir and results (scores, metrics) to result_dir.
    from omni_anomaly.main import ExpConfig, main
from argparse import ArgumentParser
from tfsnippet.utils import register_config_arguments

if __name__ == '__main__':
    config = ExpConfig()
    arg_parser = ArgumentParser()
    register_config_arguments(config, arg_parser)
    arg_parser.parse_args()
    main()

  7. Configure OmniAnomaly via ExpConfig

    master

    The ExpConfig class (inheriting from Config) is the central way to manage experiment settings. It covers dataset selection, model architecture, training hyperparameters, evaluation parameters, and output paths.

    Key configuration groups include:

    • Dataset: dataset (e.g., "machine-1-1"), x_dim, max_train_size, max_test_size.
    • Model Architecture: use_connected_z_q, use_connected_z_p, z_dim, rnn_cell ('GRU', 'LSTM', or 'Basic'), rnn_num_hidden, window_length, dense_dim, posterior_flow_type ('nf' or None), and nf_layers.
    • Training: max_epoch, batch_size, l2_reg, initial_lr, lr_anneal_factor, lr_anneal_epoch_freq, gradient_clip_norm, and early_stop.
    • Evaluation: test_n_z, test_batch_size, bf_search_min, bf_search_max, bf_search_step_size, and level (for POT algorithm).
    • Outputs: save_dir, restore_dir, result_dir, train_score_filename, test_score_filename, and save_z.

    Recommended level values for the POT algorithm:

    • SMAP: 0.07
    • MSL: 0.01
    • SMD group 1: 0.0050
    • SMD group 2: 0.0075
    • SMD group 3: 0.0001
    from omni_anomaly.main import ExpConfig
from argparse import ArgumentParser
from tfsnippet.utils import register_config_arguments

config = ExpConfig()
arg_parser = ArgumentParser()
register_config_arguments(config, arg_parser)
arg_parser.parse_args()
# config is now populated with command line overrides

  8. Dataset specifications for SMAP, MSL, and SMD

    master

    OmniAnomaly is evaluated on the following datasets:

    Dataset nameNumber of entitiesNumber of dimensionsTraining set sizeTesting set sizeAnomaly ratio(%)
    SMAP552513518342761713.13
    MSL2755583177372910.72
    SMD28387084057084204.16

    SMD Details: This dataset contains 28 different machines (named machine-<group_index>-<index>). Each machine's subset is split into equal halves for training and testing. It includes test_label (anomaly status) and interpretation_label (dimensions contributing to the anomaly).

  9. Reference: ExpConfig parameters

    master

    The following parameters are available in the ExpConfig class for controlling the OmniAnomaly pipeline.

    # dataset configuration
dataset = "machine-1-1"
x_dim = get_data_dim(dataset)

# model architecture configuration
use_connected_z_q = True
use_connected_z_p = True

# model parameters
z_dim = 3
rnn_cell = 'GRU'  # 'GRU', 'LSTM' or 'Basic'
rnn_num_hidden = 500
window_length = 100
dense_dim = 500
posterior_flow_type = 'nf'  # 'nf' or None
nf_layers = 20  # for nf
max_epoch = 10
train_start = 0
max_train_size = None  # `None` means full train set
batch_size = 50
l2_reg = 0.0001
initial_lr = 0.001
lr_anneal_factor = 0.5
lr_anneal_epoch_freq = 40
lr_anneal_step_freq = None
std_epsilon = 1e-4

# evaluation parameters
test_n_z = 1
test_batch_size = 50
test_start = 0
max_test_size = None  # `None` means full test set

# the range and step-size for score for searching best-f1
bf_search_min = -400.
bf_search_max = 400.
bf_search_step_size = 1.

valid_step_freq = 100
gradient_clip_norm = 10.

early_stop = True  # whether to apply early stop method

# pot parameters
level = 0.01

# outputs config
save_z = False  # whether to save sampled z in hidden space
get_score_on_dim = False  # whether to get score on dim. If `True`, the score will be a 2-dim ndarray
save_dir = 'model'
restore_dir = None  # If not None, restore variables from this dir
result_dir = 'result'  # Where to save the result file
train_score_filename = 'train_score.pkl'
test_score_filename = 'test_score.pkl'