next up previous contents
Visit our: CCMS Home Page
Send us your comments on this user guide: CCMS Comment Form
Next: more Window-based Applications Up: Table of Contents Previous: Chapter 4 Programming XtalView

Chapter 5

Window-based Applications



A page-based contouring program for crystallographic maps.




The map is contoured in sections of x, y, or z. The output appears in a window that is the same size as an 8-1/2 x 11" page. The program produces PostScript output that can be used on any PostScript-compatible printer. The output is fairly WYSIWYG, with the exception that nicer fonts are available on the laser printer. Stereo is available by shearing and labels, and bonds (lines) can be added or read from files. No interpolation is used in the contouring. If you want smoother sections, calculate the map on a finer grid.



The cell information is used from the crystal file.


The unit cell is used to scale the axes. Non-orthogonal axes are properly handled. The rows are always horizontal and the column is at alpha, beta or gamma depending upon the plane being sectioned.


This is read from the input map and cannot be changed.


This sets the sectioning direction in either x, y, or z. If you change this, the rows and column directions are also changed so that they do not conflict. No attempt is made to detect left-handed configurations. If you stack up sections for a mini-map, you may need to stack downwards or upwards to get the proper handedness.


There are 3 fields here. The first is a numeric field that is used to increment/decrement the section where contouring starts. The second is the value of this plane in fractions of the unit cell. If you edit this value and enter it, the nearest plane section will be found. The third field is pull-down menu for choosing the three sections 0.0, 0.5, and 1.0. If the number of sections is odd, the nearest section will be given for 0.5.


The number of sections to contour. They will all be overlaid onto each other on the screen, although when they are plotted they can be either overlaid or plotted on separate sheets. The slab always starts at plane and increases.


Rows go horizontally across the screen. This sets whether this direction is x, y, or z. It overrides the columns when changed if it conflicts with and can be overridden by planes.

Row min

The first value is in terms of grid points in nx, ny, or nz, and the second is fractions of the unit cell. You must enter fractional values for them to take effect.


This sets the direction of the columns. It has the lowest priority and therefore can't actually be used to change the column direction. However, it does indicate the direction being used. Both row and plane direction changes will override the column direction if there is a conflict.

Prev Section

This decrements the plane and redraws the contour.


This draws contours using the current settings.

Next Section

This increments the plane and redraws the contour.


After you press Resize, you can select the upper-left corner and the lower-right corner of a new bounding box. Press Resize again to redraw the map with the new size.


You can save xcontur settings in a defaults file xcontur.defaults. This is convenient if you want to look at several maps with the same settings.

Load Xcontur Defaults loads the defaults from a file.

Save Xcontur Defaults stores the current settings.

Reset to Startup resets the values to the initial quantities.

Contour Levels


The number of contour levels is set here from a minimum of 1 to a maximum of 20.


The interval between successive levels, from a minimum of 1 to the maximum value of the map.


The level of the first contour level. This may be negative. The slider ranges from the minimum of the map to the maximum. When a map is loaded, both start and the interval are set to the root-mean-square value of the map.


Press this button to redraw the screen.

Picking in the Canvas

If you use the mouse button to pick within the Canvas, the fractional coordinates of that point are returned in the Message window. Hold down the <SELECT> (left) mouse button to drag the outline of the section so that it can be positioned on the page. When you use slabs greater than 0, the vertical coordinate with the maximum density value will be printed. This allows you to find the x,y, z coordinates of a peak. The density value printed is an interpolated value and is almost always lower than the peak value.

View Pop-up


The title is initially set to the map file name. It is nice to enter something sensible here.

Display Type

You can look at the contours (default) or at the raw numbers in the map file. However, for the raw numbers only a small section can be viewed before the numbers overlap each other and become unreadable.

Row, Column Ticks

The number of grid lines and/or tick marks to make counting from 0.

Row, Column Origin

The position of the upper left corner of the section. It is easier to set this by dragging with the mouse in the canvas window.

Scale Ångstroms/cm

You can manually enter a value or pull down a menu of choices. The scale is accurate for hardcopy but is correct only if you happen to have the right size monitor. Remember, though, that the canvas window is the same size as a piece of paper if you haven't resized it, and so if the graph fills the window it will fill the paper.

Alternate solid and dashed contour

Check here to put dashed lines on every other level for an interesting effect that can make counting levels easier.

Draw grid of lines

If this is checked, a grid of lines is drawn at the frequency specified by the "row, column" ticks.

Auto Center

If this is checked, the section is centered on the page automatically. This must be disabled for stereo to work properly.

Use Line Width for Depth Cue

Although the computer screen does not have enough resolution for this to be useful, it produces a nice depth cue on laser-printed output and is highly recommended for multi-section slabs. We recommend that you set it just before printing.

Draw Labels

Enables/disables the drawing of labels. Labels can be edited using the Labels pop-up menu or loaded in the File pop-up menu. They are drawn on the section only if the x,y, z coordinate is on that section.

Draw Jack at Label Position

