Molecular replacement and autobuilding using Phaser, Rosetta, and autobuild with mr_rosetta

Author(s)

Purpose

Tools from Rosetta that are used in mr_rosetta

Steps where mr_rosetta uses structure-modeling algorithms

Summary of the procedure used in mr_rosetta

Details of the procedure used in mr_rosetta

Notes on the procedure used in mr_rosetta

Viewing solutions and restarting with saved solutions

Running mr_rosetta on a cluster

Single file system required for mr_rosetta

Read/write delay allows for slow NFS disks

Tracking your log files

Re-running parts of your mr_rosetta jobs

Failures in sub-processes

Stopping mr_rosetta

Installing Rosetta for use with mr_rosetta

Setting up for a run of mr_rosetta A. Fragment files from the Robetta server

Setting up for a run of mr_rosetta B. Alignment files fromthe hhpred server

Search models and alignment files

Output files from mr_rosetta

Graphical interface

Parameters files in mr_rosetta

Examples

Standard run of mr_rosetta:

Running mr_rosetta with a model that is already place in the unit cell

Rebuilding your model with Rosetta before MR

Running mr_rosetta from a homology search (with an hhr file)

Getting a default parameters file for mr_rosetta:

Testing mr_rosetta:

Possible Problems

Debugging problems with running mr_rosetta:

Specific limitations and problems:

Literature

Additional information

Author(s)

• mr_rosetta: Tom Terwilliger, Frank DiMaio, Randy Read, David Baker

Purpose

mr_rosetta is a procedure for extending the range of molecular replacement by combining tools from the structure-modeling field (Rosetta) with crystallographic molecular replacement, model-building, density modification and refinement. The approach is described in Dimaio et al. (2011). It can also be used to rebuild a model with a combination of Rosetta and Phenix tools.

A key requirement for using mr_rosetta is that you have to have a sequence alignment of the protein used as a template to model your target protein. You can try several different alignments, but a good alignment has to be in your set of alignments or the procedure will be unlikely to be successful. The reason is that Rosetta homology modeling makes strong use of the sequence, so if your alignment is incorrect you are essentially trying to build the wrong molecule.

The basic process is to find MR solutions with automr, rebuild them with Rosetta, then rebuild those models with phenix.autobuild. The combination of Rosetta rebuilding and phenix rebuilding is the key part of this method. In slightly more detail, this process is to select possible MR solutions (one of which must later be shown to be correct for the procedure to succeed)with automr (Phaser), score with LLG following Rosetta relaxation, pick the best solutions, rebuild each of these with Rosetta including map information (density term), score the resulting models with Rosetta, select the highest and score with LLG, verify that the top solutions are all about the same (electron density maps are correlated), and rebuild the top models with autobuild. mr_rosetta can handle a single copy of a single chain, or multiple copies of a single chain (NCS), or multiple copies of multiple chains (groups of NCS). If you supply one or more input search models, then the entire crystallographic asymmetric unit must contain some multiple of the search models you supply (phaser will be used to find copies of the search model). NCS will be found automatically in your search model and in any models assembled by mr_rosetta. NOTE: if your molecule has multiple chain types, then you cannot use the simple hhr file input (see below) and you cannot automatically run pre-refinement with rosetta on your molecule. Instead you need to use mr_model_preparation and phenix.automr to place your model. Then you can supply the aligned, placed structure to mr_rosetta for rebuilding. Additionally in this case you will need to supply a different set of fragments files for each chain type.

Tools from Rosetta that are used in mr_rosetta

• Calculation of Rosetta energies for a model.
• Model relaxation (rebuilding) including just the Rosetta standard energy term. This optional rebuilding can be carried out before molecular replacement, improving the starting model.
• Model completion and relaxation (filling in missing sections and rebuilding) with Rosetta energies and fit to a map (Dimaio et al., 2009). This step is carried out after an MR solution has been found. The placed model is used to calculate a 2Fo-Fc map and fit to this map is used as a target in addition to the standard Rosetta energies. Note: Sequence-specific fragment libraries are used in this process (obtained from the Robetta webserver).

Steps where mr_rosetta uses structure-modeling algorithms

• Prior to MR. Edited templates are optionally rebuilt before carrying out molecular replacement.
• In scoring MR solutions. MR solutions are scored by Phaser LLG scores calculated after model relaxation with Rosetta including the term for fit to the current density map.
• In rebuilding MR solutions. Initial molecular replacement solutions are rebuilt using Rosetta model completion and relaxation including the term for fit to the current density map

Summary of the procedure used in mr_rosetta

The overall process in one cycle of mr_rosetta is: (a) edit the model and place it in the unit cell (e.g., MR, molecular replacement), (b) score all MR solutions and take the best ones by LLG for further steps, (c) rebuild each model 20-2000 times using Rosetta and density-modified 2Fo-Fc map to yield Rosetta models, (d) refine Rosetta models, average density from top 20%, continue rebuilding each Rosetta model using averaged density, and (e) take top models based on LLG score and rebuild with autobuild. An optional prerefinement step is to carry out Rosetta modeling in step (a) above, before carrying out molecular replacement.

