# atanu2531/hats architecture

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

- Interactive diagram: https://gitdiagram.com/atanu2531/hats
- Repository: https://github.com/atanu2531/hats

## Overview

##### Project Type and Purpose
- This is a research-oriented machine learning codebase implementing HATS (Hierarchical Graph Attention Network) for two tasks:
a. Node classification (predicting stock movement at the node/company level)

##### High-Level File Structure Analysis
- Top-level
– README.md (project overview, usage, dependencies)
– node_classification/
– graph_classification/
- Each task directory
– Makefile & download.sh (data acquisition & execution entry points)
– src/
· base/ (base_model.py, base_train.py) – abstract classes for model structure & training loop
· config.py – hyperparameters, file paths, task-specific settings
· dataset.py – data loading + preprocessing from local files
· models/ (HATS.py) – concrete implementation of the hierarchical graph attention network
· trainer.py or graph_trainer.py – orchestration of forward/backward passes for node vs graph tasks
· evaluator.py or graph_evaluator.py – metric computation & result aggregation
· logger.py – logging utility
· main.py – ties together config → dataset → trainer → evaluator → logger

##### Key Components
A. External Data Sources (Yahoo Finance API, Wikidata)
B. Data Acquisition Layer
- download.sh (Bash script) → local raw data files
- Makefile target “download”
C. Configuration Module
- config.py defines paths, hyperparameters (learning rate, epochs, batch size)
D. Data Preprocessing & Dataset Module
- dataset.py reads raw CSV/JSON, applies normalization, constructs graph objects (adjacency, features)
E. Base Classes
- base_model.py – abstract graph neural net interface
- base_train.py – generic training loop implementation
F. Model Implementation
- HATS.py – hierarchical graph attention layers, aggregation from node to higher levels
G. Task-Specific Trainers
- node trainer vs graph trainer – batch creation, forward/backward, checkpointing
H. Evaluators
- evaluator.py / graph_evaluator.py – accuracy, F1, AUC calculations
I. Logger
- logger.py – metrics & hyperparameter logging to console or file
J. Orchestration (main.py)
- initializes config → instantiates dataset, model, trainer, evaluator → runs training/testing

##### Relationships & Data Flows
External Data → download.sh → Raw Data Storage → dataset.py → Processed Dataset
Processed Dataset + Config → Trainer → Model ← Base Classes
Trainer → Evaluator → Logger → Output Results
- For graph_classification, an extra “data_type” parameter flows from Makefile into config to select sub-graph sector.

##### Architectural Patterns & Design Principles
- Pipeline architecture: clear separation of concerns (data, config, model, training, evaluation)
- Template Method pattern in base_train.py / base_model.py providing hook methods overridden by HATS.py
- Modular design: identical module structure reused across two tasks for maintainability
- Script-driven orchestration via Makefile + main.py, enabling reproducibility

