# shenwzh3/rgat-absa architecture

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

- Interactive diagram: https://gitdiagram.com/shenwzh3/rgat-absa
- Repository: https://github.com/shenwzh3/rgat-absa

## Overview

##### Project type and purpose
- This is an open-source machine-learning research project: a PyTorch-based implementation of the “Relational Graph Attention Network for Aspect-based Sentiment Analysis.”
- Its primary purpose is to preprocess text corpora (SemEval and Twitter), build relational graph representations of sentences, train a GAT/GNN model on those graphs, and evaluate sentiment classification performance.

##### File structure
Top-level directories and scripts:
- data/ – raw data (XML, JSON) and preprocessed assets (PKL files, parsed JSONs) for SemEval and Twitter.
- data_preprocess_semeval.py & data_preprocess_twitter.py – extraction & dependency-parsing pipelines.
- datasets.py – PyTorch Dataset wrappers over preprocessed files.
- tree.py & tree_samples.json – constructs sentence dependency graphs.
- model*.py (model.py, model_gcn.py, model_utils.py) – definition of embedding layers (GloVe, BERT), graph attention layers, model forward logic.
- trainer.py – encapsulates training loop, loss, backprop, checkpointing.
- run.py & run.sh – CLI interface: parameter parsing, orchestrates preprocess (optional), dataset loading, model instantiation, training, evaluation.
- data/output-*/ – directories capturing model checkpoints, cached embeddings/vocabs, and evaluation results.

##### Key insights from README
- Uses external pre-trained embeddings: Stanford GloVe & HuggingFace BERT.
- Preprocessing may be skipped if using provided data/.
- Training entrypoint: run.sh → run.py, parameterizable.
- Core dependencies: Python 3.6, PyTorch 1.2.0, Transformers, CUDA.

##### Main components
a. Data Layer
– Raw Data Sources: SemEval XML, Twitter text
– Preprocessed Data: parsed JSON, PKLs (vocab, embeddings)
b. Preprocessing Pipeline
– data_preprocess_*.py → dependency parsing → JSON outputs
c. Dataset Module
– datasets.py wraps processed files into PyTorch Datasets & DataLoaders
d. Embedding Interfaces
– GloVeLoader (reads glove_dir)
– BERTLoader (loads pretrained bert-base-uncased)
e. Graph Construction
– tree.py builds adjacency matrices / edge lists / relation-type encodings
f. Model
– model_gcn.py: Relational Graph Attention layers, classifier head
– model_utils.py: utilities for masks, attention mechanism
g. Training Engine
– trainer.py: training loop, optimizer setup, checkpoint saving
h. Runner / Orchestrator
– run.py / run.sh: CLI parameter parser, component instantiation, invokes Trainer
i. Outputs
– Checkpoints, cached PKLs (vocab & embeddings), eval_results.txt

##### Component interactions and data flow
- DataLoader → Batch of (graph, features, labels) → Model → Predictions
- Predictions + Labels → Trainer computes Loss → Backprop → Model parameters updated
- Trainer → Checkpoint manager writes model weights & cached data to data/output-*
- Trainer after each epoch or at end → Evaluation module writes eval_results.txt

##### Architectural patterns & principles
– Pipeline pattern: distinct stages (preprocess → dataset → model → train → eval)
– Modular design: interchangeable embedding backends (GloVe vs. BERT)
– Separation of concerns: data handling vs. model vs. training logic

