# fabiantraxler/ag_binding_affinity architecture

> Architecture diagram of the GitHub repository fabiantraxler/ag_binding_affinity, 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/fabiantraxler/ag_binding_affinity
- Repository: https://github.com/fabiantraxler/ag_binding_affinity

## Overview

##### Project type and purpose
- This is a research-oriented, full-stack machine-learning framework for predicting antibody–antigen binding affinities.
- It consists of:
- Data-generation/preprocessing pipelines (Snakemake + Python scripts)
- A Python package (`src/abag_affinity`) implementing dataset loaders, graph conversion, GNN/transformer models, training and evaluation utilities
- Experiment orchestration (hyperparameter sweeps, Slurm job scripts, WandB logging)
- Analysis notebooks for post-hoc evaluation

##### High-level architecture components
A. Raw data and external resources
- PDB files, metadata YAML (in `data/` and `src/data_generation/…/resources`)
- External dataset downloads (AbDb, SAbDab, PDBBind, SKEMPI, DMS)
B. Data-generation pipelines
- Snakemake workflows (`src/data_generation/*/Snakefile`)
- Supporting scripts (`scripts/*.py`, `src/data_generation/*/scripts/`)
- Conda environments specified in `envs/*.yaml`
→ produces cleaned PDBs, CSVs of complexes, “_relaxed” structures
C. Configuration
- `src/config.yaml`, CLI argument definitions (`src/abag_affinity/utils/argparse_utils.py`)
D. Core Python package (`src/abag_affinity`)
1. Dataset module
- `dataset/*.py`: loaders for BoundComplexGraphs, DMS, hetero‐graphs
2. Graph conversion and feature extraction
- `utils/graph_conversion.py`, `pdb_processing.py`, etc.
3. Model definitions
- `model/*.py`: GNN layers, EGNN, transformer attention, regression heads, twin wrappers
- `binding_ddg_predictor/models`: alternative predictor architectures
4. Training and evaluation
- `train/training_strategies.py` (bucket_train, cross-validation)
- `train/utils.py`, `train/wandb_config.py`
- `evaluate_model.py`, validation functions
5. Entrypoint
- `main.py`: parses CLI args, instantiates dataset, model, trainer, WandB, Slurm jobs
E. Experiment orchestration
- `src/experiments/…` containing sweep configs (`*.yaml`), Snakefiles, run scripts
- `src/scripts/cluster_affinity`, `start_train.sh` for Slurm submission
F. Results and logging
- Model checkpoints, metrics logged to Weights & Biases
- CSV outputs, plots in `results/` (downloaded or reproducible)
- Analysis notebooks in `src/data_analysis/` and `src/experiments/`

##### Relationships and data flows
1. Raw PDBs & metadata → Snakemake pipelines (with `--use-conda`) → Preprocessed PDBs + CSV datasets
2. Config YAML + CLI args → DataLoader → GraphConversion → Dataset object
3. Dataset → Model → TrainingStrategy → Trained model + checkpoints
4. During training: metrics → WandB (online or offline)
5. Experiment scripts read saved models/metrics → generate plots in notebooks

