RSRef2000 GUI Editor


The RSRef2000 Editor provides a graphical user interface (GUI) for controlling refinement jobs. Control parameters (settings) are entered into a form which may be saved to a file (*.prm) or used to run a refinement job directly from the GUI.  When refining from within O, the GUI should be left running throughout the modeling session.

Preparation for Use:

The GUI is written in Python using Tkinter, a standard object-oriented interface to the Tk.

Unix users: the Tk library should be installed (it may not come with the Python). The LD_LIBRARY_PATH environmental  variable should point to the Tk installation directory, using, for example the following command in the .cshrc file: 
setenv  LD_LIBRARY_PATH /usr/local/lib

Under Windows, Python ( already contains the Tk library.

Syntax: parameter_file  -  for making  corrections to an existing parameter file. Specifying the parameter_file is optional – a new parameter file may be created or an existing parameter file may be uploaded.

Explanation of items:

Starting coordinates

PDB format file name. If refinement is carried out from “O” this field is not used – specify as “none”.

Output coordinates

Filename. If refinement is carried out from “O” this field is not used – specify as “none”.

Map file

Full path of electron density map in DSN6, or OMAP, format. The map should be to the remote machine if one is used as a compute-server.

Symmetry file

Contains non-crystallographic, and crystallographic, symmetry operators to be applied to the initial coordinates. It need contain only those operators that bring coordinates into the refinement region or the neighboring margin.  The program does not otherwise know about space group or unit cell translations, so the subset of operators that generates neighbors should be entered explicitly.  The program does not attempt to iteratively concatonate symmetry operators and/or cell translations - they must all be entered explicitly.  The format is given in the selectcoord  documentation.  Selectcoord can also be used to determine which operators generate neighboring atoms as it can be asked to find atoms that fall within a particular distance of the first protomer, and will report the number found for each operator.

Summary log file

File name.

Low resolution limit and High resolution limit

Resolution limits that were used for creating electron density map.

Atom size cut-off

In calculating model density, contributions from an atom will be ignored if the atom center is farther than this distance. The default of 3.4 A is appropriate for a 3.0 A map.  Up to a point, the larger the value the more accurate, but slower will be the calculation.  The optimal should be dependent on the resolution but is larger than some expect, because it is important to include the ripples of positive and negative density that surround a map of an atom that has been resolution-truncated..

Refinement radius

Map pixels will only be used for the refinement if they fall within this distance of any refining atom.  The best value is a compromise.  The value should be small enough to favor the stronger and more reliable densities near atom centers, but large enough to include a statistically significant number of grid points.  The default of 1.6 is appropriate for a 3. A map on a 1 A grid.   "Refinement radius" should be decreased for accurate structures at high resolution, and increased for low resolution, or coarse grids, or to increase the convergence radius. Note that the Atom size cut-off should always be larger than refinement radius.


Menu selection: zone or sphere. With “zone” one should supply residue numbers (First residue and Last residue) of a zone that will be refined. If “sphere” is chosen Radius and Center x, y, z coordinates of it should be supplied. If crystallographic or non-crystallographic symmetry is present (see Symmetry file option), the symmetry relationships between the refined region of the protomer and its copies will be retained. Selectcoord  makes the symmetry expansion, creating the symmetry equivalent copies of the protomer, and reexpand restores symmetry between atoms that have been shifted independently.

          Note that when refining a sphere the following applies: If atoms of the symmetry related subunit and not the     1st protomer are chosen to be refined, the coordinates of the 1st protomer will be changed in order to retain the symmetry. If more than one equivalent of an atom is chosen to be refined at once the symmetry relationship between them will be retained as well.

Residues within this distance outside a refinement region, zone or sphere, will not be refined (they will be fixed), but they will contribute to the calculation of electron density and to the stereochemical energy. If residues from a symmetry related subunit fall in the margin, they will also be fixed while contributing to the overall refinement.


Menu options controlling the type of optimization: conjugate gradient, slow cooling or quenching (fast cooling).

ED Weight

Weight on electron density term. There is no good way to predict a sensible value, as it depends on the absolute values of electron density values (and hence on absolute scaling of Fs) and also on the number of grid points per atom.  So, trial and error is the norm.  An approximate value can be obtained by matching the magnitude of the density residual to the stereochemical one.  A better approximation would come by matching the sizes of the atomic derivatives for density and stereochemistry.  However, ultimately the proof is in the pudding.  The value should be adjusted until the balance between map-fit and stereochemistry is good, and cross-validated indices are optimized.

MD type

Menu for choosing between torsion angle dynamics and Cartesian dynamics. This is applicable for either slow cooling or quenching protocols. The recommended protocol is torsion angle dynamics. If this fails Cartesian dynamics should be used.

Starting temperature

Higher temperature limit of molecular dynamics. This is applicable for either slowcooling or quenching protocols. 2000 K is recommended for regions that are in reasonable shape. Values as high as 30000 K may be necessary to fix intransigent regions.

Drop temperature

Rate of slowcooling. (Recommended – 500 K if starting temperature is in range of 2000 K). Note that this parameter is ignored in quenching.



Read an existing parameter file. A name with full path should be given in the adjacent prompt.

 A new window will be opened. Reading a new parameter file spawns a new GUI window (unfortunately in the Windows version, the original GUI window becomes hung).

Prepare for ‘O’

Prepares macros and initializes the O - RSRef2000 interface. Needs to be used only once in each directory where O is to be run.  See the documentation to the O - RSRef2000 interface before using this option.

Run from ‘O’

Under Windows, after selecting the region to refine, the user will be prompted in O to push this button. Available only  in Windows. (Under unix, the refinement runs automatically after selection of refining residues).

Save as

To save the parameters in the named file.


To run a stand-alone refinement job with the current settings from the RSRef2000 GUI editor. Options (-r, for use of remote machine; -nostat, to cancel statistics windows) may be specified in the options field.


Exit the editor without saving the parameter file.

ANDREI KOROSTELEV / MICHAEL S. CHAPMAN;  Last updated 03/19/2002