MANUAL

Chapter 6: Building and Refinement

As of version 0.9.x the official Elves mission ends at the calculation of a phased electron-density map. However, some very useful tools for model building and refinement have been included, and more will be coming in the future.

Refmacer Elves are a standard set-up procedure for putting an existing model into refinement with protin/refmac/arp. The merged mtz data files produced by Wedger, Scaler, or Phaser Elves can all be used as input into Refmacer Elves. In some cases, you might want to use FreeRer.com to "inherit" a FreeR_flag column from another mtz or x-plor type file. The existing model can come from just about anywhere. If you are fortunate enough to have a molecular replacement candidate, you might want to use epmr, amore, CNS or some other third-party MR program to get a "starting model" for your refinement.

At the moment, Elves only support using ARP/wARP to build a model into your map.

Complete documentation for ARP/wARP is available at the ARP/wARP homepage. It's not very diffucult to download and install. The main Elves program will set up ARP/wARP in a subdirectory called ./wARP/, including some examples and a README file. If ARP/wARP is installed on your system, the example scripts in ./wARP/ should run. Processer Elves will run ARP/wARP in this directory once they are done with Phaser Elves, provided your outer resolution limit is better than 2.3A. This will usually result in a nearly complete molecular model, and you can feed the resulting "./wARP/files/warpNtrace.brk" file into Refmacer Elves for continued, manual refinement.

Once you have a model, it is really easy to set up protin/refmac/arp using Refmacer Elves.

So, how do you use Refmacer Elves? Run the script with the data and model on their command line:

unix% Refmacer Elves amore/best.pdb mtz/best_phased.mtz

Refmacer Elves will use the information from these files to create scripts suitable for running protin/refmac/arp to refine your staring model against the provided data. If phases are available in mtz/best_phased.mtz, then phase restraints will be set up.

Like all Elves, Refmacer Elves work by writing shell scripts for CCP4 programs. These scripts have been designed to be easy to read and edit, but also contain a "smart setup" section to make them as flexible as possible in their unmodified form. Some examples of these scripts are shown here, with a brief description of how to run them:

refmac.com
is the template protin/refmac script written by Refmacer Elves. Refmacer Elves will have set up refmac.com as best they can for the model and data you provided them, but you might want to read it over before running it. The output coordinate file will always be called pdb/refmac.pdb and ./refmacout.mtz. Use it like this:

usage: scripts/refmac.com pdb/refmac123.pdb 5

will run protin/refmac to refine the coordinates in pdb/refmac123.pdb against the data you supplied to Refmacer Elves for 5 cycles (default is 50 cycles).

maps.com
is a sigmaa-map calculation script. It is designed to take the ./refmacout.mtz file from refmac.com as input. The standard 2FOFCWT and FOFCWT maps are calculated from the refmac output and placed in ./maps/. After calculating the maps, maps.com also converts them to o format (dsn6), in the "./o" directory. You will probably have to edit the top of maps.com to update the location of your mapman executable. By default, these o maps are extended to cover the model in ./pdb/starthere.pdb, but you can specify a different pdb file on the maps.com command line. Use it like this:

usage: scripts/maps.com pdb/refmac123.pdb

will calculate the standard (sigma-a) 2Fo-Fc and Fo-Fc maps from the data in ./refmacout.mtz and make sure the o maps cover the model in ./pdb/refmac123.pdb. In addition to the maps, maps.com creates an o macro for loading and viewing the new model and map into o as ./o/latest.omac. Another macro for visiting all the major difference peaks in your Fo-Fc map called ./o/visit_peaks.omac. Both of these can easily be modified to suit your specific needs.

arp.com
is a basic arpp/arp_warp script written by Refmacer Elves. By default, maps/fofc.map is checked against maps/2fofc_free.map and pdb/starthere.pdb to look for new water atoms. You might want to edit it to suit any special ideas you might have. arp.com is designed to be self-correcting, so if arp_warp doesn't like your map limits, the input maps will be extended automatically. Use it like this:

usage: scripts/arp.com pdb/refmac123.pdb

will run arpp/arp_warp (whichever was available to Refmacer) to add waters to the model in pdb/refmac123.pdb, based on peaks found in maps/fofc.map. The new model (with waters added) will be placed in ./pdb/arp.pdb.

converge.com
is a master-control script for running all of the above scripts until the refmac/arp procedure converges. Use it like this:

usage: scripts/converge.com pdb/refmac123.pdb >! converge123.log

will run scripts/refmac.com repeatedly, creating new pdb files at each step (pdb/refmac124.pdb, pdb/refmac125.pdb etc.). The output of the refmac runs is also kept (logs/refmac124.log, logs/refmac125.log etc.). Every 10 of these "refmac" cycles, scripts/maps.com will be run in order to update the "current" maps. Once the refined model stops moving (convergence), scripts/arp.com is run to add new waters. If you want to run arp every "n" cycles, then you should edit the line in converge.com where it says "arpcycle" to read "n" instead of 1000.

Rplot.com
Rplot.com is a jiffy for displaying vital statistics from one or more refmac logs. The quantities R_cryst, R_free, R_free- R_cryst, correlation coefficients, bond deviations, angle deviations, and total number of atoms refined are listed in an xloggraph-readable format. (Also works on logs from wARP refinements that use refmac.) When multiple logs are provided, they are sorted by creation date and the values from the last refinement step in each file are listed against the number extracted from the log filename. For example:

usage: Rplot.com logs/refmac*.log >! Rplot.xlog

would produce a file called Rplot.xlog that can be displayed graphically by xloggraph.

Drift.com
Drift.com is a jiffy for displaying movement statistics from two or more pdb files, and is usually used to see how much the model is moving in an x-ray refinement run. The rms change in XYZ position and B-factor are listed for C-alpha as well as for all atoms in an xloggraph-readable format. The maximum shifts in XYZ and B are also listed. Provided pdbs are sorted by creation date and separate listings are created for stepwise (i vs i+1) differences, differences from the first file (i vs 1), and differences from the last file (i vs n). The last of these is a good indicator of wether or not the model is stuck, or is still "headed somewhere" in the refinement.

usage: Drift.com pdb/refmac*.pdb >! Drift.xlog

would produce a file called Drift.xlog that can be displayed graphically by xloggraph.

As of the current alpha release:

1. Refmacer Elves do not run the scripts they write
2. the refmac.com script should always be checked for correctness
3. some editing of the pdb file may still be required

Builder Elves will be a comprehensive, perseverant and parallelizable package for building models from electron-density maps. In particular, multiple conformers and stochastic rebuilding of "difficult" regions is now being worked on. Builder Elves are scheduled to be included in Elves 2.x, but might be avaiable sooner.

Back to the Elves Manual Table of Contents.