Details of the procedure used in mr_rosetta

1. Check installation and verify that Rosetta binary and libraries are available (can specify with keywords rosetta_path (overall path to rosetta directories), and the keywords (paths relative to overall rosetta_path) rosetta_binary_dir, rosetta_binary_name, rosetta_script_dir, rosetta_database_dir)
2. Read reflections file (must be CCP4 mtz and have a freeR set; use phenix GUI or import_and_add_free to set up)
3. An optional model editing step. If an hhpred .hhr file is supplied, read through this file, download the PDB files specified, apply alignments specified to generate pairs of alignment files and edited models (e.g., 2cng.ali, 2cng_mr.pdb based on 2cng.pdb). This step is carried out by sculptor using a default protocol. NOTE 1: For tailoring of this step, use mr_model_preparation and then supply the aligned model to mr_rosetta. NOTE 2: If your structure contains more than one chain or requires more than one homology model to represent the structure, then you need to use mr_model_preparation and phenix.automr to place your model. Then you can supply the aligned, placed structure to mr_rosetta for rebuilding.
4. NOTE: The steps below are carried out for each model/alignment file pair supplied, (or for each pair generated from by mr_rosetta if an hhpred .hhr file is supplied with alignment information).
5. Check model, alignment file and sequence file to verify that they match (i.e., that the alignment file can be applied to the model to yield a model with the sequence in the sequence file). Copy overall B-factor and list of B-factors for atoms from the model to be substituted into subsequent models before scoring. Rewrite the sequence file into standard (fasta) format.
6. Optional Rosetta modelling prior to molecular replacement (prerefinement). The edited starting model (template) is rebuilt with Rosetta using the standard Rosetta energy functions and a fragments library specific to the target sequence to fill in gaps. (If no gaps are present, no fragments files are necessary).
7. Run automr to find molecular replacement solutions (default number_of_output_models=5).
8. Refine (if refine_after_mr=True) each MR solution with refine. Use resulting 2mFo-DFc map as starting point for density modification, yielding density-modified current density map for this refined solution, to be used in Rosetta rebuilding below. Ignore refined model. Note (but ignore) LLG of refined model.
9. Determine the baseline LLG for model improvement. This LLG can either be the LLG obtained in the previous step, or an LLG obtained after rebuilding the MR model with Rosetta. Optionally perform rosetta relaxation (rebuilding rescore_mr.nstruct models, typically 5) models without filling in missing sections, including a density term from the map in the prevous step. The sequence of all parts of the model at this point will match the target sequence. Score each solution by LLG. These models are not carried forward, but taking the best LLG for any rebuilt model as the score for the original model from MR. This score will be used later to prioritize MR solutions for further analysis.
10. Sample relaxation script used to run relaxation in Rosetta:

    #!/bin/sh 
    cd MR_ROSETTA_1/RESCORE_MR_1/RELAX_AND_SCORE_IN_SETS_1/RUN_1/WORK_1
     /net/terwill/rosetta/rosetta_source/bin/mr_protocols.default.linuxgccrelease \
    -database /net/terwill/rosetta/rosetta_database \
    -MR:mode cm \
    -in:file:extended_pose 1 \
    -in:file:fasta MR_ROSETTA_1/WORK_1/EDITED_1crb_fasta.txt \
    -in:file:alignment MR_ROSETTA_1/WORK_1/EDITED_1crb_2qo4.ali \
    -in:file:template_pdb MR_ROSETTA_1/AutoMR_run_1_/2QO4.1.pdb \
    -relax:default_repeats 4 \
    -relax:jump_move true \
    -edensity:mapreso   3.00 \
    -edensity:grid_spacing 1.5 \
    -edensity:mapfile \
         MR_ROSETTA_1/AutoMR_run_1_/2QO4.1_refine_001_map_coeffs.map \
    -edensity:sliding_window_wt 1.0 \
    -edensity:sliding_window 5 \
    -cm:aln_format grishin \
    -MR:max_gaplength_to_model 0 \
    -nstruct 1 \
    -ignore_unrecognized_res  \
    -overwrite 
    

