RosettaAntibodyDesign

Bold text means that these files and/or this information is provided.

Italicized text means that this material will NOT be conducted during the workshop

fixed width text means you should type the command into your terminal

If you want to try making files that already exist (e.g., input files), write them to a different directory! (mkdir my_dir)

Authors

• Tutorial and Program Author:
  • Jared Adolf_Bryfogle (jadolfbr@gmail.com)
• Edited by:
  • Benjamin K. Mueller
• Corresponding PI:
  • Roland Dunbrack (roland.dunbrack@fccc.edu)
  • Bill Schief (schief@scripps.edu)

Citation

Rosetta Antibody Design (RAbD): A General Framework for Computational Antibody Design, PLOS Computational Biology, 4/27/2018

Jared Adolf-Bryfogle, Oleks Kalyuzhniy, Michael Kubitz, Brian D. Weitzner, Xiaozhen Hu, Yumiko Adachi, William R. Schief, Roland L. Dunbrack Jr.

Overview

RosettaAntibodyDesign (RAbD) is a generalized framework for the design of antibodies, in which a user can easily tailor the run to their project needs. The algorithm is meant to sample the diverse sequence, structure, and binding space of an antibody-antigen complex. An app is available, and all components can be used within RosettaScripts for easy scripting of antibody design and incorporation into other Rosetta protocols.

The framework is based on rigorous bioinformatic analysis and rooted very much on our recent clustering of antibody CDR regions. It uses the North/Dunbrack CDR definition as outlined in the North/Dunbrack clustering paper. A new clustering paper will be out soon, and this new analysis will be incorporated into RAbD.

The supplemental methods section of the published paper has all details of the RosettaAntibodyDesign method. This manual serves to get you started running RAbD for typical use cases.

Algorithm

Broadly, the RAbD protocol consists of alternating outer and inner Monte Carlo cycles. Each outer cycle consists of randomly choosing a CDR (L1, L2, etc.) from those CDRs set to design, randomly choosing a cluster and then a structure from that cluster from the database according to the input instructions, and optionally grafting that CDR's structure onto the antibody framework in place of the existing CDR (GraftDesign). The program then performs N rounds of the inner cycle, consisting of sequence design (SeqDesign) using cluster-based sequence profiles and structural constraints, energy minimization, and optional docking. Each inner cycle structurally optimizes the backbone and repacks side chains of the CDR chosen in the outer cycle as well as optional neighbors in order to optimize interactions of the CDR with the antigen and other CDRs.

Backbone dihedral angle (CircularHarmonic) constraints derived from the cluster data are applied to each CDR to limit deleterious structural perturbations. Amino acid changes are typically sampled from profiles derived for each CDR cluster in PyIgClassify. Conservative amino acid substitutions (according to the BLOSUM62 substitution matrix) may be performed when too few sequences are available to produce a profile (e.g., for H3). After each inner cycle is completed, the new sequence and structure are accepted according to the Metropolis Monte Carlo criterion. After N rounds within the inner cycle, the program returns to the outer cycle, at which point the energy of the resulting design is compared to the previous design in the outer cycle. The new design is accepted or rejected according to the Monte Carlo criterion.

If optimizing the antibody-antigen orientation during the design (dock), SiteConstraints are automatically used to keep the CDRs (paratope) facing the antigen surface. These are termed ParatopeSiteConstraints. Optionally, one can enable constraints that keep the paratope of the antibody around a target epitope (antigen binding site). These are called ParatopeEpitopeSiteConstraints as the constraints are between the paratope and the epitope. The epitope is automatically determined as the interface residues around the paratope on input into the program, however, any residue(s) can be set as the epitope to limit unwanted movement and sampling of the antibody. See the examples and options below.

More detail on the algorithm can be found in the published paper.

General Setup and Inputs

1. Antibody Design Database

   This app requires the Rosetta Antibody Design Database. A database of antibodies from the original North Clustering paper is included in Rosetta and is used as the default . An updated database (which is currently updated bi-yearly) can be downloaded here: http://dunbrack2.fccc.edu/PyIgClassify/.

   It should be placed in Rosetta/main/database/sampling/antibodies/ It is recommended to use this up-to-date database for production runs. For this tutorial, we will use the database within Rosetta.

