README.md

---
license: cc-by-nc-sa-4.0
language:
- en
- zh
tags:
- OneScience
- life-science
- antibody
- deep-learning
- CNN
- GAN
frameworks: TensorFlow
---
<p align="center">
  <strong>
    <span style="font-size: 30px;">Antibody Deep Learning</span>
  </strong>
</p>

# Model Introduction

Antibody Deep Learning is a deep learning reproduction project for antibody CDR3 sequence analysis. It focuses on two tasks:

1. Use a convolutional neural network (CNN) to predict whether CTLA-4 and PD-1 antibody sequences are binders.
2. Use a generative adversarial network (GAN) to generate synthetic CDR3K/CDR3H sequences for CTLA-4 and PD-1.

The original project uses RMarkdown as its main entry point and calls the Python TensorFlow backend through R `keras`/`reticulate`. This repository retains the official data, pretrained weights, and original documentation, while providing equivalent scripts adapted to the current TensorFlow/DCU environment in the `scripts/` directory.

Paper:

Predicting antibody binders and generating synthetic antibodies using deep learning

https://doi.org/10.1080/19420862.2022.2069075

# Model Description

This project contains two types of models.

| Model | Task | Input | Output |
| --- | --- | --- | --- |
| CNN | Determine whether CTLA-4/PD-1 antibody sequences are binders | CDR3K + CDR3H, padded and BLOSUM62-encoded as `36 x 22 x 1` | Binary probabilities: non-binder/binder |
| GAN | Generate CDR3 sequences | 100-dimensional random noise | An amino acid image of shape `32 x 22 x 1`, decoded into CDR3 sequences |

Two CNN models are trained separately:

| Model path | Target | Description |
| --- | --- | --- |
| `weight/CNN/model_c1` | CTLA-4 | Officially trained CNN SavedModel |
| `weight/CNN/model_p1` | PD-1 | Officially trained CNN SavedModel |

The GAN includes 15 generators corresponding to different target/chain/V-gene combinations:

| ID | Official weight path | Group |
| --- | --- | --- |
| 1 | `weight/GAN/GAN_model_1` | CTLA4 heavy IGHV3-33*01 |
| 2 | `weight/GAN/GAN_model_2` | CTLA4 heavy IGHV1-18*04 |
| 3 | `weight/GAN/GAN_model_3` | CTLA4 heavy IGHV3-20*01 |
| 4 | `weight/GAN/GAN_model_4` | CTLA4 heavy IGHV4-39*01 |
| 5 | `weight/GAN/GAN_model_5` | CTLA4 light IGKV3-20*01 |
| 6 | `weight/GAN/GAN_model_6` | CTLA4 light IGKV1D-39*01 |
| 7 | `weight/GAN/GAN_model_7` | CTLA4 light IGKV1-17*01 |
| 8 | `weight/GAN/GAN_model_8` | CTLA4 light IGKV1-16*01 |
| 9 | `weight/GAN/GAN_model_9` | PD1 heavy IGHV4-4*07 |
| 10 | `weight/GAN/GAN_model_10` | PD1 heavy IGHV3-33*03 |
| 11 | `weight/GAN/GAN_model_11` | PD1 heavy IGHV1-18*04 |
| 12 | `weight/GAN/GAN_model_12` | PD1 light IGKV1-17*01 |
| 13 | `weight/GAN/GAN_model_13` | PD1 light IGKV1-6*02 |
| 14 | `weight/GAN/GAN_model_14` | PD1 light IGKV3-15*01 |
| 15 | `weight/GAN/GAN_model_15` | PD1 light IGKV1-9*01 |

# Use Cases

| Use case | Description |
| --- | --- |
| CTLA-4/PD-1 binder classification | Use the built-in CNN models to BLOSUM62-encode CDR3K + CDR3H sequences and predict binder/non-binder labels, reproducing the antibody binding classification task from the paper. |
| Synthetic antibody CDR3 generation | Use 15 GAN generators to produce synthetic CDR3 sequences grouped by CTLA-4/PD-1, heavy/light chain, and V gene. |
| Antibody engineering method reproduction | Reproduce the core workflow from the paper: convert antibody CDR3 sequences into two-dimensional "antibody images," train CNN classifiers, and use GANs to learn sequence distributions. |
| Interpretability analysis and sequence optimization | Combine model evaluation, ROC analysis, and in silico mutagenesis ideas from the original RMarkdown to analyze important CDR3 sites affecting binder classification. |

# 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

- CPUs can be used for data preprocessing, small-scale inference, and connectivity checks.
- GPUs/DCUs are recommended for training and batch inference.
- DCU users need to load the DTK module matching the current cluster and first verify that basic TensorFlow operations work correctly.

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

- After setting up the OneScience base environment, prepare the R runtime and required R packages. Example:

```bash
module load R/3.6.3-gcc-7.3.1
mkdir -p ~/R/library/3.6 ~/tmp
export R_LIBS_USER=$HOME/R/library/3.6
```