11. Take the top (max_solutions_to_rebuild=5) models from step 5 and rebuild them with Rosetta, this time filling in missing sections and including the density term with the current map (the same map as used above in relaxation) as part of the target function, generating total of (rosetta_rebuild.nstruct=20) rebuilt models. These are Rosetta models. The sequence of these models will be the same as that of the target (unless there are long gaps in the template that cannot be filled by Rosetta). Note: in many cases 20 models is sufficient...in others far more models will make the method work better (i.e., 1000 or 2000 models). This can take a lot of time unless you have a cluster to run on. This Rosetta rebuilding step uses a library of fragments specific to the target sequence to fill in any gaps. (If no gaps are present, no fragments files are necessary). Sample rebuild script used:

    #!/bin/sh 
    cd MR_ROSETTA_1/WORK_1/REBUILD_IN_SETS_1/RUN_1/WORK_1
     /net/terwill/rosetta/rosetta_source/bin/mr_protocols.default.linuxgccrelease \
    -database /net/terwill/rosetta/rosetta_database \
    -MR:mode cm \
    -in:file:extended_pose 1 \
    -in:file:fasta MR_ROSETTA_1/WORK_1/EDITED_1crb_fasta.txt \
    -in:file:alignment MR_ROSETTA_1/WORK_1/EDITED_1crb_2qo4.ali \
    -in:file:template_pdb MR_ROSETTA_1/AutoMR_run_1_/2QO4.1.pdb \
    -loops:frag_sizes 9 3.2 \
    -loops:frag_files inputs/aa1crb_09_05.200_v1_3.gz \
       inputs/aa1crb_03_05.200_v1_3.gz none \
    -loops:random_order \
    -loops:random_grow_loops_by 5 \
    -loops:extended \
    -loops:remodel quick_ccd \
    -loops:relax relax \
    -relax:default_repeats 4 \
    -relax:jump_move true \
    -edensity:mapreso     3.00 \
    -edensity:grid_spacing 1.5 \
    -edensity:mapfile  MR_ROSETTA_1/AutoMR_run_1_/2QO4.1_refine_001_map_coeffs.map \
    -edensity:sliding_window_wt 1.0 \
    -edensity:sliding_window 5 \
    -cm:aln_format grishin \
    -MR:max_gaplength_to_model 8 \
    -nstruct 1  \
    -ignore_unrecognized_res \
    -overwrite
    

12. Choose top (percentage_to_rescore=10) rebuilt models based on Rosetta score (including density term) and rescore them based on LLG
13. Determine whether the top (number_of_required_cc=5) best LLG score Rosetta models are all similar (map correlation between map for top model with each )
14. Refine with phenix.refine the top Rosetta models based on LLG (if refine_top_models.run_refine_top_models=True, percent_to_refine=20). Save new 2mFo-DFc map, density modify the map, and then average the top density-modified maps (top based on Rosetta score) to yield an averaged density map used in the next relaxation step. Ignore the refined model.
15. Relax (rebuild) the Rosetta models from into their corresponding density maps from with Rosetta, generating (relax_top_models.nstruct=5) models for each. Score each relaxed model with LLG, take best LLG as score. Save best relaxed model as new solution. Sample relax script used:

    #!/bin/sh 
    cd MR_ROSETTA_1/GROUP_OF_RESCORE_MR_ROSETTA_2/RUN_1/RESCORE_MR_1/RELAX_AND_SCORE_IN_SETS_1/RUN_1/WORK_1
     /net/terwill/rosetta/rosetta_source/bin/mr_protocols.default.linuxgccrelease \
    -database /net/terwill/rosetta/rosetta_database \
    -MR:mode relax \
    -in::file::s \
     MR_ROSETTA_1/WORK_1/REBUILD_IN_SETS_1/RUN_8/WORK_1/S_2QO4B_0001_edited.pdb \
    -relax:default_repeats 4 \
    -relax:jump_move true \
    -edensity:mapreso   3.00 \
    -edensity:grid_spacing 1.5 \
    -edensity:mapfile \
     MR_ROSETTA_1/WORK_1/REBUILD_IN_SETS_1/RUN_8/WORK_1/S_2QO4B_0001_edited_refine_001_map_coeffs.map \
    -edensity:sliding_window_wt 1.0 \
    -edensity:sliding_window 5 \
    -nstruct 1 \
    -overwrite 
    

16. Take the top (number_to_autobuild=5) relaxed refined rebuilt Rosetta models from the previous step (scored by LLG) and rebuild them with phenix.autobuild. Report the R/freeR of each model.

Notes on the procedure used in mr_rosetta

1. Viewing solutions and restarting with saved solutions

   At each stage, existing solutions are saved as a python "pkl" file and can be read back in to mr_rosetta with "mr_rosetta_solutions=xxx.pkl". These solutions can be displayed with "display_solutions=True". Existing solutions are stored as "mr_rosetta_solution" objects which keep track of the model and its history, the map_coefficients and labels, etc. These can be read in to mr_rosetta with the keyword "rosetta_solutions=results.pkl" and used as inputs for subsequent runs, starting at any step that can use those solutions. NOTE: You can re-start mr_rosetta only at the beginning of major stages (like "place_model", "rosetta_rebuild" etc)...but not in between. Normally at the end of a major stage a .pkl file is written out with text like "type this to see all the results". You can almost always give your original command, the command "start_point=xxx" and "mr_rosetta_solutions=my_pickle_file.pkl" and it should then continue on from there.

2. Running mr_rosetta on a cluster

   Jobs can be run on a single machine or on a cluster. A run command for single jobs (single_run_command="sh") and a run command for batch jobs (group_run_command=qsub) can be specified as well as the number of processors to use (nproc=200).

   The qsub command is used in Sun Grid Engine clusters. You can also use mr_rosetta on a Condor cluster, using group_run_command="condor_submit ".

3. Single file system required for mr_rosetta

   All files are stored on a single file system that must be accessible to all jobs.

