README.md

---
license: mit
language:
- en
- zh
tags:
- OneScience
- life-science
- protein
- binding-site
- GPSite
frameworks: PyTorch
---

<p align="center">
  <strong>
    <span style="font-size: 30px;">GPSite</span>
  </strong>
</p>

# Model Introduction

GPSite is a geometry-aware multitask network for protein binding-site prediction. It simultaneously predicts potential binding sites between protein residues and DNA, RNA, peptides, proteins, ATP, heme (HEM), and various metal ions. The method uses sequence representations generated by a pretrained protein language model and predicted structures to perform binding-site prediction, without relying on MSA or experimentally resolved protein structures.

Paper:

> **Genome-scale annotation of protein binding sites via language model and geometric deep learning**  
> https://doi.org/10.7554/eLife.93695

# Model Description

GPSite takes a protein FASTA sequence as input. The complete inference workflow first uses ESMFold to predict the protein structure and ProtT5-XL-UniRef50 to extract sequence representations. It then combines the predicted structure with DSSP features to construct residue-level geometric representations, and finally uses the GPSite graph neural network to output residue-level prediction scores for multiple binding-site types simultaneously.

# Use Cases

| Use case | Description |
| --- | --- |
| Protein binding-site prediction | Predict residue-level binding-site scores from a protein sequence |
| Multi-ligand binding analysis | Simultaneously predict binding sites for DNA, RNA, peptides, proteins, ATP, HEM, and various metal ions |
| Prediction without an experimental structure | Use ESMFold to predict the structure without providing an experimentally resolved structure in advance |
| Batch protein sequence analysis | Perform structure prediction, feature extraction, and site prediction on multiple protein sequences in a FASTA file |

# Usage

## 1. Using OneCode

Experience intelligent one-click AI4S programming in the OneCode online environment:

