| --- |
| 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. |
