Absolut!

Unconstrained lattice antibody-antigen bindings generator - One tool to simulate them all!

Absolut! allows the user to generate custom datasets by discretizing new antigens or annotating custom CDRH3 sequences enabling the on-demand generation of large synthetic datasets for 3D-antibody-antigen binding generated under the same, deterministic settings, with accessible computing resources.

A Greifflab product! Contact for issues / questions: philippe dot robert at ens minus lyon dot org

Please inform us with the above e-mail when creating an issue request in this github, we do not get automatic notification.

Absolut! software

• takes PDB antigens, converts them into lattice representation with integer positions.
• takes CDR3 Amino Acid sequences, and computes their best binding around a lattice antigen.
• generates features of antibody-antigen bindings directly usable for Machine Learning

Absolut! database

The database generated with Absolut! is available as repository in NIRD research data storage. The files can directly be accessed by http Database Files.

Documentation / Reference / Reproducing

You can find a more detailed documentation in the subfolder doc/HowToAbsolut.pdf

License: https://github.com/csi-greifflab/Absolut/blob/main/20221122%20Absolutt%20license.pdf

The method and analyses of antibody-antigen bindings are explained in:

• Robert and Akbar et al. 2021, Unconstrained generation of synthetic antibody-antigen structures to guide machine learning methodology for real-world antibody specificity prediction
• Robert et al 2020, 'Ymir: A 3D structural affinity model for multi-epitope vaccine simulations', iScience link

It has been used to benchmark antibody generative ML models in: Akbar and Robert et al 2021 mAbs, 'In silico proof of principle of machine learning-based antibody design at unconstrained scale' link

The scripts to reproduce Robert et al. 2021 are also provided in this repository in the folder scripts/ link

Within the code, an extended version of the tool LatFit from the LatPack package has been used for discretizing antigens, linked with the publication:

• Martin Mann, Daniel Maticzka, Rhodri Saunders, and Rolf Backofen. Classifying protein-like sequences in arbitrary lattice protein models using LatPack. In HFSP Journal, 2 no. 6 pp. 396, 2008, DOI:10.2976/1.3027681.

The changed source code is part of this package.

Download / clone

git clone https://github.com/csi-greifflab/Absolut

Usage

Absolut! can be compiled into three versions: one that doesn't require any library to be installed (AbsolutNoLib), the full version (Absolut), and a version specific for using MPI (AbominationMPI). See Installation for details.

Calling Absolut alone shows the list of available options.

./Absolut 
#or
./AbsolutNoLib

An all-in-one example for most tasks is:
plan 3GB of disk space, 2 GB memory and 500MB download

#With ./Absolut or ./AbsolutNoLib:

# Get the list of available lattice antigens
./AbsolutNoLib listAntigens

# Get the sequence and surface residue of each antigen
./AbsolutNoLib info_antigens

# Get the full information on a particular antigen
./AbsolutNoLib info_antigen 1ADQ_A

# Get the list of precomputed CDRH3 possible structures for an antigen
./AbsolutNoLib info_filenames 1FBI_X
curl -O https://ns9999k.webs.sigma2.no/10.11582_2021.00063/projects/NS9603K/pprobert/AbsolutOnline/Structures/SULSU040643e2c0a6d6343bbe8a27b079ef91-10-11-efc862c2cdef086ba79606103a3dfc62Structures.txt.zip

# Get the antibody-antigen complex of a CDRH3 sequence to an antigen (requires the downloaded file above to be in the same folder)
./AbsolutNoLib singleBinding 1FBI_X CARAAHKLARIPK

# High throughput calculation of antibody-antigen complexes for a list (repertoire) of CDRH3 sequences. Here, requests 10 threads in parallel.
./AbsolutNoLib repertoire 1FBI_X SmallSetCDR3.txt 10  #SmallSetCDR3.txt is a provided example list of CDR3s inside src/

# Calculation of structure and sequence encodings from the produced list of antibody-antigen complexes
./AbsolutNoLib getFeatures 1FBI_X 1FBI_XFinalBindings_Process_1_Of_1.txt outputFeaturesFile.txt 1 true

# Generating new antigens and visualizing complexes is only possible with the full ./Absolut

# Takes a PDB and the chains of interests, lattice resolution and discretization method and returns the C++ code for the antigen [New antigens would need to be manually added to antigenLib.cpp].
./Absolut discretize 1CZ8 VW 5.25 FuC

