ProteinDJ v3.0.1

What's Changed

• Move slurm specific gpu setting inside milton profile by @tlitfin in #54

Full Changelog: v3.0.0...v3.0.1

ProteinDJ v3.0.0

ProteinDJ v3.0.0

Major Update: PyRosectomy for commercial use, OpenMM Relaxation, and BoltzGen

Authors: @JoshuaMHardy @tlitfin @dladd

This release brings together a rewrite of dl_binder_design, analysis, and switches BindCraft to FreeBindCraft to remove the PyRosetta dependency. We have also integrated BoltzGen for fold design. Note that v3 is not backwards compatible and requires a fresh installation, as containers and models have been updated.

---

Highlights

• New step-by-step tutorial for binder design on the insulin receptor
• Replaced BindCraft with FreeBindCraft, removing the PyRosetta dependency from the binder hallucination stage.
• Rewrote dl_binder_design to drop PyRosetta in favour of OpenMM-based relaxation (GPU-accelerated, 4-5x faster than FastRelax).
• Rewrote analyse_best_designs.py (the final Analysis stage) to drop PyRosetta entirely, replacing it with PDBFixer/OpenMM relaxation, arpeggia (shape complementarity, H-bonds, SAP), and PRODIGY (binding free energy)
• Added BoltzGen as a third Fold Design engine alongside RFdiffusion and BindCraft, with new boltzgen_denovo (de novo monomer/binder generation) and boltzgen_motifscaff (existing monomer/binder sequence/structure redesign, including insertions and deletions) pipeline modes.
• Added a new option for prediction (af2_boltz) which runs AlphaFold2 first, followed by Boltz-2 on the surviving designs.
• Boltz-2 target prediction now supports targets with multiple/broken chains.
• Added an optional target-free "unbound" binder prediction with Boltz-2 (boltz_predict_unbound_binder, off by default)
• Collapsed the 8 monomer/binder RFdiffusion design_mode options into 4 (rfd_denovo, rfd_foldcond, rfd_motifscaff, rfd_partialdiff); monomer vs. binder behaviour is now auto-detected at runtime
• Removed the rfd_contigs/rfd_inpaint_seq manual contig-specification parameters entirely. RFdiffusion contigs are now always auto-generated from parameters — trim/edit your target PDB directly (e.g. in ChimeraX/PyMOL) instead of writing contig strings by hand.

FreeBindCraft / BindCraft

• Raised verbosity of the OpenMM relaxation step to report per-iteration energies.
• Relaxation across the 3 stages now always resumes from the best geometry seen so far, so the tight-tolerance stage 3 (0.1 kJ/mol/nm) refines the best structure rather than a potentially degraded one from stage 2.
• Forced temp file writes to the working directory.
• Container now explicitly installs CUDA 12 Python modules; pinned cuda-nvcc/cuda-version to 12.* to stop conda-forge from pulling CUDA 13.1+.

ProteinMPNN + FastRelax/OpenMMRelax

• dl_interface_design_multi.py now uses OpenMM relaxation instead of FastRelax (ProteinMPNN-OpenMMRelax) based on the algorithm used in FreeBindCraft, with increased logging of energies and acceptance/rejection decisions.
• Merged the af2 and dl_binder_design containers into one (dl_binder_design), since both now require GPU — the standalone af2.def and container are removed.
• ProteinMPNN weights removed from the container; now mounted at runtime via a new mpnn_models parameter, same as AF2 weights (with a matching model download step).

ProteinMPNN+OpenMMRelax benchmarking

We applied our new OpenMMRelax approach to binder design using the same benchmarking approach and five targets as in our paper, and calculated in silico success rates for AF2 prediction. Although there is some stochastic variation per target due to the random seeds, the average success rate across all targets was similar between FastRelax and OpenMMRelax, with the GPU-accelerated OpenMMRelax running 4-5x faster than CPU-bound FastRelax.