4. Read/write delay allows for slow NFS disks

   Read/write to files are (generally) accompanied by a wait for appearance of the new file of up to max_wait_time=100 sec.

5. Tracking your log files

   mr_rosetta runs all cpu-intensive jobs as sub-processes. When it submits a sub process to do the work it lists the name of the corresponding log file. You can work your way down to the bottom level at any time by reading through these log files, copying the name of the next log file, and opening it until you get to the place where the actual work is done.

6. Re-running parts of your mr_rosetta jobs

   Sub-processes are always run in sub-directories. Each sub-process has a file "RUN_FILE_1" that contains the information to run the sub-process, a parameter file PARAMS_1.eff and a log file "RUN_FILE_1.log" with the log file of running that sub-process. Note that you can use the parameters files to re-run any jobs that you want. You can say something like:

   phenix.mr_rosetta PARAMS_1.eff

   and that will rerun the job specified in that directory.

7. Failures in sub-processes

   If some sub-processes fail, normally the failures will be ignored. This is useful as your overall job can often continue even if a few refinement or rosetta jobs fail. However if the failure is from the queueing system (rather than in the actual running of the jobs) then the overall job may still fail.

8. Stopping mr_rosetta

   If you create a file "STOPWIZARD" in the top level directory (i.e., MR_ROSETTA_1/), then each job in the entire process will stop as soon as any Phenix part of the process takes over (i.e., as soon as Rosetta jobs finish).

Installing Rosetta for use with mr_rosetta

To run mr_rosetta, you need to install Rosetta from the Baker laboratory at the University of Washington. This is pretty easy, and a summary of steps is given below. Once you have installed Rosetta you need to set the environmental variable $PHENIX_ROSETTA_PATH. Then you have all the software you will need for running mr_rosetta.

Note: this set of instructions is for Rosetta version 3.2...presumably future versions will look very similar except for the numbering.

Downloading and installing Rosetta is pretty easy if your computer is compatible and it takes about an hour if you have a 2-processor machine...or just a few minutes if you have a multiprocessor machine to compile with.

NOTE: If trouble...see the FULL INSTRUCTIONS at http://www.rosettacommons.org/manuals/archive/rosetta3.2_user_guide/ or http://www.rosettacommons.org/manuals/archive/rosetta3.2_ or http://www.rosettacommons.org/manuals/archive/rosetta3.2.1_user_guide/

1. go to http://depts.washington.edu/uwc4c/express-licenses/assets/rosetta/ , find "Academic License" and click on "LICENSE". Fill out the form, and receive by email a link to the download site and a login/password.
2. Go to Rosetta 3.2 on the download site, select Download, and Download Rosetta "as one bundle". Note if you have a mac you may need to install some additional patches (please see the instructions on the download page).
3. Unpack and install Rosetta: Go to the directory where you want to install it and move the downloaded file "rosetta3.2_Bundles.tgz" there. Then...

   tar xzf rosetta3.2_Bundles.tgz
   

   This should give you a directory rosetta-3.2 that contains:

   BioTools		new_apps.note		rosetta_demos
   foldit			release.note		rosetta_fragments
   manual			rosetta_database	rosetta_source
   

   NOTE: if your directory contains .tgz files instead of the listing above you may need to also run the same tar command on the individual .tgz files.
4. Now you want to compile. You must have python on your machine...if not you will need to install it from http://www.python.org/. You will also need scons. If you don't have scons you can get it from www.scons.org/. NOTE: you will need version 2.2 or later of python and 0.96.1 of scons. You can check your versions with:

     python --version
     scons --version
   

5. NOTE 2: on Ubuntu you may also need zlib1g-dev. You can get this library and scons with:

       sudo su   # UBUNTU ONLY FOR INSTALLING zlib1g and scons
       apt-get install zlib1g-dev
       apt-get install scons
   

6. In the scons command below the "-j2" means use 2 processors....adjust for your system. Takes about 1 hour with 2 processors.

   cd rosetta_source
   python external/scons-local/scons.py -j2 bin mode=release
   cd ..
   

   If you get to "scons: done building targets." you are all set!
7. Notice where you have installed rosetta. The directory you just set up, now containing "rosetta_source" and "rosetta_database" is to be called "PHENIX_ROSETTA_PATH". If this directory is... /net/sigma/raid1/rosetta-3.2 then you can now set a local environmental variable in your ".profile" (sh or bash shell) or ".cshrc" (c-shell) to mark where rosetta is located: if you are using the bash or sh shells:

   export PHENIX_ROSETTA_PATH=/your-path-to-rosetta-here/rosetta-3.2
   

   or sh (C-shell):

   setenv PHENIX_ROSETTA_PATH /your-path-to-rosetta-here/rosetta-3.2
   

8. If your machine is behind a firewall and there is a proxy server you need to go through, then if you use a .hhr file to download files from the PDB then you will need to specify your proxy server. You can use the following command to specify the proxy server (replacing it with YOUR proxy server). If you are using the bash or sh shells:

   export HTTP_PROXY=proxyout.mydomain.edu:8080

   or sh (C-shell):

   setenv HTTP_PROXY proxyout.mydomain.edu:8080
   

