| --- |
| license: mit |
| pipeline_tag: other |
| library_name: pytorch |
| tags: |
| - graph-neural-network |
| - cyclic-peptides |
| - permeability |
| - molecular-property-prediction |
| - chemistry |
| - particle-permeability |
| base_model: seyonec/PubChem10M_SMILES_BPE_450k |
| --- |
| |
| # 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](https://github.com/akiyamalab/cycpeptmp) |
| dataset (PAMPA assay), optionally augmented with the |
| [CycPeptMPDB-4D](https://zenodo.org/records/18754430) conformational-dynamics |
| features. |
|
|
| It accompanies a 6-page conference paper (see [`main.tex`](main.tex) / |
| [`main.pdf`](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. |
|
|
| ```bash |
| # 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: |
|
|
| ```bash |
| 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: |
|
|
| ```bash |
| TEXINPUTS="./ieee:" pdflatex main.tex |
| ``` |
|
|
| ## Hugging Face model card |
|
|
| This repository is also published as a Hugging Face model repo: |
| **[devansh0703/CycPepGNN](https://huggingface.co/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. |
|
|
| ```python |
| import torch |
| checkpoint = torch.load("best_Full_1024.pt", map_location="cpu") # see scripts for the full state dict layout |
| ``` |
|
|
| ## Citation |
|
|
| ```bibtex |
| @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`](LICENSE). Data files retain their original CycPeptMPDB / |
| CycPeptMPDB-4D licenses (see the respective archives). |
