{"id":21695259,"url":"https://github.com/martinpacesa/BindCraft","last_synced_at":"2025-07-18T09:30:46.141Z","repository":{"id":257869550,"uuid":"859248033","full_name":"martinpacesa/BindCraft","owner":"martinpacesa","description":"User friendly and accurate binder design pipeline","archived":false,"fork":false,"pushed_at":"2025-06-30T10:27:30.000Z","size":3610,"stargazers_count":574,"open_issues_count":7,"forks_count":122,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-06-30T11:30:35.447Z","etag":null,"topics":["alphafold2","binder","design","protein","pyrosetta"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/martinpacesa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-18T10:45:09.000Z","updated_at":"2025-06-30T10:27:34.000Z","dependencies_parsed_at":"2025-06-02T10:41:55.429Z","dependency_job_id":"dce2d5d7-f676-427f-a694-9802237a894b","html_url":"https://github.com/martinpacesa/BindCraft","commit_stats":null,"previous_names":["martinpacesa/bindcraft"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/martinpacesa/BindCraft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinpacesa%2FBindCraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinpacesa%2FBindCraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinpacesa%2FBindCraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinpacesa%2FBindCraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martinpacesa","download_url":"https://codeload.github.com/martinpacesa/BindCraft/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinpacesa%2FBindCraft/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265733722,"owners_count":23819398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alphafold2","binder","design","protein","pyrosetta"],"created_at":"2024-11-25T19:00:58.160Z","updated_at":"2025-07-18T09:30:46.126Z","avatar_url":"https://github.com/martinpacesa.png","language":"Python","funding_links":[],"categories":["Python","Design","🔬 Domain-Specific Applications"],"sub_categories":["🧬 Biology \u0026 Medicine"],"readme":"# BindCraft\n![alt text](https://github.com/martinpacesa/BindCraft/blob/main/pipeline.png?raw=true)\n\nSimple binder design pipeline using AlphaFold2 backpropagation, MPNN, and PyRosetta. Select your target and let the script do the rest of the work and finish once you have enough designs to order!\n\n[Preprint link for BindCraft](https://www.biorxiv.org/content/10.1101/2024.09.30.615802)\n\n**Note: Before posting an issue, read the complete wiki \u003ca href=\"https://github.com/martinpacesa/BindCraft/wiki/De-novo-binder-design-with-BindCraft\"\u003ehere\u003c/a\u003e. Issues that are covered in the wiki will be closed without an answer.**\n\n## Installation\nFirst you need to clone this repository. Replace **[install_folder]** with the path where you want to install it.\n\n`git clone https://github.com/martinpacesa/BindCraft [install_folder]`\n\nThe navigate into your install folder using *cd* and run the installation code. BindCraft requires a CUDA-compatible Nvidia graphics card to run. In the *cuda* setting, please specify the CUDA version compatible with your graphics card, for example '11.8'. If unsure, leave blank but it's possible that the installation might select the wrong version, which will lead to errors. In *pkg_manager* specify whether you are using 'mamba' or 'conda', if left blank it will use 'conda' by default. \n\nNote: This install script will install PyRosetta, which requires a license for commercial purposes. The code requires about 2 Mb of storage space, while the AlphaFold2 weights take up about 5.3 Gb.\n\n`bash install_bindcraft.sh --cuda '12.4' --pkg_manager 'conda'`\n\n## Google Colab\n\u003ca href=\"https://colab.research.google.com/github/martinpacesa/BindCraft/blob/main/notebooks/BindCraft.ipynb\"\u003e\n  \u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/\u003e\n\u003c/a\u003e \u003cbr /\u003e\nWe prepared a convenient google colab notebook to test the bindcraft code functionalities. However, as the pipeline requires significant amount of GPU memory to run for larger target+binder complexes, we highly recommend to run it using a local installation and at least 32 Gb of GPU memory.\n\n**Always try to trim the input target PDB to the smallest size possible! It will significantly speed up the binder generation and minimise the GPU memory requirements.**\n\n**Be ready to run at least a few hundred trajectories to see some accepted binders, for difficult targets it might even be a few thousand.**\n\n\n## Running the script locally and explanation of settings\nTo run the script locally, first you need to configure your target .json file in the *settings_target* folder. In the json file are the following settings:\n\n```\ndesign_path         -\u003e path where to save designs and statistics\nbinder_name         -\u003e what to prefix your designed binder files with\nstarting_pdb        -\u003e the path to the PDB of your target protein\nchains                -\u003e which chains to target in your protein, rest will be ignored\ntarget_hotspot_residues   -\u003e which position to target for binder design, for example `1,2-10` or chain specific `A1-10,B1-20` or entire chains `A`, set to null if you want AF2 to select binding site; better to select multiple target residues or a small patch to reduce search space for binder\nlengths           -\u003e range of binder lengths to design\nnumber_of_final_designs   -\u003e how many designs that pass all filters to aim for, script will stop if this many are reached\n```\nThen run the binder design script:\n\n`sbatch ./bindcraft.slurm --settings './settings_target/PDL1.json' --filters './settings_filters/default_filters.json' --advanced './settings_advanced/default_4stage_multimer.json'`\n\nThe *settings* flag should point to your target .json which you set above. The *filters* flag points to the json where the design filters are specified (default is ./filters/default_filters.json). The *advanced* flag points to your advanced settings (default is ./advanced_settings/default_4stage_multimer.json). If you leave out the filters and advanced settings flags it will automatically point to the defaults.\n\nAlternatively, if your machine does not support SLURM, you can run the code directly by activating the environment in conda and running the python code:\n\n```\nconda activate BindCraft\ncd /path/to/bindcraft/folder/\npython -u ./bindcraft.py --settings './settings_target/PDL1.json' --filters './settings_filters/default_filters.json' --advanced './settings_advanced/default_4stage_multimer.json'\n```\n\n**We recommend to generate at least a 100 final designs passing all filters, then order the top 5-20 for experimental characterisation.** If high affinity binders are required, it is better to screen more, as the ipTM metric used for ranking is not a good predictor for affinity, but has been shown to be a good binary predictor of binding. \n\nBelow are explanations for individual filters and advanced settings.\n\n## Advanced settings\nHere are the advanced settings controlling the design process:\n\n```\nomit_AAs                        -\u003e which amino acids to exclude from design (note: they can still occur if no other options are possible in the position)\nforce_reject_AA                 -\u003e whether to force reject design if it contains any amino acids specified in omit_AAs\ndesign_algorithm                -\u003e which design algorithm for the trajecory to use, the currently implemented algorithms are below\nuse_multimer_design             -\u003e whether to use AF2-ptm or AF2-multimer for binder design; the other model will be used for validation then\nnum_recycles_design             -\u003e how many recycles of AF2 for design\nnum_recycles_validation         -\u003e how many recycles of AF2 use for structure prediction and validation\nsample_models = True            -\u003e whether to randomly sample parameters from AF2 models, recommended to avoid overfitting\nrm_template_seq_design          -\u003e remove target template sequence for design (increases target flexibility)\nrm_template_seq_predict         -\u003e remove target template sequence for reprediction (increases target flexibility)\nrm_template_sc_design           -\u003e remove sidechains from target template for design\nrm_template_sc_predict          -\u003e remove sidechains from target template for reprediction\npredict_initial_guess           -\u003e Introduce bias by providing binder atom positions as a starting point for prediction. Recommended if designs fail after MPNN optimization.\npredict_bigbang                 -\u003e Introduce atom position bias into the structure module for atom initilisation. Recommended if target and design are large (more than 600 amino acids).\n\n# Design iterations\nsoft_iterations                 -\u003e number of soft iterations (all amino acids considered at all positions)\ntemporary_iterations            -\u003e number of temporary iterations (softmax, most probable amino acids considered at all positions)\nhard_iterations                 -\u003e number of hard iterations (one hot encoding, single amino acids considered at all positions)\ngreedy_iterations               -\u003e number of iterations to sample random mutations from PSSM that reduce loss\ngreedy_percentage               -\u003e What percentage of protein length to mutate during each greedy iteration\n\n# Design weights, higher value puts more weight on optimising the parameter.\nweights_plddt                   -\u003e Design weight - pLDDT of designed chain\nweights_pae_intra               -\u003e Design weight - PAE within designed chain\nweights_pae_inter               -\u003e Design weight - PAE between chains\nweights_con_intra               -\u003e Design weight - maximise number of contacts within designed chain\nweights_con_inter               -\u003e Design weight - maximise number of contacts between chains\nintra_contact_distance          -\u003e Cbeta-Cbeta cutoff distance for contacts within the binder\ninter_contact_distance          -\u003e Cbeta-Cbeta cutoff distance for contacts between binder and target\nintra_contact_number            -\u003e how many contacts each contact esidue should make within a chain, excluding immediate neighbours\ninter_contact_number            -\u003e how many contacts each contact residue should make between chains\nweights_helicity                -\u003e Design weight - helix propensity of the design, Default 0, negative values bias towards beta sheets\nrandom_helicity                 -\u003e whether to randomly sample helicity weights for trajectories, from -1 to 1\n\n# Additional losses\nuse_i_ptm_loss                  -\u003e Use i_ptm loss to optimise for interface pTM score?\nweights_iptm                    -\u003e Design weight - i_ptm between chains\nuse_rg_loss                     -\u003e use radius of gyration loss?\nweights_rg                      -\u003e Design weight - radius of gyration weight for binder\nuse_termini_distance_loss       -\u003e Try to minimise distance between N- and C-terminus of binder? Helpful for grafting\nweights_termini_loss            -\u003e Design weight - N- and C-terminus distance minimisation weight of binder\n\n# MPNN settings\nmpnn_fix_interface              -\u003e whether to fix the interface designed in the starting trajectory\nnum_seqs                        -\u003e number of MPNN generated sequences to sample and predict per binder\nmax_mpnn_sequences              -\u003e how many maximum MPNN sequences per trajectory to save if several pass filters\nsampling_temp = 0.1             -\u003e sampling temperature for amino acids, T=0.0 means taking argmax, T\u003e\u003e1.0 means sampling randomly.\")\n\n# MPNN settings - advanced\nbackbone_noise                  -\u003e backbone noise during sampling, 0.00-0.02 are good values\nmodel_path                      -\u003e path to the MPNN model weights\nmpnn_weights                    -\u003e whether to use \"original\" mpnn weights or \"soluble\" weights\nsave_mpnn_fasta                 -\u003e whether to save MPNN sequences as fasta files, normally not needed as the sequence is also in the CSV file\n\n# AF2 design settings - advanced\nnum_recycles_design             -\u003e how many recycles of AF2 for design\nnum_recycles_validation         -\u003e how many recycles of AF2 use for structure prediction and validation\noptimise_beta                   -\u003e optimise predictions if beta sheeted trajectory detected?\noptimise_beta_extra_soft        -\u003e how many extra soft iterations to add if beta sheets detected\noptimise_beta_extra_temp        -\u003e how many extra temporary iterations to add if beta sheets detected\noptimise_beta_recycles_design   -\u003e how many recycles to do during design if beta sheets detected\noptimise_beta_recycles_valid    -\u003e how many recycles to do during reprediction if beta sheets detected\n\n# Optimise script\nremove_unrelaxed_trajectory     -\u003e remove the PDB files of unrelaxed designed trajectories, relaxed PDBs are retained\nremove_unrelaxed_complex        -\u003e remove the PDB files of unrelaxed predicted MPNN-optimised complexes, relaxed PDBs are retained\nremove_binder_monomer           -\u003e remove the PDB files of predicted binder monomers after scoring to save space\nzip_animations                  -\u003e at the end, zip Animations trajectory folder to save space\nzip_plots                       -\u003e at the end, zip Plots trajectory folder to save space\nsave_trajectory_pickle          -\u003e save pickle file of the generated trajectory, careful, takes up a lot of storage space!\nmax_trajectories                -\u003e how many maximum trajectories to generate, for benchmarking\nacceptance_rate                 -\u003e what fraction of trajectories should yield designs passing the filters, if the proportion of successful designs is less than this fraction then the script will stop and you should adjust your design weights\nstart_monitoring                -\u003e after what number of trajectories should we start monitoring acceptance_rate, do not set too low, could terminate prematurely\n\n# debug settings\nenable_mpnn = True              -\u003e whether to enable MPNN design\nenable_rejection_check          -\u003e enable rejection rate check\n```\n\n## Filters\nHere are the features by which your designs will be filtered, if you don't want to use some, just set *null* as threshold. *higher* option indicates whether values higher than threshold should be kept (true) or lower (false). Features starting with N_ correspond to statistics per each AlphaFold model, Averages are accross all models predicted.\n```\nMPNN_score            -\u003e MPNN sequence score, generally not recommended as it depends on protein\nMPNN_seq_recovery       -\u003e MPNN sequence recovery of original trajectory\npLDDT             -\u003e pLDDT confidence score of AF2 complex prediction, normalised to 0-1\npTM               -\u003e pTM confidence score of AF2 complex prediction, normalised to 0-1\ni_pTM             -\u003e interface pTM confidence score of AF2 complex prediction, normalised to 0-1\npAE               -\u003e predicted alignment error of AF2 complex prediction, normalised compared AF2 by n/31 to 0-1\ni_pAE             -\u003e predicted interface alignment error of AF2 complex prediction,  normalised compared AF2 by n/31 to 0-1\ni_pLDDT             -\u003e interface pLDDT confidence score of AF2 complex prediction, normalised to 0-1\nss_pLDDT            -\u003e secondary structure pLDDT confidence score of AF2 complex prediction, normalised to 0-1\nUnrelaxed_Clashes       -\u003e number of interface clashes before relaxation\nRelaxed_Clashes         -\u003e number of interface clashes after relaxation\nBinder_Energy_Score       -\u003e Rosetta energy score for binder alone\nSurface_Hydrophobicity      -\u003e surface hydrophobicity fraction for binder\nShapeComplementarity      -\u003e interface shape complementarity\nPackStat            -\u003e interface packstat rosetta score\ndG                -\u003e interface rosetta dG energy\ndSASA             -\u003e interface delta SASA (size)\ndG/dSASA            -\u003e interface energy divided by interface size\nInterface_SASA_%        -\u003e Fraction of binder surface covered by the interface\nInterface_Hydrophobicity        -\u003e Interface hydrophobicity fraction of binder interface\nn_InterfaceResidues       -\u003e number of interface residues\nn_InterfaceHbonds       -\u003e number of hydrogen bonds at the interface\nInterfaceHbondsPercentage   -\u003e number of hydrogen bonds compared to interface size\nn_InterfaceUnsatHbonds      -\u003e number of unsatisfied buried hydrogen bonds at the interface\nInterfaceUnsatHbondsPercentage  -\u003e number of unsatisfied buried hydrogen bonds compared to interface size\nInterface_Helix%        -\u003e proportion of alfa helices at the interface\nInterface_BetaSheet%      -\u003e proportion of beta sheets at the interface\nInterface_Loop%         -\u003e proportion of loops at the interface\nBinder_Helix%         -\u003e proportion of alfa helices in the binder structure\nBinder_BetaSheet%       -\u003e proportion of beta sheets in the binder structure\nBinder_Loop%          -\u003e proportion of loops in the binder structure\nInterfaceAAs          -\u003e number of amino acids of each type at the interface\nHotspotRMSD           -\u003e unaligned RMSD of binder compared to original trajectory, in other words how far is binder in the repredicted complex from the original binding site\nTarget_RMSD           -\u003e RMSD of target predicted in context of the designed binder compared to input PDB\nBinder_pLDDT          -\u003e pLDDT confidence score of binder predicted alone\nBinder_pTM            -\u003e pTM confidence score of binder predicted alone\nBinder_pAE            -\u003e predicted alignment error of binder predicted alone\nBinder_RMSD           -\u003e RMSD of binder predicted alone compared to original trajectory\n```\n\n## Implemented design algorithms\n\u003cul\u003e\n \u003cli\u003e2stage - design with logits-\u003epssm_semigreedy (faster)\u003c/li\u003e\n \u003cli\u003e3stage - design with logits-\u003esoftmax(logits)-\u003eone-hot (standard)\u003c/li\u003e\n \u003cli\u003e4stage - design with logits-\u003esoftmax(logits)-\u003eone-hot-\u003epssm_semigreedy (default, extensive)\u003c/li\u003e\n \u003cli\u003egreedy - design with random mutations that decrease loss (less memory intensive, slower, less efficient)\u003c/li\u003e\n \u003cli\u003emcmc - design with random mutations that decrease loss, similar to Wicky et al. (less memory intensive, slower, less efficient)\u003c/li\u003e\n\u003c/ul\u003e\n\n## Known limitations\n\u003cul\u003e\n \u003cli\u003eSettings might not work for all targets! Number of iterations, design weights, and/or filters might have to be adjusted. Target site selection is also important, but AF2 is very good at detecting good binding sites if no hotspot is specified.\u003c/li\u003e\n \u003cli\u003eAF2 is worse at predicting/designing hydrophilic then it is at hydrophobic interfaces.\u003c/li\u003e\n \u003cli\u003eSometimes the trajectories can end up being deformed or 'squashed'. This is normal for AF2 multimer design, as it is very sensitive to the sequence input, this cannot be avoided without model retraining. However these trajectories are quickly detected and discarded. \u003c/li\u003e\n\u003c/ul\u003e\n\n## Credits\nThanks to Lennart Nickel, Yehlin Cho, Casper Goverde, and Sergey Ovchinnikov for help with coding and discussing ideas. This repository uses code from:\n\u003cul\u003e\n \u003cli\u003eSergey Ovchinnikov's ColabDesign (https://github.com/sokrypton/ColabDesign)\u003c/li\u003e\n \u003cli\u003eJustas Dauparas's ProteinMPNN (https://github.com/dauparas/ProteinMPNN)\u003c/li\u003e\n \u003cli\u003ePyRosetta (https://github.com/RosettaCommons/PyRosetta.notebooks)\u003c/li\u003e\n\u003c/ul\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartinpacesa%2FBindCraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartinpacesa%2FBindCraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartinpacesa%2FBindCraft/lists"}