Epion09g/MolGNN-Tox21-Predictor

🧬 Graph ML-Enabled Molecular Design Assistant using Graph Neural Networks

<div align="center">

    

🔬 An AI-powered molecular toxicity prediction web application using state-of-the-art Graph Neural Networks

🚀 Live Demo • 📖 Documentation • 🧠 Models • 📊 Results

</div>

📋 Table of Contents

• —Overview
• —Key Features
• —Live Demo
• —Tox21 Endpoints
• —Model Architectures
• —Model Performance
• —Installation
• —Usage
• —Project Structure
• —Technical Details
• —Deployment
• —Team
• —References
• —License

🎯 Overview

MolGNN Tox21 Predictor is a comprehensive molecular toxicity prediction system that leverages Graph Neural Networks (GNNs) to assess the potential toxicity of chemical compounds. The system predicts toxicity across all 12 endpoints of the Tox21 benchmark dataset, which is widely used in drug discovery, pharmaceutical research, and chemical safety assessment.

Why Graph Neural Networks for Molecules?

Molecules are naturally represented as graphs where:

• —Nodes = Atoms (with features like atomic number, charge, hybridization)
• —Edges = Chemical bonds (with features like bond type, aromaticity)

GNNs can learn molecular representations directly from this graph structure, capturing both local atomic environments and global molecular properties without requiring hand-crafted molecular descriptors.

✨ Key Features

🚀 Live Demo

Try the application now: https://huggingface.co/spaces/Epion09g/MolGNN-Tox21-Predictor

Quick Start Examples

Try these SMILES strings in the demo:

🎯 Tox21 Endpoints

The Tox21 dataset contains toxicity labels for 12 biological assays, divided into two categories:

Nuclear Receptor (NR) Panel

Stress Response (SR) Panel

🧠 Model Architectures

We implemented and compared three state-of-the-art GNN architectures:

1. GINE (Graph Isomorphism Network with Edge features)

Input → GINEConv(256) → BatchNorm → ReLU → Dropout
      → GINEConv(256) → BatchNorm → ReLU → Dropout
      → GINEConv(256) → BatchNorm → ReLU → Dropout
      → GINEConv(256) → BatchNorm → ReLU → Dropout
      → [MeanPool || SumPool] → Linear(512→256) → Linear(256→12)

Key Features:

• —Incorporates edge attributes (bond types)
• —Based on Weisfeiler-Lehman graph isomorphism test
• —Best theoretical expressiveness among the three

2. GCN (Graph Convolutional Network)

Input → GCNConv(256) → BatchNorm → ReLU → Dropout
      → GCNConv(256) → BatchNorm → ReLU → Dropout
      → GCNConv(256) → BatchNorm → ReLU → Dropout
      → GCNConv(256) → BatchNorm → ReLU → Dropout
      → [MeanPool || SumPool] → Linear(512→256) → Linear(256→12)

Key Features:

• —Classical spectral-based convolution
• —Efficient and well-understood
• —Good baseline performance

3. GATv2 (Graph Attention Network v2)

Input → GATv2Conv(256, heads=4) → BatchNorm → ELU → Dropout
      → GATv2Conv(256, heads=4) → BatchNorm → ELU → Dropout
      → GATv2Conv(256, heads=4) → BatchNorm → ELU → Dropout
      → GATv2Conv(256, heads=4) → BatchNorm → ELU → Dropout
      → [MeanPool || SumPool] → Linear(512→256) → Linear(256→12)

Key Features:

• —Dynamic attention mechanism
• —Multi-head attention (4 heads)
• —Learns to weight neighbor contributions

📊 Model Performance

Scaffold Split Results (Recommended for Realistic Evaluation)

Per-Endpoint Performance (GINE Model)

🛠️ Installation

Prerequisites

• —Python 3.10 or higher
• —pip package manager
• —(Optional) CUDA-compatible GPU for faster inference

Step 1: Clone the Repository

git clone https://github.com/eliot-99/Graph-ML-Enabled-Molecular-Design-Assistant-using-Graph-Neural-Networks.git
cd Graph-ML-Enabled-Molecular-Design-Assistant-using-Graph-Neural-Networks

Step 2: Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate (Linux/Mac)
source venv/bin/activate

# Activate (Windows)
venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Install PyTorch Geometric (if needed)

# For CPU
pip install torch_geometric
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.0.0+cpu.html

# For CUDA 11.8
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.0.0+cu118.html

Step 5: Run the Application

python app.py

Open your browser and navigate to: http://localhost:7860

📖 Usage

Single Molecule Prediction

1. 1.Enter a SMILES string in the input field
2. 2.Select a model (GINE, GCN, GATv2, or All)
3. 3.Click "Predict"
4. 4.View results with 2D/3D molecular visualization

Batch Prediction

