Modelpublic

OneScience-Group/Antibody_deep_learning

sourceHugging Facecc-by-nc-sa-4.0updated 14d agoView on Hugging Face

0likes

Model Card

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

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.

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