##### Technologies & Frameworks
- Python 3.x
- TensorFlow 1.11.0 for all neural network operations
- NumPy for numerical preprocessing
- Bash + Makefile for data download and experiment orchestration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Sources
    Yahoo["Yahoo Finance API"]:::external
    Wiki["Wikidata"]:::external

    %% Graph Classification Pipeline
    subgraph "Graph Classification Pipeline"
        direction TB
        g_make["Makefile"]:::data_acq
        g_download["download.sh"]:::data_acq
        g_raw["Raw Data"]:::storage
        g_dataset["dataset.py"]:::data_acq
        g_processed["Processed Dataset"]:::storage
        g_config["config.py"]:::config
        g_base_model["base_model.py"]:::model
        g_base_train["base_train.py"]:::model
        g_HATS_graph["HATS.py"]:::model
        g_graph_trainer["graph_trainer.py"]:::train_eval
        g_graph_evaluator["graph_evaluator.py"]:::train_eval
        g_logger_graph["logger.py"]:::train_eval
        g_main_graph["main.py"]:::config
    end

    %% Node Classification Pipeline
    subgraph "Node Classification Pipeline"
        direction TB
        n_make["Makefile"]:::data_acq
        n_download["download.sh"]:::data_acq
        n_raw["Raw Data"]:::storage
        n_dataset["dataset.py"]:::data_acq
        n_processed["Processed Dataset"]:::storage
        n_config["config.py"]:::config
        n_base_model["base_model.py"]:::model
        n_base_train["base_train.py"]:::model
        n_HATS_node["HATS.py"]:::model
        n_trainer["trainer.py"]:::train_eval
        n_evaluator["evaluator.py"]:::train_eval
        n_logger["logger.py"]:::train_eval
        n_main["main.py"]:::config
    end

    %% Flows for Graph Pipeline
    Yahoo --> g_make
    Wiki --> g_make
    g_make --> g_download
    g_download --> g_raw
    g_raw --> g_dataset
    g_dataset --> g_processed
    g_processed --> g_config
    g_config --> g_base_model
    g_base_model --> g_HATS_graph
    g_base_train --> g_HATS_graph
    g_HATS_graph --> g_graph_trainer
    g_graph_trainer --> g_graph_evaluator
    g_graph_evaluator --> g_logger_graph
    g_logger_graph --> g_main_graph

    %% Flows for Node Pipeline
    Yahoo --> n_make
    Wiki --> n_make
    n_make --> n_download
    n_download --> n_raw
    n_raw --> n_dataset
    n_dataset --> n_processed
    n_processed --> n_config
    n_config --> n_base_model
    n_base_model --> n_HATS_node
    n_base_train --> n_HATS_node
    n_HATS_node --> n_trainer
    n_trainer --> n_evaluator
    n_evaluator --> n_logger
    n_logger --> n_main

    %% Click Events - Graph Classification
    click g_make "https://github.com/atanu2531/hats/tree/master/graph_classification/Makefile"
    click g_download "https://github.com/atanu2531/hats/blob/master/graph_classification/download.sh"
    click g_dataset "https://github.com/atanu2531/hats/blob/master/graph_classification/src/dataset.py"
    click g_config "https://github.com/atanu2531/hats/blob/master/graph_classification/src/config.py"
    click g_base_model "https://github.com/atanu2531/hats/blob/master/graph_classification/src/base/base_model.py"
    click g_base_train "https://github.com/atanu2531/hats/blob/master/graph_classification/src/base/base_train.py"
    click g_HATS_graph "https://github.com/atanu2531/hats/blob/master/graph_classification/src/models/HATS.py"
    click g_graph_trainer "https://github.com/atanu2531/hats/blob/master/graph_classification/src/graph_trainer.py"
    click g_graph_evaluator "https://github.com/atanu2531/hats/blob/master/graph_classification/src/graph_evaluator.py"
    click g_logger_graph "https://github.com/atanu2531/hats/blob/master/graph_classification/src/logger.py"
    click g_main_graph "https://github.com/atanu2531/hats/blob/master/graph_classification/src/main.py"

    %% Click Events - Node Classification
    click n_make "https://github.com/atanu2531/hats/tree/master/node_classification/Makefile"
    click n_download "https://github.com/atanu2531/hats/blob/master/node_classification/download.sh"
    click n_dataset "https://github.com/atanu2531/hats/blob/master/node_classification/src/dataset.py"
    click n_config "https://github.com/atanu2531/hats/blob/master/node_classification/src/config.py"
    click n_base_model "https://github.com/atanu2531/hats/blob/master/node_classification/src/base/base_model.py"
    click n_base_train "https://github.com/atanu2531/hats/blob/master/node_classification/src/base/base_train.py"
    click n_HATS_node "https://github.com/atanu2531/hats/blob/master/node_classification/src/models/HATS.py"
    click n_trainer "https://github.com/atanu2531/hats/blob/master/node_classification/src/trainer.py"
    click n_evaluator "https://github.com/atanu2531/hats/blob/master/node_classification/src/evaluator.py"
    click n_logger "https://github.com/atanu2531/hats/blob/master/node_classification/src/logger.py"
    click n_main "https://github.com/atanu2531/hats/blob/master/node_classification/src/main.py"

    %% Styles
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px
    classDef data_acq fill:#cff,stroke:#036,stroke-width:1px
    classDef storage fill:#eef,stroke:#036,stroke-width:1px
    classDef config fill:#eec,stroke:#630,stroke-width:1px
    classDef model fill:#cfc,stroke:#060,stroke-width:1px
    classDef train_eval fill:#fec,stroke:#c60,stroke-width:1px
```