Sequence Design Method	HA	IL7Rα	IR	PD-L1	TrkA	Average
v2 ProteinMPNN(Soluble)	5.0%	5.8%	27.6%	33.9%	8.5%	16.2%
v3 ProteinMPNN(Soluble)	6.4%	9.8%	23.1%	33.9%	8.6%	16.4%
v2 ProteinMPNN(Soluble) + FastRelax	6.1%	9.1%	29.6%	52.3%	18.1%	23.0%
v3 ProteinMPNN(Soluble) + OpenMMRelax	4.9%	15.1%	30.1%	52.1%	13.5%	23.1%

Analysis & Filtering

• analyse_best_designs.py rewritten to remove PyRosetta:
  • Each predicted structure is now energy-minimized once (PDBFixer + OpenMM), preserving per-atom B-factors, and every metric is calculated from that single relaxed structure.
  • Interface shape complementarity (Lawrence & Colman algorithm), hydrogen bonds, buried unsatisfied hydrogen bonds (angle-dependent), and SAP score are now calculated with arpeggia instead of the sc binary/PyRosetta.
  • Binding free energy (pr_intface_deltaG) is now predicted with PRODIGY's IC-NIS model (kcal/mol) instead of Rosetta's InterfaceAnalyzerMover (Rosetta Energy Units).
  • Removed the defunct pr_intface_packstat / pr_TEM metrics and associated filters (pr_min_intface_packstat / pr_max_tem) metrics, which had no open-source equivalent.
  • Designs where the binder and target chains have no interface contact at all (e.g. a failed prediction) no longer crash the Analysis stage -- BSA, shape complementarity, deltaG, H-bonds, and unsatisfied H-bonds are reported as zero instead of raising an error.
  • Fixed handling of mkdssp >=4.0's PDB/mmCIF auto-detection for headerless AF2/Boltz output PDBs.
• Fold-based filtering (FilterFold) now uses BioPython (+DSSP) to calculate radius of gyration and the number of secondary structures, with the same mkdssp >=4.0 header fix applied.
• Sequence-property filtering (extinction coefficient, isoelectric point) split out of filter_analysis.py into a new dedicated scripts/filter_seq.py, exposed via a renamed FilterSeq process (replaces FilterMPNN).
• prep_fampnn_designs.py rewritten to use PDBFixer + FASPR (pyfaspr) instead of PyRosetta for backbone/side-chain restoration, preserving per-residue B-factor/occupancy metadata.
• New mpnn_time metric added alongside existing mpnn_score / fampnn_avg_psce.

Structure Prediction

• af2_initial_guess predict.py now uses BioPython for I/O, PDBfixer/Pyfaspr to add side-chains, instead of PyRosetta
• prep_boltz_yaml.py now detects chain breaks (C→N distance > 3 Å) and splits a target into multiple chains (B, C, D, …) before prediction.
• align_boltz.py updated to align/compute RMSD against all non-binder target chains, rather than assuming a single chain B.
• New metrics: boltz_ptm_binder (binder-only pTM) and boltz_ptm_target (mean pTM across all target chains). boltz_iptm is redefined as the mean binder→target interface pTM across all target chains.
• New pred_method option: af2_boltz, which cascades the two existing structure prediction methods -- AlphaFold2 Initial-Guess runs first as a fast pre-filter, survivors are filtered with any af2_* thresholds, and only the surviving designs are then re-predicted and filtered with Boltz-2 (boltz_* thresholds). This gives Boltz-2-quality metrics on the final design set while avoiding the cost of running Boltz-2 on every candidate.
  • When af2_boltz is used, both af2_* and boltz_* metric columns are populated for designs that make it through both stages.
  • Ranking (--rank_designs) defaults to the Boltz-2 metrics (boltz_ptm / boltz_ipSAE_min) when pred_method is af2_boltz, since Boltz-2 is the final/most-refined stage.
• Added persistent cache for AlphaFold2 to reduce compilation overhead of jax models by caching compiled kernels on disk, which persists across multiple runs (af2_jax_compilation_cache_dir). Each cache file is valid for a single design+target length and a single GPU model e.g. A30 only.
• Added ipTM metric for AlphaFold2 with filter (af2_min_iptm). Renamed metric field names for Boltz-2 from *_interface to *_iptm, *_iplddt, and *_ipde for consistency.
• Added an optional target-free "unbound" binder prediction with Boltz-2 (boltz_predict_unbound_binder, off by default), which predicts the binder chain alone as a monomer to check whether it folds consistently in the absence of the target. Binder design modes only; runs alongside the existing (bound) Boltz-2 prediction and adds new metrics: boltz_unbound_rmsd, boltz_unbound_conf_score, boltz_unbound_ptm, boltz_unbound_plddt, boltz_unbound_pde metrics with matching filters (boltz_max_unbound_rmsd, boltz_min_unbound_conf_score, boltz_min_unbound_ptm, boltz_min_unbound_plddt, boltz_max_unbound_pde).