2. Starting Structure

   The protocol begins with the three-dimensional structure of an antibody-antigen complex. Designs should start with an antibody bound to a target antigen (however optimizing just the antibody without the complex is also possible). Camelid antibodies are fully supported. This structure may be an experimental structure of an existing antibody in complex with its antigen, a predicted structure of an existing antibody docked computationally to its antigen, or even the best scoring result of low-resolution docking a large number of unrelated antibodies to a desired epitope on the structure of a target antigen as a prelude to de novo design.

   The program CAN computationally design an antibody to anywhere on the target protein, but it is recommended to place the antibody at the target epitope. It is beyond the scope of this program to determine potential epitopes for binding, however servers and programs exist to predict these. Automatic SiteConstraints can be used to further limit the design to target regions.

3. Model Numbering and Light Chain identification

   The input PDB file must be renumbered to the AHo Scheme and the light chain gene must be identified. This can be done through the PyIgClassify Server.

   On input into the program, Rosetta assigns our CDR clusters using the same methodology as PyIgClassify. The RosettaAntibodyDesign protocol is then driven by a set of command-line options and a set of design instructions provided as an input file that controls which CDR(s) are designed and how. Details and example command lines and instruction files are provided below.

   The gene of the light chain should always be set on the command-line using the option -light_chain, these are either lamda or kappa. PyIgClassify will identify the gene of the light chain.

   For this tutorial, the starting antibody is renumbered for you.

4. Notes for Tutorial Shortening

   Always set the option, -outer_cycle_rounds to 5 in order to run these examples quickly. The default is 25. We include this in our common options file that is read in by Rosetta at the start. We will only be outputting a single structure, but typical use of the protocol is with default settings of -outer_cycle_rounds and an nstruct of at least 1000, with 5000-10000 recommended for jobs that are doing a lot of grafting. For De-novo design runs, one would want to go even higher. Note that the Docking stage increases runtime significantly as well.

   The total number of rounds is: outer_cycle_rounds * nstruct.

5. General Notes

   This tutorial assumes that you have Rosetta added to your PATH variable, as this is how Rosetta is generally run. If you do not already have this done, add the rosetta applications to your path. For example, using tcsh shell, do this:

       setenv PATH ${PATH}:${HOME}/rosetta_workshop/rosetta/main/source/bin
       setenv PATH ${PATH}:${HOME}/rosetta_workshop/rosetta/main/source/tools

   We will be using JSON output of the scorefile, as this is much easier to work with in python and pandas, and when generating a large amount of data (however this option is not necessary). We use the option -scorefile_format json

   All of our common options for the tutorial are in the common file that you will copy to your working directory. Rosetta will look for this file in your working directory or your home folder in the directory $HOME/.rosetta/flags. See this page for more info on using rosetta with custom config files: https://www.rosettacommons.org/docs/latest/rosetta_basics/running-rosetta-with-options#common-options-and-default-user-configuration

   All tutorials have generated output in output_files and their approximate time to finish on a single (core i7) processor.

Tutorial

Tutorial A: General Design

In many of these examples, we will use the application for simplicity, however, ALL options are available using the AntibodyDesignMover. XML lines are given if you are more comfortable in RosettaScripts. A skeleton XML file is provided for you if you want to go the RosettaScripts route. Note that the mover does not run InterfaceAnalyzer to report interface scores at the end of the run in the tutorial version of Rosetta. This is changed in the most current version of Rosetta. https://www.rosettacommons.org/docs/latest/scripting_documentation/RosettaScripts/Movers/movers_pages/antibodies/AntibodyDesignMover

You must still use the -light_chain command-line option.

Lets copy the files we need first:

    mkdir work_dir
    cd work_dir
    cp ../input_files/my_ab.pdb .
    cp ../input_files/color_cdrs.pml .
    cp ../input_files/rabd.xml .
    cp ../input_files/common .

You are starting design on a new antibody, that is not bound to the antigen in the crystal. This is difficult and risky, but we will show how one could go about this anyway. We start by selecting a framework. Here, we use the trastuzumab framework as it expresses well, is thermodynamically stable with a Tm of 69.5 degrees, and has been shown repeatedly that it can tolerate CDRs of different sequence and structure. Note that the energy of the complex is high as we are starting from a manual placement of the antibody to antigen. If we relax the structure too much, we will fall into an energy well that is hard to escape without significant sampling.

We are using an arbitrary protein at an arbitrary site for design. The PDB of our target is 1qaw. 1qaw is an oligomer of the TRP RNA-Binding Attenuation Protein from Bacillus Stearothermophilus. It is usually a monomer/dimer, but at its multimeric interface is a tryptophan residue by itself. As the concentration of TRP rises, the probability of finding a fully oligomeric complex increases, which in this state helps to decrease TRP production through the TRP-operon regulatory mechanism.

