Ab-SELDON: Leveraging Diversity Data for an Efficient Automated Computational Pipeline for Antibody Design

Ab-SELDON (Antibody Structural Enhancement Leveraging Diversity for Optimization of iNteractions) is a modular and easily customizable computational antibody design pipeline capable of iteratively optimizing an antibody-antigen (Ab-Ag) interaction in five different modification steps, including CDR and framework grafting, and mutagenesis. The optimization process is guided by diversity data collected from millions of publicly available human antibody sequences. This approach enhanced the exploration of the chemical and conformational space of the paratope during computational tests involving the optimization of an anti-HER2 antibody. Optimization of another antibody against Gal-3BP stabilized the Ab-Ag interaction in molecular dynamics simulations. Tests with SKEMPI’s Ab-Ag mutations also demonstrated the pipeline’s ability to correctly identify the effect of most mutations.

# Contents
This compacted file contains:
1) The software, Ab-SELDON, itself in two versions and ready download and to run, provided the software requirements have been installed. For more information, visit https://github.com/SFBBGroup/Ab-SELDON.
2) Test data used to demonstrate Ab-SELDON's functionality. This is divided between the mutation tests with SKEMPI, and the optimization tests with an anti-HER2 antibody.

# Test data
1) In her2_test_data, you will find the inputs and outputs of optimizations performed on an anti-HER2 antibody using Ab-SELDON's diversity-guided or randomized modification modes. The analyses made using these outputs are also available.
2) In skempi_tests, you will find the analyses done to assess the ability of Ab-SELDON's scoring protocol to correctly identify and approve beneficial mutations, including data on the correlation between the interaction energy predicted by the protocol and the experimentally determined post-mutation affinity change. 

# Ready-to-run examples of the pipeline

Ab-SELDON versions
To quickly test the pipeline, two versions are available in separate folders. 
To run an optimization example, simply enter either of these folders and execute the main script with the command `sh seldon.sh`.

ab-seldon-paper-v6.2
Version used in the paper's optimization experiments. 
- While the individual modules can be run independently and in any order, this requires manual setup. 
- The inputs must be named `complex_[NAME].pdb` and `[NAME].fasta`.
- Uses the same settings used in the optimization tests of the paper. Folders with settings files for diversity-guided (`diversity/`) or random (`random/`) optimizations are available.

ab-seldon-ready-v6.45
Most current version of the pipeline as of march 2025. This new version has a few differences compared to the paper version.
- The use of the optimization modules in non-default order and number has become much simpler with the introduction of the `steps` parameter. For more information, visit the [instructions for the configuration file](https://github.com/SFBBGroup/Ab-SELDON/blob/main/configuration_file_instructions.md).
- Customizable modification approval thresholds have been added to the pipeline, through the `scoring_strictness` and `approval_threshold` parameters in the configuration file.
- The input files must have the same name ([NAME].pdb and [NAME].fasta)
- A bug has been corrected in the OAS CDR grafting module (`swap_bnk_v6.45.py`), where CDRs whose germline was represented in the database by too few sequences could cause an infinite loop.
- Nevertheless, these differences are not relevant to the tests made with the previous version.

Alternative .pdb complexes and associated .fasta files are also available in the `example-complexes/` subfolders. To optimize any of these complexes, simply copy the fasta and pdb files to the main pipeline folder and edit the `prepare|input_name` parameter accordingly, before running the main script.
To test the basic functionality of the pipeline's modules, you can set the `n_cycles`/`max_cycles` and `num_fullmemory` parameters to reduce the number of optimization cycles. Suggested values are:
- `n_cycles`/`max_cycles` = 2
- `num_fullmemory` = 1

For more information about these parameters and how to edit the configuration file, visit the instructions for the configuration file.