README.md

---
frameworks:
- PyTorch
language:
- en
license: unknown
tags:
- OneScience
- bioscience
- protein-protein-interaction-site-prediction
- graph-neural-network
- MVGNN-PPIS
- ProtT5
- AlphaFold3
tasks: []
datasets: []
---

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

# Model Introduction

MVGNN-PPIS is an open-source protein-protein interaction site prediction model developed by WW-AILab. Given precomputed protein sequence and structural features, the model predicts the probability that each amino acid residue belongs to a protein-protein interaction site.

MVGNN-PPIS uses a multi-view graph neural network to jointly model local sequence adjacency relationships and three-dimensional spatial neighborhood relationships.

Paper: [MVGNN-PPIS: A novel multi-view graph neural network for protein-protein interaction sites prediction based on Alphafold3-predicted structures and transfer learning](https://doi.org/10.1016/j.ijbiomac.2025.140096)

# Model Description

MVGNN-PPIS integrates ProtT5 residue representations, DSSP secondary-structure features, and AlphaFold3-predicted structures. Graph convolution and graph Transformer modules are then used to extract complementary local and global information.

The model provides the following main capabilities:

- Uses 1038-dimensional residue-level node features composed of ProtT5 and DSSP features;
- Builds a spatial K-nearest-neighbor graph based on side-chain atom centroid coordinates;
- Uses sequence adjacency matrices to capture local residue relationships;
- Performs ensemble prediction using five official checkpoints;
- Outputs residue-level protein-protein interaction site probabilities;
- Computes AUC, AUPRC, MCC, Accuracy, Precision, Recall, and F1 on labeled test datasets.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Protein-protein interaction site prediction | Predict residue-level interaction probabilities from precomputed sequence and structural features. |
| Test60 benchmark evaluation | Reproduce evaluation using the upstream PRO-Test60 dataset, precomputed features, and five-fold model checkpoints. |
| Protein functional-site screening | Rank candidate residues by predicted interaction probability for downstream experimental analysis. |
| DCU inference validation | Validate five-fold model loading and full-dataset inference in a DTK/HIP-enabled PyTorch environment. |

# Usage

## 1. OneCode

You can use the OneCode online environment for an intelligent one-click AI4S programming experience:

[Try OneCode for AI4S Programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Installation

**Hardware Requirements**

- PyTorch must be installed;
- GPU/DCU memory usage and runtime depend on protein length, batch size, and the number of parallel worker processes.

### Download the Model Package

Install the Hugging Face command-line tool and download the model repository:

```bash
pip install -U huggingface_hub

hf download OneScience-Group/MVGNN-PPIS --local-dir ./MVGNN-PPIS
cd MVGNN-PPIS
```

### Install the Runtime Environment

**DCU Environment**

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

pip install onescience[bio-dcu] \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai
```

Install the additional dependencies declared in `requirements.txt`:

```bash
conda activate onescience311
python -m pip install -r requirements.txt
```

### Weights and Data Preparation

Basic inference requires five official checkpoints, the test-set CSV file, and the corresponding precomputed features:

| Asset | Location | Purpose |
| --- | --- | --- |
| MVGNN checkpoint | `weight/fold0.ckpt` | Five-fold ensemble member 0 |
| MVGNN checkpoint | `weight/fold1.ckpt` | Five-fold ensemble member 1 |
| MVGNN checkpoint | `weight/fold2.ckpt` | Five-fold ensemble member 2 |
| MVGNN checkpoint | `weight/fold3.ckpt` | Five-fold ensemble member 3 |
| MVGNN checkpoint | `weight/fold4.ckpt` | Five-fold ensemble member 4 |
| Test60 dataset | `weight/datasets/PRO_Test60.csv` | Protein IDs, sequences, and labels |
| Precomputed features | `weight/feature/` | Model inference inputs |

Each protein ID must have the following five tensor files:

```text
weight/feature/<ID>_X.tensor
weight/feature/<ID>_adj.tensor
weight/feature/<ID>_node_feature.tensor
weight/feature/<ID>_mask.tensor
weight/feature/<ID>_label.tensor
```

By default, `scripts/inference.py` loads these assets according to `conf/config.json` and validates all checkpoint and feature files before inference.

If required files are missing, the script reports the number of missing files and their expected locations.

Basic inference directly uses the precomputed features released by the original authors. ProtT5, AlphaFold3, and DSSP do not need to be downloaded or executed at runtime for this workflow.

### Quick Inference

Run the following command from the root directory of the Hugging Face model package:

```bash
HIP_VISIBLE_DEVICES=0 python scripts/inference.py
```

The default configuration uses:

```text
weight/datasets/PRO_Test60.csv
weight/feature/
weight/
```

and writes the results to:

```text
output/prediction/result.csv
output/prediction/test.log
```

To view all command-line options:

```bash
python scripts/inference.py --help
```

### Custom Paths and Runtime Parameters

The inference script uses paths relative to the model package and does not depend on the current working directory.

You can modify `conf/config.json` or override the default configuration through command-line arguments:

```bash
python scripts/inference.py \
  --dataset weight/datasets/PRO_Test60.csv \
  --feature-path weight/feature \
  --weight-path weight \
  --output-path output/prediction \
  --device cuda \
  --num-workers 8
```

Command-line arguments take precedence over the configuration file.

A custom dataset must still provide the following columns:

```text
ID
sequence
label
```

For each protein ID, the corresponding five precomputed tensor files must also be provided.

### Prediction Outputs

`result.csv` stores:

- Protein IDs;
- Amino acid sequences;
- Residue-level predicted interaction probabilities.

`test.log` stores:

- Model configuration;
- Evaluation metrics for labeled datasets.

### Feature Generation

The `scripts/process_feature/` directory retains the upstream feature-generation code involving ProtT5, AlphaFold3-predicted structures, and DSSP.

This workflow requires additional resources, including:

- ProtT5 model files;
- Complete protein structure files;
- DSSP and other required external tools.

Feature generation is not part of the basic inference workflow.

For benchmark reproduction and standard inference, it is recommended to use the precomputed features released by the original authors.

Only when processing new proteins or regenerating features is it necessary to prepare ProtT5, AlphaFold3, DSSP, and the associated resources according to the upstream repository documentation.

### Training

The upstream MVGNN-PPIS repository does not provide a directly executable complete training entry point or the complete training dataset.

It primarily provides official pretrained checkpoints and prediction-related code.

Therefore, this Hugging Face model package does not provide training commands.

# OneScience Official Resources

| Platform | OneScience Main 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

- Paper: [MVGNN-PPIS: A novel multi-view graph neural network for protein-protein interaction sites prediction based on Alphafold3-predicted structures and transfer learning](https://doi.org/10.1016/j.ijbiomac.2025.140096)

- Official implementation: https://github.com/WW-AILab/MVGNN-PPIS

- At the time this Hugging Face model package was prepared, the upstream repository did not provide an explicit `LICENSE` file. Users should confirm the permitted scope of use, modification, and redistribution with the original authors before using or redistributing the source code, pretrained weights, or datasets.

- ProtT5, AlphaFold3, DSSP, datasets, pretrained assets, and other third-party resources are subject to their respective original copyright notices, licenses, and terms of use.

- The top-level [`LICENSE.md`](LICENSE.md) file in this model package records the currently known licensing status and third-party asset notices. It does not grant any additional rights to upstream materials.