It's a beautiful protein, with a cool mechanism. We will attempt to design an antibody that binds to two subunits to stabilize the dimeric state of the complex in the absence of TRP. Note that de novo design currently takes a large amount of processing power. Each tutorial below is more complex than the one before it. The examples we have for this tutorial are short runs to show HOW it can be done, but more outer_cycle_rounds and nstruct would produce far better models than the ones you will see here - as we will need to sample the relative orientation of the antibody-antigen complex through docking, the CDR clusters and lengths, the internal backbone degrees of freedom of the CDRs, as well as the sequence of the CDRs and possibly the framework. As you can tell, just the sampling problem alone is difficult. However, this will give you a basis for using RAbD on your own.

1. Sequence Design

   Using the application is as simple as setting the -seq_design_cdrs option. This simply designs the CDRs of the heavy chain using cdr profiles if they exist for those clusters during flexible-backbone design. If the clusters do not exist (as is the case for H3 at the moment), we use conservative design by default. Run the command (make sure to have set the Rosetta paths earlier so the command points to the correct place):

       antibody_designer.linuxgccrelease -s my_ab.pdb \
           -seq_design_cdrs L1 L3 -light_chain kappa -nstruct 5 -out:prefix tutA1_
   
   
       <AntibodyDesignMover name="RAbD" seq_design_cdrs="L1,L3">

   This will take a few minutes (227 seconds on my laptop). Ouptut structures and scores are in ../output_files if you wish to copy them over. Score the input pose using the InterfaceAnalayzer application:

       InterfaceAnalyzer.linuxgccrelease -s my_ab.pdb -interface LH_ABCDEFGIJKZ -out:prefix native_

   Take a look at our scorefile, sort according to the interface energy, dG separated, which is calculated by the InterfaceAnalyzerMover. The score is calculated by scoring the complex, separating the antigen from the antibody, repacking side-chains at the interface, rescoring the separated complex, and then taking the difference between the two scores - i.e. the dG.

       scorefile.py --scores dG_separated --output tab tutA1_score.sc | sort  -k2 -k1

   Is it better than our input pose?

       scorefile.py --scores dG_separated --output tab tutA1_score.sc native_score.sc | sort  -k2 -k1 

2. Graft Design

   Now we will be enabling graft design AND sequence design on L1 and L3 loops. With an nstruct of 5, we are doing 25 design trials total. Run the command:

       antibody_designer.linuxgccrelease -s my_ab.pdb -graft_design_cdrs L1 L3 \
           -seq_design_cdrs L1 L3 -light_chain kappa -nstruct 5 -out:prefix tutA2_
   
   
       <AntibodyDesignMover name="RAbD" seq_design_cdrs="L1,L3" graft_design_cdrs="L1,L3">

   This will take a about 2-3 times as long as sequence design, as grafting a non-breaking loop takes time. This took 738 seconds on my laptop. Ouptut structures and scores are in ../output_files if you wish to copy them over.

   Typically, we require a much higher -outer_cycle_rounds and nstruct to see anything significant. Did this improve energies? (Note that, due to the limited number of models produced in this tutorial, even though a protocol should yeild a better, lower energy design, it may not due to the stocastic nature of Rosetta.)

       scorefile.py --scores dG_separated --summary tutA1_score.sc tutA2_score.sc
       scorefile.py --scores dG_separated --output tab native_score.sc \
           tutA1_score.sc tutA2_score.sc | sort -k2 -k1

   Take a look at the lowest (dG) scoring pose in pymol - do you see any difference in L1 and L3 loops there? Do they make better contact than what we had before?

   Lets take a look in pymol. Run the command:

       pymol my_ab.pdb tutA2_* 

   And then in pymol:

       @color_cdrs.pml
       center full_epitope

   How different are the L1 and L3 loops? Have any changed length?

   Open the PDB file of the lowest energy in a text editor. Go to the end of the file. Have the clusters changed from the native? To get the native cluster, open the PDB and look at the REMARK lines. This was generated using the identify_cdr_clusters application.

