{"id":28937337,"url":"https://github.com/rosettacommons/rfantibody","last_synced_at":"2026-03-14T16:36:49.861Z","repository":{"id":283431137,"uuid":"920371930","full_name":"RosettaCommons/RFantibody","owner":"RosettaCommons","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-10T05:36:46.000Z","size":2342,"stargazers_count":165,"open_issues_count":26,"forks_count":47,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-11T15:56:13.574Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/RosettaCommons.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}},"created_at":"2025-01-22T03:09:53.000Z","updated_at":"2025-04-11T15:33:48.000Z","dependencies_parsed_at":"2025-03-20T08:33:09.852Z","dependency_job_id":null,"html_url":"https://github.com/RosettaCommons/RFantibody","commit_stats":null,"previous_names":["rosettacommons/rfantibody"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/RosettaCommons/RFantibody","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2FRFantibody","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2FRFantibody/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2FRFantibody/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2FRFantibody/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RosettaCommons","download_url":"https://codeload.github.com/RosettaCommons/RFantibody/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RosettaCommons%2FRFantibody/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261367514,"owners_count":23147852,"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":[],"created_at":"2025-06-22T21:05:33.096Z","updated_at":"2026-03-14T16:36:49.853Z","avatar_url":"https://github.com/RosettaCommons.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RFantibody\n### Structure-Based _de novo_ Antibody Design\n\n![](https://github.com/RosettaCommons/RFantibody/blob/main/github_image.png)\n\n# Description\nRFantibody is a pipeline for the structure-based design of _de novo_ antibodies and nanobodies. RFantibody consists of three separate methods:\n- Protein backbone design with an antibody-finetuned version of [RFdiffusion](https://www.nature.com/articles/s41586-023-06415-8)\n- Protein sequence design with [ProteinMPNN](https://www.science.org/doi/10.1126/science.add2187)\n- _In silico_ filtering of designs using an antibody-finetuned version of [RoseTTAFold2](https://www.biorxiv.org/content/10.1101/2023.05.24.542179v1)\n\nThe RFantibody pipeline is described in detail in [this preprint](https://www.biorxiv.org/content/10.1101/2024.03.14.585103v1)\n\n# Table of Contents\n- [Requirements](#requirements)\n- [Downloading Weights](#downloading-weights)\n- [Installation](#installation)\n  - [Local Installation (Without Docker)](#local-installation-without-docker)\n  - [Docker Installation (Alternative)](#docker-installation-alternative)\n  - [Apptainer Installation (HPC)](#apptainer-installation-hpc)\n- [Command Line Interface](#command-line-interface)\n  - [Inference Commands](#inference-commands)\n  - [Quiver Utilities](#quiver-utilities)\n  - [Full Pipeline Example](#full-pipeline-example)\n- [Usage](#usage)\n  - [HLT File Format](#hlt-file-format)\n  - [Input Preparation](#input-preparation)\n  - [RFdiffusion](#rfdiffusion)\n  - [ProteinMPNN](#proteinmpnn)\n  - [RF2](#rf2)\n- [Practical Considerations for Antibody Design](#practical-considerations-for-antibody-design)\n  - [Selecting a Target Site](#selecting-a-target-site)\n  - [Nanobody Docks](#nanobody-docks)\n  - [Truncating your Target Protein](#truncating-your-target-protein)\n  - [Picking Hotspots](#picking-hotspots)\n  - [Antibody Design Scale](#antibody-design-scale)\n  - [Choosing CDR Lengths](#choosing-cdr-lengths)\n  - [Filtering Strategies](#filtering-strategies)\n- [Quiver Files](#quiver-files)\n- [Conclusion](#conclusion)\n\n\n# Requirements\n\n### GPU Acceleration\n\nRFantibody requires an NVIDIA GPU with CUDA support to run. You can check whether you have a compatible NVIDIA GPU available by running:\n```\nnvidia-smi\n```\nIf this command runs successfully then you have a compatible GPU and RFantibody will be able to run on it.\n\n### System Requirements\n\n- **GPU**: NVIDIA GPU with CUDA 11.8+ support\n- **OS**: Linux (Ubuntu 22.04 recommended)\n\n\n# Installation\n\n## Local Installation (Without Docker)\n\nThis is the recommended installation method for most users. It installs RFantibody directly on your system.\n\n### 1. Install uv (Package Manager)\n\nRFantibody uses [uv](https://docs.astral.sh/uv/) for fast, reliable dependency management. uv will automatically download the required Python version (3.10) if needed.\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\nAfter installation, restart your terminal or run:\n```bash\nsource ~/.bashrc  # or ~/.zshrc if using zsh\n```\n\n### 2. Clone the Repository\n\n```bash\ngit clone https://github.com/RosettaCommons/RFantibody.git\ncd RFantibody\n```\n\n### 3. Download Model Weights\n\n```bash\nbash include/download_weights.sh\n```\n\n### 4. Set Up the Python Environment\n\nFrom the RFantibody directory, run:\n```bash\nuv sync\n```\nThis uses uv to:\n- Download Python 3.10 if not already installed\n- Create a virtual environment in `.venv/`\n- Install all dependencies including PyTorch with CUDA 11.8 support\n- Install [Deep Graph Library](https://www.dgl.ai) from CUDA-enabled wheels\n\n### 5. Activate the Environment\n\nAfter setup, you can either:\n\n**Option A**: Activate the virtual environment (recommended):\n```bash\nsource .venv/bin/activate\nrfdiffusion --help\n```\n\n**Option B**: Prefix commands with `uv run`:\n```bash\nuv run rfdiffusion --help\n```\n\n### Verifying the Installation\n\nRun the following to verify that RFantibody is installed correctly:\n```bash\nuv run rfdiffusion --help\n```\nThis should display the RFdiffusion help message with available options.\n\n---\n\n## Docker Installation (Alternative)\n\nDocker provides a containerized environment that isolates RFantibody from your host system. This can be useful for:\n- Simplified dependency management\n- Reproducible environments across different machines\n- Avoiding conflicts with existing system packages\n\n### Prerequisites\n\nInstall Docker from [here](https://docs.docker.com/engine/install/). If you are running RFantibody on cloud compute, Docker may already be installed. Check by running:\n```\nwhich docker\n```\n\nYou will need to add yourself to the docker group to run containers without sudo:\n```\nsudo usermod -aG docker $USER\n```\nAfter running this command, restart your terminal session for this change to take effect.\n\n### Build the Docker Image\n\nNavigate to the directory where RFantibody is downloaded, then build the Docker image:\n```\ndocker build -t rfantibody .\n```\n\n### Start the Docker Container\n\nRun the following command to start the container:\n```\ndocker run --name rfantibody --gpus all -v .:/home --memory 10g -it rfantibody\n```\nThis will put you into the RFantibody container at the `/home` directory which mirrors the directory that you ran the command from.\n\n### Set Up the Python Environment (Inside Container)\n\nFrom inside the RFantibody container, navigate to the project root and run:\n```bash\ncd /home\nuv sync\n```\n\n---\n\n## Apptainer Installation (HPC)\n\n[Apptainer](https://apptainer.org/) (formerly Singularity) is a container platform designed for HPC environments. Unlike Docker, it runs without root privileges and integrates with job schedulers like SLURM.\n\n### Prerequisites\n\nInstall Apptainer on Ubuntu:\n```bash\nsudo apt update\nsudo add-apt-repository -y ppa:apptainer/ppa\nsudo apt update\nsudo apt install -y apptainer\n```\n\n### Build the Apptainer Image\n\nNavigate to the RFantibody directory and build the image:\n```bash\ncd RFantibody\nsudo apptainer build rfantibody.sif rfantibody.def\n```\n\nThis creates a self-contained `rfantibody.sif` file (~8GB) with all dependencies, model weights, and the Python environment pre-installed.\n\n### Running Commands\n\nAlways use the `--nv` flag (for GPU support) and `--writable-tmpfs` flag (for temporary file writes):\n\n```bash\n# Get help for any command\napptainer exec --nv --writable-tmpfs rfantibody.sif rfdiffusion --help\napptainer exec --nv --writable-tmpfs rfantibody.sif proteinmpnn --help\napptainer exec --nv --writable-tmpfs rfantibody.sif rf2 --help\n```\n\n### Bind Mounting Data\n\nUse `-B` to mount directories from your host system:\n\n```bash\n# Mount a data directory\napptainer exec --nv --writable-tmpfs \\\n    -B /path/to/data:/data \\\n    rfantibody.sif rfdiffusion \\\n    -t /data/target.pdb \\\n    -f /data/framework.pdb \\\n    -o /data/output \\\n    -n 10\n```\n\n### Full Pipeline Example (Apptainer)\n\n```bash\n# Set up bind mount\nDATA_DIR=scripts/examples\nAPPTAINER_OPTS=\"--nv --writable-tmpfs -B $DATA_DIR:/data\"\n\n# 1. Design backbones with RFdiffusion\napptainer exec $APPTAINER_OPTS rfantibody.sif rfdiffusion \\\n    -t /data/example_inputs/flu_HA.pdb \\\n    -f /data/example_inputs/h-NbBCII10.pdb \\\n    -q /data/example_outputs/1_app_rfdiffusion.qv \\\n    -n 2 \\\n    -l \"H1:7,H2:6,H3:5-13\" \\\n    -h \"B146,B170,B177\"\n\n# 2. Design sequences with ProteinMPNN\napptainer exec $APPTAINER_OPTS rfantibody.sif proteinmpnn \\\n    -q /data/example_outputs/1_app_rfdiffusion.qv \\\n    --output-quiver /data/example_outputs/2_app_proteinmpnn.qv \\\n    -n 4 \\\n    -t 0.2\n\n# 3. Predict structures with RF2\napptainer exec $APPTAINER_OPTS rfantibody.sif rf2 \\\n    -q /data/example_outputs/2_app_proteinmpnn.qv \\\n    --output-quiver /data/example_outputs/3_app_rf2.qv \\\n    -r 10\n\n# 4. Extract scores to scripts/examples/example_outputs/3_app_rf2.sc\napptainer exec $APPTAINER_OPTS rfantibody.sif qvscorefile /data/example_outputs/3_app_rf2.qv\n```\n\n### Interactive Shell\n\nTo enter an interactive shell inside the container:\n```bash\napptainer shell --nv --writable-tmpfs rfantibody.sif\n```\n\nType `exit` or press `Ctrl+D` to exit.\n\n### SLURM Integration\n\nExample SLURM batch script:\n```bash\n#!/bin/bash\n#SBATCH --job-name=rfantibody\n#SBATCH --gres=gpu:1\n#SBATCH --mem=32G\n#SBATCH --time=4:00:00\n\napptainer exec --nv --writable-tmpfs \\\n    -B /scratch/$USER:/data \\\n    /path/to/rfantibody.sif rfdiffusion \\\n    -t /data/target.pdb \\\n    -f /data/framework.pdb \\\n    -o /data/designs \\\n    -n 100\n```\n\n# Command Line Interface\n\nRFantibody provides a set of command-line tools for running the design pipeline and working with Quiver files. After setting up the environment, these commands are available directly in your terminal.\n\n## Inference Commands\n\n### RFdiffusion (Backbone Design)\n\n```bash\nrfdiffusion -t antigen.pdb -f framework.pdb -o designs/ab -n 10\n```\n\nKey options:\n- `-t, --target`: Target PDB file (antigen)\n- `-f, --framework`: Framework PDB file (antibody scaffold)\n- `-o, --output`: Output prefix for designs\n- `-q, --output-quiver`: Output to Quiver file instead of PDBs\n- `-n, --num-designs`: Number of designs to generate\n- `-l, --design-loops`: Loop lengths, e.g., `\"H1:7,H2:6,H3:5-13,L1:8-13,L2:7,L3:9-11\"`\n- `-h, --hotspots`: Hotspot residues, e.g., `\"A305,A456\"`\n- `--deterministic`: Enable reproducible results\n\nExample with all options:\n```bash\nrfdiffusion \\\n    -t target.pdb \\\n    -f framework.pdb \\\n    -q designs.qv \\\n    -n 100 \\\n    -l \"H1:7,H2:6,H3:5-13,L1:8-13,L2:7,L3:9-11\" \\\n    -h \"T305,T456\" \\\n    --deterministic\n```\n\n### ProteinMPNN (Sequence Design)\n\n```bash\nproteinmpnn -i structures/ -o sequences/ -n 5\n```\n\nKey options:\n- `-i, --input-dir`: Input directory of PDB files\n- `-q, --input-quiver`: Input Quiver file\n- `-o, --output-dir`: Output directory for PDB files\n- `--output-quiver`: Output Quiver file\n- `-l, --loops`: Loops to design (default: `H1,H2,H3,L1,L2,L3`)\n- `-n, --seqs-per-struct`: Sequences per structure\n- `-t, --temperature`: Sampling temperature (default: 0.1)\n- `--deterministic`: Enable reproducible results\n\nExample with Quiver files:\n```bash\nproteinmpnn -q backbones.qv --output-quiver sequences.qv -n 5 -t 0.2\n```\n\n### RF2 (Structure Prediction)\n\n```bash\nrf2 -i structures/ -o predictions/\n```\n\nKey options:\n- `-p, --input-pdb`: Single input PDB file\n- `-i, --input-dir`: Input directory of PDB files\n- `-q, --input-quiver`: Input Quiver file\n- `-o, --output-dir`: Output directory for PDB files\n- `--output-quiver`: Output Quiver file\n- `-r, --num-recycles`: Recycling iterations (default: 10)\n- `-s, --seed`: Random seed for reproducibility\n- `--hotspot-show-prop`: Proportion of hotspot residues to show to model (default: 0.1)\n\nExample with Quiver files:\n```bash\nrf2 -q sequences.qv --output-quiver predictions.qv -r 10\n```\n\n## Quiver Utilities\n\nCommands for working with Quiver files (protein design databases):\n\n| Command | Description |\n|---------|-------------|\n| `qvls` | List all tags in a Quiver file |\n| `qvextract` | Extract all PDB files from a Quiver |\n| `qvextractspecific` | Extract specific PDBs by tag name |\n| `qvscorefile` | Extract scores to a TSV file |\n| `qvsplit` | Split into multiple files |\n| `qvslice` | Extract specific tags to new Quiver |\n| `qvrename` | Rename tags in a Quiver file |\n| `qvfrompdbs` | Create a Quiver from PDB files |\n\nAll commands support `--help` for detailed usage information.\n\n## Full Pipeline Example\n\nWe provide a complete pipeline script at `scripts/examples/nanobody_full_pipeline.sh` that runs all three steps of the RFantibody workflow. Here's a walkthrough:\n\n### Configuration\n\nThe script defines editable parameters at the top:\n\n```bash\n# Input files\nTARGET_PDB=\"scripts/examples/example_inputs/flu_HA.pdb\"       # Target antigen\nFRAMEWORK_PDB=\"scripts/examples/example_inputs/h-NbBCII10.pdb\" # Nanobody framework\n\n# Output directory\nOUTPUT_DIR=\"scripts/examples/example_outputs/nb_ha_pipeline\"\n\n# RFdiffusion parameters\nNUM_DESIGNS=1000                        # Number of backbone designs\nDESIGN_LOOPS=\"H1:7,H2:6,H3:5-13\"        # CDR loop lengths\nHOTSPOTS=\"B146,B170,B177\"               # Target residues to focus binding\n\n# ProteinMPNN parameters\nNUM_SEQS=4                              # Sequences per backbone\nSAMPLING_TEMP=0.2                       # Sampling temperature\n\n# RF2 parameters\nNUM_RECYCLES=10                         # Recycling iterations\n```\n\n### Step 1: RFdiffusion (Backbone Design)\n\n```bash\nuv run rfdiffusion \\\n    --target \"$TARGET_PDB\" \\\n    --framework \"$FRAMEWORK_PDB\" \\\n    --output-quiver \"$OUTPUT_DIR/1_rfdiffusion.qv\" \\\n    --num-designs \"$NUM_DESIGNS\" \\\n    --design-loops \"$DESIGN_LOOPS\" \\\n    --hotspots \"$HOTSPOTS\"\n```\n\nThis generates nanobody backbone structures docked to the target, with CDR loops designed to contact the specified hotspot residues.\n\n### Step 2: ProteinMPNN (Sequence Design)\n\n```bash\nuv run proteinmpnn \\\n    --input-quiver \"$OUTPUT_DIR/1_rfdiffusion.qv\" \\\n    --output-quiver \"$OUTPUT_DIR/2_proteinmpnn.qv\" \\\n    --seqs-per-struct \"$NUM_SEQS\" \\\n    --temperature \"$SAMPLING_TEMP\"\n```\n\nTakes the backbone designs and generates amino acid sequences for the CDR loops. Multiple sequences per backbone increases diversity.\n\n### Step 3: RF2 (Structure Prediction)\n\n```bash\nuv run rf2 \\\n    --input-quiver \"$OUTPUT_DIR/2_proteinmpnn.qv\" \\\n    --output-quiver \"$OUTPUT_DIR/3_rf2.qv\" \\\n    --num-recycles \"$NUM_RECYCLES\"\n```\n\nPredicts the final structures and provides confidence scores (pLDDT, PAE) for filtering.\n\n### Working with Results\n\nAfter the pipeline completes, use Quiver utilities to analyze results:\n\n```bash\n# List all designs\nqvls $OUTPUT_DIR/3_rf2.qv\n\n# Extract information on how well RFdiffusion targeted the hotspots for each design\nqvscorefile $OUTPUT_DIR/1_rfdiffusion.qv\n\n# Extract RF2 scores to a tab-separated scorefile (3_rf2.sc)\nqvscorefile $OUTPUT_DIR/3_rf2.qv\n\n# Extract all PDBs for visual inspection\nqvextract $OUTPUT_DIR/3_rf2.qv -o final_designs/\n```\n\n### Running the Pipeline\n\n```bash\nbash scripts/examples/nanobody_full_pipeline.sh\n```\n\nThe script outputs three Quiver files representing each stage, allowing you to inspect intermediate results or restart from any step.\n\n# Usage\n\n\u003e **Note:** The examples below assume you have the RFantibody environment active. Either activate it with `source .venv/bin/activate`, or prefix each command with `uv run` (e.g., `uv run rfdiffusion ...`).\n\n## HLT File Format\nWe must pass structures between the different steps of the RFantibody pipeline. Each step of the pipeline must know:\n- The antibody-target complex structure we are currently designing for\n- Which chain is the Heavy chain, Light chain, and Target chain\n- Which residues are in which of the CDR loops\n\nTo enable the passing of this information between steps of the pipeline, we define a file format that we call an HLT file. An HLT file is simply a .pdb file but with the following modifications:\n- The Heavy chain is denoted as chain id 'H'\n- The Light chain is denoted as chain id 'L'\n- The Target chain(s) are denoted as chain id 'T' (even if there are multiple target chains)\n- The order of the chains in the file is Heavy then Light then Target\n- At the end of the file are PDB Remarks indicating the 1-indexed absolute (not per-chain) residue index of each of the CDR loops. For example:\n  ```\n  REMARK PDBinfo-LABEL:   32 H1\n  REMARK PDBinfo-LABEL:   52 H2\n  ```\n\n## Input Preparation\n\nThe antibody-finetuned version of RFdiffusion in RFantibody requires an HLT-remarked framework structure as input. We provide a script to perform this conversion:\n```bash\npython scripts/util/chothia_to_HLT.py -inpdb mychothia.pdb -outpdb myHLT.pdb\n```\n\nThis script expects a Chothia annotated .pdb file. A great source for these files is [SabDab](https://opig.stats.ox.ac.uk/webapps/sabdab-sabpred/sabdab), which provides Chothia annotated structures of all antibodies and nanobodies in the PDB and is updated every few months.\n\nWe provide the HLT-formatted antibody and nanobody frameworks that were used in the design campaigns from the RFantibody preprint here:\n```\nNanobody Framework: scripts/examples/example_inputs/h-NbBCII10.pdb\nScFv Framework: scripts/examples/example_inputs/hu-4D5-8_Fv.pdb\n```\n\n## RFdiffusion\n\nThe first step in RFantibody is to generate antibody-target docks using an antibody-finetuned version of RFdiffusion. Here is an example command that will run RFdiffusion:\n```bash\nrfdiffusion \\\n    -t scripts/examples/example_inputs/rsv_site3.pdb \\\n    -f scripts/examples/example_inputs/hu-4D5-8_Fv.pdb \\\n    -o scripts/examples/example_outputs/ab_des \\\n    -n 20 \\\n    -l \"H1:7,H2:6,H3:5-13,L1:8-13,L2:7,L3:9-11\" \\\n    -h \"T305,T456\"\n```\n\nLet's go through this command in more detail to understand what these options are doing:\n- `-t, --target`: A path to the target structure that we wish to design antibodies against. This is commonly a cropped target structure to reduce the computational expense of running the pipeline. Cropping strategies are explained in more depth [here](#truncating-your-target-protein).\n- `-f, --framework`: A path to the HLT-formatted antibody framework that we wish to use for our design. RFdiffusion will only design the structure and sequence of regions of the framework which are annotated as loops, this allows us to design the dock and loops of already optimized frameworks.\n- `-o, --output`: The prefix of the .pdb file outputs that we will generate.\n- `-n, --num-designs`: The number of designs we should generate.\n- `-l, --design-loops`: A mapping of each CDR loop to a range of allowed loop lengths. The length of each loop is sampled uniformly from this range and is sampled independently of the lengths sampled for other loops. If a CDR loop exists in the framework but is not specified, this CDR loop will have its sequence and structure fixed during design. If a CDR loop is included but no range of lengths is provided (e.g., `H1:7`), this CDR loop will have its sequence and structure designed but only with the specified length.\n- `-h, --hotspots`: A list of hotspot residues that define our epitope. We discuss selecting hotspots in more detail [here](#selecting-a-target-site).\n\nFor Quiver file output, use `-q` instead of `-o`:\n```bash\nrfdiffusion \\\n    -t target.pdb \\\n    -f framework.pdb \\\n    -q designs.qv \\\n    -n 100 \\\n    -l \"H1:7,H2:6,H3:5-13,L1:8-13,L2:7,L3:9-11\" \\\n    -h \"T305,T456\"\n```\n\nRun `rfdiffusion --help` to see all available options.\n\n## ProteinMPNN\n\nThe second step in RFantibody is to take the docks generated by RFdiffusion and assign sequences to the CDR loops. We do this using the base version of ProteinMPNN, ie. not an antibody-finetuned model. For convenience, we package the necessary ProteinMPNN scripts in this repo and provide a wrapper that enables the design of just the CDR loops using ProteinMPNN.\n\nAt its simplest, ProteinMPNN may be run on a directory of HLT-formatted .pdb files using the following command:\n```bash\nproteinmpnn -i /path/to/inputdir -o /path/to/outputdir\n```\n\nThis will design all CDR loops and will provide one sequence per input structure. To generate multiple sequences per structure or use Quiver files:\n```bash\n# Generate 5 sequences per structure with Quiver I/O\nproteinmpnn -q backbones.qv --output-quiver sequences.qv -n 5\n\n# Specify which loops to design and adjust temperature\nproteinmpnn -i structures/ -o sequences/ -l \"H1,H2,H3\" -t 0.2\n```\n\nRun `proteinmpnn --help` to see all available options.\n\n## RF2\n\nThe final step of the RFantibody pipeline is to use our antibody-finetuned RF2 to predict the structure of the sequences we just designed. We then assess whether RF2 is confident that the sequence will bind as we designed.\n\nAt its simplest, RF2 may be run on a directory of HLT-formatted .pdb files using the following command:\n```bash\nrf2 -i /path/to/inputdir -o /path/to/outputdir\n```\n\nBy default this will run with 10 recycling iterations and with 10% of hotspots provided to the model. We don't yet know what combination of these hyperparameters will be most predictive of design success but it should be possible to tune these values once we have data on more antibody and nanobody campaigns.\n\nFor Quiver file I/O or to adjust recycling iterations:\n```bash\n# Use Quiver files with 10 recycles\nrf2 -q sequences.qv --output-quiver predictions.qv -r 10\n\n# Run on a single PDB file\nrf2 -p design.pdb -o predictions/\n```\n\n### JSON Input\n\nRF2 also accepts JSON files containing antibody sequences and target structures. This is useful when you have antibody sequences (without coordinates) and a known target structure. Each entry in the JSON contains heavy/light chain sequences and the target's 3D coordinates:\n\n```bash\nrf2 -j targets.json -o predictions/\n```\n\nThe JSON file should be a dictionary keyed by sample ID, where each entry has:\n- `Hseq`: Heavy chain amino acid sequence (one-letter codes)\n- `Lseq`: Light chain amino acid sequence (one-letter codes)\n- `hotspots`: Boolean array marking target interface residues (length = target length)\n- `T`: Target structure dict with `seq` (integer-encoded), `xyz` (Lx27x3 coordinates), `mask` (Lx27 atom mask), `idx`, `pdb_idx`, and `cdr_bool`\n\n### TCR-MHC Prediction\n\nFor TCR structure prediction against MHC-peptide targets, use the JSON input format with the TCR-specific weights:\n\n```bash\nrf2 -j tcr_targets.json -o predictions/ \\\n    --weights weights/RFab_noframework-nosidechains-5-10-23_trainingparamsadded.pt \\\n    --hotspot-show-prop 0\n```\n\nThe TCR weights (`RFab_noframework-nosidechains-5-10-23_trainingparamsadded.pt`) are downloaded automatically by `include/download_weights.sh` and use the older BinderNetwork architecture, which is auto-detected at load time.\n\nRun `rf2 --help` to see all available options.\n\n# Practical Considerations for Antibody Design\nDesigning antibodies is similar to designing _de novo_ binders but is in an earlier stage of development. Here we share advice and learnings on how best to use this pipeline to design antibodies which will work experimentally. We expect some of this advice to change as more antibody design campaigns are performed and best-practices crystallize. Several of these sections are adapted from the analogous section of the RFdiffusion README as these two methods share many similarities and the advice applies to both.\n\n## Selecting a Target Site\n\nNot every site on a target protein is a good candidate for antibody design. For a site to be an attractive candidate for binding it should have \u003e~3 hydrophobic residues for the binder to interact with. Binding to charged polar sites is still quite hard. Binding to sites with glycans close to them is also hard since they often become ordered upon binding and you will take an energetic hit for that. Binding to unstructured loops has historically been hard but [this paper](https://www.nature.com/articles/s41586-023-06953-1) outlines a strategy to use RFdiffusion to bind unstructured peptides which share much in common unstructured loops, using this strategy should work with antibodies but depending on the flexibility of the loop, you will pay an energetic price for ordering the loop during binding.\n\n## Nanobody Docks\n\nWhen you begin looking at your nanobody outputs, you may notice that many are binding in a side-on dock. This is not a bug and is a result of the model being trained on natural nanobody docks which often bind in this side-on docking style and make some framework-mediated contacts. You may be able to tune your hotspots and CDR lengths to get a more antibody-like dock, but we recommend that if you desire an antibody-like dock, then you should design with an antibody framework.\n\n## Truncating your Target Protein\n\nRFdiffusion and RF2 scale in runtime as O(N^2) where N is the number of residues in your system. As such, it is a very good idea to truncate large targets so that your computations are not unnecessarily expensive. All steps in the RFantibody pipeline are designed to allow for a truncated target. Truncating a target is an art. For some targets, such as multidomain extracellular membranes, a natural truncation point is where two domains are joined by a flexible linker. For other proteins, such as virus spike proteins, this truncation point is less obvious. Generally you want to preserve secondary structure and introduce as few chain breaks as possible. You should also try to leave ~10A of target protein on each side of your intended target site. We recommend using PyMol to truncate your target protein.\n\n## Picking Hotspots\n\nHotspots are a feature that we integrated into the model to allow for the control of the site on the target which the antibody will interact with. During training, we classify a target residue as a hotspot if it has an average Cβ distance to the closest 5 antibody CDR residues of less than 8 Angstroms. Of all of the hotspots which are identified on the target 0-100% of these hotspots are actually provided to the model and the rest are masked. We find that RFantibody is more sensitive to exactly which hotspots are selected than vanilla RFdiffusion is. Where RFdiffusion tends to generative long helices when given a bad set of hotspots, RFantibody will generally just generate an undocked antibody if a bad set of hotspots is given. It is a very good idea to run a few pilot runs before generating thousands of designs to make sure the number of hotspots you are providing will give results you like.\n\n## Antibody Design Scale\n\nFor some of the target campaigns that we report on in our manuscript, we were able to identify VHH binders from a set of 95 designs. In the more general case, however, we expect that design campaigns in the 10k range will be required to identify hits. This is in large part due to the lack of a reliable filtering metric (discussed further in the [Filtering Strategies](#filtering-strategies) section). All data, both positive and negative, is useful for tuning and evaluating filters so if you run a design campaign and wish to share your data with the broader community that would be extremely helpful for moving toward a more reliable filter, higher success rates, and cheaper design campaigns.\n\n## Choosing CDR Lengths\n\nThe loop ranges that we used for our design campaigns are provided in the RFdiffusion example files. We determined these ranges by looking at the frequency of naturally occuring lengths for each loop and trying to cover most of the density with our range. We also tried to choose relatively short H3 loops, as we figured these would be easier to design and predict while still giving us enough length to bind effectively. There are some targets where having a long H3 may be useful, for instance when targeting a hydrophobic pocket in a protein. In these cases, the H3 range should be increased beyond what we provide in the examples.\n\n## Filtering Strategies\n\nWe recommend the following minimal filtering critieria: \u003cbr /\u003e\n\u003cbr /\u003e\nRF2 pAE \u003c 10 \u003cbr /\u003e\nRMSD (design versus RF2 predicted) \u003c 2\u0026#197; \u003cbr /\u003e\nIt may also be helpful to filter by Rosetta ddG \u003c -20 \u003cbr /\u003e\n\u003cbr /\u003e\nThe lack of an effective filter is the main limitation of the RFantibody pipeline at the moment. The version of RF2 that we provide may show weak enrichment of binders over non-binders in some cases but more data is needed to make this conclusion convincingly. Newly available structure prediction models such as AF3 present a promising alternative to RF2 and we are in the process of evaluating these models for predictivity on our design campaigns.\n\n# Quiver Files\n\nWhen running large-scale design campaigns it is often useful to have a single file which holds many designs and the scores associated with those designs. This is gentler on file systems than storing and accessing thousands of individual .pdb files. We offer the ability to use [Quiver files](https://github.com/nrbennet/quiver) in the RFantibody pipeline. These files are simply one large file with the contents of many smaller files inside of them. Each entry has a unique name and can store meta_data about the entry.\n\nRFantibody provides command line tools for working with Quiver files. These are composable (pipe-able) commands inspired by Brian Coventry's [silent_tools](https://github.com/bcov77/silent_tools) project. Use `--help` with any command for detailed options.\n\n```bash\n# make a quiver file\nqvfrompdbs *.pdb \u003e my.qv\n\n# ask what's in a quiver file\nqvls my.qv\n\n# ask how many things are in a quiver file\nqvls my.qv | wc -l\n\n# extract all pdbs from a quiver file\nqvextract my.qv\n\n# extract to a specific directory\nqvextract my.qv -o output_dir/\n\n# extract the first 10 pdbs from a quiver file\nqvls my.qv | head -n 10 | qvextractspecific my.qv\n\n# extract a random 10 pdbs from a quiver file\nqvls my.qv | shuf | head -n 10 | qvextractspecific my.qv\n\n# extract a specific pdb from a quiver file\nqvextractspecific my.qv name_of_pdb_0001\n\n# produce a scorefile from a quiver file\nqvscorefile my.qv \u003e scores.tsv\n\n# combine qv files\ncat 1.qv 2.qv 3.qv \u003e my.qv\n\n# rename tags in a quiver file\nqvls my.qv | sed 's/$/_v2/' | qvrename my.qv \u003e renamed.qv\n\n# slice specific tags into a new quiver file\nqvls | shuf | head -n 10 | qvslice \u003e subset.qv\n\n# split a quiver file into groups of 100\nqvsplit my.qv 100 -o split_dir/\n```\n\n## Reading and Writing Quiver Files\nAll steps of RFantibody allow for the use of Quiver files. The syntax is summarized here:\n\nRFdiffusion takes only a .pdb file target and framework as input. To output the designed backbones at quiver files append this argument to your input command:\n```\ninference.quiver=/path/to/myoutput.qv\n```\n\nFor ProteinMPNN, to input and output a Quiver file, use the following two arguments:\n```\n-inquiver /path/to/myinput.qv -outquiver /path/to/myoutput.qv\n```\n\nRFantibody takes the following two configs to work with Quiver file input and output\n```\ninput.quiver=/path/to/myinput.qv output.quiver=/path/to/myoutput.qv\n```\n\n# Conclusion\nWe are really excited to release RFantibody open-source! We can't wait to see what kinds of designs the broader community comes up with. We have worked hard to make this codebase as easy to setup and run as possible but please open a GitHub issue if you run into any problems.\n\n\\- Nate, Joe, and the RFantibody Team\n\n---\n\nRFantibody builds directly off of the architecture and weights of several methods which we acknowledge here. We thank Minkyung Baek and Frank DiMaio for developing RoseTTAFold and RoseTTAFold2 which the original RFdiffusion and our antibody-fine tuned RoseTTAFold2 model are based off of. We thank Justas Dauparas for developing ProteinMPNN which we provide an antibody-specific wrapper for in this repo. As the antibody-finetuned RFdiffusion we provide here is directly based off of the original version of RFdiffusion, we also thank David Juergens, Brian Trippe, and Jason Yim who co-developed the original RFdiffusion with us. RFantibody is released under an MIT License (see LICENSE file). It is free for both non-profit and for-profit use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosettacommons%2Frfantibody","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frosettacommons%2Frfantibody","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frosettacommons%2Frfantibody/lists"}