##### Technologies & frameworks
– Python 3.6.8, PyTorch 1.2.0 (autograd, Datasets, DataLoader)
– HuggingFace Transformers for BERT
– CUDA 9.0 for GPU acceleration
– Standard NLP tools for dependency parsing (e.g., spaCy or biaffine parser)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Layer
    subgraph "Data Layer"
        RS("SemEval XML"):::data
        RT("Twitter Text"):::data
        PJS("SemEval Parsed JSONs"):::data
        PJT("Twitter Parsed JSONs"):::data
        PKL("Cached PKLs"):::data
        ER("Evaluation Results (eval_results.txt)"):::data
    end

    %% Preprocessing Pipeline
    subgraph "Preprocessing Pipeline"
        PS("data_preprocess_semeval.py"):::process
        PT("data_preprocess_twitter.py"):::process
    end

    %% Dataset & DataLoader
    subgraph "Dataset Module"
        DS("datasets.py"):::process
        DL("DataLoader"):::process
    end

    %% Embedding Interfaces
    subgraph "Embedding Interfaces"
        EL("model_utils.py"):::process
        GL("GloVe Files"):::external
        BL("BERT Model"):::external
    end

    %% Graph Construction
    subgraph "Graph Construction"
        TM("tree.py"):::process
        TS("tree_samples.json"):::process
    end

    %% Model
    subgraph "Model Definitions"
        MD("model.py"):::model
        MG("model_gcn.py"):::model
    end

    %% Training Engine
    subgraph "Training Engine"
        TR("trainer.py"):::process
    end

    %% Runner / Orchestrator
    subgraph "Runner / Orchestrator"
        RP("run.py"):::process
        RShell("run.sh"):::process
    end

    %% Data Flow
    RS -->|raw XML| PS
    RT -->|raw text| PT
    PS -->|.json outputs| PJS
    PT -->|.json outputs| PJT
    PJS --> DS
    PJT --> DS
    DS --> DL
    DL -->|batch of graphs + features| MG
    DS -->|vocab indices| MD
    EL --> MG
    GL --> EL
    BL --> EL
    TM --> MG
    TS --> TM
    MG -->|predictions| TR
    MD -->|model utils| TR
    TR -->|checkpoints| PKL
    TR -->|eval results| ER
    RP --> RShell
    RShell --> RP
    RP --> DS
    RP --> PS
    RP --> PT
    RP --> TR

    %% Click Events
    click RS "https://github.com/shenwzh3/rgat-absa/blob/master/data/semeval14/*.xml"
    click RT "https://github.com/shenwzh3/rgat-absa/blob/master/data/twitter/*.raw"
    click PJS "https://github.com/shenwzh3/rgat-absa/blob/master/data/semeval14/*_depparsed.json"
    click PJT "https://github.com/shenwzh3/rgat-absa/blob/master/data/twitter/*_depparsed.json"
    click PKL "https://github.com/shenwzh3/rgat-absa/blob/master/data/output-gcn*/pkls/*.pkl"
    click ER "https://github.com/shenwzh3/rgat-absa/blob/master/data/output-gcn/eval_results.txt"
    click PS "https://github.com/shenwzh3/rgat-absa/blob/master/data_preprocess_semeval.py"
    click PT "https://github.com/shenwzh3/rgat-absa/blob/master/data_preprocess_twitter.py"
    click DS "https://github.com/shenwzh3/rgat-absa/blob/master/datasets.py"
    click EL "https://github.com/shenwzh3/rgat-absa/blob/master/model_utils.py"
    click TM "https://github.com/shenwzh3/rgat-absa/blob/master/tree.py"
    click TS "https://github.com/shenwzh3/rgat-absa/blob/master/tree_samples.json"
    click MD "https://github.com/shenwzh3/rgat-absa/blob/master/model.py"
    click MG "https://github.com/shenwzh3/rgat-absa/blob/master/model_gcn.py"
    click TR "https://github.com/shenwzh3/rgat-absa/blob/master/trainer.py"
    click RP "https://github.com/shenwzh3/rgat-absa/blob/master/run.py"
    click RShell "https://github.com/shenwzh3/rgat-absa/blob/master/run.sh"

    %% Styles
    classDef data fill:#cce5ff,stroke:#1f78b4,stroke-width:1px;
    classDef process fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef model fill:#ffe5b4,stroke:#ff8c00,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#ebebeb,stroke:#6c757d,stroke-width:1px,stroke-dasharray: 2 2;
```