3. Basic De Novo Run

   Here, we want to do a de novo run (without docking), starting with randomly grafted CDRs, instead of the native CDRs in the starting antibody (this is only for the CDRs that are actually undergoing graft-design). This is useful, as we will begin the design run with very high energy and work our way down. Note that since this is an entirely new interface for our model protein, this interface is already at a very high energy - and so this procedure is less needed, but it should be noted how to do this. (139 seconds on my laptop)

       antibody_designer.linuxgccrelease -s my_ab.pdb -graft_design_cdrs L1 L3 \
           -seq_design_cdrs L1 L3 -light_chain kappa -random_start -nstruct 1 -out:prefix tutA3_
   
       <AntibodyDesignMover name="RAbD" graft_design_cdrs="L1,L3" seq_design_cdrs="L1,L3" 
                                                                         random_start="1"/>

   Would starting from a random CDR help anywhere? Perhaps if you want an entirely new cluster or length to break a patent or remove some off target effects? We will use it below to start de novo design with docking. Since the CDRs are native, these are already energetically favorable.

4. RosettaScripts RAbD Framework Components

   This tutorial will give you some exprience with your own XML antibody design protocol using the RosettaAntibodyDesign components. We will take the light chain CDRs from a malaria antibody and graft them into our antibody. In the tutorial we are interested in stabilizing the grafted CDRs in relation to the whole antibody, instead of interface design to an antigen.

   We will graft the CDRs in, minimize the structure with CDR dihedral constraints to not purturb the CDRs too much, and then design the framework around the CDRs while designing the CDRs and neighbors. The result should be mutations that better accomodate our new CDRs. This can be useful for humanizing potential antibodies or framework switching, where we want the binding properties of certain CDRs, but the stability or immunological profile of a different framework.

   1. Copy the Files

      cp ../input_files/ab_design_components.xml .
      cp ../input_files/malaria_cdrs.pdb .

      Take a look at the XML. We are using the AntibodyCDRGrafter to do the grafting of our CDRs. We then add constraints using CDRDihderalConstraintMovers for each CDR. Next, we do a round of packing/minimization/packing using the RestrictToCDRsAndNeighborsOperation and the CDRResidueSelector. This task operation controls what we pack and design. It first limits packing and design to only the CDRs and its neighbors. By specifying the designframework=1_ option we allow the neighbor framework residues to design, while the CDRs and antigen neighbors will only repack. If we wanted to disable antigen repacking, we would pass the DisableAntibodyRegionOperation task operation. Using this, we can specify any antibody region as antibodyregion_, cdrregion_, or antigenregion_ and we can disable just design or both packing and design.

      These task operations allow us to chisel exactly what we want to design in antibody, sans a residue-specific resfile (though we could combine these with one of them!). These TaskOperations will eventually also become ResidueSelectors, to increase their utility further.

      Finally, we use the SimpleMetric system to obtain our final sequence of the CDRs to compare to our native antibody as well as pymol selections of our CDRs.
      • https://www.rosettacommons.org/docs/latest/scripting_documentation/RosettaScripts/SimpleMetrics/SimpleMetrics

      More Documentation is available here:

      • https://www.rosettacommons.org/docs/latest/scripting_documentation/RosettaScripts/RosettaScripts

      • https://www.rosettacommons.org/docs/latest/scripting_documentation/RosettaScripts/TaskOperations/TaskOperations-RosettaScripts#antibody-and-cdr-specific-operations

      • https://www.rosettacommons.org/docs/latest/scripting_documentation/RosettaScripts/Movers/Movers-RosettaScripts#antibody-modeling-and-design-movers

   2. Run the protocol or copy the output (357 seconds).

      rosetta_scripts.linuxgccrelease -parser:protocol ab_design_components.xml \
          -input_ab_scheme AHO_Scheme -cdr_definition North \
          -s my_ab.pdb -out:prefix tutA4_ \
          -nstruct 5 -score:weights ref2015_cart -check_cdr_chainbreaks false

   3. Look at the score file. Are the sequences different between what we started with? How about the interaction energies?

Tutorial B: Optimizing Interface Energy (opt-dG)

1. Optimizing dG

   Here, we want to set the protocol to optimize the interface energy during Monte Carlo instead of total energy. The interface energy is calculated by the InterfaceAnalyzerMover through a specialized MonteCarlo called MonteCarloInterface. This is useful to improve binding energy and generally results in better interface energies . Resulting models should still be pruned for high total energy. This was benchmarked in the paper, and has been used for real-life designs to the HIV epitope (825 seconds).

       antibody_designer.linuxgccrelease -s my_ab.pdb -graft_design_cdrs L1 L3 \
           -seq_design_cdrs L1 L3 -light_chain kappa -mc_optimize_dG  -nstruct 5 \
           -out:prefix tutB1_
   
       <AntibodyDesignMover name="RAbD" seq_design_cdrs="L1,L3" graft_design_cdrs="L1,L3" 
                                                                       mc_optimize_dG="1" />

   Use the scorefile.py script to compare this to tutorial A2. Are the interface energies better? Has the Shape Complementarity improved (sc score) improved?