Enables/disables the drawing of a jack at the position of the label. The size of the jack can be changed with the slider.

Draw Bonds

Bonds can be superimposed on the sections. They are drawn only if their x, y, z coordinates are on that section. The line width of the bond on the printed output can be varied from thick to thin to make it more obvious.

Draw side by Side Stereo

The scale is halved and two images are drawn for side-by-side stereo. This is done by shearing each successive section.

Stereo Separation

Sets the distance the two images are apart from each other.

Hint: Set the contour level very high while you fiddle with the stereo parameters so that drawing is quick until you get them right, and then lower the level for the final picture.

Stereo Depth

This sets the shear angle and modifies the apparent depth.


Causes the picture to re-draw.

File Pop-up


This sets a filter for the file list box. It defaults to *.map, and all the files in the current directory that match the filter are displayed in the file list.


Forces the file list to be updated. Use this after changing the filter or the working directory.


The current working directory.

Map File

The source of the map. This field can be filled either from the command line as the first argument, by selecting a file name in the file list, or by typing it in.

Labels File

The labels can be loaded from or saved to this file. It has the format of lines of x y z label, where x, y, and z are the coordinates and label is a text string. xpatpred produces a label file that xcontur can display.

Bonds File

Bonds can be loaded or saved. The bond file has the vu format of lines of x1 y1 z1 x2 y2 z2 color, where x1, y1, and z1 are the starting coordinates of a line and x2, y2, and z2 are the end coordinates. The color is not used by the current version of xcontur. xfit also displays/creates vu files. A number of utilities for producing vu files from PDB files and other sources exist. See pdb_to_vu and grinchbones.

Number of bonds

This is for your information and is not editable.

File List

To pick a file in the list, first click on the File field you want to load into to put the input focus there (the little triangular cursor), and then select a file name with the <SELECT> (left) mouse button.

Print Pop-up

Print to

You can select a file or a printer. You may need to send large pictures to a file and then print them with the -s option because they are too large to spool directly.


A valid name of a printer connected to your computer. Leave this blank to use the default printer.


Name of the file. The directory in the Files pop-up is added unless the name starts with "./" or "/".

Print sections separately

If this option is checked, each section is printed on a separate page. This saves you from having to print them one by one by selecting the entire slab, this option, and then printing.

Labels Pop-up

Can be used to edit the labels list. Its functions are insert/replace/delete. Use the Files pop-up to load a labels file.


xtalview(1), xpatpred(1), grinchbones(1)



Disk full meter.


xdf partition


xdf can be used to monitor disk usage. After it starts, it updates the disk usage of the partition it was started with. The usage is shown on the gauge, and the partition is displayed on the footer.


xdf /usr

Shows the amount of /usr that is used. Since xdf updates every three minutes to avoid overusing computer resources, a sudden jump in disk usage will not show up immediately.





Electron-density histogram plotter.


xedh []


xedh is a normalized electron-density histogram plotter. It can be used to compare histograms between phase sets and between different crystals. The histogram for a correctly phased protein with a given percent solvent and resolution range is characteristic. Any deviations are due to phase errors. By comparing your phase set with those of other well-refined proteins in the same resolution range, you can guess the amount of phase error. For example, when comparing right- and left-handed maps that include anomalous scattering information, the correct hand will have the sharper histogram.

The histograms can be saved and loaded in the File window.

File Pop-up Window has several options, as described below.

Directory tells where to find the data files.
List lists the files matching the displayed filename filter.
Map File shows the currently selected input map file.

Solvent mask is an optional B.C. Wang envelope file (from the program envelope). If it exists, then it is used to determine the protein and solvent regions of the unit cell.

Load menu button allows you to load All Points in Map, Protein Points Only, Protein Points Full Scale, Solvent Points Only, or Solvent Points Full Scale.

mask file allows you to separate protein and solvent.

Histogram specifies the filename of an .edh file to save the histogram information.

Number specifies the position of the histogram to be saved or loaded.

Load loads a histogram file at the position in the Number field.

Save Histogram saves the histogram indicated by the number field into the filename.

Save Graph saves all the histograms into one file.

Clear allows you to clear the graph canvas.

Edit pop-up window provides:


Match gives you a numerical match between the loaded histograms for comparison purposes. The match is the root-mean-square of the differences taken point-by-point.


Print allows you to print the histograms.


This pops up a floating legend that gives information about the curves int he graph window.


The methods are still being developed. In the future, example histograms and more information on determining phase errors may be available.





Calculates an electron density map or a Patterson function map by the Fast-Fourier Transform method.


xfft phasefile mapfile



A crystal file is needed with the cell and symmetry records present. Note that symmetry records should have centering expanded explicitly (i.e., C2 should have 8 symmetry operators, not 4, with the last 4 being 1/2+x,1/2+y, z of the first 4.)

Unit Cell

This is obtained from the crystal file. It can be overwritten by manually entering a value. Note, however, that there is no way to overwrite the symmetry operators.


