Newsletter contents... UP

Tcl/Tk based crystallographic software : current state and new programs

L.M. Urzhumtseva#* and A.G. Urzhumtsev§*

#UPR de Biologie Structurale, IGBMC, Parc d’innovation, B.P. 163, Illkirch, France
§LCM3B, Université Nancy 1, Faculté des Sciences, 54506, Vandoeuvre-lès-Nancy, France
*IMPB, RAS, Pushchino, Moscow Region, 142292, Russia

e-mail :


A series of interactive crystallographic programs, aimed to facilitate some routine crystallographic jobs, is in the course of development. These programs are based on the Tcl/Tk language (Osterhaut, 1993). Some of these programs have been reported earlier (CONFOR, CONVROT). A new program, CRITXPL, which presents the results of the X-PLOR refinement (Brünger, 1992) in the form of a number of plots, is available.

I. Introduction

The current state of crystallographic work shows a discrepancy between the complexity of existing methods and their routine applications. This gap can be reduced by user-friendly programs using the rich graphic possibilities of modern computers. Another problem where such programs are important is crystallographic data processing. In our series of programs, which fill some "holes" in crystallographic software the choice for the Tcl/Tk macrolanguage (Osterhaut, 1993) has been done because of its accessibility (free of charge) and the compatibility of the scripts with different types of computers (SGI, DEC Alpha, IBM PC, …).

The first programs were chosen to answer some routine needs in protein crystallography. The historically first program, CONFOR, changes the formats of standard crystallographic data files. The second, CONVROT, helps in the transitions between different rotation and orthogonalisation conventions, which is important, in particular, for the molecular replacement analysis. The third program, CRITXPL, allows to present a long X-PLOR output file after model refinement in a graphic form and to manipulate this presentation. Some details of these programs are discussed below.


Refinement of an atomic model using X-PLOR (Brünger, 1992) is currently carried out in a large number of macromolecular crystallography laboratories. The main results of the refinement are a model and the corresponding log-file which shows the process of refinement, giving crucial information on the success or failure of the process and proposes necessary modifications, for example, of the weights for different criteria. This log-file is a long list which contains a large amount of tables with criteria values, showing their variation during the refinement. The analysis of these tables takes significant time and effort.

The program CRITXPL has been developed to give a graphical representation of the variation of the minimisation criteria during an X-PLOR refinement. The program can be run either after X-PLOR or "in parallel" to it. In the latter case, the graphics can be easily updated during the refinement. To start the data processing, the name of an X-PLOR log-file can be chosen through the menu. This file can eventually contain several "minimisation processes". A process is defined as a sequence of X-PLOR "refinement frames" with increasing cycle number and with the same list of criteria. To easily identify the process to be displayed, a special line of comments can be optionally used in the X-PLOR script. For every process, CRITXPL shows, as a function of the cycle number, the plot of the gradient, of the temperature, of the R- and R-free factors, and, optionally, the plots of other criteria used. The latest values of the criteria are displayed numerically. The full list of all criteria applied in the analysed process is given by a set of buttons which can be used to remove, to replace or to show a plot of a chosen criterion. A maximum of eight criteria can be shown simultaneously. Any combination of them can be chosen and changed at any moment. The processes can be displayed either one by one or together. The latter option is useful for molecular dynamics; in this case, the criteria values both in the first and the last points of the chosen processes are displayed. The plots can be updated during an X-PLOR run, can be shown in a larger scale, and the point coordinates (the cycle number and the criterion value) can be obtained using a "mouse".


The need to describe the orientation of a known model is obvious for crystallographers. Possible descriptions by 3 (or 4) parameters differ by:

a) the choice of the rotated object (body or coordinate system),

b) the definition of the positive direction of the rotation (clockwise or counter-clockwise),

c) the type of angles (Eulerian or polar),

d) the choice of parameters inside a given type of angles,

e) the orthogonalisation convention for a given crystal.