2. Optimizing Interface Energy and Total Score (opt-dG and opt-E)

   Here, we want to set the protocol to optimize the interface energy during the Monte Carlo cycles, but we want to add some total energy to the weight. Because the overall magnitude of the total energy will dominate the overall energy sum, we will only add a small weight for total energy. This has not been fully benchmarked, but if your models have very bad total energy when using opt-dG - consider using it. (892 seconds)

   antibody_designer.linuxgccrelease -s my_ab.pdb  -graft_design_cdrs L1 L3 \
       -seq_design_cdrs L1 L3 -light_chain kappa -mc_optimize_dG \
       -mc_total_weight .01 -mc_interface_weight .99 -nstruct 5 -out:prefix tutB2_

   Use the scorefile.py script to compare total energies (total_score) of this run vs the one right before it. Are the total scores better?

Tutorial C: Towards De Novo Design: Integrated Docking and Design

This tutorial takes a long time to run as docking is fairly slow - even with the optimizations that are part of RAbD. PLEASE USE THE PRE-GENERATED OUTPUT. The top 10 designs from each tutorial and associated scorefiles of a 1000 nstruct cluster run are in the output directory. Note that we are starting these tutorials with a pre-relaxed structure in order to get more reliable Rosetta energies. Since we are running a large nstruct, we will escape the local energy well that this leads us into.

