GPCRact

This repository serves as the official implementation and reproducibility package for the paper
GPCRact: a hierarchical framework for predicting ligand-induced GPCR activity via allosteric communication modeling (Briefings in Bioinformatics, 2026).

We provide the complete source code, preprocessed datasets, training scripts, and analysis notebooks required to reproduce the findings presented in the manuscript.

🚀 Key Features

• Mechanism-Driven Architecture: Combines E(n)-equivariant GNNs with dual attention to model "binding → allosteric propagation → activity"
• Functionally Critical Subgraphs: Efficient 3D atomistic graph construction focusing on binding and allosteric sites.
• Reproducible Pipeline: Fully automated workflow from raw PDB/Bioassay data to final evaluation.
• Bias-Aware Benchmarking: Includes rigorous scaffold-based splits and re-implementations of SOTA baselines.

📋 Table of Contents

• Repository Structure
• Installation
• Reproducibility Workflow
  • Step 1: Data Construction
  • Step 2: Model Training
  • Step 3: Inference
  • Step 4: Benchmarking
  • Step 5: Analysis & Figure Generation
• Citation
• Contact

---

📁 Repository Structure

We have unified all resources into a single structured repository to facilitate full reproducibility.

GPCRact/
├── analysis/           # Jupyter Notebooks for reproducing figures and statistical analyses
├── benchmarks/         # Implementation of baseline models (DeepREAL, AiGPro, 3D-GNN)
├── configs/            # Configuration files (YAML) for training and HPO
├── data/               # Datasets
│   ├── raw/            # Raw data files (GPCRactDB v1)
│   ├── resources/      # Auxiliary bio-info files (PDB info, MSA, etc.)
│   └── splits/         # Exact Train/Val/Test scaffold splits used in the paper
├── preprocessing/      # Scripts to reconstruct the dataset from scratch
├── scripts/            # Executable scripts for Training, Inference, and HPO
├── src/                # Core library code (Model architecture, Layers, Dataloaders)
├── environment.yml     # Conda environment file
└── README.md           # Master documentation

⚙️ Installation

We recommend using Conda to manage the environment for full reproducibility.

1. Clone the repository:

   git clone https://github.com/hyojin0912/HJ-GPCRact.git
   cd HJ-GPCRact

2. Create and activate the Conda environment:

   conda env create -f environment.yml
   conda activate gpcract

   Alternatively, you can install packages using pip:

   pip install -r requirements.txt

🔬 Reproducibility Workflow

This section explicitly delineates the steps to reproduce the results reported in our study.

Step 1: Data Construction

Users can reconstruct the GPCRactDB from raw public data or use the pre-generated splits provided in data/splits/. To build from scratch, follow the pipeline in the preprocessing/ directory:

# Example: Running the final dataset creation step
jupyter notebook preprocessing/04_create_final_dataset.ipynb

• Note: The exact scaffold-based split files (scaffold_train.csv, scaffold_val.csv, scaffold_test.csv) used in our study are already provided in data/splits/ to ensure fair benchmarking.

Step 2: Training the Model 🏋️‍♂️

To train the GPCRact model from scratch using the provided splits:

1. Configure: Modify configs/training_config.yaml if necessary.
2. Run: Execute the training script.

python scripts/train.py \
    --data_dir data/splits \
    --save_dir checkpoints/ \
    --epochs 100

For detailed arguments, see scripts/README.md.

Step 3: Inference 🚀

To predict the activity (Agonist/Antagonist/Non-binder) of novel GPCR-ligand pairs using a trained model:

python scripts/inference.py \
    --data_dir data/splits \
    --model_path checkpoints/best_model.pt \
    --output_dir results/

Step 4: Benchmarking 📊

We provide the full source code and execution scripts for the baseline models compared in the manuscript (DeepREAL, AiGPro, 3D-GNN). All baselines were retrained on the identical GPCRact dataset.

• DeepREAL: See benchmarks/DeepREAL/

• AiGPro: See benchmarks/AiGPro/ (Docker support included)

• 3D-GNN Baseline: See benchmarks/3D-GNN/

Step 5: Analysis & Figure Generation 📉

To reproduce the statistical analyses, mechanistic interpretations, and main figures (Fig 1, 3, 4, 7), run the notebooks in the analysis/ directory.

• 01_receptor_dynamics_analysis.ipynb: Structural ground truth analysis (Fig 1).

• 02_sequence_structure_correlation.ipynb: MSA vs. 3D dynamics (Fig 3).

• 03_activity_decision_tree.ipynb: Decision tree for activity rules (Fig 4).

• 04_mechanistic_interpretability.ipynb: Attention weight analysis (Fig 7).

Supplementary Validations: PRS analysis, Sensitivity analysis, and Mutation studies are also included.

🎓 Citation

If you use GPCRact in your research, please cite the following paper:

@article{son2026gpcract,
  title={GPCRact: a hierarchical framework for predicting ligand-induced GPCR activity via allosteric communication modeling},
  author={Son, Hyojin and Yi, Gwan-Su},
  journal={Briefings in Bioinformatics},
  volume={27},
  number={1},
  pages={bbaf719},
  year={2026},
  doi={10.1093/bib/bbaf719}
}

📬 Contact

For questions, bug reports, or feedback, please contact Hyojin Son at hyojin0912@kaist.ac.kr.