In protein crystallography, at least about 20 of these variants are used by different programs. Unfortunately, this variety (which reflects the point of view of different authors) does not allow an easy understanding for users of crystallographic packages and a straightforward comparison of results. Actually, what the majority of crystallographers needs is simply to have a rotation matrix, R, which should be applied to the coordinates of the model to place it in the unit cell as the rotation function suggests. However, these matrices are not always given by the authors.

The program CONVROT (Urzhumtseva & Urzhumtsev, 1997) can convert the rotation description from any of the widely used molecular replacement systems to any other. All rotation conventions are considered from a common point of view (rotation matrices which are applied to the body's coordinates) which facilitates the transfer of results between the systems. It should be noted that all rotation conventions are defined in a Cartesian coordinate system, which for a given crystal can be introduced in various ways. The knowledge of the orthogonalisation agreement is also important when the crystal has symmetry because the corresponding operator(s) are naturally defined in crystallographic coordinates. The program can recalculate rotation parameters when the orthogonalisation convention is changed. In order to facilitate the analysis of the rotation function and the comparison of results of different molecular packages, CONVROT can provide the full list of rotation parameters symmetrically related to given ones, if such symmetries are defined.

The computational part of the program is written in standard FORTRAN. The program can be used in two different modes. Firstly, it can be run in a usual command-line shell such as UNIX or VMS. The input of the control data and the output of the results are organised in the form of a dialogue, and no special documentation is necessary in order to use the program. CONVROT can be run on any type of computer.

Secondly, a user-friendly environment for this program is developed with the use of the Tcl/Tk macrolanguage (Ousterhout, 1993). In this case all control data can be defined using menu and the order of data definition is arbitrary. The rotation parameters and the symmetry operators can be either typed in the corresponding windows or chosen by clicking the name of the corresponding file in a list. The output information is saved in a disk file. The program has an extended help for rotation and orthogonalisation conventions. This help includes definitions of the parameters, corresponding matrices, formulae for parameter recalculation and necessary references.


The variety of the formats for main crystallographic data (structure factors, maps, atomic coordinates) creates a problem of data exchange between different applications. The program CONFOR (Urzhumtseva and Urzhumtsev, 1996) was planned to be a user-friendly converter of such files. The basic effort has been concentrated in the development of the part corresponding to the conversion of map files while the parts corresponding to the structure factors and coordinates have only few basic options for a time being. The program can read a density file, check the header information and save the map, optionally only partially and/or in different axes orientation, in a new format. It is also possible to change the variable part of the header, e.g., unit cell parameters; this can be important when preparing the map files for some versions of graphic display programs which have limitations in the unit cell size they can handle.

V. Technical information

The computational part of programs is written in Fortran 77, and the interactive graphics part is written in Tcl/Tk (Osterhaut, 1993). CONFOR uses the CCP4 library and some FRODO/O subroutines with the kind permission of their authors. The programs can be ran at a SGI computer and an Alpha DEC station under UNIX or at IBM PC under LINUX with the Tcl/Tk libraries installed. The program can be also run at IBM PC or Macintosh with a X-terminal simulator like exodus, xwin etc. CRITXPL accepts log-file produced by the 3.1x, 3.8x X-PLOR versions as well as by CNS.

No special documentation is necessary due to the menu-based character of the program. On-line help is available. The programs source code and the Tcl/Tk script are available on request from the authors. The corresponding e-mail address is . The authors thank Dr. A.Podjarny for his reading the manuscript and correction the language.



Brünger, A.T. (1992) X-PLOR. A System for X-ray Crystallography and NMR, Version 3.1. Yale University, Connecticut, USA

Osterhout, J.K. (1993) Tcl and Tk Toolkit. Reading, MA : Addison-Wesley Publishing Company

Urzhumtseva, L.M., Urzhumtsev, A.G. (1996) "Programs based on the Tcl/Tk interface. I. CONFOR - program to reformat crystallographic data files". CCP4 Newsletter on Protein Crystallography, 32b, 41-43

Urzhumtseva, L.M., Urzhumtsev, A.G. (1997) "Tcl/Tk based programs. II. CONVROT: program to recalculate different rotation descriptions". J.Appl. Cryst., 402-410

Newsletter contents ... UP