1. RosettaDocking

   In this example, we use integrated RosettaDock (with sequence design during the high-res step) to sample the antibody-antigen orientation, however we don't care where the antibody binds to the antigen. Just that it binds, ie - No Constraints. The RAbD protocol always has at least Paratope SiteConstraints enabled to make sure any docking is contained to the paratope (like most good docking programs). This takes too long to run, so PLEASE USE THE OUTPUT GENERATED FOR YOU. We will use opt-dG here and for these tutorials, we will be sequence-designing all cdrs to begin to create a better interface. Note that sequence design happens wherever packing occurs - Including during high-resolution docking.

       antibody_designer.linuxgccrelease -s my_ab_relaxed.pdb -graft_design_cdrs L1 L2 L3 H1 H2 \
           -seq_design_cdrs L1 L2 L3 H1 H2 H3 -light_chain kappa \
           -mc_optimize_dG -do_dock -nstruct 1000 -random_start -out:prefix tutC1_
   
       <AntibodyDesignMover name="RAbD" mc_optimize_dG="1" do_dock="1" 
                      seq_design_cdrs="L1,L2,L3,H1,H2,H3" graft_design_cdrs="L1,L2,L3,H1,H2"/>

   Use pymol to load the files

       cp -r ../output_files/top10_C1/ .
       cp ../output_files/tutC1_score.sc .
       pymol my_ab.pdb top10_C1/* 

   In pymol

       @color_cdrs.pml
       center full_epitope

   Where is the antibody in the resulting designs? Are the interfaces restricted to the Paratope? Has the epitope moved relative to the starting interface?

2. Auto Epitope Constraints

   Here we will again perform docking and design, but we will incorporating auto-generated SiteConstraints to keep the antibody around the starting interface residues. These residues are determined by being within 6A to the CDR residues (This interface distance can be customized). Again, these results are provided for you.

       antibody_designer.linuxgccrelease -s my_ab_relaxed.pdb -graft_design_cdrs L1 L3 \
           -seq_design_cdrs L1 L2 L3 H1 H2 H3 -light_chain kappa \
           -mc_optimize_dG -do_dock -use_epitope_constraints -nstruct 1000 -out:prefix tutC2_
   
       <AntibodyDesignMover name="RAbD" mc_optimize_dG="1" do_dock="1" use_epitope_csts="1" 
                      seq_design_cdrs="L1,L2,L3,H1,H2,H3" graft_design_cdrs="L1,L2,L3,H1,H2"/>

   Use pymol to load the files

       cp -r ../output_files/top10_C2/ .
       cp ../output_files/tutC2_score.sc .
       pymol my_ab.pdb top10_C2/* 

   In pymol

       @color_cdrs.pml
       center full_epitope

   How do these compare with with the previous tutorial? Are the antibodies closer to the starting interface? Are the scores better?

3. Specific Residue Epitope Constraints

   Once again we will perform docking and design, but we will specify the Epitope Residues and Paratope CDRs to guide the dock/design to have these interact. For now, we are more focused on the light chain. We could do this as a two-stage process, where we first optimize positioning and CDRS of the light chain and then the heavy chain or simply add heavy chain CDRs to the paratope CDRs option.

       antibody_designer.linuxgccrelease -s my_ab_relaxed.pdb -graft_design_cdrs L1 L3 \
           -seq_design_cdrs L1 L2 L3 H1 H2 H3 -light_chain kappa -do_dock -use_epitope_constraints \
           -paratope L1 L3 -epitope 38J 52J 34K 37K -nstruct 1000 -out:prefix tutC3_
   
       <AntibodyDesignMover name="RAbD" mc_optimize_dG="1" do_dock="1" use_epitope_csts="1" 
                      epitope_residues="38J,52J,34K,37K" paratope_cdrs="L1,L3" 
                      seq_design_cdrs="L1,L2,L3,H1,H2,H3" graft_design_cdrs="L1,L2,L3,H1,H2"/>

   Again, load these into Pymol.

       cp -r ../output_files/top10_C3 .
       cp ../output_files/tutC3_score.sc .
       pymol my_ab.pdb top10_C3/* 

   in pymol:

       @color_cdrs.pml
       center full_epitope

   Now that we have specified where we want the interface to be and are additionally designing more CDRS, how do the enegies compare? Are we starting to get a decent interface with the lowest energy structure?

   How do these compare with the previous runs?

Tutorial D: Advanced Settings and CDR Instruction File Customization

Once again, all output files are in ../output_files. Please use these if you want as many of these take around 10 minutes to run.

1. CDR Instruction File

   More complicated design runs can be created by using the Antibody Design Instruction file. This file allows complete customization of the design run. See below for a review of the syntax of the file and possible customization. An instruction file is provided where we use conservative design on L1 and graft in L1, H2, and H1 CDRs at a longer length to attempt to create a larger interface area. More info on instruction file syntax can be found at the end of this tutorial. (764 seconds)

       cp ../input_files/my_instruction_file.txt .
       cp ../input_files/default_cdr_instructions.txt .

   Take a look at the default CDR instructions. These are loaded by default into Rosetta. There is syntax examples at the end of the file.

       antibody_designer.linuxgccrelease -s my_ab.pdb \
           -graft_design_cdrs L1 H2 H1 -seq_design_cdrs L1 L3 H1 H2 H3 -light_chain kappa \
           -cdr_instructions my_instruction_file.txt -random_start -nstruct 5 -out:prefix tutD1_
   
       <AntibodyDesignMover name="RAbD" instruction_file="my_instruction_file.txt" 
                seq_design_cdrs="L1,L3,H1,H2,H3" graft_design_cdrs="L1,H2,H1" random_start="1"

2. Dissallow AAs and the Resfile

   Here, we will disallow ANY sequence design into Proline and/or Cysteine residues, while giving a resfile to further LIMIT design and packing at specific positions. These can be given as 3 or 1 letter codes and mixed codes such as PRO and C are accepted. Note that the resfile does NOT turn any residues ON, it is simply used to optionally LIMIT design residue types and design and packing positions. Resfile syntax can be found here: https://www.rosettacommons.org/docs/wiki/rosetta_basics/file_types/resfiles. Note that specifying a resfile and disallowing amino acids are only currently available as command line options that are read by RAbD.

   Runtime is approximately 200 seconds.

       cp ../input_files/my_resfile.resfile .

   Take a look at the resfile. Can you describe what it is we are doing with it?

       antibody_designer.linuxgccrelease -s my_ab.pdb -seq_design_cdrs L1 L3 H1 H2 H3 \
           -light_chain kappa -resfile my_resfile.resfile -disallow_aa PRO CYS \
           -nstruct 5 -out:prefix tutD2_
   
       <AntibodyDesignMover name="RAbD" seq_design_cdrs="L1,L3,H1,H2,H3" />

3. Mintype

   Here, we will change the minimization type to relax. This mintype enables Flexible-Backbone design. Our default is to use min/pack cycles, but relax typically works better. However, it also takes considerably more time! This tutorial takes about 339 seconds for one model!

       antibody_designer.linuxgccrelease -s my_ab.pdb -seq_design_cdrs L1 L3 H1 H3 \ 
           -light_chain kappa -resfile my_resfile.resfile -disallow_aa PRO CYS -mintype relax \
           -nstruct 1 -out:prefix tutD3_
   
       <AntibodyDesignMover name="RAbD" seq_design_cdrs="L1,L3,H1,H3" mintype="relax"/>

4. Framework Design

   Finally, we want to allow the framework residues AROUND the CDRs to be designed and any interacting antigen residues to design as well. In addition, we will disable conservative framework design as we want something funky (this is not typically recommended and is used here to indicate what you CAN do). Note that we will also design the interface of the antigen using the -design_antigen option. This can be useful for vaccine design. Note that these design options are cmd-line ony options currently. Approx 900 second runtime.

       antibody_designer.linuxgccrelease -s my_ab.pdb -seq_design_cdrs L1 L3 H1 H3 \
           -light_chain kappa -resfile my_resfile.resfile -disallow_aa PRO CYS \
           -mintype relax -design_antigen -design_framework \
           -conservative_framework_design false -nstruct 1 -out:prefix tutD4_
   
       <AntibodyDesignMover name="RAbD" seq_design_cdrs="L1,L3,H1,H3" mintype="relax"/>

5. H3 Stem, kT, and Sequence variablility.

   Finally, we want increased variability for our sequence designs. So, we will increase number of sampling rounds for our cluster profiles using the -seq_design_profile_samples option, increase kT, and allow H3 stem design.

   We will enable H3 Stem design here, which can cause a flipping of the H3 stem type from bulged to non-bulged and vice-versa. Typically, if you do this, you may want to run loop modeling on the top designs to confirm the H3 structure remains intact. Note that once again, these sequence-design specific options must be set on the cmd-line.

   Description of the seq_design_profile_samples option (default 1): "If designing using profiles, this is the number of times the profile is sampled each time packing done. Increase this number to increase variability of designs - especially if not using relax as the mintype."

   This takes approx 450 seconds.

       antibody_designer.linuxgccrelease -s my_ab.pdb -seq_design_cdrs L1 L2 H3 \
           -graft_design_cdrs L1 L2 -light_chain kappa -design_H3_stem -inner_kt 2.0 \
           -outer_kt 2.0 -seq_design_profile_samples 5 -nstruct 5 -out:prefix tutD5_
   
       <AntibodyDesignMover name="RAbD" seq_design_cdrs="L1,L3,H1,H3" mintype="relax" 
                                                               inner_kt="2.0" outer_kt="2.0"/>

   How different is the sequence of L1,L2, and H3 from our starting antibody?

You should now be ready to explore and use RosettaAntibodyDesign on your own. Congrats! Thanks for going through this tutorial!

Reference Manual

Antibody Design CDR Instruction File

The Antibody Design Instruction File handles CDR-level control of the algorithm and design. It is used to create the CDRSet for sampling whole CDRs from the PDB, as well as fine-tuning the minimization steps and sequence design strategies.

For example, in a redesign project, we may only want to design a particular CDR and explore the local conformations within its starting CDR cluster, or we may simply want to optimize the sequence of a CDR or set of CDRs using our cluster profiles. These examples can be accomplished using the CDR Instruction File. This file uses a simple syntax where each CDR is controlled individually in the first column, and then a rudimentary language controls each part of the antibody design machinery. The file controls which CDRs are sampled, what the final CDRSet will be, whether sequence design is performed and how, and which minimization type will be used to optimize the structure and sequence for each CDR. Some of these commands can also be controlled via command-line options for simple-to-setup runs. Any option set via command-line (such as -graft_design_cdrs and -seq_design_cdrs will override anything set in the instruction file)

Syntax

The CDR Instruction file is composed of tab or white-space delimited columns. The first column on each line specifies which CDR the option is for. For each option, 'ALL' can be given to control all of the CDRs at once. ALL can also be used in succession to first set all CDRs to something and then one or more CDRs can be set to something else in succeeding lines. Commands are not lower- or upper-case-sensitive. A '#' character at the beginning of a line is a file comment and is skipped.

First column - CDR

Second Column - TYPE

Other columns can be used to specify lists, etc.

Instruction Types

Example

#H3 no design; just flexible motion of the loop

#SET All to design first
ALL GraftDesign ALLOW
ALL SeqDesign ALLOW

#Fix H3 and disallow GraftDesign for H1 and L2
L2 GraftDesign FIX
H1 GraftDesign FIX

#Disallow GraftDesign and SeqDesign for H3
H3 FIX

ALL MinProtocol MINTYPE relax

ALL CDRSet EXCLUDE PDBIDs 1N8Z 3BEI

#ALL CDRSet EXCLUDE Clusters L1-11-1 L3-9-cis7-1 H2-10-1

General Design Syntax

CDRSet Syntax (General)

CDRSet Syntax (Include and Excludes)

This set of options either includes only the items specified or it excludes specific items. The syntax is thus:

L1 CDRSet INCLUDE_ONLY option list of items

OR

L1 CDRSet EXCLUDE option list of items

The options for this type of CDRSet syntax are listed below

Sequence Design Instructions

The Sequence Design Instructions, used with the keyword SeqDesign after the CDR specifier, is used to control the sequence design aspect of the algorithm. In addition to controlling which CDRs undergo sequence design, the Sequence Design options control which strategy to use when doing sequence design (primary strategy), and which strategy to use if the primary strategy cannot be used for that CDR (fallback strategy).

Currently, the fallback strategy is used if the primary strategy does not meet statistical requirements. For example, using cluster-based profiles for sequence design (which is the default), it is imperative that the particular cluster has at least some number of sequences in the database for the strategy to be successful. By default, this cutoff is set at 10 and uses the command-line option, -seq_design_stats_cutoff Z. This means that if a cluster has less than 10 members and the primary strategy is to use cluster-based profiles, then the fallback strategy will be used. The default fallback strategy for all of the CDRs is the use of a set of conservative mutations with data coming from the BLOSUM62 matrix by default, with the set of mutations allowed consisting of those substitutions with positive or zero scores in the matrix. For example, if we have a D at some position for which we are using this fallback strategy, the set of allowed mutants would be N, Q, E, and S. Further, the set of conservative mutations can be controlled using the command-line option, -cons_design_data_source source, where other BLOSUM matrices can be specified. All BLOSUM matrices can be used for conservative design, where the numbers (40 vs. 62 vs. 80 etc.) indicate the sequence similarity cutoffs used to derive the BLOSUM matrices - with higher numbers being a more conservative set of mutations.

General Syntax

Strategy Types

Etc

Minimization

Many minimization types are implemented; however, they each require a different amount of time to run. See the MinType descriptions below for a list of acceptable options and their use.

Default Settings

These settings are overridden by your set instruction file/command-line options

#General
ALL FIX
DE FIX

ALL WEIGHTS 1.0

#Minimization - Options: min, relax, ds_relax cartesian, backrub, repack, none
ALL MinProtocol MINTYPE min

#Neighbors.  These are conservative values used in benchmarking.  Limit these to speed up runs.
L1 MinProtocol Min_Neighbors L2 L3
L2 MinProtocol Min_Neighbors L1
L3 MinProtocol Min_Neighbors L1 H3
H1 MinProtocol Min_Neighbors H2 H3
H2 MinProtocol Min_Neighbors H1
H3 MinProtocol Min_Neighbors L1 L3

#Length
ALL CDRSet LENGTH MAX 25
ALL CDRSet LENGTH MIN 1


#Profile Design
ALL SeqDesign STRATEGY PROFILES
ALL SeqDesign FALLBACK_STRATEGY CONSERVATIVE

##DE Loops can be designed.  They use conservative design by default since we have no profile data!
DE SeqDesign STRATEGY CONSERVATIVE

GraftDesign Sampling Algorithms

These change the way CDRs are sampled from the antibody design database. They can be specified using the -design_protocol flag.

Structure Optimization Types

These 'Mintypes' can be independently set for each CDR through the instruction file or generally set using the command line option -mintype. The default is min, as this has some optimization and does not take a very long time (and has been shown to be comparable to relax). Although we refer to 'design' we mean side-chain packing, with any residues/CDRs set to design as designing. For further information on the algorithm and strategies used for sequence design, please see the instruction file overview and the methods section of the paper.

Circular Harmonic Dihedral Constraints are added to each CDR according the cluster of the CDR or the starting dihedrals if this is a rare cluster that has no data. These ensure that minimization and design does not destroy the loop.

RosettaScripts and PyRosetta

The Full protocol that is the application is available to RosettaScripts as the AntibodyDesignProtocol. This just has a few extra options before and after design such as running fast relax and or snug dock.

The Configurable main Mover is available as the AntibodyDesignMover.

Individual components of RAbD can be used to create your own custom antibody modeling and design protocols in RosettaScripts (or PyRosetta).

Command-line Options

General Options

Basic settings for an easy-to-setup run

Energy Optimization settings (opt-dG)

Protocol Rounds

Distance Detection

Paratope + Epitope

Regional Sequence Design

Seq Design Control

Profile Stats

Constraint Control

Fine Control

Outlier Control

Protocol Steps

Memory management / CDRSet caching

Benchmarking