# ml4bm-lab/gennius architecture

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

- Interactive diagram: https://gitdiagram.com/ml4bm-lab/gennius
- Repository: https://github.com/ml4bm-lab/gennius

## Overview

##### Overall Project Type and Purpose
- This is a computational biology project focusing on drug–target interaction (DTI) prediction using graph neural networks.
- Its purpose is to generate drug–target predictions faster and more accurately by leveraging a GNN encoder and a neural network classifier.
- The project includes both core model training/inference and extensive preprocessing, validation, and baseline experiments, as well as support for grid-search hyperparameter tuning and docker-based deployment.

##### Main Components
A. Data Management and Preprocessing:
- Data Input: Represent the raw and processed datasets (Data/Raw, Data directory with annotated and preprocessed files, and multiple datasets like DRUGBANK, BIOSNAP, etc.).
- Preprocessing Modules: Include Code/data_preprocessing.py, Code/data_preprocessing_removing_repeated_edges.py, and equivalent scripts in Baselines and pretrain_protemb directories.
- External Data Sources: For example, data fetched from PubChem, Uniprot (as noted for protein embeddings).

B. Core Model Components:
- GNN Encoder: Based on SAGEConv layers (4 hidden layers, Tanh activation, sum aggregation) as described in the README.
- NN-Classifier: Two-layer linear model with ReLU activations, also using a sum aggregation.
- Main Execution Flow: Represent Code/main.py that ties these model components together and accepts parameters (e.g., embedding dimension).

C. Training, Evaluation, and Validation:
- Training Pipeline: Illustrate the module where the model is trained (with Adam optimizer, specific learning rate, and dropout parameters) as part of the Code scripts.
- Evaluation Scripts: Include Code/validation.py, Code/compare_dtis_retrieve_unknown.py, and supporting scripts that generate TSVs and figures (e.g., figure_boxplot_inferring_dtis.py).

D. Baselines and Comparative Studies:
- Baselines Directory: Split into sub-components such as simple_baselines (with logistic regression and random forest implementations), feature_corr for assessing feature correlations, and pretrain_protemb for experiments involving pre-trained protein embeddings.
- Generalization Analysis: Highlight the pipeline under Baselines/simple_baselines/baseline_generalization and scripts like execute4generalization.py, which assess performance across multiple datasets.

E. Experiment Management and Deployment:
- Hyperparameter Tuning: Include the GridSearchCodes folder that holds scripts for grid search (gridsearch_GeNNius.py, generate_grid.py).
- Docker: Represent the Dockerfile and instructions how containerization is used to run the experiments in a consistent environment.
- Logging and Results: Show directories like Results for output files and logs to complete the feedback loop.

##### Relationships and Data Flow
- Data flows from the “Data/Raw” and “Data/Annotation” into the preprocessing modules, which then produce “HeteroData” objects ready for training.
- Preprocessed data feeds into the core training routine (invoked by Code/main.py and supported by utilities in Code/utils.py).
- The trained model (embedding generation via the GNN encoder and classification via the NN classifier) is then used for inference, DTI prediction, or generalization analyses.
- Evaluation and visualization components (in Code/validation.py and Code/tsnes) interact with the output from the core model.
- Baselines and grid search experiments run parallel pipelines to benchmark performance against the main GeNNius model.
- The Docker environment encapsulates the complete system for consistent execution, linking to the build pipeline from Docker/Dockerfile.