##### Architectural patterns and design principles
- Modular separation of concerns: data‐gen vs. core package vs. experiments vs. analysis
- Pipeline‐as‐code: Snakemake defines reproducible DAG of data transformations
- Extensibility: predictor architectures pluggable under `binding_ddg_predictor/models`
- Configuration driven: YAML + CLI for datasets, training hyperparameters, environments

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        MetadataYAML["metadata_dms_studies.yaml"]:::data
        PreparedPDBs["prepared_pdbs/"]:::data
    end

    %% Data-Generation Pipelines
    subgraph "Snakemake Data-Gen" 
        SnakemakeDSL["Snakemake Workflows"]:::code
        SnkFiles["Snakefiles & Scripts"]:::code
        CondaEnvs["Conda Envs"]:::config
    end

    Preprocessed["Preprocessed Data"]:::data

    %% Configuration Layer
    subgraph "Configuration"
        ConfigYAML["config.yaml"]:::config
        ArgParse["argparse_utils.py"]:::config
    end

    %% Core Package
    subgraph "Core Package"
        subgraph "Dataset Module"
            DataLoader["data_loader.py"]:::code
            HeteroLoader["hetero_data_loader.py"]:::code
            BackboneLoader["backbone_data_loader.py"]:::code
            AdvUtils["advanced_data_utils.py"]:::code
        end
        subgraph "Graph Conversion & Feature Extraction"
            GraphConv["graph_conversion.py"]:::code
            PdbProc["pdb_processing.py"]:::code
            FeatureExt["feature_extraction.py"]:::code
        end
        subgraph "Model Definitions"
            GConvLayers["graph_conv_layers.py"]:::code
            GConvModels["graph_conv_models.py"]:::code
            GNNModel["gnn_model.py"]:::code
            EGNN["egnn_clean.py"]:::code
            Twin["twin_wrapper.py"]:::code
            Heads["regression_heads.py"]:::code
            subgraph "DDG Predictor Models"
                Attention["attention.py"]:::code
                Predictor["predictor.py"]:::code
                Residue["residue.py"]:::code
                Common["common.py"]:::code
            end
        end
        subgraph "Training & Evaluation"
            TrainStrat["training_strategies.py"]:::code
            TrainUtils["utils.py"]:::code
            WandbCfg["wandb_config.py"]:::code
            EvalModel["evaluate_model.py"]:::code
        end
        Entrypoint["main.py"]:::code
    end

    %% Experiment Orchestration
    subgraph "Experiment Orchestration"
        ExpDir["src/experiments/"]:::code
        StartTrain["start_train.sh"]:::code
        ClusterAffinity["cluster_affinity"]:::code
        ClusterJob["cluster_train.job"]:::code
    end

    %% Analysis Notebooks
    subgraph "Analysis Notebooks"
        DataAnalysis["src/data_analysis/"]:::code
        DatasetAnalysis["dataset_analysis/"]:::code
        Exploratory["exploratory_analysis/"]:::code
        GraphAnalyze["graph_analyze.py"]:::code
    end

    %% External Services & Results
    subgraph "External Services"
        Slurm["Slurm Cluster"]:::external
        WAndB["Weights & Biases"]:::external
    end
    subgraph "Results"
        Checkpoints["Model Checkpoints"]:::data
        Metrics["Metrics & CSVs"]:::data
        Plots["Plots & Notebooks"]:::data
    end

    %% Data Flow
    MetadataYAML --> SnakemakeDSL
    PreparedPDBs --> SnakemakeDSL
    CondaEnvs --> SnakemakeDSL
    SnakemakeDSL --> Preprocessed
    SnkFiles --> Preprocessed

    Preprocessed --> DataLoader
    Preprocessed --> HeteroLoader
    Preprocessed --> BackboneLoader
    Preprocessed --> AdvUtils

    ConfigYAML --> Entrypoint
    ArgParse --> Entrypoint
    Entrypoint --> DataLoader

    DataLoader --> GraphConv
    HeteroLoader --> GraphConv
    BackboneLoader --> GraphConv
    AdvUtils --> GraphConv
    PdbProc --> FeatureExt
    FeatureExt --> GConvLayers

    GraphConv --> GConvLayers
    GConvLayers --> TrainStrat
    Heads --> TrainStrat
    TrainStrat --> EvalModel

    Entrypoint --> TrainStrat

    TrainStrat --> Checkpoints
    TrainStrat --> WAndB

    StartTrain --> Slurm
    ClusterAffinity --> Slurm
    Slurm --> Entrypoint

    Checkpoints --> ExpDir
    Metrics --> ExpDir
    WAndB --> ExpDir
    ExpDir --> DataAnalysis
    DataAnalysis --> DatasetAnalysis
    DataAnalysis --> Exploratory
    DataAnalysis --> GraphAnalyze

    %% Click Events
    click MetadataYAML "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/data/metadata_dms_studies.yaml"
    click PreparedPDBs "https://github.com/fabiantraxler/ag_binding_affinity/tree/main/data/prepared_pdbs/"
    click SnakemakeDSL "https://github.com/fabiantraxler/ag_binding_affinity/tree/main/src/data_generation/"
    click SnkFiles "https://github.com/fabiantraxler/ag_binding_affinity/tree/main/src/data_generation/*/Snakefile"
    click SnkFiles "https://github.com/fabiantraxler/ag_binding_affinity/tree/main/src/data_generation/*/scripts/"
    click CondaEnvs "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/envs/abag_env.yaml"
    click CondaEnvs "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/envs/environment.yaml"
    click CondaEnvs "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/envs/generation_environment.yml"
    click CondaEnvs "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/envs/rosetta_environment.yml"
    click ConfigYAML "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/config.yaml"
    click ArgParse "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/utils/argparse_utils.py"
    click DataLoader "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/dataset/data_loader.py"
    click HeteroLoader "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/dataset/hetero_data_loader.py"
    click BackboneLoader "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/dataset/backbone_data_loader.py"
    click AdvUtils "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/dataset/advanced_data_utils.py"
    click GraphConv "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/utils/graph_conversion.py"
    click PdbProc "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/utils/pdb_processing.py"
    click FeatureExt "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/utils/feature_extraction.py"
    click GConvLayers "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/model/graph_conv_layers.py"
    click GConvModels "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/model/graph_conv_models.py"
    click GNNModel "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/model/gnn_model.py"
    click EGNN "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/model/egnn_clean.py"
    click Twin "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/model/twin_wrapper.py"
    click Heads "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/model/regression_heads.py"
    click Attention "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/binding_ddg_predictor/models/attention.py"
    click Predictor "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/binding_ddg_predictor/models/predictor.py"
    click Residue "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/binding_ddg_predictor/models/residue.py"
    click Common "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/binding_ddg_predictor/models/common.py"
    click TrainStrat "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/train/training_strategies.py"
    click TrainUtils "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/train/utils.py"
    click WandbCfg "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/train/wandb_config.py"
    click EvalModel "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/evaluate_model.py"
    click Entrypoint "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/abag_affinity/main.py"
    click ExpDir "https://github.com/fabiantraxler/ag_binding_affinity/tree/main/src/experiments/"
    click StartTrain "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/scripts/start_train.sh"
    click ClusterAffinity "https://github.com/fabiantraxler/ag_binding_affinity/tree/main/src/scripts/cluster_affinity"
    click ClusterJob "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/scripts/cluster_train.job"
    click DataAnalysis "https://github.com/fabiantraxler/ag_binding_affinity/tree/main/src/data_analysis/"
    click DatasetAnalysis "https://github.com/fabiantraxler/ag_binding_affinity/tree/main/src/data_analysis/dataset_analysis/"
    click Exploratory "https://github.com/fabiantraxler/ag_binding_affinity/tree/main/src/data_analysis/exploratory_analysis/"
    click GraphAnalyze "https://github.com/fabiantraxler/ag_binding_affinity/blob/main/src/data_analysis/graph_analyze/graph_analyze.py"

    %% Styles
    classDef data fill:#bbdefb,stroke:#90caf9;
    classDef code fill:#c8e6c9,stroke:#66bb6a;
    classDef config fill:#eeeeee,stroke:#bdbdbd;
    classDef external fill:#ffe0b2,stroke:#ffb74d;
```
