# amitroy7781/gad-nr architecture

> Architecture diagram of the GitHub repository amitroy7781/gad-nr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amitroy7781/gad-nr
- Repository: https://github.com/amitroy7781/gad-nr

## Overview

##### Project Type and Purpose
- This is a research‐oriented Python implementation (via Jupyter notebooks) of the GAD-NR algorithm for graph anomaly detection. It is not a full‐stack web service but an experimental ML pipeline: data ingestion, model definition (encoder + decoder), training (loss computation), and evaluation benchmarks.

##### File Structure Analysis
- Top‐level files only:
- Benchmarking.ipynb – notebook to run experimental comparisons.
- GAD-NR.ipynb – notebook implementing the GAD-NR model end to end (data loading, training, evaluation).
- requirements.txt – Python dependencies.
- README.md – project description, architecture, usage, experimental results.

##### Key Insights from README
- Core model architecture:
- Encoder = Feature‐wise MLP → GNN message passing → node embeddings
- Decoder splits into three branches:
a. MLP for self‐feature reconstruction (MSE loss)
b. MLP for degree reconstruction (MSE loss)
c. MLP estimating Gaussian neighbor‐feature distribution (KL divergence)
- Data handling: sampling fixed-size neighbor sets per node.
- Evaluation: ROC AUC over structural, contextual, and joint anomaly types.

a. Main Components
- Data Ingestion Module
– Input: graph dataset (nodes + features + adjacency)
– Outliers generator (contextual & structural)
- Preprocessing & Sampling
– Neighbor sampler (sample_size parameter)
– Data loader constructs mini‐batches of (node, neighbors)
- Model (GAD-NR)
– Encoder block
· Feature MLP
· GNN layer (e.g., GCN)
– Decoder block (three parallel heads)
· Self‐feature MLP → ŷ_feature
· Degree MLP → ŷ_degree
· Gaussian MLP → μ, σ for neighbor features
- Loss & Optimization
– MSE(self‐feature) + MSE(degree) + KL(neighbor) weighted by λ’s
– Optimizer (e.g., Adam)
– Learning‐rate scheduler (if any)
- Evaluation & Benchmarking
– Compute anomaly scores
– ROC AUC, comparison plots (in Benchmarking.ipynb)

b. Relationships & Data Flow
1. Raw graph → Preprocessing
2. Preprocessed batches → Encoder → Latent embeddings
3. Embeddings → Decoder heads → Reconstructions / Distributions
4. Reconstructions + Ground truth → Loss computation
5. Gradients → Optimizer → Model update
6. Trained model → Evaluation module → Metrics/Plots

c. Architectural Patterns & Design Principles
- Modular separation: Data pipeline, model definition, training loop, evaluation
- Multi‐task learning: three reconstruction objectives combined
- Graph Neural Network pattern: encoder–decoder architecture
- Notebook orchestration: experiments as sequential cells rather than a packaged service

d. Key Technologies & Libraries
- PyTorch (+ torch‐geometric) for GNN layers
- Numpy/pandas for data handling
- Matplotlib/seaborn for result plots
- Jupyter notebooks as the entrypoint for experiments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dataset
    RAW["Raw Graph Dataset"]:::external

    %% Notebooks Orchestration
    NB1["GAD-NR.ipynb\n(entrypoint)"]:::notebook
    NB2["Benchmarking.ipynb\n(benchmark experiments)"]:::notebook

    %% Documentation
    README["README.md\n(project overview)"]:::docs
    REQ["requirements.txt\n(dependencies)"]:::docs

    %% Core Pipeline
    RAW --> NB1
    NB1 --> DataIngest
    DataIngest --> Preprocess
    Preprocess --> Encoder
    Encoder --> Decoder

    subgraph Decoder
        direction TB
        DecSelf["Decoder: Self-feature MLP"]:::green
        DecDegree["Decoder: Degree MLP"]:::green
        DecNeighbor["Decoder: Gaussian Neighbor MLP"]:::green
    end

    Decoder --> LossOpt
    LossOpt --> Evaluation
    Evaluation --> NB2

    %% Side docs
    README --> NB1
    REQ --> NB1

    %% Nodes with mapping
    DataIngest["Data Ingestion Module\n(sample_size, λ weights)"]:::blue
    Preprocess["Preprocessing & Sampling\n(neighbor sampler, data loader)"]:::blue
    Encoder["Encoder\nFeature MLP + GNN Layer"]:::green
    DecSelf["Decoder: Self-feature MLP"]:::green
    DecDegree["Decoder: Degree MLP"]:::green
    DecNeighbor["Decoder: Gaussian Neighbor MLP"]:::green
    LossOpt["Loss & Optimization\nMSE(self-feature)+MSE(degree)+KL(neighbor)\nOptimizer: Adam"]:::orange
    Evaluation["Evaluation Module\nROC AUC, Plots"]:::purple

    click DataIngest "https://github.com/amitroy7781/gad-nr/blob/master/GAD-NR.ipynb"
    click Preprocess "https://github.com/amitroy7781/gad-nr/blob/master/GAD-NR.ipynb"
    click Encoder "https://github.com/amitroy7781/gad-nr/blob/master/GAD-NR.ipynb"
    click DecSelf "https://github.com/amitroy7781/gad-nr/blob/master/GAD-NR.ipynb"
    click DecDegree "https://github.com/amitroy7781/gad-nr/blob/master/GAD-NR.ipynb"
    click DecNeighbor "https://github.com/amitroy7781/gad-nr/blob/master/GAD-NR.ipynb"
    click LossOpt "https://github.com/amitroy7781/gad-nr/blob/master/GAD-NR.ipynb"
    click Evaluation "https://github.com/amitroy7781/gad-nr/blob/master/GAD-NR.ipynb"
    click NB2 "https://github.com/amitroy7781/gad-nr/blob/master/Benchmarking.ipynb"
    click README "https://github.com/amitroy7781/gad-nr/blob/master/README.md"
    click REQ "https://github.com/amitroy7781/gad-nr/blob/master/requirements.txt"

    classDef blue fill:#D0E8F2,stroke:#0366d6,stroke-width:1px;
    classDef green fill:#C8E6C9,stroke:#2e7d32,stroke-width:1px;
    classDef orange fill:#FFE0B2,stroke:#e65100,stroke-width:1px;
    classDef purple fill:#E1BEE7,stroke:#6a1b9a,stroke-width:1px;
    classDef external fill:#CFD8DC,stroke:#455a64,stroke-width:1px,stroke-dasharray: 5 5;
    classDef notebook fill:#FFF9C4,stroke:#f9a825,stroke-width:1px,stroke-dasharray: 2 2;
    classDef docs fill:#F5F5F5,stroke:#9e9e9e,stroke-width:1px;
```
