# bozdaglab/graf architecture

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

- Interactive diagram: https://gitdiagram.com/bozdaglab/graf
- Repository: https://github.com/bozdaglab/graf

## Overview

##### Project Type and Purpose
- GRAF is a research/experimental Python project for Graph Attention-aware Fusion Networks. It implements graph neural network (GNN) models that leverage both node-level and association-level attention to fuse multiple heterogeneous networks. The ultimate goal is to compute fused networks and then apply Graph Convolutional Networks (GCN) for node classification. The README and file tree confirm that it is not a full-stack web application or extensive open-source tool but rather a self-contained experimental research codebase.
- The project is designed for generating network embeddings, evaluating performance with metrics (F1 scores, accuracy, etc.) and outputting results in a structured folder (GRAF_results).

##### File Structure
- The top-level file GRAF.py acts as the entry point for running the experiment.
- The sampledata folder contains the input dataset (e.g., DrugADR.pkl).
- The GRAF_results folder stores all outputs:
- Contains results folders labeled with hyperparameter/configuration info (e.g., “DrugADR_0.01_32_10”).
- Within these, several subfolders (e.g., GRAF_prob_0.9 and GRAF_prob_1) store pickled embeddings, excel sheets with evaluation metrics, and attention weights in .pkl and .xlsx formats.
- Configuration details (e.g., hyperparameters for early stopping, learning rates, hidden sizes) are encoded into the folder names, which is important for tracking experiments.
- The LICENSE.txt and README.md files provide the background and legal information, while the environment package versions listed ensure reproducibility.

##### Key Components
- Data Input Module:
- Source: sampledata folder (e.g., DrugADR.pkl).
- Responsible for loading and preprocessing inputs.
- Main Execution Script:
- The GRAF.py file orchestrates the execution.
- Graph Attention and Fusion Module:
- Contains both the node-level attention mechanism and association-level attention mechanism.
- Network fusion process that aggregates the learned attentions and applies edge elimination.
- Graph Convolutional Network (GCN) Module:
- Implements the GCN architecture on the fused network, incorporating node features.
- Result Processing and Output Module:
- Saves intermediate files (attention vectors, fused network) and final results (embeddings, .xlsx metric summaries) inside subfolders within GRAF_results.
- Dependencies & Environment:
- Underlying frameworks such as PyTorch, Torch-Geometric, and associated libraries.
- These can be depicted as external dependencies supporting the computation modules.

##### Relationships and Data Flow
- The script then processes the data through the Graph Attention & Fusion Module where two distinct attention paths (node-level and association-level) are computed.
- Their outputs are fused together and refined through selective edge elimination.
- The refined (fused) network is then passed into the GCN module which produces the final node embeddings/outputs.
- The results are stored (both intermediate artifacts and final metrics) to the GRAF_results directory for further analysis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    DataInput["Data Input"]:::data
    MainScript["Main Execution Script"]:::core

    subgraph "Graph Attention Module"
        NodeAttention["Node-Level Attention"]:::module
        AssocAttention["Association-Level Attention"]:::module
    end
    AttentionFusion["Attention Fusion & Edge Elimination"]:::module

    NetworkFusion["Network Fusion Component"]:::module

    subgraph "Graph Convolutional Network (GCN) Module"
        GCN_09["GCN Output (Prob0.9)"]:::module
        GCN_1["GCN Output (Prob1)"]:::module
    end

    Results["Result Processing and Output Module"]:::results

    Dependencies["External Dependencies (PyTorch, Torch-Geometric, numpy, pandas)"]:::external

    DataInput -->|"loads"| MainScript
    MainScript -->|"triggers"| NodeAttention
    MainScript -->|"triggers"| AssocAttention
    NodeAttention -->|"attends"| AttentionFusion
    AssocAttention -->|"attends"| AttentionFusion
    AttentionFusion -->|"merges"| NetworkFusion
    NetworkFusion -->|"feeds"| GCN_09
    NetworkFusion -->|"feeds"| GCN_1
    GCN_09 -->|"outputs"| Results
    GCN_1 -->|"outputs"| Results

    MainScript ---|"depends"| Dependencies
    NodeAttention ---|"depends"| Dependencies
    AssocAttention ---|"depends"| Dependencies
    GCN_09 ---|"depends"| Dependencies
    GCN_1 ---|"depends"| Dependencies

    click DataInput "https://github.com/bozdaglab/graf/blob/main/sampledata/DrugADR.pkl"
    click MainScript "https://github.com/bozdaglab/graf/blob/main/GRAF.py"
    click AttentionFusion "https://github.com/bozdaglab/graf/blob/main/GRAF_results/DrugADR_0.01_32_10/Attentions.xlsx"
    click NetworkFusion "https://github.com/bozdaglab/graf/blob/main/GRAF_results/DrugADR_0.01_32_10/Fused_network.pkl"
    click GCN_09 "https://github.com/bozdaglab/graf/blob/main/GRAF_results/DrugADR_0.01_32_10/GRAF_prob_0.9"
    click GCN_1 "https://github.com/bozdaglab/graf/tree/main/GRAF_results/DrugADR_0.01_32_10/GRAF_prob_1"
    click Results "https://github.com/bozdaglab/graf/tree/main/GRAF_results"

    classDef data fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#1b4f72,stroke-width:2px;
    classDef module fill:#d5f5e3,stroke:#196f3d,stroke-width:2px;
    classDef results fill:#fadbd8,stroke:#922b21,stroke-width:2px;
    classDef external fill:#ebdef0,stroke:#6c3483,stroke-width:2px;
```
