Sovereign 8s.is mirror of standardgalactic/omnilib-ml
  • Jupyter Notebook 97.5%
  • Python 2.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-03-04 08:27:06 -08:00
figures updated figures 2026-03-04 08:27:06 -08:00
model_checkpoints updated repo 2025-08-19 12:07:23 -07:00
nabstab updates 2026-01-12 08:06:36 -08:00
nbfitnessml.egg-info updated license and setup.py 2025-08-20 21:34:36 -07:00
scripts Merge branch 'interpretability' 2025-12-30 11:06:16 -08:00
.gitignore updated files for review - works on macbook 2025-08-20 17:39:45 -07:00
DeepLift.ipynb updated figures 2026-03-04 08:27:06 -08:00
evaluate_fitness.sh updated files for review - works on macbook 2025-08-20 17:39:45 -07:00
evaluate_fitness_scores.py updated files for review - works on macbook 2025-08-20 17:39:45 -07:00
LICENSE.txt added license for real 2025-08-20 21:36:16 -07:00
README.md Update data folder link in README 2026-01-12 10:45:21 -08:00
requirements.txt package requirements 2025-08-21 09:21:44 -07:00
run_tango.py added tango script 2025-07-17 22:05:33 -07:00
setup.py added captum to requirements 2026-01-12 09:45:39 -08:00
train_cnn.sh updated files for review - works on macbook 2025-08-20 17:39:45 -07:00
train_lr.sh updated files for review - works on macbook 2025-08-20 17:39:45 -07:00
train_model.py updated files for review - works on macbook 2025-08-20 17:39:45 -07:00

omnilib-ml

Official repository for the paper Hypervariable loop profiling decodes sequence determinants of antibody stability.

This repository contains code and data to train and evaluate models for predicting the stability of nanobodies based on their CDR sequences. We also provide pretrained models for the same task, as well as code to run inference on new sequences.

In general, these models work best with the synthetic libraries described in this paper: Yeast surface display platform for rapid discovery of conformationally selective nanobodies, as well as the current work. This is to ensure best compatibility with the framework used in these synthetic libraries - other frameworks may not work as well.

Installation

Depending on your use case, you can do a package install, or just use the repository as a library (e.g. in a Jupyter/Colab notebook).

I would recommend creating a new virtual environment for this project, to avoid conflicts with other packages. We used python==3.10.15

First, install a version of pytorch that works on your system (GPU or CPU). We used torch 2.2.0, but more recent versions should also work. Since the models we trained are fairly small, the CPU version should still be very efficient.

# for CPU only installation
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

# -OR- Cuda 11.8 and 2.2.0 (what we used)
pip install torch==2.2.2 torchvision==0.17.2 torchaudio==2.2.2 --index-url https://download.pytorch.org/whl/cu118

# -OR- (more recent)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

Then, either package install:

pip install -e .

or local (notebook style):

pip install -r requirements.txt

Note that the requirements.txt file includes the versions that we used during development, but it's likely that more recent versions of the packages will work as well.

Data

We provide preprocessed and generated data for model training, and evaluation. Data generated as part of the figures in the paper are also provided. The data folder is stored at the following zenodo link

Once downloaded, the data can be extracted to the data folder in the root of the repository.

tar -xvf data.tar.gz

I set up paths assuming the following structure:

├── data
├── figures
├── model_checkpoints
│   ├── CNN
│   └── LR
├── nabstab
│   ├── datasets
│   ├── models
│   ├── tango.py
│   ├── constants.py
│   └── utils.py
├── README.md
├── requirements.txt
...
├── setup.py

Models

Data Format

The classifier models require a dataframe/csv with the following columns: cdr1, cdr2, cdr3, stability

example:

CDR1,CDR2,CDR3,stability
RTFTSYT,LVAAITSSGGST,AADYRASGPYCGYY,high
STFDSNA,LVAAISWSGTSTY,AADPGEPYAYGY,high
...
YIFDGYA,LVARITYSSGSTY,NAPAYWFRLRRYDS,low
SIFGVNA,LVASISSGGSTN,AAVLYRTSRYSQALNY,low

Training a Model

We provide training scripts for both logistic regression and convolutional neural network models.

To train a model, you can use the following command (after modiying the parameters as needed):

# Logistic Regression
bash train_lr.sh

# Convolutional Neural Network
bash train_cnn.sh

These models are fairly lightweight. On my machine (Apple M2 Pro - CPU), the LR model takes ~90 seconds to train over 10 epochs, using the full dataset (~1M samples). The CNN model, with the parameters we used, takes significantly longer.

If you're using CPU, we'd recommend maybe using a smaller dataset, which is provided in data/model_training_data/train_subset.csv. This subset has ~30k samples, and a CNN model (with the same architecture) trained on it takes about 90 seconds to train over 10 epochs.

Running Inference

To run inference on a new set of sequences, you can use the evaluate_fitness_scores.py script. This script takes a fasta file with sequences, and a set of trained models, and outputs the fitness scores for each sequence. The output is a CSV file with the sequences and their corresponding fitness scores.

bash evaluate_fitness.sh

Pretrained Model Checkpoints

As part of this work, we provide the following pretrained models, as well as code to train new models, as well as run inference.

OmniLib Fitness Classifiers

Model Description Parameters Location
CNN Convolutional Neural Network 8k model_checkpoints/CNN/cnn_24_fc_8.pt
LR Logistic Regression 1k model_checkpoints/LR/20231223_LR.pt

Figures

All figures from the paper that use the datasets and models in this repository are provided in the figures directory. For each figure, there is a juptyer notebook that generates the figure. The notebooks are named according to the figure they generate. Furthermore, the outputs of the notebooks are provided in the figures directory as well.