[Try intelligent one-click AI4S programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Installation and Usage

**Hardware Requirements**

- A GPU/DCU is recommended for running GPSite because ESMFold structure prediction in the complete workflow requires substantial computation and GPU memory.
- GPSite supports CPU execution, but the structure prediction stage is significantly slower without a GPU/DCU.

### Set Up the Runtime Environment

#### DCU Environment

```bash
# Activate DTK and CONDA first
conda create -n onescience311 python=3.11 -y
conda activate onescience311

# Install with uv support
pip install onescience[bio] \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai
```

#### Environment Notes
- If you encounter missing dependencies or version incompatibilities during execution, refer to the dependency versions specified in `requirements.txt` and install or adjust the relevant dependencies as needed.
- The following versions are recommended for ProtTrans-related dependencies:

```bash
python -m pip install \
  "transformers==4.30.1" \
  "tokenizers==0.13.3" \
  "sentencepiece==0.1.99"
```

- ESMFold-related dependencies can be installed as follows:

```bash
python -m pip install "fair-esm[esmfold]"
python -m pip install modelcif==0.7
```

- GPSite also requires `dllogger`. If online installation fails, download the `dllogger` source code and install it locally from the source directory:

```bash
python -m pip install /path/to/dllogger-master
```

### Prepare Weights and Models

Complete GPSite inference depends not only on the GPSite weights in this repository, but also on ProtT5, ESMFold, and ESM-2 weights. Complete the following preparations before first use.

#### 1) GPSite Model Weights

The `model/` directory in the GPSite repository contains five trained weights:

```text
model/
├── fold0.ckpt
├── fold1.ckpt
├── fold2.ckpt
├── fold3.ckpt
└── fold4.ckpt
```

During inference, the five models above are loaded in sequence and their prediction results are averaged. The complete model package downloaded from Hugging Face should already include these weights required for GPSite inference, so separate downloads are normally unnecessary.

#### 2) ProtT5-XL-UniRef50

GPSite uses ProtT5-XL-UniRef50 to extract protein sequence representations. The model can be downloaded from:

```text
https://zenodo.org/record/4644188
```

After downloading the model, make sure that `PROTTRANS_DIR` in `scripts/run_infer.sh` points to the actual model directory. `scripts/predict.py` reads this path through the `PROTTRANS_PATH` environment variable.

#### 3) ESMFold and ESM-2

The official version of GPSite automatically downloads ESMFold and ESM-2 on the first run. If the runtime environment has limited network access or is offline, prepare the local weights in advance. The recommended location is:

```text
weight/checkpoints/
├── esmfold_3B_v1.pt
├── esm2_t36_3B_UR50D.pt
└── esm2_t36_3B_UR50D-contact-regression.pt
```

Also make sure that `ESMFOLD_HUB_DIR` in `scripts/run_infer.sh` points to the `weight` directory within the project.

ESMFold v1 also loads ESM-2 internally, so at least the following files are required:

```text
esmfold_3B_v1.pt
esm2_t36_3B_UR50D.pt
```
It is also recommended to keep:

```text
esm2_t36_3B_UR50D-contact-regression.pt
```

#### 4) DSSP

GPSite calls the following during structural feature extraction:

```text
scripts/feature_extraction/mkdssp
```

Before first use, make sure that this file has execute permission:

```bash
chmod +x scripts/feature_extraction/mkdssp
```

## 3. Quick Start

### Download the Model Package

```bash
hf download OneScience-Group/GPSite --local-dir ./GPSite
cd GPSite
```
- Complete GPSite inference additionally depends on **ProtT5-XL-UniRef50, ESMFold, ESM-2, and OpenFold**. Follow "Prepare Weights and Models" to install the relevant models, weights, and OpenFold first.
- GPSite additionally depends on OpenFold. OpenFold must be installed in the current Python/Conda environment; its source code does not need to remain in the project directory. To install from source, download and extract the OpenFold source code, then run the following in the source directory:

```bash
python3 setup.py install
```

# Example Data

The official GPSite example input is located at:

```text
conf/example/demo.fa
```

The input uses the standard FASTA format:

```text
>protein_id
MSEQUENCE...
```

GPSite automatically creates an output subdirectory based on the FASTA filename. For example, if the input is `conf/example/demo.fa`, the output will be located at:

```text
<OUTPUT_DIR>/demo/
```

# Inference

Before running inference, enter the GPSite project root and make sure that the model paths in `scripts/run_infer.sh` have been changed to the actual paths in your environment:

```bash
cd /path/to/GPSite
```

In particular, check:

```bash
PROTTRANS_DIR="/path/to/prot_t5_xl_uniref50"
ESMFOLD_HUB_DIR="/path/to/weight"
```

The basic usage of the inference script is:

```bash
bash scripts/run_infer.sh <GPU_ID> <FASTA_PATH> <OUTPUT_DIR>
```

Arguments:

| Argument | Description |
| --- | --- |
| `<GPU_ID>` | GPU index to use; in a single-GPU environment, this is typically `0` |
| `<FASTA_PATH>` | Path to the input FASTA file; a relative or absolute path can be used |
| `<OUTPUT_DIR>` | Root output directory; the script automatically creates a subdirectory based on the FASTA filename |

Run the demo:

```bash
bash scripts/run_infer.sh 0 ./conf/example/demo.fa ./results/
```

The command above reads `conf/example/demo.fa` and generates intermediate files and final prediction results under `./results/demo/`.

Run your own FASTA file:

```bash
bash scripts/run_infer.sh 0 /path/to/your.fa ./results/
```

For example, if the input file is `/public/home/user/test.fa` and the root output directory is `./results/`, the final prediction results are typically located at:

```text
./results/test/pred/
```

During inference, GPSite sequentially performs ESMFold structure prediction, ProtT5 sequence representation extraction, DSSP structural feature extraction, and prediction with the five GPSite models. When the process completes successfully, the terminal log should contain messages similar to:

```text
Feature extraction is done
Prediction is done
Results are saved in <OUTPUT_DIR>/<FASTA_NAME>/pred/
```

## Inference Workflow

The complete inference workflow is:

```text
FASTA input
  ↓
ESMFold structure prediction
  ↓
ProtT5 sequence representation extraction
  ↓
PDB / DSSP / geometric feature processing
  ↓
GPSite five-model inference
  ↓
Average the outputs of the five models
  ↓
Residue-level scores for 10 binding-site types
```

# Output Description

Assuming that the input file is `demo.fa` and the root output directory is `./results/`, the final prediction results are located at:

```text
./results/demo/pred/
```

The main results include:

```text
pred/
├── overview.txt
├── A0A009IHW8.txt
└── A0A011QK89.txt
```

The files are:

- `overview.txt`: Summary of the overall prediction results for all input proteins.
- `<Protein_ID>.txt`: Residue-level prediction results for the corresponding protein.

The residue-level prediction files contain scores for the following 10 binding-site types:

```text
DNA
RNA
Peptide
Protein
ATP
HEM
ZN
CA
MG
MN
```

According to the official GPSite documentation, residues with normalized prediction scores greater than `0.5` can be considered predicted binding sites.

# Official OneScience Information

| Platform | Main OneScience repository | Skills repository |
| --- | --- | --- |
| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |


# Citation and License

- Original GPSite paper: [Genome-scale annotation of protein binding sites via language model and geometric deep learning](https://doi.org/10.7554/eLife.93695).
- The official GPSite source code is released under the MIT License; see `LICENSE` in the repository root.
- If you use this repository in research, we recommend citing the original GPSite paper and the relevant OneScience project information. If you use external models such as ESMFold or ProtT5, also include citations as required by the respective projects.