How fabiantraxler/ag_binding_affinity works
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