# ResGrid-PepPI Standalone Package

ResGrid-PepPI is a two-task deep learning framework for peptide--protein interaction prediction and residue-level sequence labeling. The standalone package is organized to match the core innovations described in the manuscript:

1. **Dual-branch residual fusion for pair-level PepPIs prediction**  
   A stable dual-tower sequence branch is combined with a direct cross-chain interaction branch. The interaction branch is added as a residual correction through a learnable gate.

2. **Pair-specific residue-level sequence labeling**  
   Binding site identification is formulated as a sequence labeling task. Protein-side and peptide-side residues are assigned binding/non-binding labels under a specific peptide--protein pairing context.

3. **Cross/intra-chain context modeling**  
   Cross-chain attention captures partner-chain information, while intra-chain attention preserves sequence dependencies within each chain.

4. **Directional pair-grid aggregation**  
   A residue-level pair grid is constructed. Row, column, main-diagonal, and anti-diagonal contexts are extracted to model local interface continuity and complementary cross-chain matching patterns.

5. **Side-specific residue labeling heads**  
   Protein-side and peptide-side labeling heads are separated to learn residue-level sequence labeling patterns.

---

## Installation

```bash
conda create -n resgrid-peppi python=3.10 -y
conda activate resgrid-peppi
pip install -r requirements.txt
```

For GPU training, install the PyTorch build matching your CUDA version from the official PyTorch website.

---

## Configuration

Edit `configs/default.yaml`. All paths are placeholders and should be replaced by local paths:

```yaml
paths:
  task1_pairs: "/path/to/data/task1_pairs.csv"
  task2_contacts: "/path/to/data/task2_contacts.pkl"
  task1_embeddings: "/path/to/cache/task1_t5_embeddings"
  task2_embeddings: "/path/to/cache/task2_t5_embeddings"
  output_dir: "/path/to/output/resgrid_peppi_runs"
```

---

## Training

### Train Task 1 pair-level model

```bash
python scripts/train_task1.py --config configs/default.yaml
```

### Train Task 2 residue-level sequence labeling model

```bash
python scripts/train_task2.py --config configs/default.yaml
```

### Run two-task 5-fold cross-validation

```bash
python scripts/train_two_task_cv.py --config configs/default.yaml
```

---

## Inference

```bash
python scripts/predict.py \
  --config configs/default.yaml \
  --task1-checkpoint /path/to/checkpoints/best_task1_pair_model.pt \
  --task2-checkpoint /path/to/checkpoints/best_task2_residue_model.pt \
  --input examples/sample_pairs.csv \
  --output /path/to/output/predictions.csv
```

The output contains pair-level interaction probability and optional residue-level site probabilities when the Task 2 checkpoint is provided.

---

## Notes for website release

This package is designed as a clean standalone code release. It does not contain private data, absolute server paths, or local training logs. Replace placeholder paths with local paths before running.