1. 1.Prepare a CSV file with a column named SMILES:

   SMILES
   CCO
   CC(=O)Oc1ccccc1C(=O)O
   Cn1cnc2c1c(=O)n(c(=O)n2C)C

1. 1.Upload the CSV file
2. 2.Select model(s) for prediction
3. 3.Download results as CSV

API Usage (for Developers)

import requests

# Single prediction
response = requests.post('http://localhost:7860/predict', data={
    'smiles': 'CCO',
    'model': 'gnn'  # Options: gnn, gcn, gatv2, all
})
results = response.json()

📁 Project Structure

Graph-ML-Enabled-Molecular-Design-Assistant/
│
├── 📄 app.py                    # Flask web application
├── 📄 requirements.txt          # Python dependencies
├── 📄 Dockerfile               # Docker configuration
├── 📄 README.md                # This file
├── 📄 LICENSE                  # MIT License
│
├── 📁 models/                  # Pre-trained model weights
│   ├── best_gnn_tox21_scaffold.pt    # GINE model (~2MB)
│   ├── best_gcn_tox21_scaffold.pt    # GCN model (~2MB)
│   └── best_gatv2_tox21_scaffold.pt  # GATv2 model (~2MB)
│
├── 📁 templates/               # HTML templates
│   ├── index.html             # Main prediction interface
│   └── about.html             # About page
│
├── 📁 notebooks/               # Training notebooks
│   ├── GAT_Tox21.ipynb
│   ├── Tox21 classification with GATv2.ipynb
│   ├── Tox21 classification with GATv2_ver_2.ipynb
│   ├── train_esol.ipynb
│   └── tox21_gnn_comparison_scaffold.csv
│
└── 📁 data/                    # Auto-generated dataset cache

🔧 Technical Details

Molecular Featurization

Node Features (9 dimensions): | Feature | Description | Range | |---------|-------------|-------| | Atomic Number | Element type | 1-118 | | Chirality | Stereochemistry | 0-3 | | Formal Charge | Ionic charge | -2 to +2 | | Explicit Hs | Explicit hydrogens | 0-4 | | Hybridization | sp, sp2, sp3, etc. | 0-5 | | Aromaticity | Is aromatic? | 0-1 | | In Ring | Part of ring? | 0-1 | | Radical Electrons | Unpaired electrons | 0-2 | | Degree | Number of bonds | 0-6 |

Edge Features (3 dimensions): | Feature | Description | |---------|-------------| | Single Bond | Is single bond? (0/1) | | Double Bond | Is double bond? (0/1) | | Triple Bond | Is triple bond? (0/1) |

Training Configuration

{
    "optimizer": "Adam",
    "learning_rate": 0.001,
    "weight_decay": 1e-5,
    "batch_size": 64,
    "epochs": 100,
    "early_stopping_patience": 15,
    "dropout": 0.25,
    "hidden_channels": 256,
    "num_layers": 4,
    "pooling": "mean + sum",
    "split": "scaffold"
}

🌐 Deployment

Hugging Face Spaces (Current Deployment)

The app is deployed at: https://huggingface.co/spaces/Epion09g/MolGNN-Tox21-Predictor

Docker Deployment

# Build image
docker build -t molgnn-tox21 .

# Run container
docker run -p 7860:7860 molgnn-tox21

Local Development

python app.py
# Access at http://localhost:7860

👥 Team

This project was developed as part of an academic research initiative on Graph ML-Enabled Molecular Design at the intersection of machine learning and computational chemistry.

Contributors

📚 References

Papers

1. 1.Tox21 Challenge: Huang, R., et al. "Tox21Challenge to Build Predictive Models of Nuclear Receptor and Stress Response Pathways." Frontiers in Environmental Science (2016).

1. 1.MoleculeNet: Wu, Z., et al. "MoleculeNet: A Benchmark for Molecular Machine Learning." Chemical Science (2018). arXiv:1703.00564

1. 1.GIN: Xu, K., et al. "How Powerful are Graph Neural Networks?" ICLR (2019). arXiv:1810.00826

1. 1.GATv2: Brody, S., et al. "How Attentive are Graph Attention Networks?" ICLR (2022). arXiv:2105.14491

Libraries

• —PyTorch - Deep learning framework
• —PyTorch Geometric - GNN library
• —RDKit - Cheminformatics toolkit
• —Flask - Web framework
• —3Dmol.js - Molecular visualization

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

🙏 Acknowledgments

• —Tox21 Challenge organizers for the benchmark dataset
• —PyTorch Geometric team for the excellent GNN library
• —RDKit developers for cheminformatics tools
• —Hugging Face for free hosting on Spaces

<div align="center">

⭐ Star this repo if you find it useful!

Made with ❤️ for computational chemistry and drug discovery


</div>