A defaults file, hardwired as xfft.defaults, can be saved or loaded. Also, defaults can be reset to startup values. This is handy when you recalculate maps often with the same parameters. Note that you can save a defaults file and then copy it to a new name and then copy it back at a later date. In this way, several standard methods can be saved.

Direction of Planes

The output can be in x, y, or z planes. This is only necessary for possible use of the output map by non-XtalView programs, since all XtalView programs can read all 3 sort orders.

Map Type

There are several choices of map coefficients available.

Input File

This file can have several different formats. For Fourier maps, either the phs format (h,k,l,fo,fc,phi) or XPLOR format can be used. For Pattersons, these can be used plus fin and df formats.


Specifies the type of input file. For Pattersons with df formats, there are three choices for defining the difference to be used in computing the Patterson coefficients. Which you use depends upon what is in each of the 4 columns in the df file. Normally, columns 1 and 2 are native data and its sigmas, and columns 3 and 4 are isomorphous data (a column is a pair of f and sigma(f)). To make an isomorphous difference, Patterson map use (3+4) - (1+2), which means the average of 1 and 2 minus the average of 3 and 4, or FPH - FP. Note that, when calculating the average, missing observations are not included.

Resolution Filter

Set these values to your desired limits. The order is unimportant, since computers are perfectly capable of figuring out which number is the min and which is the max (the other one).

Outlier Filter

This gets rid of outliers when you are making Patterson maps. Specifically, if the absolute value of the difference is greater than x percent of the average of the two observations, the reflection is rejected. This is important when making Patterson maps so that a few bad apples don't spoil the whole bunch. A value of 100 percent is a conservative value to use.

Note: On numeric fields you must enter return if you edit the data with the keyboard to register the edit.

Read Phase File

This button reads in the data. It is usually not necessary to use it, though, because the calculate button (below) can figure out if the data needs to be read in. Sometimes you may want to find out the grid before calculating the map, or you may have changed the input data file and want to force a rereading of the input data. In any case, after reading the data some useful information is printed in the Message window for you to edit. Also, if you change any of the data above this button after calculating a map, you must use this button to have that change take effect.

Grid Number in X, Y, Z

This is the number of points in x, y and z to be used in calculating the FFT. The FFT method requires these to be multiples of 2, 3, 5, and 7 and nx to be even. The program restricts you to these values if you use the little arrows by the grid values to increase or decrease them. Usually you do not need to set nx, ny, and nz directly, as explained below.

OR Percentage of minimum resolution

This sets the grid to the next largest value that will give a grid spacing that is equal to the minimum d-spacing or resolution times the percentage. For example, if the input data had a minimum d-spacing of 2.0 and 50% is chosen, the grid will be set as close to 1.0 Ångstroms as possible. If the cell edge was, say, 48.3 Å, then 48.3 is tried, but since this is not an integer it is rounded up to 49. An FFT requires that the grid be at least 50% of the minimum d-spacing (actually, it must be twice the maximum index input but it works out to the same thing). The map will be smoother if 33% (the default) is used. More than this usually has little benefit in smoothing the map and requires much more storage, since the size of the map goes up as the cube of the grid size. Set this field to zero to prevent overriding the nx, ny, nz fields.

OR approximate spacing in Ångstroms

If both nx, ny, nz and the percent of minimum resolution are 0, then this field is used to set nx, ny, nz by finding the nx, ny, nz that gives the closest grid-spacing in Ångstroms that is also a valid FFT grid. For example, if you have a 77.77 Å cell edge and ask for a 1.0 Ångstrom grid then 78 is tried, but since this is not a multiple of 2, 3, 5, or 7, 80 is used.

Output Map File

The XtalView convention is to use the extension .map. This file is in FSFOUR binary FORTRAN format.


This is the "Apply" button. When it is pressed, the FFT is calculated and the map is output. If the FFT is large, it may take several minutes to return. The program tries to ascertain if the data needs to be reread when you change various values. It usually decides to reread even when it is strictly unnecessary. Directory This tells where to find the data files.


If you want a coefficients type that is not available, you can always precalculate them and put them in the Fo column and then make an Fo map.

Example: To make a 3Fo-2Fc map using awk and xfft:

awk '{print $1,$2,$3,3*$4-2*$5,$6}' input.phs | xfft -

In XtalView, a dash (-) means use stdin for input files or stdout for output files. At other times, a binary file with the phases is used. For example, to use a Furey format PHASIT output file (fort.31) using dumpphasit, which writes its output on stdout: dumpphasit fort.31 | xfft -

Unfortunately, if you use stdin or stdout for I/O, then the history file will know only that stdin was used but has no way of picking up the original file used and so the thread of data files will be broken at this point.


The FFT code was supplied by Lynn Ten Eyck. Andy Arvai is partly responsible for the FFT driver routine.


xtalview(1), dumpphasit(1)

next up previous contents
Visit our: CCMS Home Page
Send us your comments on this user guide: CCMS Comment Form
Next: more Window-based Applications Up: Table of Contents Previous: Chapter 4 Programming XtalView