# imperial-qore/tranad architecture

> Architecture diagram of the GitHub repository imperial-qore/tranad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imperial-qore/tranad
- Repository: https://github.com/imperial-qore/tranad

## Overview

##### Main Components
- Data Repository: The “data” directory contains multiple datasets (e.g., SMAP_MSL, SMD, SWaT, etc.) organized by source and experiments. These datasets are the raw inputs for anomaly detection.
- Preprocessing Module: The preprocess.py script is responsible for taking these datasets and preparing them (format conversion, normalization, splitting, etc.) for model training and evaluation.
- Model Training/Execution Engine: The main.py is the primary entry point that accepts command-line parameters like “--model” and “--dataset”. It drives training and testing for different anomaly detection algorithms (TranAD, GDN, MAD_GAN, etc.).
- Model Components & Utilities: The “src” folder contains core modules:
- models.py for model implementations,
- diagnosis.py for evaluating and diagnosing results,
- dlutils.py, parser.py, plotting.py, and others that support the training, logging, and visualization process.
There’s also a configuration component (params.json in src and constants.py) that sets experiment parameters.
- Results & Visualization: The “results” directory stores output metrics while the “plots” directory holds generated visualizations (e.g., training graphs and anomaly detection outputs).

##### Relationships & Data Flow
- Input Flow: Raw datasets from the “data” folder are fed into the preprocessing module.
- Preprocessing Flow: Preprocess.py processes the datasets, ensuring that the formats align with what the training module expects.
- Training Pipeline: main.py initiates the training routine by accepting model and dataset inputs. It loads configurations from src/params.json and constants.
- Model Execution: Within main.py, the chosen model (e.g., TranAD or one of its ablated versions) is instantiated (via src/models.py) and then trained on the preprocessed data. Auxiliary modules in src (like diagnosis.py and utils.py) help with logging, evaluating, and diagnosing the anomaly detection performance.
- Output Flow: Once training and testing are complete, result metrics are written into the “results” folder and visualized via graphs stored in the “plots” folder. These outputs can also be used to conduct further ablation studies and comparisons.

##### Architectural Patterns & Design Principles
- Modular design: Separation between data preprocessing, model training, and evaluation.
- Configurability: Centralized parameters (params.json and constants.py) allow for reproducibility and varied experimental setups.
- Extensibility: The system supports multiple anomaly detection models (as well as ablation variants) making it easy to add future techniques.
- Pipeline orchestration: A clear pipeline from raw input to processing to training/testing to output generation.

##### Relevant Technologies & Frameworks
- Python (>=3.7) as the main language.
- PyTorch framework for deep learning (as indicated by installation instructions).
- Standard Python libraries for file handling, plotting (likely matplotlib or similar), and data manipulation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input Layer
    subgraph "Data Input"
        A["Data Repository"]:::data
        click A "https://github.com/imperial-qore/tranad/tree/main/data/"
        B["Preprocessing Module"]:::pre
        click B "https://github.com/imperial-qore/tranad/blob/main/preprocess.py"
        A -->|"InputData"| B
    end

    %% Training & Execution Layer
    subgraph "Training & Execution"
        C["Orchestration Engine (main.py)"]:::engine
        click C "https://github.com/imperial-qore/tranad/blob/main/main.py"
        B -->|"ProcessedData"| C

        %% Model Layer
        subgraph "Model Layer"
            D["Model Implementations (models.py)"]:::model
            click D "https://github.com/imperial-qore/tranad/blob/main/src/models.py"
            C -->|"InitiateTraining"| D
        end

        %% Configuration & Utilities
        subgraph "Configuration & Utilities"
            E["Params (params.json)"]:::config
            click E "https://github.com/imperial-qore/tranad/blob/main/src/params.json"
            F["Constants (constants.py)"]:::config
            click F "https://github.com/imperial-qore/tranad/blob/main/src/constants.py"
            G["Parser (parser.py)"]:::config
            click G "https://github.com/imperial-qore/tranad/blob/main/src/parser.py"
            H["DL Utils (dlutils.py)"]:::config
            click H "https://github.com/imperial-qore/tranad/blob/main/src/dlutils.py"
            I["Utility (utils.py)"]:::config
            click I "https://github.com/imperial-qore/tranad/blob/main/src/utils.py"
            C -->|"LoadConfig"| E
            C -->|"LoadConfig"| F
            C -->|"UseParser"| G
            C -->|"UseDLUtils"| H
            C -->|"UseUtils"| I
        end

        %% Evaluation & Visualization
        subgraph "Evaluation & Visualization"
            J["Diagnosis (diagnosis.py)"]:::eval
            click J "https://github.com/imperial-qore/tranad/blob/main/src/diagnosis.py"
            K["Plotting (plotting.py)"]:::eval
            click K "https://github.com/imperial-qore/tranad/blob/main/src/plotting.py"
            C -->|"RunDiagnosis"| J
            C -->|"GeneratePlots"| K
        end
    end

    %% Output Generation Layer
    subgraph "Output Generation"
        L["Results Repository"]:::output
        click L "https://github.com/imperial-qore/tranad/tree/main/results/"
        M["Plots Repository"]:::output
        click M "https://github.com/imperial-qore/tranad/tree/main/plots/"
        D -->|"OutputModel"| L
        J -->|"DiagnosticResults"| L
        K -->|"Visualizations"| M
    end

    %% Styles
    classDef data fill:#f9e79f,stroke:#b03a2e,stroke-width:2px;
    classDef pre fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef engine fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef model fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef config fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;
    classDef eval fill:#f5cba7,stroke:#e74c3c,stroke-width:2px;
    classDef output fill:#d1f2eb,stroke:#16a085,stroke-width:2px;
```
