# ucrbioinfo/abaffinity architecture

> Architecture diagram of the GitHub repository ucrbioinfo/abaffinity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ucrbioinfo/abaffinity
- Repository: https://github.com/ucrbioinfo/abaffinity

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        direction TB
        UI_Notebooks_Perf["AbAffinity Performance Notebooks"]:::ui
        UI_Notebooks_Gen["Antibody Generation Analysis Notebooks"]:::ui
        UI_Example["Example_Ab-Affinity.ipynb"]:::ui
        UI_Readme["README.md"]:::ui
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Raw_CSV["Raw CSV Datasets"]:::data
        Gen_CSV["Generated Sequence CSVs"]:::data
    end

    %% Model Layer
    subgraph "Model Layer (AbAffinity)" 
        direction TB
        subgraph "Preprocessing Modules"
            direction TB
            Pre_create["create_dataset.py"]:::core
            Pre_data["data.py"]:::core
        end
        subgraph "Embedding Engine"
            direction TB
            Emb_esm2["esm2.py"]:::core
            Emb_axial["axial_attention.py"]:::core
            Emb_mha["multihead_attention.py"]:::core
            Emb_rotary["rotary_embedding.py"]:::core
        end
        subgraph "Model Definition"
            direction TB
            Mod_aff["affinity_pred_model.py"]:::core
            Mod_mods["modules.py"]:::core
        end
        subgraph "Inference API / CLI"
            direction TB
            Inf_main["main.py (AbAffinity API)"]:::core
        end
        Package_cfg["setup.py / requirements.txt"]:::core
    end

    %% Generation Pipeline
    subgraph "Generation Pipeline" 
        direction TB
        subgraph "Genetic Algorithm Scripts"
            direction TB
            GA_ab["generate_GA_abmodel.py"]:::pipeline
            GA_pssm["generate_GA_pssm.py"]:::pipeline
            GA_rand["generate_GA_random.py"]:::pipeline
        end
        subgraph "Simulated Annealing Scripts"
            direction TB
            SA_ab["generate_SA_ABModel.py"]:::pipeline
            SA_pssm["generate_SA_PSSM.py"]:::pipeline
            SA_rand["generate_SA_Random.py"]:::pipeline
        end
        SBATCH["sbatch_script.sh"]:::pipeline
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HF["Huggingface Model Repo"]:::ext
        Cluster["SLURM Compute Cluster"]:::ext
    end

    %% Connections
    UI_Notebooks_Perf -->|reads| Raw_CSV
    UI_Notebooks_Perf -->|reads| Gen_CSV
    UI_Notebooks_Gen -->|reads| Gen_CSV
    UI_Example -->|calls API| Inf_main

    Raw_CSV --> Pre_create
    Pre_create --> Pre_data
    Pre_data --> Emb_esm2
    Pre_data --> Emb_axial
    Emb_esm2 --> Mod_aff
    Emb_axial --> Mod_aff
    Emb_mha --> Mod_aff
    Emb_rotary --> Mod_aff
    Mod_aff --> Inf_main
    HF --> Inf_main
    Inf_main -->|predicts| UI_Notebooks_Perf

    GA_ab --> Inf_main
    GA_pssm --> Inf_main
    GA_rand --> Inf_main
    SA_ab --> Inf_main
    SA_pssm --> Inf_main
    SA_rand --> Inf_main
    SBATCH --> GA_ab
    SBATCH --> GA_pssm
    SBATCH --> GA_rand
    SBATCH --> SA_ab
    SBATCH --> SA_pssm
    SBATCH --> SA_rand
    GA_ab --> Gen_CSV
    GA_pssm --> Gen_CSV
    GA_rand --> Gen_CSV
    SA_ab --> Gen_CSV
    SA_pssm --> Gen_CSV
    SA_rand --> Gen_CSV

    Cluster --> SBATCH

    %% Click Events
    click Pre_create "https://github.com/ucrbioinfo/abaffinity/blob/main/src/AbAffinity/create_dataset.py"
    click Pre_data "https://github.com/ucrbioinfo/abaffinity/blob/main/src/AbAffinity/data.py"
    click Emb_esm2 "https://github.com/ucrbioinfo/abaffinity/blob/main/src/AbAffinity/esm2.py"
    click Emb_axial "https://github.com/ucrbioinfo/abaffinity/blob/main/src/AbAffinity/axial_attention.py"
    click Emb_mha "https://github.com/ucrbioinfo/abaffinity/blob/main/src/AbAffinity/multihead_attention.py"
    click Emb_rotary "https://github.com/ucrbioinfo/abaffinity/blob/main/src/AbAffinity/rotary_embedding.py"
    click Mod_aff "https://github.com/ucrbioinfo/abaffinity/blob/main/src/AbAffinity/affinity_pred_model.py"
    click Mod_mods "https://github.com/ucrbioinfo/abaffinity/blob/main/src/AbAffinity/modules.py"
    click Inf_main "https://github.com/ucrbioinfo/abaffinity/blob/main/src/AbAffinity/main.py"
    click Package_cfg "https://github.com/ucrbioinfo/abaffinity/blob/main/src/setup.py"
    click Package_cfg "https://github.com/ucrbioinfo/abaffinity/blob/main/src/requirements.txt"
    click GA_ab "https://github.com/ucrbioinfo/abaffinity/blob/main/Antibodies Generation/generate_GA_abmodel.py"
    click GA_pssm "https://github.com/ucrbioinfo/abaffinity/blob/main/Antibodies Generation/generate_GA_pssm.py"
    click GA_rand "https://github.com/ucrbioinfo/abaffinity/blob/main/Antibodies Generation/generate_GA_random.py"
    click SA_ab "https://github.com/ucrbioinfo/abaffinity/blob/main/Antibodies Generation/generate_SA_ABModel.py"
    click SA_pssm "https://github.com/ucrbioinfo/abaffinity/blob/main/Antibodies Generation/generate_SA_PSSM.py"
    click SA_rand "https://github.com/ucrbioinfo/abaffinity/blob/main/Antibodies Generation/generate_SA_Random.py"
    click SBATCH "https://github.com/ucrbioinfo/abaffinity/blob/main/Antibodies Generation/sbatch_script.sh"
    click Gen_CSV "https://github.com/ucrbioinfo/abaffinity/tree/main/Antibodies Generation/Generated Antibodies/"
    click Raw_CSV "https://github.com/ucrbioinfo/abaffinity/blob/main/data/cdr_similarity_sabdab.csv"
    click Raw_CSV "https://github.com/ucrbioinfo/abaffinity/blob/main/data/test_data_with_labels.csv"
    click Raw_CSV "https://github.com/ucrbioinfo/abaffinity/blob/main/data/thermostability_dataset.csv"
    click UI_Notebooks_Perf "https://github.com/ucrbioinfo/abaffinity/tree/main/notebooks/Ab-Affinity performance/"
    click UI_Notebooks_Gen "https://github.com/ucrbioinfo/abaffinity/tree/main/notebooks/Antibody Generation/"
    click UI_Example "https://github.com/ucrbioinfo/abaffinity/blob/main/notebooks/Example_Ab-Affinity.ipynb"
    click UI_Readme "https://github.com/ucrbioinfo/abaffinity/blob/main/README.md"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef pipeline fill:#d4edda,stroke:#333,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef ui fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef ext fill:#e2e3e5,stroke:#333,stroke-width:1px
```
