Blame for README.md

---
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**

![License](https://img.shields.io/badge/license-MIT-blue.svg)

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).