If the R module path on the cluster is not `/public/software/apps/R-3.6.3/bin`, first use the commands below to determine the actual path and update `PATH` in the subsequent commands accordingly:

```bash
which Rscript
Rscript --version
```
Because R 3.6.3 is an older version, some current CRAN packages are no longer compatible. It is recommended to install dependencies from a historical CRAN snapshot:
```bash
env -i \
HOME=$HOME \
USER=$USER \
PATH=/usr/bin:/bin:/public/software/apps/R-3.6.3/bin \
R_LIBS_USER=$HOME/R/library/3.6 \
TMPDIR=$HOME/tmp \
Rscript -e 'options(repos=c(CRAN="https://packagemanager.posit.co/cran/2023-10-20")); install.packages(c("reticulate","dplyr","ggplot2","readr","tidyr","purrr","tibble","stringr","forcats","mltools","caret","pROC","remotes"), type="source")'
```
After installation, verify that the R packages load correctly:

```bash
env -i \
HOME=$HOME \
USER=$USER \
PATH=/usr/bin:/bin:/public/software/apps/R-3.6.3/bin \
R_LIBS_USER=$HOME/R/library/3.6 \
TMPDIR=$HOME/tmp \
Rscript -e 'library(reticulate); library(caret); library(pROC); cat("R packages OK\n")'
```
When running R scripts later, explicitly pass `R_LIBS_USER=$HOME/R/library/3.6`; otherwise, you may encounter an error such as `there is no package called ...`.

- If you encounter TensorFlow issues during execution, use the platform-adapted TensorFlow wheel and load the matching DTK module. For example:

```bash
# 1. Download the platform TensorFlow wheel
wget --content-disposition 'https://download.sourcefind.cn:65024/file/4/tensorflow/DAS1.8/tensorflow-2.13.1+das.opt1.dtk2604-cp311-cp311-manylinux_2_28_x86_64.whl'

# 2. Install TensorFlow
pip install tensorflow*

# 3. Load the corresponding DTK
module load compiler/dtk/26.04
```

# Quick Start

## 1. Download the Model Package

```bash
hf download OneScience-Group/Antibody_deep_learning --local-dir ./Antibody_deep_learning
cd Antibody_deep_learning
```

# Data and Weight Details

## Included Data

| Path | Description |
| --- | --- |
| `model/CNN/all_ab_pre_post.txt` | CNN raw input table containing CDR3K, CDR3H, antigen, pre/post frequency, fold change, and other information. |
| `model/BLOSUM62_with_deletion.Rdata` | BLOSUM62 encoding matrix containing 20 amino acids, `X`, and the gap `-`. |
| `model/CNN/c1.RDS` / `model/CNN/p1.RDS` | CTLA-4/PD-1 train/test split objects. |
| `model/CNN/*train*.RDS` / `model/CNN/*test*.RDS` | CNN training and test tensors with one-hot labels. |
| `model/GAN/seq_all.RDS` | Preprocessed GAN CDR3 sequences grouped by target/chain/V gene. |
| `model/GAN/seq_all_encoded.RDS` | List of GAN training tensors encoded with BLOSUM62. |

## Included Weights

| Path | Description |
| --- | --- |
| `weight/CNN/model_c1` | Official CTLA-4 CNN SavedModel. |
| `weight/CNN/model_p1` | Official PD-1 CNN SavedModel. |
| `weight/GAN/GAN_model_1` to `weight/GAN/GAN_model_15` | The 15 official GAN generator SavedModels. |

# Inference Examples

## 1. CNN Model Inference

Purpose: Load `weight/CNN/model_c1` and `weight/CNN/model_p1` to classify CTLA-4/PD-1 binders.

```bash
env -i \
HOME=$HOME \
USER=$USER \
PATH=$PATH:/public/software/apps/R-3.6.3/bin \
LD_LIBRARY_PATH=$LD_LIBRARY_PATH \
R_LIBS_USER=$HOME/R/library/3.6 \
RETICULATE_PYTHON=$(which python) \
PYTHONNOUSERSITE=1 \
TMPDIR=$HOME/tmp \
Rscript scripts/02_cnn_inference.R
```

Output files:

```text
model/CNN/c1_tf218_inference_result.RDS
model/CNN/p1_tf218_inference_result.RDS
```

## 2. GAN Model Inference

Purpose: Load `weight/GAN/GAN_model_1` through `weight/GAN/GAN_model_15`, with each model generating 100 CDR3 sequences.

```bash
env -i \
HOME=$HOME \
USER=$USER \
PATH=$PATH:/public/software/apps/R-3.6.3/bin \
LD_LIBRARY_PATH=$LD_LIBRARY_PATH \
R_LIBS_USER=$HOME/R/library/3.6 \
RETICULATE_PYTHON=$(which python) \
PYTHONNOUSERSITE=1 \
TMPDIR=$HOME/tmp \
Rscript scripts/03_gan_inference.R
```

