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 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.

Running ARP/wARP

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.

Refmacer Elves HOWTO

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.

Scripts Written by Refmacer Elves

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:
is the template protin/refmac script written by Refmacer Elves. Refmacer Elves will have set up 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/ 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).
is a sigmaa-map calculation script. It is designed to take the ./refmacout.mtz file from as input. The standard 2FOFCWT and FOFCWT maps are calculated from the refmac output and placed in ./maps/. After calculating the maps, also converts them to o format (dsn6), in the "./o" directory. You will probably have to edit the top of 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 command line. Use it like this:

usage: scripts/ 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, 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.
is a basic arpp/arp_warp script written by Refmacer Elves. By default, maps/ is checked against maps/ and pdb/starthere.pdb to look for new water atoms. You might want to edit it to suit any special ideas you might have. 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/ 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/ The new model (with waters added) will be placed in ./pdb/arp.pdb.
is a master-control script for running all of the above scripts until the refmac/arp procedure converges. Use it like this:

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

will run scripts/ 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/ will be run in order to update the "current" maps. Once the refined model stops moving (convergence), scripts/ is run to add new waters. If you want to run arp every "n" cycles, then you should edit the line in where it says "arpcycle" to read "n" instead of 1000. is a jiffy for displaying vital statistics from one or more refmac logs. The quantities Rcryst, Rfree, Rfree- Rcryst, 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: logs/refmac*.log >! Rplot.xlog

would produce a file called Rplot.xlog that can be displayed graphically by xloggraph. 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: pdb/refmac*.pdb >! Drift.xlog

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

Refmacer Elves alpha-version Caveats

As of the current alpha release:

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

The Future: Builder Elves

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.

This page is not finished. It will never be finished, and neither will yours. Admit it.

James Holton <>