Blame for README.md

---
frameworks:
- TensorFlow
language:
- en
license: mit
tags:
- OneScience
- bioscience
- nanobody
- antigen
- BiLSTM
- attention
- DCU
tasks:
- binary-classification
datasets:
- SAbDab-nano
---

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

# Model Introduction

NABP-LSTM-Att is a binary classification model that predicts whether a nanobody binds to an antigen using sequence information only.

The model separately encodes the nanobody CDR and antigen sequences, extracts interaction features through one-dimensional convolution, bidirectional LSTM, and a soft attention mechanism, and finally outputs a binding probability between 0 and 1.

Paper: [NABP-LSTM-Att: Nanobody–Antigen binding prediction using bidirectional LSTM and soft attention mechanism](https://doi.org/10.1016/j.compbiolchem.2025.108490)

# Model Description

The default model uses the following inputs and architecture:

- The nanobody CDR is represented using 3-mers with an input length of 24;
- The antigen is represented using 1-mers with an input length of 2371;
- CDR sequence embeddings are added to CDR positional/index embeddings before being passed through a convolutional layer;
- The antigen sequence is processed through an independent embedding layer and convolutional layer;
- The two feature streams are concatenated and aggregated using a BiLSTM and soft attention layer;
- A Sigmoid output layer produces a single binding probability;
- Binary cross-entropy is used as the training objective.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Nanobody–antigen binding prediction | Predict the probability of binding from CDR and antigen sequence features. |
| Official test-set evaluation | Evaluate the official pretrained model using AUROC and AUPR. |
| Model retraining | Train the model from randomly initialized weights using the precomputed training and validation datasets. |
| DCU compatibility validation | Validate inference, backward propagation, parameter updates, and device placement on DCU. |

# 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**

- Running in the OneScience Hygon DCU environment is recommended;
- The current adaptation has been validated on BW DCU;
- Both inference and training support single-device execution.

### Download the Model Package

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

```bash
python -m pip install -U huggingface_hub

hf download OneScience-Group/NABP-LSTM-Att --local-dir ./NABP-LSTM-Att
cd NABP-LSTM-Att
```

### Install the OneScience Base Environment

```bash
conda create -n onescience311 python=3.11 -y
conda activate onescience311

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

### Version Compatibility

This project requires an upgraded DTK and TensorFlow environment.

Load DTK and install the additional dependencies:

```bash
module load compiler/dtk/26.04

python -m pip install --upgrade --no-deps -r requirements.txt
```

### Weights and Data Preparation

The Hugging Face model package already contains the precomputed features, k-mer vocabularies, and official pretrained weights required for inference and training.

No additional dataset download is required for the default workflow.

The default assets are:

```text
conf/data/features/cdr_kmer3_ag_kmer1/
weight/cdr_kmer3_ag_kmer1/Model99.h5
```

### Quick Inference

**Purpose:** Evaluate the complete official test set using the pretrained weights. The script reports AUROC, AUPR, runtime, and throughput, and can optionally save the prediction results.

```bash
python scripts/evaluate_test_set.py \
  --batch-size 64 \
  --output output/test_predictions.npz
```

### Full-Dataset Training

**Purpose:** Train the model from randomly initialized weights using the complete training dataset and evaluate it on the validation set.

By default, training runs for 100 epochs.

Checkpoints are written to:

```text
output/checkpoints/
```

The official pretrained weights are not overwritten.

Run:

```bash
python scripts/train.py
```

To validate the complete training pipeline with only one epoch, run:

```bash
python scripts/train_one_epoch.py \
  --batch-size 64 \
  --output-dir output/one_epoch_run1
```

### Minimal Compatibility Validation

Use the following commands to perform lightweight inference and training validation:

```bash
python scripts/verify_minimal_inference.py --samples 8

python scripts/verify_minimal_training.py \
  --batch-size 8 \
  --steps 3
```

### Custom Data

Custom sequences must first be converted into CDR and antigen feature objects that are compatible with the pickle format used by the official dataset.

Scripts for data acquisition, dataset splitting, k-mer TSV generation, and feature encoding are provided in:

```text
scripts/
```

When rebuilding the dataset from the original SAbDab-nano data, additional external tools such as CD-HIT and Clustal Omega are also required.

# 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

- Ahmed, F. S., Aly, S., El-Tabakh, M. A. M., & Liu, X. (2025). [NABP-LSTM-Att: Nanobody–Antigen binding prediction using bidirectional LSTM and soft attention mechanism](https://doi.org/10.1016/j.compbiolchem.2025.108490). *Computational Biology and Chemistry*, **118**, 108490.
- Original project: https://github.com/FMoonlightS/NABP-LSTM-Att
- This project is distributed under the MIT License.
- Model assets, datasets, and external tools remain subject to their respective original licenses and terms of use.