Output files:

```text
model/GAN/gen_seq_tf218.RDS
model/GAN/gen_seq_tf218.tsv
```

# Training Examples

## 1. Data Preprocessing

Purpose: Generate intermediate CNN/GAN training data.

```bash
env -i \
HOME=$HOME \
USER=$USER \
PATH=$PATH:/public/software/apps/R-3.6.3/bin \
R_LIBS_USER=$HOME/R/library/3.6 \
TMPDIR=$HOME/tmp \
Rscript scripts/01_prepare_data_compat.R
```

Outputs include:

```text
model/CNN/c1_train.RDS
model/CNN/c1_test.RDS
model/CNN/p1_train.RDS
model/CNN/p1_test.RDS
model/GAN/seq_all_encoded.RDS
```

## 2. CNN Training

First export Python-readable data:

```bash
env -i \
HOME=$HOME \
USER=$USER \
PATH=$PATH:/public/software/apps/R-3.6.3/bin \
LD_LIBRARY_PATH=$LD_LIBRARY_PATH \
R_LIBS_USER=$HOME/R/library/3.6 \
RETICULATE_PYTHON=$(which python) \
PYTHONNOUSERSITE=1 \
TMPDIR=$HOME/tmp \
Rscript scripts/04_export_cnn_npz.R
```

Train:

```bash
python scripts/05_train_cnn.py
```

Outputs:

```text
weight/CNN/model_c1_dcu
weight/CNN/model_p1_dcu
weight/CNN/model_c1_dcu_eval.npz
weight/CNN/model_p1_dcu_eval.npz
```

## 3. GAN Training

First export Python-readable data:

```bash
env -i \
HOME=$HOME \
USER=$USER \
PATH=$PATH:/public/software/apps/R-3.6.3/bin \
LD_LIBRARY_PATH=$LD_LIBRARY_PATH \
R_LIBS_USER=$HOME/R/library/3.6 \
RETICULATE_PYTHON=$(which python) \
PYTHONNOUSERSITE=1 \
TMPDIR=$HOME/tmp \
Rscript scripts/06_export_gan_npz.R
```

Single-model smoke test:

```bash
python scripts/07_train_gan.py --model-id 1 --rounds 20
```

Complete single-model training:

```bash
python scripts/07_train_gan.py --model-id 1 --rounds 100
```

Train all 15 models:

```bash
for i in $(seq 1 15); do
  echo "===== training GAN model $i ====="
  python scripts/07_train_gan.py --model-id $i --rounds 100
done
```

Outputs:

```text
weight/GAN/GAN_model_1_dcu through weight/GAN/GAN_model_15_dcu
weight/GAN/GAN_model_1_dcu_loss.npz through weight/GAN/GAN_model_15_dcu_loss.npz
```

## 4. Generate Sequences with Newly Trained GAN Models

Single model:

```bash
python scripts/08_generate_from_trained_gan.py \
  --model-id 1 \
  --n-seq 100 \
  --out-tsv model/GAN/gen_seq_trained_model_1_dcu.tsv
```

All models:

```bash
python scripts/08_generate_from_trained_gan.py \
  --model-id 0 \
  --n-seq 100 \
  --out-tsv model/GAN/gen_seq_trained_all_dcu.tsv
```

Generation statistics:

```bash
python - <<'PY'
import pandas as pd
import re

df = pd.read_csv("model/GAN/gen_seq_trained_all_dcu.tsv", sep="\t")
df["length"] = df["aa"].astype(str).str.len()
df["valid"] = df["aa"].astype(str).str.fullmatch(r"[ARNDCQEGHILKMFPSTWYV]+")

summary = (
    df.groupby(["model_id", "group"])
      .agg(
          n_seq=("aa", "size"),
          n_unique=("aa", "nunique"),
          min_len=("length", "min"),
          median_len=("length", "median"),
          max_len=("length", "max"),
          valid_rate=("valid", "mean"),
      )
      .reset_index()
)

print(summary.to_string(index=False))
summary.to_csv("model/GAN/gen_seq_trained_all_dcu_summary.tsv", sep="\t", index=False)
PY
```


# 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 Antibody Deep Learning paper: [Predicting antibody binders and generating synthetic antibodies using deep learning](https://doi.org/10.1080/19420862.2022.2069075).

- Paper details: Yoong Wearn Lim, Adam S. Adler, David S. Johnson. *mAbs* 14(1):2069075, 2022. DOI: [10.1080/19420862.2022.2069075](https://doi.org/10.1080/19420862.2022.2069075).

- Original code and data source: [ywlim/Antibody_deep_learning](https://github.com/ywlim/Antibody_deep_learning). This repository is listed in the paper's data availability statement.

- The relevant source code is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0); see `LICENSE` in the repository root. When using, modifying, or redistributing this project's content, comply with the attribution, non-commercial use, and share-alike requirements.

- If you use this project in research, cite both the original paper and the relevant OneScience information.