rfab-harness

Campaign orchestration for de novo antibody design against cancer and rare disease targets

February 2026

The Pipeline

RFAntibody designs antibodies in three stages, each a separate ML model:

Stage 1 (RFdiffusion) generates antibody backbone structures using SE(3)-equivariant denoising diffusion. You specify which target residues to contact (hotspots) and how long each CDR loop should be. It produces thousands of diverse backbone conformations.

Stage 2 (ProteinMPNN) fills in amino acid sequences for each backbone, designing multiple sequence variants per structure. The CDR-specific masking ensures the framework regions stay fixed while loop sequences are optimized.

Stage 3 (RF2) predicts the structure of each designed antibody-antigen complex and scores it. Three metrics determine whether a design is worth pursuing:

Designs passing all three filters are ranked by a composite score (0.4×pAE + 0.3×RMSD + 0.3×ddG, min-max normalized) and exported as individual PDB files ready for experimental validation.

What the Harness Adds

• Campaign-as-config — One YAML file defines target, antibody format, CDR lengths, pipeline parameters, and filtering thresholds
• Target preparation — Automatic PDB fetching from RCSB, epitope-based truncation (10Å buffer), hotspot validation (hydrophobicity, contiguity), framework conversion to HLT format
• 15 validation rules — Catches misconfigured campaigns before burning GPU hours (hotspot ⊆ epitope, CDR ranges within biological limits, VHH vs scFv chain requirements)
• Multi-GPU parallelization — Automatic splitting via Quiver qvsplit across available GPUs
• Checkpoint/resume — Pipeline stages write checkpoint files; interrupted runs resume from the last completed stage
• Analysis pipeline — Score extraction from Quiver files, configurable filtering, composite ranking, HTML/CSV reports with score distributions, PDB + FASTA export
• Experimental planning — Auto-generated protocols for gene synthesis orders (yeast codon-optimized), yeast surface display screening, SPR kinetics, and OrthoRep affinity maturation

Quick Start

# Install
git clone https://github.com/inventcures/repro_rfantibody_for-cancer-targets.git
cd repro_rfantibody_for-cancer-targets
pip install -e .

# Validate a campaign config (no GPU needed)
rfab validate campaigns/smoke_test.yaml

# Dry run — prepare inputs, check everything works
rfab run campaigns/smoke_test.yaml --dry-run --rfantibody-root ./RFAntibody

# Full campaign
rfab run campaigns/cancer/pdl1_vhh.yaml --rfantibody-root ./RFAntibody

# Re-analyze with different thresholds
rfab analyze campaigns/cancer/pdl1_vhh.yaml

Paper Reproductions

Six configs reproduce the targets from Bennett et al. (2025) with exact parameters from the paper:

Cancer Targets

Ten campaigns targeting validated cancer antigens, prioritized by structural data quality and therapeutic precedent:

Rare Disease Targets

Technical Details

Campaign Config Schema

Each campaign is a YAML file with six sections:

# campaigns/cancer/pdl1_vhh.yaml
campaign:
  name: "pdl1_vhh"

target:
  pdb_id: "5N2C"
  chain_id: "A"
  epitope_residues: [54, 56, 58, 60, 62, ...]
  hotspot_residues: [56, 60, 115]
  truncation:
    enabled: true
    buffer_angstroms: 10.0

antibody:
  format: "vhh"
  framework: "builtin:NbBCII10"
  cdr_loops:
    H1: "7"
    H2: "6"
    H3: "5-13"    # variable length range

pipeline:
  rfdiffusion:
    num_designs: 10000
  proteinmpnn:
    sequences_per_backbone: 5
    temperature: 0.2

filtering:
  pae_threshold: 10.0
  rmsd_threshold: 2.0
  ddg_threshold: -20.0

Validation Rules

The harness validates 15 rules before any GPU computation:

• Exactly one target source (PDB ID xor local file)
• Hotspot residues must be a subset of epitope residues
• Minimum 3 epitope residues and 3 hotspot residues
• VHH format cannot specify light chain CDRs (L1/L2/L3)
• scFv format must specify both heavy and light chain CDRs
• Builtin framework name must exist in the framework registry
• CDR loop lengths must fall within biological limits (max 20 residues)
• Range specs must be valid (min ≤ max)
• Minimum 50 designs (below this, too few for meaningful filtering)
• ProteinMPNN temperature between 0.01 and 1.0

Antibody Formats

Composite Scoring

Designs passing all filters are ranked by:

score = 0.4 × norm(pAE) + 0.3 × norm(RMSD) + 0.3 × norm(ddG)

where norm() is min-max normalization across all passing designs (lower composite score = better candidate). Weights reflect that binding confidence (pAE) is the most informative single metric per the original paper.

From Computation to Experiment

The harness includes experimental planning modules that generate protocols for the complete design-to-validation cycle:

• Gene synthesis — Yeast codon-optimized sequences with restriction site removal, ready for vendor upload (Twist, IDT, GenScript)
• Yeast surface display (YSD) — Expression induction, FACS staining (anti-HA-FITC + target-PE), sorting gates, timeline
• SPR characterization — Immobilization chemistry, concentration series (1.5–500 nM), kinetic fitting (1:1 Langmuir), regeneration conditions
• Affinity maturation — OrthoRep continuous evolution plan: 4 selection rounds with decreasing antigen concentration, expected ~100× affinity improvement over 8 weeks

This mirrors the validation workflow from the RFAntibody paper, where YSD screening followed by SPR confirmation identified binders from 1–2% of computationally passing designs.