##### Architectural Patterns and Design Principles
- There is a clear separation between data ingestion/preprocessing, model training, evaluation, and result visualization.
- The code is modularized into directories (Code, Baselines, Data, GridSearchCodes) that indicate discrete concerns and allow for extensibility.
- Integration of external resources (e.g., Uniprot embeddings) and baseline experiments as parallel comparative pipelines.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Management
    subgraph "Data Management"
        A1["Raw Data Input"]:::data
        A2["Annotated Data Input"]:::data
    end

    %% External Data Sources
    C["External Data Sources (PubChem/Uniprot)"]:::external

    %% Preprocessing Modules
    subgraph "Preprocessing Modules"
        B1["Preprocessing: Code/data_preprocessing.py"]:::preproc
        B2["Preprocessing: Code/data_preprocessing_removing_repeated_edges.py"]:::preproc
        B3["Protein Preprocessing: Code/data_preprocessing_prot.py"]:::preproc
        B4["Protein Preprocessing: Code/data_preprocessing_removing_repeated_edges_prot.py"]:::preproc
    end

    %% Main Execution & Core Model
    D["Main Execution Flow (Training) - Code/main.py"]:::train
    E["Core Model: GNN Encoder & NN-Classifier - Code/GeNNius.py"]:::core

    %% Evaluation Modules
    subgraph "Evaluation"
        F1["Evaluation: Code/validation.py"]:::eval
        F2["Comparison: Code/compare_dtis_retrieve_unknown.py"]:::eval
    end

    %% Visualization Modules
    subgraph "Visualization"
        G1["Figure: Code/figure_boxplot_inferring_dtis.py"]:::visual
        G2["t-SNE Visualization: Code/tsnes"]:::visual
    end

    %% Baselines and Comparative Studies
    subgraph "Baselines & Comparative Studies"
        H1["Baselines: simple_baselines"]:::baseline
        H2["Pre-trained Protein Embeddings: Baselines/pretrain_protemb"]:::baseline
    end

    %% Hyperparameter Tuning
    I["Hyperparameter Tuning: GridSearchCodes"]:::hptype

    %% Docker Deployment
    J["Docker Deployment: Docker/Dockerfile"]:::docker

    %% Logging and Results
    subgraph "Logging & Results"
        K1["Results Directory"]:::logging
        K2["Baselines/simple_baselines/Results"]:::logging
    end

    %% Data flow relationships
    A1 -->|"feeds"| B1
    A2 -->|"feeds"| B1
    C -->|"supplies"| B3
    B1 --> D
    B2 --> D
    B3 --> D
    B4 --> D
    D --> E
    E -->|"informs"| F1
    E -->|"informs"| F2
    E -->|"informs"| G1
    E -->|"informs"| G2

    %% Parallel experiment pipelines
    B1 -->|"used by"| H1
    B3 -->|"used by"| H2
    A1 -->|"supports"| I
    A2 -->|"supports"| I
    D --> I

    %% Logging of results
    D --> K1
    D --> K2
    H1 --> K1
    H1 --> K2
    H2 --> K1
    H2 --> K2
    I  --> K1
    I  --> K2

    %% Docker deployment link
    D -->|"containerized by"| J

    %% Click Events
    click A1 "https://github.com/ml4bm-lab/gennius/tree/main/Data/Raw"
    click A2 "https://github.com/ml4bm-lab/gennius/tree/main/Data/Annotation"
    click B1 "https://github.com/ml4bm-lab/gennius/blob/main/Code/data_preprocessing.py"
    click B2 "https://github.com/ml4bm-lab/gennius/blob/main/Code/data_preprocessing_removing_repeated_edges.py"
    click B3 "https://github.com/ml4bm-lab/gennius/blob/main/Baselines/pretrain_protemb/Code/data_preprocessing_prot.py"
    click B4 "https://github.com/ml4bm-lab/gennius/blob/main/Baselines/pretrain_protemb/Code/data_preprocessing_removing_repeated_edges_prot.py"
    click D "https://github.com/ml4bm-lab/gennius/blob/main/Code/main.py"
    click E "https://github.com/ml4bm-lab/gennius/blob/main/Code/GeNNius.py"
    click F1 "https://github.com/ml4bm-lab/gennius/blob/main/Code/validation.py"
    click F2 "https://github.com/ml4bm-lab/gennius/blob/main/Code/compare_dtis_retrieve_unknown.py"
    click G1 "https://github.com/ml4bm-lab/gennius/blob/main/Code/figure_boxplot_inferring_dtis.py"
    click G2 "https://github.com/ml4bm-lab/gennius/tree/main/Code/tsnes"
    click H1 "https://github.com/ml4bm-lab/gennius/tree/main/Baselines/simple_baselines"
    click H2 "https://github.com/ml4bm-lab/gennius/tree/main/Baselines/pretrain_protemb"
    click I "https://github.com/ml4bm-lab/gennius/tree/main/GridSearchCodes"
    click J "https://github.com/ml4bm-lab/gennius/tree/main/Docker/Dockerfile"
    click K1 "https://github.com/ml4bm-lab/gennius/tree/main/Results"
    click K2 "https://github.com/ml4bm-lab/gennius/tree/main/Baselines/simple_baselines/Results"

    %% Styles
    classDef data fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef preproc fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef train fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef core fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef eval fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef visual fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
    classDef baseline fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef hptype fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef docker fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef logging fill:#E8F8F5,stroke:#17A589,stroke-width:2px;
```