Fold Conditioning

• Replaced PyRosetta DSSP with BioPython DSSP (mkdssp) for secondary structure assignment in create_scaffolds.py
• Removed incomplete P-SEA fallback (get_sse)
• Changed GenerateRFDFoldCond process label from pyrosetta_tools to python_tools (which already includes biopython and dssp)

RFdiffusion

• Collapsed monomer_denovo/binder_denovo into rfd_denovo, monomer_foldcond/binder_foldcond into rfd_foldcond, monomer_motifscaff/binder_motifscaff into rfd_motifscaff, and monomer_partialdiff/binder_partialdiff into rfd_partialdiff. Each mode now auto-detects monomer vs. binder design from whether input_pdb (and, for rfd_motifscaff/rfd_partialdiff, chain count/contigs) indicates a target is present, via a single is_binder_mode flag computed once and threaded through the workflow. Existing pipeline configs using the old 8 mode names will need to be updated to the new 4 mode names
• bindsweeper updated to match: binder_schema.json mode keys and mode-prefix checks renamed from binder_* to rfd_*.
• hotspot_residues now supports comma-separated residue ranges (e.g. A115-120) and whole-chain tokens (e.g. B) in addition to single residues, expanded internally into individual residues for RFdiffusion's ppi.hotspot_res — previously only single residues were supported, unlike BindCraft/BoltzGen.
• Removed th...

ProteinDJ v2.2.1

What's Changed

• Fix MacOS incompatible xargs flag by @JoshuaMHardy in #38

Full Changelog: v2.2.0...v2.2.1

ProteinDJ v2.2.0 - Paired sweeping parameters

What's Changed

Paired Parameters for Bindsweeper

Paired parameters allow you to sweep multiple parameters in lock-step, rather than as a Cartesian product. This is useful when parameters are inherently linked — for example, each target PDB has a corresponding MSA file or specific hotspot residues.

sweep_params:
  uncropped_target_pdb:
    values:
      - "input/protein1.pdb"
      - "input/protein2.pdb"
      - "input/protein3.pdb"
    paired_with:
      boltz_msa_path:
        - "input/msas/protein1.a3m"
        - "input/msas/protein2.a3m"
        - "input/msas/protein3.a3m"

Bug Fixes:

• Fix BindCraft advanced parameters helper in main.nf by @nskirk in #36
• ipSAE filename matching
• Validation of design length ignored when providing rfd_contigs
• Ranking now uses integers for file name matching and only outputs top N designs in ranked_designs.csv
• Changed ProteinMPNN to use a batch_id instead of task_id (which can change on resume)

New Contributors

• @nskirk made their first contribution in #36

Full Changelog: v2.1.1...v2.2.0

ProteinDJ v2.1.1 - Patch

Bug fixes and minor additions:

• Removed hardcoded required fields from nextflow_schema.json and schemas/nextflow_schema_custom.json to allow dynamic handling via the schema generation script. Modified generate_mode_schemas.py to explicitly define required parameters for each workflow mode, ensuring mode-specific schemas correctly enforce their requirements.
• Added a manifest section in nextflow.config to include contributor details, project description, DOI, and version, improving project documentation and discoverability. This enforces Nextflow version >= 24.04 as a requirement at launch

ProteinDJ v2.1.0 - Ranking and Analysis Filtering

Overview

This update focuses on enhancing ProteinDJ's output organization and filtering capabilities by adding design ranking functionality and a fourth filtering stage for biophysical analysis, along with significant documentation improvements and metric refinements.

Major Changes by Category:

1. Design Ranking System