9. Now you are completely ready to go with Rosetta and with mr_rosetta.

Setting up for a run of mr_rosetta A. Fragment files from the Robetta server

To run mr_rosetta on your structure, you will need to use the Robetta fragment server at the Univ. of Washington to generate 9-mer and 3-mer fragments from the PDB that are compatible with your sequence file. This takes a few hours but is very easy to do.

To obtain the two required files:

1. go to: http://robetta.bakerlab.org/fragmentsubmit.jsp
2. register
3. paste your sequence file into the form
4. Receive an email from the server after a few hours that our files are ready
5. Download the files (two files, with similar filenames, one containing a 9 and and one a 3 like: aat000_09_05.200_v1_3.gz and aat000_03_05.200_v1_3.gz)
6. These are your fragment files. You will need to list them in your mr_rosetta parameters file
7. NOTE1: if your chain has more than 650 residues, then you will need to split it up into pieces of 650 residues or fewer before submitting the sequence to the Robetta server. Then you will get several 3-mer and 9-mer fragments files, one for each piece that you submit. You can then simply paste these together after editing all but the first to fix the residue numbers. To edit the files just use

   phenix.phenix.adjust_robetta_resid <fragment_file_name> <new_fragment_file_name> <offset-for-residue numbers>
   

8. NOTE2: if you have multiple chain types in your structure then you will want to have a separate set of fragments files for each chain type. You can specify these with: fragment_files_chain_list, fragment_files_3_mer_by_chain, and fragment_files_9_mer_by_chain instead of fragment_files. Use fragment_files_chain_list to define which chain ID each of your fragment_files_3_mer_by_chain and fragment_files_9_mer_by_chain go with.
9. NOTE3: You only need one set of fragments files for each UNIQUE chain. So if chains A and C are the same, you just need to specify fragments for chain A. If you have two different chains A and B and fragment files frag_A_3 frag_A_9 frag_B_3 frag_B_9 then you should use: fragment_files_chain_list=A fragment_files_chain_list=B fragment_files_3_mer_by_chain=frag_A_3 fragment_files_9_mer_by_chain=frag_A_9 fragment_files_3_mer_by_chain=frag_B_3 fragment_files_9_mer_by_chain=frag_B_9

Setting up for a run of mr_rosetta B. Alignment files from the hhpred server

You will need to tell mr_rosetta what to use as search models and the alignment between the search models and your target structure. The easiest way is to use the hhpred server (Söding J. (2005) Protein homology detection by HMM-HMM comparison. Bioinformatics 21, 951-960.) Here is what to do:

1. go to: http://toolkit.tuebingen.mpg.de/hhpred and paste in your sequence and hit submit job (using all defaults).
2. In a few minutes there will be a new page with alignments in color. You want to click on the little Save button on the line above all the alignments. Save that .hhr file; this contains a list of all the PDB entries with similar sequences and the alignments.
3. Repeat the run of hhpred (hit "Rerun job"), this time selecting Alignment mode as global in the middle of the page. Save the resulting .hhr file as well.

Search models and alignment files

If you supply an hhr analysis file from hhpred, you do not need to worry (usually) about the details of your search models and alignment files. However you can supply mr_rosetta with your own list of search models and a corresponding list of alignment files. This section describes what the alignment files need to look like (two ways you can format these files.) Here are your options for supplying alignment information:

• If you have a pre-edited PDB file (i.e., you ran something beforehand to make the sequence be just what you want), then you just supply the PDB file and the sequence file (which may be identical or the PDB file may have deletions relative to the sequence file) as in the sample scripts.
• Otherwise if you have a .ali alignment file (see below) , you can supply that along with the PDB file and the sequence file, and then phenix will use sculptor to apply the alignment .
• Otherwise, and commonly, you supply a .hhr file, and mr_rosetta downloads the pdb and applys the alignment in the hhr file (and you don't have to supply either sequence or hhr file).
• If you want to apply an alignment yourself with an hhr file, you can use mr_model_preparation
• If you want to apply an alignment yourself with an alignment file that just contains 4 lines (1) > (greater-than-symbol), then title for target sequence (2) target sequence with - for gaps (3) >the sequence of the target and (4) the sequence of the protein in the template PDB you are supplying, then you can use mr_model_preparation

You can generate an alignment file with phenix.muscle if you do not have one from another source. Use a command like this:

phenix.muscle -in my_two_sequences.dat -out my_alignment.ali

> title text for sequence of target (your structure) to follow
LVLKWVMSTKYVEAGELKEGSYVVIDGEPCRVVEIEKSKTGKHGSAKARIVAVGVFDGGKRTLSLPVDAQVEVPIIEKFT
AQILSVSGDVIQLMDMRDYKTIEVPMKYVEEEAKGRLAPGAEVEVWQILDRYKIIRVKG
> title text for sequence of template (supplied PDB) to follow
qlmdmrd AQILSVSGDVIQLMDMRDYKTIEVPMKYVEEEAKGRLAPGAEVEVWQILDRYKIIRVKG qlmdmrd

> title text for sequence of target (your structure) to follow
LVLKWVMSTKYVEAGELKEGSYVVIDGEPCRVVEIEKSKTGKHGSAKARIVAVGVFDGGK
RTLSLPVDAQVEVPIIEKFTAQILSVSGDVIQLMDMRDYKTIEVPMKYVEEEAKGRLAPG
AEVEVWQILDRYKIIRVKG-------
> title text for sequence of template (supplied PDB) to follow
------------------------------------------------------------
-------------QLMDMRDAQILSVSGDVIQLMDMRDYKTIEVPMKYVEEEAKGRLAPG
AEVEVWQILDRYKIIRVKGQLMDMRD

You have two options for alignment files if you are going to use one.

• You can use an alignment file that sculptor can recognize. This file looks like this (there must be exactly the same number of characters for the target and the template sequences (including dashes for gaps):

  > title text for sequence of target (your structure) to follow
  VDFNGYWKMLSNENFEEYLRALDVNVALRKIANLLKPDKEIVQDGDHMIIRTLSTFRNYIMDFQVGKEFEEDLTGIDD
  > title text for sequence of template (supplied PDB) to follow
  -AFSGTWQVYAQENYEEFLRAISLPEEVIKLAKDVKPVTEIQQNGSDFTITSKTPGKTVTNSFTIGKEAEIT--TMDG
  

• Alternatively, you can use a second format for the alignment file for mr_rosetta (This file is different than the alignment file for sculptor or mr_model_preparation; it is a MODELLER-style .ali file). Here is a sample:

  ## 1CRB_ 2qo4_A
  # hhsearch
  scores_from_program: 0 1.00
  1 VDFNGYWKMLSNENFEEYLRALDVNVALRKIANLLKPDKEIVQDGDHMIIRTLSTFRNYIMDFQVGKEFEEDLTGIDD
  0 -AFSGTWQVYAQENYEEFLRAISLPEEVIKLAKDVKPVTEIQQNGSDFTITSKTPGKTVTNSFTIGKEAEIT--TMDG
  --
  

  Here is what has to be on each line:

  1. Line 1: two ## signs, then target PDB ID then template PDB ID. NOTE: the template PDB ID must match the starting characters of your input search model file names (the file names themselves, not including the path to them)
  2. Line 2 just has a # sign and the word hhsearch
  3. Line 3 just has some text like scores_from_program: 0 1.00
  4. Line 4 has a number, then the entire sequence of the structure to be solved (the target), all on one line. The number is how many residues at the N-terminus of this sequence are to be ignored in generating a model. Usually this is 0, but if you supply a sequence that is not what is in your crystal, it could have some other number. If you are supplying a template PDB file that has residues to be removed, indicate these positions with a dash (-) in your sequence. Note: the sequence on this line cannot start with a dash.
  5. Line 5 has a number, then the matching sequence of the template PDB, using dashes (-) to indicate residues that are not present in the template PDB There must be exactly the same number of characters in the sequence of your target and the sequence of your template. The number is how many residues at the N-terminus of your template PDB are to be ignored. If you have fully edited your template PDB to match the target sequence, the number will be 0.
  6. line 6 has two dashes: --

Output files from mr_rosetta

The output files from mr_rosetta are the same as those from .autobuild: a model and map coefficients. These will be in a subdirectory listed at the end of your log file. The files will be something like: MR_ROSETTA_1/..../AutoBuild_run_1_/overall_best.pdb and MR_ROSETTA_1/..../AutoBuild_run_1_/overall_best_denmod_map_coeffs.mtz.

Graphical interface

A GUI for MR-Rosetta is now available in the "Molecular replacement" category. Its function is essentially identical to that of the command-line version, but many of the details are not shown by default. In addition to the methods described above for configuring your system to use Rosetta from PHENIX, the GUI also includes a preferences setting in the "Wizards" section for defining the path to the Rosetta installation. If the GUI does not detect that you have the environment set up correctly, it will issue a warning when started. The configuration tab in the GUI includes a list into which any combination of input files may be added; the file types should be recognized (and any relevant data they contain extracted, such as space group and MTZ label information) automatically. For more complex inputs involving fragment files, click the button labeled "Other inputs" below the list of files.
The number of processors to use will be set to one fewer than the total the number of CPU cores PHENIX thinks are available, but if you are using a queueing system this number can be increased. You can change how MR-Rosetta runs child processes by clicking the "Job control" button in the lower left-hand corner of the configuration tab. Because it usually takes hours to run, MR-Rosetta will always be launched by the GUI as a "detached" job, meaning that you can close the GUI without killing the process, and resume it later. While MR-Rosetta is running, the current set of solutions will be continuously updated in a tab labeled "Current results", with the relevant score (LLG from Phaser, Rosetta score, or R-factor). You may view any of these solutions by clicking the buttons next to them.
Once the job is complete, a simply summary tab will be displayed, listing the output files and basic statistics such as R-factors. If the program was successful, the R-free will usually be below 50%, although this may vary depending on resolution and data quality. Buttons are provided to start additional programs or view the model and maps.

Parameters files in mr_rosetta

When you run mr_rosetta it will write out a mr_rosetta_params.eff parameter file that can be used to re-run mr_rosetta (just as for essentially all PHENIX methods).

Examples

Standard run of mr_rosetta:

Before you run mr_rosetta, you need to get fragment files from the Robetta server (see Setting up for a run of mr_rosetta, part A, above). Then you need an hhr alignment information file from the hhpred server (see Setting up for a run of mr_rosetta, part B, above), or else a search model and an alignment file to go with it. Once you have these files, running mr_rosetta is easy. If you have a search model (coords1.pdb) and an alignment file for it (coords1.ali), and fragment files test3.gz and test9.gz, and a data file fobs.mtz with FP SIGFP and FreeR_flag, you can type:

phenix.mr_rosetta \
  seq_file=seq.dat \
  data=coords1.mtz \
  alignment_files=coords1.ali \
  search_models=coords1.pdb \
  already_placed=False\
  fragment_files = test3.gz \
  fragment_files = test9.gz \
  rescore_mr.relax=False \
  rosetta_models=20 \
  ncs_copies=2 \
  space_group=p212121  \
  use_all_plausible_sg=False \
  nproc=200 \
  group_run_command=qsub

Running mr_rosetta with a model that is already place in the unit cell

You can run mr_rosetta as a purely model-building tool as well. This is convenient if you have found a MR solution but cannot rebuild it successfully. Here is an example. The keyword to use is already_placed=True:

phenix.mr_rosetta \
  seq_file=seq.dat \
  data=coords1.mtz \
  search_models=coords1.pdb \
  already_placed=True \
  fragment_files = test3.gz \
  fragment_files = test9.gz \
  rescore_mr.relax=False \
  rosetta_models=20 \
  ncs_copies=2 \
  space_group=p212121  \
  use_all_plausible_sg=False \
  nproc=200 \
  group_run_command=qsub

Rebuilding your model with Rosetta before MR

If your search model is too distant to find a molecular replacement solution, you can prerefine your model with Rosetta before carrying out molecular replacement. Here is an example. The keyword to use is: run_prerefine=True. NOTE 1: It is best to specify the number of ncs_copies if you use run_prerefine. If you do not, then you may end up running several parallel jobs, each of which is independently carrying out prerefinement on the same input model (to be used later with different numbers of ncs copies). Once you have run your job with one value of ncs_copies, you can just use the best prerefined model from that job as a search model in your other runs.

phenix.mr_rosetta \
  seq_file=seq.dat \
  data=coords1.mtz \
  search_models=coords1.pdb \
  run_prerefine=True \
  number_of_prerefine_models=1000 \
  fragment_files = test3.gz \
  fragment_files = test9.gz \
  rescore_mr.relax=False \
  rosetta_models=20 \
  ncs_copies=2 \
  space_group=p212121  \
  use_all_plausible_sg=False \
  nproc=200 \
  group_run_command=qsub

phenix.mr_rosetta \
  seq_file=seq.dat \
  search_models=coords1.pdb \
  run_prerefine=True \
  number_of_prerefine_models=1000

MR_ROSETTA_1/GROUP_OF_PLACE_MODEL_1/RUN_FILE_1.log

Running mr_rosetta from a homology search (with an hhr file)

If you have run hhpred and obtained a .hhr file with a list of alignments of proteins in the PDB with your sequence, you can run starting from your sequence file and this .hhr file. Here is an example. The keyword to use is: hhr_files=my_hhr_file.hhr.

 phenix.mr_rosetta \
  seq_file=bfr258e.fasta \
  data=bfr258e_data.mtz \
  hhr_files=bfr258e.hhr \
  read_hhpred.number_of_models=1 \
  read_hhpred.number_of_models_to_skip=0 \
  fragment_files=aabfr__03_05.200_v1_3.gz \
  fragment_files=aabfr__09_05.200_v1_3.gz \
  rescore_mr.relax=False \
  rosetta_models=20 \
  ncs_copies=1 \
  nproc=200 \
  group_run_command=qsub 

Getting a default parameters file for mr_rosetta:

Usually you will want to edit a parameters file so that you can specify more details of the run. You can get a default parameters file with:

phenix.mr_rosetta 

Testing mr_rosetta:

You can do a test of mr_rosetta to make sure everything is ok with:

phenix_regression.wizards.test_command_line_rosetta_quick_tests

Possible Problems

Debugging problems with running mr_rosetta:

If mr_rosetta fails, the first thing (after just checking the commands you used) is to run the mr_rosetta regression tests to make sure that the installations of phenix and rosetta are both ok:

phenix_regression.wizards.test_command_line_rosetta_quick_tests

If the tests all are OK, then there is something specific to your data or script. The best way to debug this is to go to the last sub-process that has failed or hung and look at the log file, and possibly re-run that step from the terminal. Here is how to get there:

1. In your main log file the last lines will be something like...

   Starting job 1...Log will be: /net/omega/raid1/scratch1/terwillMR_ROSETTA_2/GROUP_OF_PLACE_MODEL_1/RUN_FILE_1.log
   

2. This log file in turn may say that further jobs were submitted...if so, go to the end of that log file...find the name of the next log file...etc... until you are at the very last thing done.
3. Your last run is in the directory where RUN_FILE_1.log is located. There will be the following files (more if there are lots of runs in this directory of course):

   terwill@sigma> cd MR_ROSETTA_2/GROUP_OF_PLACE_MODEL_1/
   terwill@sigma> ls -tlr
   total 60
   -rwx------ 1 terwill lanl  1495 Feb  5 14:54 RUN_FILE_1.sh*
   -rwx------ 1 terwill lanl   282 Feb  5 14:54 RUN_FILE_1*
   -rw-r--r-- 1 terwill lanl  6431 Feb  5 14:54 PARAMS_1.eff
   -rw-r--r-- 1 terwill lanl  6564 Feb  5 14:54 mr_rosetta_params.eff
   -rw-r--r-- 1 terwill lanl   130 Feb  5 14:54 INFO_FILE_1
   drwxr-xr-x 6 terwill lanl  4096 Feb  5 16:44 RUN_1/
   -rw-r--r-- 1 terwill lanl 21575 Feb  5 16:45 RUN_FILE_1.log
   -rw-r--r-- 1 terwill lanl    51 Feb  5 16:46 JOBS_RUNNING
   

   Here:
   • PARAMS_1.eff are the parameters used in the run
   • RUN_FILE_1.sh actually runs the job (e.g., phenix.mr_rosetta PARAMS_1.eff) NOTE: usually this is mr_rosetta but it could also be another routine, so you do have to look at it or the first line of PARAMS_1.eff which will name the routine used.
   • RUN_FILE_1.log is the log file for this run. Look at the end of this file.
   • The job is run in RUN_1/
   The key here is that you can type

     phenix.mr_rosetta PARAMS_1.eff
   

   and the exact same job that failed or ran will be run again. You can use this to debug what is going on.
4. Look at the log file RUN_FILE_1.log and the files in RUN_1/. Notice what the last file written in RUN_1/ is...this may give a clue as to when and where the problem occurred. Usually there will be an error message in RUN_FILE_1.log that may be informative.
5. If the run in question is a Rosetta job, then the actual Rosetta job is run in a subdirectory of RUN_1/ This will be in a directory like:

   MR_ROSETTA_2/GROUP_OF_ROSETTA_REBUILD_1/RUN_1/REBUILD_IN_SETS_1/RUN_5/WORK_1
   

   Here this is in RUN_1 of a group of rosetta models, set 1, run 5, working directory. In this directory you will find something like:

   terwill@sigma> cd WORK_1/
   terwill@sigma> ls -tlr
   total 684
   -rw-r--r-- 1 terwill lanl   1475 Feb  5 16:48 rebuild.flags
   -rwxr-xr-x 1 terwill lanl    304 Feb  5 16:48 run_rebuild.sh*
   -rw-r--r-- 1 terwill lanl 422921 Feb  5 17:26 S_3DZB__0001.pdb
   -rw-r--r-- 1 terwill lanl    665 Feb  5 17:26 score.sc
   -rw-r--r-- 1 terwill lanl  97437 Feb  5 17:26 rebuild.log
   -rw-r--r-- 1 terwill lanl 158717 Feb  5 18:17 S_3DZB__0001_ed.pdb
   

   Here:
   • rebuild.flags are the commands to Rosetta
   • run_rebuild.sh is a command file to run Rosetta with rebuild.flags
   • rebuild.log is the log file
   You can look at the log file and see if there are any messages. Then you can rerun the Rosetta job in a scratch directory with:

   mkdir junk
   cd junk
   ../run_rebuild.sh
   

   With luck, you will get the same errors and you can debug from there by changing the parameters or input files in rebuild.flags to see what was causing the problems.

   Specific limitations and problems:

   mr_rosetta does not have the full flexibility of autobuild, so you may want to get a nearly-complete model with mr_rosetta and then use autobuild to increase the completeness and quality. You may also want to take the output of mr_rosetta and then put it back in as input to mr_rosetta and re-run it to improve your model.

   File names of PDB files for mr_rosetta need to have at least 4 characters before the .pdb. So test.pdb is fine, but my.pdb is not.

   Literature

   • Frank DiMaio, Thomas C. Terwilliger, Randy J. Read, Alexander Wlodawer, Gustav Oberdorfer, Eugene Valkov, Assaf Alon, Deborah Fass, Herbert L. Axelrod, Debanu Das, Sergey M. Vorobiev, Hideo Iwai, P. Raj Pokkuluri & David Baker (2011) "Increasing the Radius of Convergence of Molecular Replacement by Density and Energy Guided Protein Structure Optimization" Nature, 473, 540-543.
   • DiMaio, F., Tyka, M.D., Baker, M.L., Chiu, W., Baker, D. (2009). "Refinement of Protein Structures into Low-Resolution Density Maps Using Rosetta" J. Mol. Biol. 392, 181-190.

   Additional information