DDI_single

Single-sequence domain assembly for multi-domain proteins

中文文档请参阅 README_ch.md

DDI_single (Domain Distance Inference, single-sequence) is a domain assembly method for multi-domain proteins that relies solely on the amino acid sequence. It uses the protein language model ESM-1b to extract sequence features and an improved Gated Cross-Attention module to predict inter-domain residue pair distances and orientations, enabling correct spatial assembly of structural domains.

Pipeline

The pipeline takes a protein sequence and domain definitions as input. ESM-1b extracts per-residue embeddings, which are split by domain and refined through 4 Gated Cross-Attention layers with 4 recycle iterations. The model predicts inter-domain distance and orientation distributions (d, ω, θ, φ), which are combined with intra-domain constraints and fed into Rosetta for 3D structure assembly.

---

Key Features

Feature	Description
Single-sequence input	No MSA or homologous templates required; uses ESM-1b for sequence embeddings
Gated cross-attention	Bidirectional cross-attention with gating to capture inter-domain residue interactions
Recycle refinement	4 rounds of iterative feature extraction to strengthen inter-domain relationship modeling
Multi-task prediction	Outputs distance (d) and dihedral angle (ω, θ, φ) distributions for inter-domain residue pairs
Rosetta integration	Predictions serve as spatial constraints for domain assembly and energy minimization

---

Performance

Inter-domain residue pair distance prediction accuracy (given known domain definitions):

Method	Top-10	Top-5	Top-1
trRosettaX_single	50.6%	55.6%	61.3%
DDI_single	74.5%	78.6%	83.2%

Domain assembly success rate (TM-score > 0.5):

Scenario	DDI_single	trRosettaX_single
Known domain conformations	74.4% (681 samples)	44.5%
Unknown domain conformations	73.9% (115 samples)	58.3%

---

Quick Start

1. Install dependencies

pip install torch fair-esm numpy einops huggingface_hub

ESM-1b pretrained weights (~2.5 GB) will be downloaded automatically on first run.

2. Download model weights

Model checkpoints are hosted on this repository (~4.7 GB):

huggingface-cli download SilenceZong/DDI_single DDI_single.pth --local-dir .

Or download with Python

from huggingface_hub import hf_hub_download

hf_hub_download(repo_id="SilenceZong/DDI_single", filename="DDI_single.pth", local_dir=".")

3. Prepare input

• FASTA file — full-length amino acid sequence (standard FASTA format)
• Domain ranges — 1-based residue intervals, multiple ranges separated by ;

Example FASTA:

>protein
MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSG...

Example domain definitions:

• Domain 1: 1-150;200-280 (two discontinuous segments)
• Domain 2: 151-199;281-400

4. Run prediction

python predict.py <fasta> <domain1> <domain2> <output.npz> [--weights PATH] [--device cpu|cuda]

# CPU (default)
python predict.py protein.fasta "1-150" "151-300" result.npz

# GPU
python predict.py protein.fasta "1-150" "151-300" result.npz --device cuda

# Custom weights path
python predict.py protein.fasta "1-150" "151-300" result.npz --weights /path/to/DDI_single.pth

5. Load results

Results are saved as .npz with the following fields:

Field	Shape	Description
dist	[1, 37, L1, L2]	Inter-domain Cβ distance distribution (2–20 &Angst;)
omega	[1, 25, L1, L2]	Ω dihedral angle distribution
theta	[1, 25, L1, L2]	θ dihedral angle distribution
phi	[1, 13, L1, L2]	φ dihedral angle distribution
domain1_index	[L1]	0-based indices of Domain 1 residues
domain2_index	[L2]	0-based indices of Domain 2 residues

import numpy as np

data = np.load("result.npz")
dist = data["dist"]          # shape: [1, 37, L1, L2]
d1_idx = data["domain1_index"]
d2_idx = data["domain2_index"]

---

Domain Assembly Workflow

Inter-domain constraints predicted by DDI_single can be combined with Rosetta for energy-minimization-based domain assembly:

1. Known domain conformations — Extract intra-domain constraints from PDB, predict inter-domain constraints with DDI_single, concatenate, and fold with Rosetta
2. Unknown domain conformations — Predict intra-domain constraints with trRosettaX_single first, then replace/enhance inter-domain constraints with DDI_single, and assemble with Rosetta

---

Model Architecture

Module	Description
Single_DDI_sESM	Wraps ESM-1b and the domain assembly network
GAU	Gated cross-attention unit with Pre-LN and GELU feed-forward layers
feature_extractor	Bidirectional cross-attention updating both domain representations
inter_head	Predicts d / ω / θ / φ from attention maps

Hyperparameters (config.py)

Parameter	Value
GAU layers	4
Attention heads	16
Head channels (GAU)	256
Prediction heads	40
Prediction head channels	128
Recycle iterations	4

---

Project Structure

DDI_single/
├── config.py          # Model and training hyperparameters
├── model.py           # Network architecture (GAU, Single_DDI, Single_DDI_sESM)
├── predict.py         # Inference script
├── pipeline.png       # Full pipeline diagram
├── DDI_single.pth     # Model weights
├── README.md          # English documentation
└── README_ch.md       # Chinese documentation

---

Citation

If you use DDI_single in your research, please cite:

@article{ddi_single,
  title   = {DDI_single: Single-sequence-based Domain Assembly via Gated Cross-Attention},
  author  = {Shengyi Zong},
  journal = {},
  year    = {}
}

Acknowledgements

• ESM — Protein language model
• trRosettaX — Single-sequence structure prediction baseline
• Rosetta — Structure modeling and energy minimization

License

Apache 2.0