• New script: rank_designs.py - Ranks designs based on prediction quality metrics
• New parameters:
  • rank_designs - Enable/disable ranking of outputs
  • ranking_metric - Specify metric for ranking (e.g., af2_pae_interaction, boltz_ipSAE_min)
  • max_designs - Limit number of top designs to output
  • max_seqs_per_fold - Limit sequences per fold to increase fold diversity
• Output structure: Added ranked_designs/ directory and ranked_designs.csv to results

2. Analysis Filtering Stage (4th Stage)

• New script: filter_analysis.py - Filter designs after PyRosetta analysis
• Can now filter using biophysical and sequence metrics including:
  • Interface quality: shape complementarity, H-bonds, unsatisfied H-bonds, packing
  • Energy: ΔG, ΔG/BSA ratio, total energy metric (TEM)
  • Solubility: SAP (Spatial Aggregation Propensity) scores for monomer and complex
  • Sequence properties: extinction coefficient, isoelectric point, surface hydrophobics
  • Secondary structure: helices, strands, radius of gyration

3. Boltz-2 Enhancements

• New metrics from ipSAE analysis (MIT-licensed scripts from Digital Biotechnology Lab):
  • ipSAE_min - Minimum Interaction Prediction Score from Aligned Errors
  • LIS - Local Interaction Score
  • pDockQ2_min - Minimum Predicted DockQ Score v2
  • boltz_pae_interaction - PAE at interaction interfaces
• New scripts:
  • analyse_boltz_batch.py - Parallel batch processing of ipSAE metrics
  • analyse_boltz_calc.py - Core ipSAE calculation engine
• New filtering parameters: 4 additional Boltz filtering criteria
• Template support: boltz_use_templates now defaults to true
• MSA support: New boltz_input_msa parameter for providing target MSA files (.a3m format)

4. Metric Naming Standardization

Renamed metrics for consistency across the pipeline:

• bc_target_rmsd → bc_rmsd_target
• boltz_overall_rmsd → boltz_rmsd_overall
• boltz_binder_rmsd → boltz_rmsd_binder
• boltz_target_rmsd → boltz_rmsd_target
• pr_surfhphobics_% → pr_surfhphobics
• Added boltz_ptm_binder and boltz_ptm_target alongside existing boltz_ptm

5. PyRosetta Analysis Improvements

• New metrics:
  • pr_intface_deltaGtoBSA - ΔG to BSA ratio
  • pr_intface_unsat_hbonds - Unsatisfied hydrogen bonds
  • pr_SAP - Spatial Aggregation Propensity (solubility predictor) of designed chain
  • pr_SAP_complex - SAP of binder when in complex with targer
• Reorganized output: Metrics now grouped logically in analyse_batch.py

6. BindSweeper Updates

• Version bump: 0.1.9 → 2.1.0 (aligned with ProteinDJ version)
• New CLI options to parellise and resume unfinished runs:
  • --resume - Use Nextflow's -resume flag for caching
  • --parallel - Execute combinations in parallel with isolated caches
  • --max-parallel - Control parallel execution limit (default: 4)
• Success metrics tracking: Now tracks all 4 stages including analysis filtering
• BindCraft mode support: Added bindcraft_denovo to binder schema
• Improved testing: New test suites for validators and success rate analyzer

7. Documentation Enhancements

• README.md updates:
  • Expanded filtering recommendations with literature references
  • Added BindCraft-specific built-in filters explanation
  • Updated output directory structure
  • Added citations for ipSAE scripts
• Parameters documentation:
  • New parameters for ranking designs
  • Updated Boltz parameter descriptions with units
  • Clarified filter parameter directions (higher/lower is better)
• BindSweeper documentation:
  • Detailed explanation of --resume functionality
  • Parallel execution usage examples
  • Performance optimization tips

8. Container Updates

• New container: python_tools - Lightweight Python environment (BioPython, Pandas, PyYAML, Matplotlib) for processes that do not need PyRosetta
• Version bumps: All containers updated to v2.1
• Used for prep scripts that don't need heavy dependencies

9. Success Metrics Calculation

• Enhanced generate_success_metrics.py:
  • Now tracks pred_generated (before filtering) vs pred_filtered
  • Adds analysis_filtered count
  • Properly handles skip stages (None values for skipped retention rates)
  • Uses first non-zero count as entry point for overall success rate