# Visualizing of available antigens in 3D
./Absolut visualize 1FBI_X 

# Visualizing many binding complexes  
./Absolut visualize 1FBI_X 1FBI_XFinalBindings_Process_1_Of_1.txt -95.5

# Visualizing binding hotspots
./Absolut hotspots 1FBI_X 1FBI_XFinalBindings_Process_1_Of_1.txt -95.5 4 

Installation

Absolut! was written in C++.

Three versions are provided with more or less library requirements: Absolut, AbsolutNoLib and AbominationMPI. All versions require a C++ compiler. We recommend starting with AbsolutNoLib, which is easier to install, as most tasks are already available with this version.

1/ AbsolutNoLib requires no additional library, and can perform all tasks except user interface for discretization and 3D visualization. We recommend first compiling/running AbsolutNoLib, which should work smoothly.

# Make sure to have a g++ compiler and make, for instance sudo apt-get install build-essential 
cd src
make		# This creates 'AbsolutNoLib' executable. 

2/ AbominationMPI is the MPI parallelized version for high throughput repertoire bindings generation.

• requires MPI compiler and headers

cd src
#Depending on your MPI compiler,
make MPIcxx
#or
make MPIc++
#or
make MPIgxx
# This creates 'AbominationMPI' executable.

3/ Absolut is the full version,

• requires the Qt framework
• requires freeglut library (or another other C++ glut library) for visualizing 3D lattice structures
• requires the gsl library for discretizing new antigens
• requires wget and curl, for downloading files (like PDBs when discretizing)
• optionally, a sorftware to visualize PDBs (like rasmol)

Installing and then linking the libraries can be tricky depending on the OS. Full help for installing these libraries (especially in Windows) is provided in the documentation doc/HowToAbsolut It is also possible to use Absolut! with a user-defined custom subset of libraries (See in the full documentation).

Installing on linux (simplest):

sudo apt-get update
#sudo apt-get install build-essential  #if you don't have g++ and make 
sudo apt-get install libgsl-dev
sudo apt-get install curl
sudo apt-get install libgsl-dev
sudo apt-get install freeglut3-dev

#to find the available qt packages in your distribution
apt-cache search qtbase
apt-cache search libqt5

#These packages should do the job
sudo apt-get install qtbase5-dev
sudo apt-get install qtcreator
sudo apt-get install libqt5svg5
sudo apt-get install libqt5printsupport5

#To visualize PDB structures during discretization
sudo apt-get install rasmol

#For using pdb-tools (manipulating pdb files during discretization), python is needed
# sudo apt install python3
# and make sure that python is callable by "python":
sudo apt-get install python-is-python3

Installing on Windows:

Compiling

#Please DO NOT compile the full version in src/ folder, it would destroy the Absolut/ subfolder and the original Makefile ...
#We recommend to compile into src/bin because Absolut! expects the pdb-tools scripts to be directly in ../pdb-tools
cd src/bin/
qmake ../Absolut/Absolut.pro	#qmake creates a new Makefile embedding Qt libraries locations
make		#This creates Absolut

Alternately, if you have installed the Qt framework with qtcreator,

qtcreator Absolut/Absolut.pro
#or
qtcreator Absolut/AbsolutNoLib.pro
#or
qtcreator Absolut/AbsolutNoLibMPI.pro

Installing on MAC:

#if no recent g++ compiler, use this command (will also install g++)
brew install gcc 
brew install wget
brew install qt
brew install gsl
brew install freeglut

Then, from the src/bin/ folder,

qmake ../Absolut/Absolut.pro
make

Some OS specific points: Inside Absolut/Absolut.pro, your compiler might recognize only -o1 or -O1. Linking the libraries might require that you provide their folder. Can either add it in the Absolut.pro linker options, or inside the Makefile manually (but then do not run qmake anymore). -framework openGL should work for openGL and already be added. Depending on your g++ compiler, there might be conflicts between the C++ language of the libraries and the C++ standard libraries provided with the compiler. This might be solved by adding "QMAKE_CXXFLAGS += -std=c++14 -std=c++17" inside Absolut/Absolut.pro. We didn't add these lines by default in case your C++ compiler doesn't support C++17.

*Note, the libraries Latfit, pdb-tools and soil are provided inside Absolut with their compatible version