Skip to content
matiolliptPublic

About

GraphletMolNet is a graphlet-based model to predict molecular interactions of proteins and ligands.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

GraphletMolNet (GMN)

Python 3.11+ uv PyTorch Geometric MLflow

GraphletMolNet (GMN) is a computational biology framework for predicting Protein-Protein Interactions (PPI) using graphlet-based structural topological representations, protein language model embeddings (ProtBERT), and Graph Neural Networks (GNN).


Overview

Traditional sequence-based PPI prediction models often struggle to capture 3D spatial binding interfaces. GraphletMolNet addresses this by converting protein tertiary structures (derived from AlphaFold models) into residue interaction contact graphs ("graphlets"). Using a Siamese Graph Convolutional Network (GCN), the model learns topological interaction representations to classify protein-protein pair link likelihood.

Key Features

  • Gold-Standard Dataset Ingestion: Downloads and cleans the Bernett et al. (2024) benchmark PPI dataset from Figshare, removing obsolete SwissProt accessions, duplicate interactions, and self-loops.
  • AlphaFold Graph Construction: Downloads 3D PDB structures (AF-{pid}-F1-model_v4.pdb) and transforms $C_\alpha$ contacts ($< 8.0\text{ \AA}$) into PyTorch Geometric graph structures with 20-dimensional amino acid features.
  • ProtBERT Embeddings: Computes per-protein mean-pooled sequence embeddings via Rostlab/prot_bert.
  • Siamese GNN Link Predictor: Trains a dual GCN encoder (GraphletEncoder) combined with a Hadamard product and absolute difference MLP classifier (GraphletLinkPredictor).
  • MLflow Tracking: Integrated experiment tracking for loss, balanced accuracy, ROC-AUC metrics, and model checkpoints.

Architecture & Data Flow

[ Figshare PPI Raw Data ] 
       │ 
       ▼ (scripts/preprocess_dataset.py)
[ Cleaned Splits: train.csv, val.csv, test.csv ]
       │ 
       ▼ (scripts/build_alphafold_db.py)
 ┌─────┴───────────────────────────────────────────┐
 │ Fetch AlphaFold PDBs ──► PyG Graphlets (.pt)    │
 │ Generate ProtBERT Sequence Embeddings            │
 └─────┬───────────────────────────────────────────┘
       │ 
       ▼ (scripts/train_graphlet_model.py)
[ Siamese GCN Link Predictor ] ──► [ MLflow Experiment Tracking ]

Getting Started

Prerequisites

  • uv (Recommended) or pip
  • Python 3.11+
  • CUDA-compatible GPU (Optional, for fast GNN training & ProtBERT inference)

Installation

# Clone the repository
git clone <repo-url>
cd gmn

# Sync virtual environment & install dependencies
uv sync

Usage Guide

1. Preprocess Datasets

Download and clean the Bernett et al. (2024) gold-standard PPI dataset splits:

uv run scripts/preprocess_dataset.py

This fetches raw Figshare splits (Intra1, Intra0, Intra2), removes obsolete SwissProt accessions (via UniProt FTP), strips duplicate interactor pairs and self-loops, and outputs train.csv, val.csv, and test.csv in data/raw/.

2. Fetch AlphaFold Structures & Build Graphlets

Download PDB structure models from EBI AlphaFold, build residue interaction contact graphs ($C_\alpha &lt; 8.0\text{ \AA}$), filter long sequences ($&gt;1500$ residues), and compute ProtBERT sequence embeddings:

uv run scripts/build_alphafold_db.py

Outputs are written to:

  • data/processed/alphafold/pdbs/: Downloaded .pdb structure files
  • data/processed/graphlets/: PyTorch Geometric graph objects ({pid}.pt)
  • data/processed/seq_embeddings/: ProtBERT sequence embeddings

3. Model Training & Evaluation

Train the Siamese Graphlet GNN model with MLflow experiment tracking:

# Standard training run
uv run scripts/train_graphlet_model.py

# GPU training run (using filtered dataset splits)
uv run scripts/train_graphlet_gpu.py

To launch the MLflow UI and inspect performance metrics:

uv run mlflow ui

Project Structure

gmn/
├── AGENTS.md                 ← Operational guidelines for AI agents
├── pyproject.toml            ← Package configuration & uv dependencies
├── README.md                 ← Project documentation
├── gmn/                      ← Core library package
│   ├── __init__.py
│   ├── paths.py              ← Central path registry
│   ├── logger_setup.py       ← Project-wide logging configuration
│   ├── fetch.py              ← Figshare dataset downloader & cleaner
│   ├── pdb_utils.py          ← AlphaFold PDB downloader & PyG graph builder
│   ├── protein_embedding.py  ← ProtBERT sequence embedding generator
│   ├── datasets.py           ← PyTorch Datasets & graphlet pair collator
│   ├── graphlet_model.py     ← GraphletEncoder & GraphletLinkPredictor (Siamese GCN)
│   ├── models.py             ← Alternate GCN link predictor module
│   └── training_helpers.py   ← Training and evaluation helper stubs
├── scripts/                  ← Execution Scripts & Entrypoints
│   ├── preprocess_dataset.py ← Download and clean gold-standard dataset splits
│   ├── build_alphafold_db.py ← PDB structure retrieval, graphlet generation, ProtBERT
│   ├── build_local_alphafold.py ← Legacy AlphaFold database builder script
│   ├── train_graphlet_model.py  ← Main GNN model training entrypoint with MLflow
│   └── train_graphlet_gpu.py    ← GPU variant training script
├── data/                     ← Data storage (raw / interim / processed)
├── docs/                     ← Technical documentation (`fetch.md`)
└── notebooks/                ← Exploratory data analysis notebooks

Roadmap & Production Goals

The matched protein representation baseline is staged separately from the legacy training pipeline. See baseline checkpoints and commands for the traceable registry, strict structure audit, frozen sampling, and review gates.

  • Script Refactoring: Resolve legacy script issues (build_local_alphafold.py missing import and train_graphlet_gpu.py path registry reference).
  • Unified Configuration: Add YAML-based configuration management for hyperparameters.
  • Unit Test Suite: Implement pytest coverage for graph construction, dataset collators, and network layers.
  • Multi-Modal Integration: Fuse ProtBERT sequence embeddings with GCN topological representations.
  • CI/CD Pipeline: Add GitHub Actions for automated linting (ruff) and testing.

Tip

Always use uv run to ensure scripts execute within the managed virtual environment.

About

GraphletMolNet is a graphlet-based model to predict molecular interactions of proteins and ligands.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages