CycPepGNN — GNN Baselines for Cyclic Peptide Membrane Permeability

Evaluating GNNs and Conformational Dynamics for Cyclic Peptide Membrane Permeability

CycPepGNN is a research repository for predicting the membrane permeability of cyclic peptides on the CycPeptMPDB dataset (PAMPA assay), optionally augmented with the CycPeptMPDB-4D conformational-dynamics features.

It accompanies a 6-page conference paper (see main.tex / main.pdf) that evaluates a graph neural network (GNN) baseline fused with RDKit descriptors and physicochemical properties, and analyzes why the gap to the state of the art (MSF-CPMP, MSE 0.092, R² 0.88) remains open.

Highlights

• Fully open-source pipeline. Every script downloads its own data at runtime from the public CycPeptMPDB and Zenodo archives — no manual download.
• Four comparable architectures sharing one auxiliary-feature fusion design: a 4-layer GIN Conv baseline, a 5-layer refined variant, an ablation harness with sequence encoding + SMILES-enumeration augmentation, and a frozen ChemBERTa-2 + Morgan-fingerprint variant.
• Pretrained checkpoints for the full-dataset and 4D variants at two hidden widths.
• Reproducible metrics (see table below) with feature lists and a pinned requirements.txt.

Results

Model	Data	Test MSE	Test R²
CycPepGNN (4× GINConv + 66 desc + 16 physchem)	Full (6,941)	0.601	0.467
CycPepGNN (+, 4D branch, 11 conf. features)	4D subset (5,160)	0.632	0.429
CycPeptMP (literature)	Full	0.271	0.780
MultiCycPermea (literature)	Full	0.160	~0.75
MSF-CPMP (SOTA, literature)	Full	0.092	0.88

Key finding: the 4D conformational features did not help the baseline — the dominant effect is the ~26 % reduction in dataset size (6,941 → 5,160). The gap to SOTA is attributed to SMILES-enumeration augmentation, monomer-level sequence encoding, and multi-task learning, all three of which are implemented in this repository so they can be ablated directly.

Repository layout

Path	Description
train.py	Baseline CycPepGNN: 4× GINConv + 66 RDKit descriptors + 16 physchem + optional 11 4D features. Runs full vs 4D experiments.
train_final.py	Refined variant: 5× GINConv + descriptors + amino-acid sequence one-hot + 4D, with configurable SMILES enumeration.
train_comprehensive.py	Ablation harness: 4D subset with/without 4D, with/without sequence encoding, with/without augmentation. (GPU-only, uses .cuda().)
train2.py	Frozen ChemBERTa-2 CLS embedding + 2048-bit Morgan fingerprint + descriptors + 4D. Downloads the HF model at runtime.
best_*.pt	Pretrained checkpoints (Full = full dataset, With4D = 4D branch; 512/1024 = hidden width).
cycpeptmpdb_raw.csv, cycpeptmpdb_4d.csv	Local snapshots of the two datasets. Not used by the scripts (they stream from the network at runtime).
main.tex, main.pdf	The paper (IEEEtran, 6 pages) — compile with pdflatex main.tex using the vendored ieee/IEEEtran.cls.
fig_*.png, results_*.png	Paper figures (architecture, dataset overview, results).
AGENTS.md	Agent onboarding notes for this repo.

Installation

Requires Python 3.9+, a CUDA-capable GPU (tested on an NVIDIA RTX 4060 Laptop, 8 GB), and network access at training time.

# 1) Install PyTorch with CUDA first (see https://pytorch.org), then:
pip install -r requirements.txt

# 2) torch_geometric needs its extension helpers:
pip install torch_geometric

# 3) rdkit is typically installed via conda:
conda install -c conda-forge rdkit    # or: pip install rdkit-pypi

transformers is only needed for train2.py.

Usage

Run any script and it downloads the dataset (~16 MB) at startup:

python train.py                 # baseline: full dataset + 4D experiments
python train_final.py           # refined variant with sequence encoding
python train_comprehensive.py   # ablation experiments (GPU only)
python train2.py                # ChemBERTa-2 + Morgan fingerprint variant

Each script prints test MSE / MAE / R² at the best validation checkpoint. Target PAMPA values are normalized to zero mean / unit variance internally and metrics are converted back to log P_app (cm/s) units.

Reproduction note. Reported numbers use a fixed random split convention (80/10/10) and seed = 42. Descriptor values are RDKit-version dependent; pin the versions in requirements.txt to match the paper exactly.

Paper

• main.tex / main.pdf (6 pages, IEEEtran conference format)
• Compile: pdflatex main.tex with the vendored class:

TEXINPUTS="./ieee:" pdflatex main.tex

Hugging Face model card

This repository is also published as a Hugging Face model repo: devansh0703/CycPepGNN on the Hub. The Hub copy includes this README (used as the model card), the pretrained checkpoints, the raw dataset snapshots, and all code/source of the paper.

import torch
checkpoint = torch.load("best_Full_1024.pt", map_location="cpu")  # see scripts for the full state dict layout

Citation

@misc{raulo2026cycpeptgnn,
  title  = {Evaluating GNNs and Conformational Dynamics for Cyclic Peptide Membrane Permeability},
  author = {Devansh Raulo},
  year   = {2026},
  howpublished = {\url{https://github.com/devansh0703/CycPepGNN}},
  note   = {Conference manuscript (6 pages), IEEEtran}
}

License

MIT — see LICENSE. Data files retain their original CycPeptMPDB / CycPeptMPDB-4D licenses (see the respective archives).