OneScience-Group/Antibody_deep_learning

Antibody Deep Learning

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

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

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

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:

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:

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:

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:

# 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

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.

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:

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.

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:

model/GAN/gen_seq_tf218.RDS
model/GAN/gen_seq_tf218.tsv

Training Examples

1. Data Preprocessing

Purpose: Generate intermediate CNN/GAN training data.

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:

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:

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:

python scripts/05_train_cnn.py

Outputs:

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:

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:

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

Complete single-model training:

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

Train all 15 models:

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:

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:

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:

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:

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.

• Paper details: Yoong Wearn Lim, Adam S. Adler, David S. Johnson. mAbs 14(1):2069075, 2022. DOI: 10.1080/19420862.2022.2069075.

• Original code and data source: 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.