10. Metadata Management

• Updated metadata_converter.py:
  • Fixed seq_id output formatting (integer strings instead of floats)
  • Added all new metric columns to column ordering
  • Improved JSONL conversion for analysis metrics

Testing & Quality:

• New test files:
  • test_binder_validator.py - Validates BindCraft parameter handling
  • test_success_rate_analyzer.py - Tests metric calculation with skip scenarios
• Updated tests: Enhanced sweep engine tests for parallel execution
• Linting: Maintained Ruff compliance

Breaking Changes:

• Metric names changed (affects CSV column names and filter parameters)
• Container versions updated (requires re-pull)
• BindSweeper version jump requires awareness of new features

Backward Compatibility:

• Pipeline modes unchanged
• Config file structure preserved

ProteinDJ v2.0.0 - Major Update

This update introduces support for BindCraft and HyperMPNN to the ProteinDJ pipeline, template-guided structure prediction with Boltz-2, and improves container definitions for better compatibility.

Support for new design tools:

• Added BindCraft as a supported binder design tool, including its Apptainer container definition (apptainer/bindcraft.def) and integration into the build script (apptainer/build_containers.sh). BindCraft is now listed as a required external package in the documentation, and its design mode (bindcraft_denovo) is described in the usage guide.
• Added HyperMPNN support by downloading model weights in the dl_binder_design container and updating citations/documentation.

New features:

• Updated Boltz-2 to the latest release and implemented optional templates for structure prediction. This allows the user to bias structure prediction of the target chain towards the input, similar to AlphaFold2 Initial-Guess.
• Implemented automatic contig generation for RFdiffusion iff contigs are not provided. The generated contigs will include all protein residues in the input PDB. Users can still provide contigs to override this behaviour. For binder_foldcond mode, PyTorch files are now automatically generated for the target protein which removes a preparation step for the user.

Documentation and configuration updates:

• Updated README to reflect new supported tools and modes, changed parameter names to generalize beyond RFdiffusion (e.g., rfd_mode → design_mode, rfd_num_designs → num_designs), clarified design modes, and added BindCraft and HyperMPNN citations.
• Revised filtering stage terminology to be tool-agnostic (e.g., "Fold Filtering" instead of "RFD Filtering").

Container and build improvements:

• Updated container definitions for AlphaFold2 Initial Guess (apptainer/af2.def) and RFdiffusion (apptainer/rfdiffusion.def) to use newer CUDA versions and package dependencies for improved compatibility. Added test commands to check python dependencies.
• Moved containers to GitHub Container Repository (GHCR) with version tagging for future updates
• Added labels and help sections to containers for better documentation and usability.

Minor fixes and clarifications:

• Re-cropped images in README.
• Add validation of input files when skipping design stages
• Fixed typos and improved consistency in citations and documentation formatting.
• Reorganised validation functions and added validation of hardware resource requests
• Updated limitations and parameter descriptions in the README for clarity.

New Contributors

• @tlitfin made their first contribution in #14

Full Changelog: v1.1.0...v2.0.0

ProteinDJ v1.1.0 - Minor updates and bug fixes

This release addresses feedback from users with improvements to documentation and usability. It also resolves some bugs with Bindsweeper and adds new parameters to zip PDB file outputs and to enable Boltz-2x functionality.

What's Changed

• Added warning about non-standard amino acids in input files by @joshhardywehi in #2
• Restored .gitignore and removed timing.csv file generation by @joshhardywehi in #3
• Adding a unique date/time to output directory name by @joshhardywehi in #4
• Fix: Added default for bindsweeper_param_combo parameter by @joshhardywehi in #5
• BindSweeper fixes by @joshhardywehi in #6
• Documentation updates and new optional parameters by @joshhardywehi in #7
• Update to v1.1 by @joshhardywehi in #8

Full Changelog: v1.0.0...v1.1.0

Thanks to @Birkinshaw, @dvbrown, @knimak, @nskirk for testing and feedback

ProteinDJ v1.0.0 - Initial Release

The initial release of ProteinDJ