How ucrbioinfo/abaffinity works
Project type and purpose
• This is a mono-repo containing two related subsystems:
a. AbAffinity: a Python package (src/AbAffinity) implementing a large-language-model-based predictor for scFv antibody binding affinity, embeddings, and contact maps.
b. Antibodies Generation: a set of standalone scripts and SBATCH pipeline for generating candidate antibody sequences via Genetic Algorithm (GA), Simulated Annealing (SA), PSSM-based sampling, and random sampling, then scoring them (CSV outputs).
• The primary use case is to take antibody heavy+light chain sequences (combined into an scFv), use the AbAffinity model to predict binding affinity or derive embeddings/contact maps, and to generate new candidate sequences via optimization pipelines.
File structure
• Top-level folders:
• src/AbAffinity – core package with modules (data ingestion, model definition, attention layers, embedding, prediction, CLI in main.py), setup.py, requirements.txt.
• Antibodies Generation – scripts to generate and score new antibody sequences (generate_*.py), output CSVs, SBATCH script.
• data – raw CSV datasets (cdr_similarity, thermostability, labeled test data).
• notebooks – exploratory and analysis Jupyter notebooks for both AbAffinity performance and Antibodies Generation.
• README.md – project overview and usage.
• Patterns: clear separation of library code (src), generation pipelines, raw data, and analysis notebooks.
README for additional insights
• Describes AbAffinity’s features: get_affinity(), get_embeddings(), get_contact_map().
• Technical stack: Python, PyTorch/TorchScript (implied by tensor outputs), Huggingface model repo, Jupyter notebooks.
a. Main components
1) User Interface layer
• Python API (AbAffinity class in main.py)
• CLI entry point (if any)
• Jupyter Notebooks (in notebooks/)
2) Data layer
• Input sequences (heavy/light)
• Raw datasets (data/)
• Generated sequence CSVs (Antibodies Generation/Generated Antibodies/)
3) Generation pipeline
• Simulated Annealing modules (generate_SA_*.py)
• Genetic Algorithm modules (generate_GA_*.py)
• Random/PSSM samplers
• SBATCH orchestration script
4) Model layer (src/AbAffinity)
• Preprocessing: create_dataset.py, data.py
• Embedding engine: esm2.py or axial_attention.py, multihead_attention.py, rotary_embedding.py
• Model definition: affinity_pred_model.py, modules.py
• Inference API: main.py (AbAffinity class)
5) External services
• Huggingface model repo for pretrained weights
• Compute cluster (SLURM via sbatch)
b. Relationships and data flows
• User notebooks or CLI call AbAffinity.make_scFv() → pipeline to merge heavy/light + linker.
• That sequence flows into AbAffinity.get_affinity() / get_embeddings() / get_contact_map().
• Internally data passes from preprocessing → tokenization/embedding → model layers → output tensor or figure.
• Generation scripts import or invoke AbAffinity’s scoring function (fitness evaluation) on candidate sequences, writing results to CSV.
• Notebooks ingest raw data or generated CSVs to analyze performance or similarity.
c. Architectural patterns / principles
• Layered architecture: UI → Data → Model → Inference.
• Modular design: each responsibility in its own module.
• Extensibility: new generation strategies can be added as separate scripts.
• Reusability: core predictive model separated into a pip-installable package.
d. Key technologies / frameworks
• Python 3, PyTorch, Huggingface/transformers (ESM2).
• SLURM SBATCH for HPC pipeline.
• Jupyter notebooks for interactive analysis.
• CSV files for data interchange.