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).
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.
- 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.
[ 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 ]
- uv (Recommended) or
pip - Python 3.11+
- CUDA-compatible GPU (Optional, for fast GNN training & ProtBERT inference)
# Clone the repository
git clone <repo-url>
cd gmn
# Sync virtual environment & install dependencies
uv syncDownload and clean the Bernett et al. (2024) gold-standard PPI dataset splits:
uv run scripts/preprocess_dataset.pyThis 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/.
Download PDB structure models from EBI AlphaFold, build residue interaction contact graphs (
uv run scripts/build_alphafold_db.pyOutputs are written to:
data/processed/alphafold/pdbs/: Downloaded.pdbstructure filesdata/processed/graphlets/: PyTorch Geometric graph objects ({pid}.pt)data/processed/seq_embeddings/: ProtBERT sequence embeddings
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.pyTo launch the MLflow UI and inspect performance metrics:
uv run mlflow uigmn/
├── 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
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.pymissing import andtrain_graphlet_gpu.pypath registry reference). - Unified Configuration: Add YAML-based configuration management for hyperparameters.
- Unit Test Suite: Implement
pytestcoverage 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.