Map-fitting and molecular modeling program to display or manipulate models and fit to electron density.


xfit v3.7.


xfit [-bw] [-std] [-save] [.pdb .phs .fcf .map .vu .vp .script .bones .seq]


All the files on the command line are loaded according to their extension. If you have files with different extensions, they can be loaded using the files option. xfit accepts PDB files, phase files (in X-Plor, TNT, or CIF (SHELX List 6) format; ".fcf" is accepted as equivalent to ".phs"), map files, vu (vector or line) file, viewpoint files, script files, ridgelines (bones) files, and sequence files.

The -bw flag forces the program to be black and white, even on a color display. It works on the SUN only.

The -std flag prevents the Accelerated Canvas from being invoked on SGIs and on SUNs with GX graphics. This is intended for users displaying remotely on a workstation that does not support GL or GX.

The -save flag causes the active model to be automatically written to a back-up file whenever the user changes it. The same can be accomplished by putting "AutoSave on" in the .xfitrc file. The back-up file is put in the current directory and has a name of the form xfit_autosave_PID.pdb where PID is the process id.

Xfit is a large and complex program with 18 windows and many possible operations. Some of the more notable features are:

Xfit Main Menu

The Xfit main window has a number of submenus of pop ups and pull downs for its specific functions. These submenus are listed in the table below and detailed descriptions of each submenu are also included in this document.

files window
ridgelines window
lsq fit window
canvas window
view window
show window
color window
fft window
plot window
refine window
controls window
contours window
model window
SFCalc window
labels window
tools window
waters window
errors window

Environment Variables

XFITPENTDIR gives the name of the directory containing pentamer data. It is usually $XTALVIEWHOME/data/pdbvec. You can copy pdbvec to another location and change the structures used in the pentamer database by changing this environment variable.
See the README file in the $XTALVIEWHOME/data/pdbvec directory for more information.

PRINTER gives the name of the default printer in the PostScript Plot window. PRINTERCOMMAND gives the command for printing, not including the printer name; by default it is "lpr -P", but you could set it to, say, "lp -d".

On SUNs with GX, control of the buffering method is provided through the environment variable XFIT_DBUF. By default, hardware double-buffering is used on machines that seem to support it. Type "setenv XFIT_DBUF colormap" to get an image with less-than-perfect depth-cueing, or "setenv XFIT_DBUF off" to get a better-looking image that flashes badly when you manipulate the view.

Also SUN-specific are the environment variables XFITGS (set to 1 to cure spurious lines that are drawn on the canvas on some SUNs), EZXGLFONT (defaults to "Roman_M"; set to "Roman_D" to access a more attractive, slower, font), and EZXGLNOZBUF (suppresses Z-buffering).


xfit determines the screen depth and uses color if the depth is 8 bits or greater. The color database is loaded from ./colors.dat if available, then from $XTALVIEWHOME/data/colors.dat. Normally the latter is used, but for special purposes the file can be overridden with ./colors.dat. However, none of the built-in default colors will make sense if ./colors.dat is completely different. This option is normally used to change the shades of the colors to more favorable ones for different display devices. For example, the author uses a separate colors.dat for making slides. A little white has been added to the red, and the blue has been made closer to cyan in order to show up better on film.

SUNs with GX cards use color double-buffering to make the display three times faster. The drawback of this is that only eight colors are available and there is no depth-cueing. See the XFIT_DBUF description under "Environment Variables," above.

Note: hardware double-buffering does not work on SUN TurboGX+ machines.


The mouse is used for rotations and translation, picking, and model manipulation. Your mouse should have three buttons: <Select> (left), <Adjust> (center), and <Menu> (right). (You can change the order of these buttons by editing lines in the ~/.Xdefaults file; see an XView or Open Look manual for more information.) In Linux, you can emulate a 3-button mouse - see the system manual - or even better, buy a 3-button mouse.

To pick something, click the <Select> (left) button. To rotate something, hold the <Select> button down and drag the pointer. Z rotations are done by dragging left and right in the upper portion of the screen. (When the cursor is in the upper portion of the screen, it changes from a "+" shape to a "Z" shape to indicate the change in function.)

<Adjust> changes purpose, depending upon the mode (indicated in the lower right corner of the screen). At startup, the program is in Center mode: dragging <Adjust> centers the screen. Dragging near the top of the screen adjusts the z positions. By holding down the <Select> and <Adjust> buttons simultaneously and moving the pointer vertically, you can zoom the image in or out. In Linux, double-button modes do not work: use the i and o keys to zoom.

<Menu> brings up a menu to change the mode. The modes Translate, Rotate, and Torsion are operative if a portion of the model has been selected for fitting. Move and Translate work by dragging <Adjust> in the same way as for <Select> (described above).


For torsions, you must first pick a vector around which you want to torsion (using <Select>). Hit the tail of the vector first (bond), then the head, and then select Torsion in the menu. All the atoms bonded to the head and currently selected are included in the torsion group. Dragging <Adjust> left and right torsions the group about the selected vector.

Stacked torsions are not supported, although once you get used to the "click-atom, click-atom, select-torsion" routine you can change torsions quickly. (Note that the pop-up menu can be pinned for easier use).

Keyboard Shortcuts

If a single residue is selected for fitting, the side-chain torsions can be set up by hitting the appropriate number on the keyboard while the mouse pointer is in the Canvas window. For example, hitting 1 sets up chi1 and hitting 2 sets up chi2. This is much faster than picking atoms and selecting Torsion.


If your (SUN or SGI) computer is equipped with a dialbox, you can use it instead of the mouse to change the viewpoint. By default, the dials are set up as follows:

Rotate Y Translate X

Rotate X Translate Y

Rotate Z Translate Z

Zoom Slab

(In Insight II Mouse mode, Rotate X and Rotate Y are interchanged.)

Holding down the <Shift> key while rotating a dial moves the current atoms in place of the <Adjust> mouse button.

You can customize the position and sensitivity of the dial functions by putting lines similar to the following in your .xfitrc file or in a script file:

DialSet View
RotateY     N    1.0   TranslateX N    1.0
RotateX     N    1.0   TranslateY N    1.0
RotateZ     N    1.0   TranslateZ N    1.0
Zoom        L    1.0   Slab       L    1.0

These lines are in free format. The numbers control dial sensitivity; "L" or "N" controls whether response is linear or nonlinear. (If it's nonlinear, the difference in effect between large and small movements of the dial is greater.) A window pops up to show you which dial functions correspond to which dials. More dial functions and more dial sets will be added in future releases.

Atom stack

xfit uses an atom stack for many operations. All operations use a prefix notation. First, the operands are selected and put on the stack; then the command is given. For example, you can put two atoms on the stack and hit Distance in the main window; put three atoms on the stack and hit Angle in the main window; put four atoms on the stack and select "Calculate torsion angle for top 4" from the menu on the main window's torsion button; put two atoms on the stack and select "Bond top 2 atoms on stack" or "Break bond between top 2 atoms" from the Bonds Menu button on the main menu.

Atoms are pushed onto the stack in two ways: by picking on the screen and by picking from the atom list in the Model window.

The main window button called "Expand Top 2" supplements the last two atoms you picked with all the residues between them, and puts a range of residues on the stack.

How to Select

A fragment is selected for fitting or structure factor calculation by first putting the appropriate atom(s) on the stack and then selecting one of the fit options. To put an atom on the stack, pick it on the screen or select it in the Model window (see below).

The item labelled atom in the Canvas menu selects the atom on the top of the stack. Atoms selects all the atoms on the stack. Residue selects the entire residue that contains the atom on the top of the stack. Residues selects all residues that contain an atom on the entire stack. Group selects all the residues in the same group as the residue containing the atom on the top of the stack. Groups are set in the Model window. Molecule selects the entire model. The selected atoms are referred to as the current group. Bonding is irrelevant.

Use the Clear stack button in the main window before setting up atoms or residues. If you are dissatisfied with your selection, hit Cancel. Reset puts you back to your starting positions and Apply commits your fit.

When a model is selected for fitting, its old positions are saved in one of 20 slots. Select Save Set in the Main menu selects the slot containing the model to be undone, and then Swap will toggle between the saved and fit model. Judicious users will still save their model to disk often with the Save button, and may also want to use the AutoSave feature.

Some definitions

Internally, xfit uses the following hierarchy to describe models: A molecule is all the atoms given in a single PDB file. A chain is all the atoms with the chain-ID column set to the same value in the PDB file. A fragment is a stretch of residues bonded together. A residue is all the contiguous atoms with the same residue-ID in the PDB file, and an atom is a single line in the PDB file that begins with either ATOM or HETATM. Additionally, the user can specify a group in the Model window that is an arbitrary grouping of residues.

An atom has a name such as CA or CB, an occupancy, a B-value, and x, y, z coordinates. A residue contains an array of atoms, and has a name such as 1 or 152, and a type such as ALA, HEM, or H2O. A chain is specified by a single character. A molecule is referenced by the original filename.


Lines derived from bonds and points are drawn on the screen. Any atoms within a specified radius in the same residue are bonded. The exception is peptide bonds, which are made if the N-C distance is reasonable, and phosphate bonds between bases in DNA. If two adjacent residues contain only single CA atoms, they are bonded if they are less than 4.5 Å apart. The remaining points (such as water) are drawn as three short orthogonal lines, or a jack. Other polymers, such as carbohydrate, are not connected.

PDB files have a record, CONECT, which can be used to specify a bond between any two atoms. These residues are read and the specified bonds put in a special list so that these bonds are always made regardless of geometry. This is useful for connecting prosthetic groups to the protein such as thio-ether linkages or metal ligand bonds. If you make a bond in xfit, use the Bond command, and then save the model, the CONECT information is written at the end of the file and will be read the next time the model is loaded.

Contours Window

Contours are iso-values in an electron-density map. Five levels are provided in xfit. The map is scaled such that one sigma is equal to 50. The startup contour levels are 1,2,3,4,5 sigma and can be adjusted later. The contouring algorithm is fast but not always pretty (for instance, it makes no attempts to resolve saddle points). To make the contours prettier, use a finer grid. Three times the maximum h, k, and l are usually about right. (The maximum index can be found from (cell edge)/dmin). If you have one long axis, this one can be made at twice the maximum index and will still look fine. A large number of contours can slow rotations. One useful option is to select the Skip Contours option in the Controls window. This causes the program to skip drawing contours if it cannot draw the contours between mouse events and then re-draw them when rotations stop. Since the model is usually being used as a guide to the eye for rotations, dragging the map along is not always necessary. In this way, you can speed up rotations considerably.

Contouring Method in the Contour Map window may be set to "Cube," "Sphere," "Different Axes," or "Blob." The first three methods define the density as bounded by a cube, sphere, or oblong box, respectively. "Blob" (the name derives from an old program of Colin Broughton's that could draw either a box-shaped or a blob-shaped map) specifies the density to be rendered as being within a specific radius of any of the current atoms. (The blob map changes whenever the current atoms change. This is useful when one wants to confine one's attention to density near where one is fitting; but to preserve a blob map, one should save the contour lines to a file and load it as a vu object.) "Cube/Sphere Radius" specifies the radius of the sphere for the Sphere method, or the half-width of the cube for the Cube method. A Axis, B Axis, and C Axis specify the dimensions for the Box method. "Extend blob around current atoms by" specifies the radius for the Blob method.

When "Auto Contour on Scroll" is enabled in the Contour Map window (the default), the map is automatically re-contoured whenever the user translates the view. Users with slower computers will probably want to disable this option by putting in their .xfitrc file the line "autocontour off".

"Lock Clipping Planes" in contour window

Ridgelines Window

Use the xskel program to produce a ridgeline file from a phase file or use the ASCII Save Filename option in interp. xskel is an interface to the UNC mkskel program and produces output that can be read directly in the Files window.

You can also interactively change the contour level and box size. To pick an edge, set the Pick mode to Edges. To color an edge, select the type you want to color the edge, select the Color Edges Pick mode, and then pick the edge you want to color. An entire side chain can be colored at once by setting the Pick mode to edges, picking an edge to place it on the stack, and then clicking on color side chain. The last color side chain can be undone with the undo color button. The regular model building features of xfit can be used to build models over the ridgelines.

Background Objects

To build complex background objects, layer individual vu objects in the View window. Each vu object can be turned on and off using the Show window. For example, you can make a vu object with side chains and another with mainchain. The sidechains can then be blinked on and off by clicking on the appropriate line in the vu list. Individual residues of interest can be colored individually. Multi-colored objects are composed by building up from individual pieces. Objects with a higher number overdraw lower-numbered objects. Models overdraw vu objects, so turn off the model to see coincident vu objects.

Hint: Use several individual objects instead of a few complicated objects.

Canvas Window

Objects are drawn in the Canvas window. On SGIs and on SUNs with GX, the Canvas menu in the main window has two options: Accelerated Canvas and PostScript Preview Canvas. Accelerated Canvas is the default. The two canvases differ in the following ways:

A ruler is drawn at the bottom of the screen with the scale in Ångstroms. Objects can be dragged over to the ruler for measurement. In the upper left is a gnomon that shows the laboratory axes. The <Menu> button pulls up a menu that can be pinned and left up permanently if desired. By using the pull-up menu, you can avoid constantly moving back and forth between the screen and a side menu.

The menu items are:

Center @ pick Centers at the last atom or edge picked.

Center mode Puts the mouse in center mode, in which <Adjust> (middle mouse button) moves the center of the screen.

Translate mode Current atoms can be translated with <Adjust> (middle mouse button). Note the difference between this and center--they are easily confused. A common mistake is to forget to go back to center mode to move the screen center.

Rotate mode Current atoms can be rotated with <Adjust> (middle mouse button).

Torsion mode Two ends of a current bond are picked first. The atoms attached to the second end will become a group that can be torsioned around the selected bond. The atoms must all be in the current group.

Contour Contours at the center of the screen using the values in the Contour window.

Atom Selects the last-picked atom.

Atoms Selects all of the atoms in the stack.

Residue Selects the residue to which the top atom belongs.

Isolate Selects the residue containing the top atom and breaks all bonds between it and other residues. After fitting, you will want to select "Rebuild Bonds" from the Bonds menu.

Residues Selects all the residues containing any atom in the stack.

Group Selects the group to which the top atom belongs. (Groups are set up in the Model window.)

Molecule Selects the entire molecule of which the top of the stack is a member.

Rotate X clockwise 90 degrees

Rotate X counter-clockwise 90 degrees

Rotate Y clockwise 90 degrees

Rotate Y counter-clockwise 90 degrees The two rotate Y commands are especially useful for centering an object in density. First, center in one view; then rotate Y 90 to fix the third direction; then rotate Y -90 back to the starting view.

Rotate Z clockwise 90 degrees

Rotate Z counter-clockwise 90 degrees

Toggle Stereo Toggles stereo mode.

Swap Menu Toggles between the default canvas menu and an expert menu for advanced users.


When xfit starts up, one of the windows that automatically appears is a toolbar called "Xfit Tools". The toolbar persists in stereo mode to make accessing functions easier. It contains:

  • a menu button that lets you bring up all the pop-up menus
  • a menu button that brings up Canvas Menu that you usually bring up with the right mouse button
  • a menu button that brings up the Expert Menu that you get when you swap the canvas menu
  • a menu with facilities for automated map fitting. See the World Wide Web page http://www.scripps.edu/pub/dem-web/tutorial/xfitauto.html for a tutorial on these facilities.
  • If you close the toolbar, you can restore it with the "Tools" button in the Main Window.

    Mouse Functions in the Canvas Window

    Use the <Select> (left) mouse button to:

    Click Pick atom

    Drag Rotate view x-y

    Drag top of screen Rotate zor Drag + <Ctrl>

    Drag + <Adjust> Scale or zoom the view

    or Drag + <Shift>

    The function of the <Adjust> (middle) mouse button depends upon its mode, which is set with the <Menu> (right) mouse button. The default translates the view; dragging near the top of the screen translates in z.

    The <Menu> (right) mouse button brings up the fitting menu to select atom, atoms, residue, or residues, rotate, translate, and change torsion. It also allows you to change the mode of the middle mouse button to allow fitting of the currently selected model. Center restores the translate view mode.

    In Insight II Mouse mode, <Menu> rotates, <Select>+<Menu> rotates in z, <Select>+<Adjust> translates in z, and <Adjust>+<Menu> zooms. <Select> by itself is used for picking only. What is ordinarily the right-mouse menu is available through the toolbar only; you'll probably want to pin it up. For <Select> +<Adjust> and <Select> +<Menu>, you must press <Adjust> and<Menu> before <Select>; otherwise, the <Select> will be interpreted as an atom pick.

    Keyboard Shortcuts

    Show Window

    The show window contains controls that allow which objects are shown in the canvas window. Objects can be hidden by selecting them on the list in the Show window. Useful information about each object is also given to identify it. A difficult-to-identify object can often be found by toggling it on and off. Hide all objects that are not needed to increase the rotation speed. Object blinking is set up here (see the section on Blinking). The "Turn H's" toggle controls the visibility of hydrogens globally in all models (including models subsequently read in.) Contacts (created with the "Draw Contacts" option in the Controls window) can also be cleared in this window.


    The Show window contains controls that allow you to set up two blink groups and then alternately blink them on and off. First, highlight all the groups you want in one set and make sure the others are unhighlighted. Then select Set Group 1. Now, un-highlight group 1, highlight group 2, and select Set Group 2. Objects not included in either group will not appear. Objects in both groups will stay on all the time. You can turn on and off blinking and you will not need to reset the groups unless you want to change them. The speed of the blinking is set in the Controls window.

    Model Window

    The currently active model is listed in the Model window. When a residue is selected, the atoms in that residue show up in the atom list. When an atom is picked in this window, it is put onto the atom stack. It can then be used for stack-based operations such as Center or Distance. This is the quickest way to center on a particular residue.

    When a residue is selected, it is highlighted and becomes the focus residue. Its information is listed in the bottom of the window in the Type and Name fields. Several residues can be highlighted, but only the last one is the focus residue: the one that is in the lower fields. Highlighted residues can be grouped together in a single group. An entire group can be moved as a unit after being selected (using the "Group" item in the right-mouse menu). A group number above 0 must be chosen, since 0 means ungroup. Before selecting a group, it may be wise to clear all selections to prevent residues that have scrolled off the list from being accidentally added.

    Residues may be deleted with the Delete button. They can be un-deleted at any time by hitting Delete again. The menu item Purge Deleted Residues from Model purges deleted residues for ever. You can delete an atom by highlighting it and then selecting Delete Atom. This is probably best used with caution, but it's especially nice to get rid of unwanted hydrogens. You can also edit the B-value and/or occupancy by changing the values and then pushing the replace button.

    The Go To button next to the residue name field allows you to center on a specified residue: you can either select the desired residue on the scrolling list or type its name in the name field (and if your model has multiple chains, the chain identifier in the "Chain Id:" field) before clicking on "Go To".

    The model number field at the top of the Model window mirrors the number on the Main window; it makes it easier to flip between models.

    The Insert button has a pull-down menu with a number of features. You can insert a new residue before and after the focus residue: First select the insertion point; then edit the name and type of the residue. All of the types in the dictionary will be listed in the pull-down menu at the end of the Type field. Then select Insert.Before or Insert.After. The new residue will appear in the center of the screen. Insert.Replace is similar, except the new residue is least-squares fit to the focus residue and the old residue is deleted. Thus, a replace can be undone by undeleting the old residue and deleting the new residue. "Replace and Fit" is similar to "Replace" except that after insertion, the new residue's side-chain is torsioned to best fit the electron density map selected in the Refine window. "Change to Next Confomer" cycles through the rotamers in the dictionary, an alternative to the 'c' key on the keyboard (see the section on Rotamers below). "Cut selected into Buffer", "Copy selected into buffer", "Paste buffer before", and "Paste buffer after" are used to cut and paste groups of residues; check the "Non-exclusive" checkbox so that you can select more than one residue at a time, then select your group of residues, then select "Cut" or "Copy". "Split Residue" splits a residue's side chain about a torsion to allow fitting multiple positions. A torsion must be selected first (i.e., put the residue in single residue fitting mode, and hit the number key of the CHI torsion angle to split about). The two halves of the side-chain will have A and B added to the atom name as per Protein Data Bank terminology. If you subsequently select "Residue" from the right-mouse menu, the atoms in only one of positions will be made current.

    The Insert menu also has a Pentamer pull-right menu. If it is grayed out, the pentamer information and programs have not been installed (see XFITPENTDIR under Environment Variables above). The pentamer option allows least-squares fitting a pentamer with one that has the closest geometry from a list of well-refined structures. The middle three (or first four or last four) residues can then be replaced with the pentamer residues. The only atoms that must be in the target pentamer are CA atoms.

    The quickest way to build a protein model is to place single CA atoms (type MRK in dict.pdb) in the density. Keep the CAs in order as much as possible, since their order matters for the pentamer fitting (see also Sort by Sequence Number below). Pick the first residue of 5 contiguous residues in the residue list and then select Insert.Pentamer.Best_fit_pentamer. A pentamer should appear as a separate model least-squares fit to the target residues. If it is acceptable, select Insert.Pentamer.Replace_middle_three to replace the new residues in your model. The side chains of the new residues will be whatever was in the structure database. You then replace these side-chains by picking the residue to be changed in the residue list, selecting the correct type with the little pull-down button by the Type field, and selecting Insert.Replace. The side-chain is then torsioned into its density.

    The Model.Sequence menu has the following items: Replace Name changes the name and chain ID of the selected residue to the ones in the Name and Chain ID fields. Renumber Chain renumbers the residues of the currently selected chain, using the number in the Name field for the N-terminus, and increasing by one until the C-terminus is reached. Assign Chain IDs changes the chain IDs of all of the residues in the selected chain to the one in the Chain ID field. Fix Chain Numbers finds the individual chains in the model and renumbers them. (This number is not output, but used by the program only. It should not be necessary to issue this command as operations that change the chains should do this already, but just in case...) Reverse Chain containing Selection reverses a chain from N to C termini, swapping the termini and reordering the residues in between. (It does not fix bonding of the peptides. This can be done on the Auto-fit menu, by Poly-Ala the chain followed by setting the sequence or by using the Pentamer function and replacing the main chains in successive overlapping pentamers.) Reverse Top 2 residues on Stack is a milder version of Reverse Chain. Sort by Sequence Number sorts the chains in the order indicated by the name of the N-terminal residue.


    Rotamer selection from the most common confomers is available. Pick the residue you want to replace, hit the c key to cycle through the confomers, then accept or reject. The confomers are presented you in order of their appearance in the residue dictionary; make your own dictionary if you want. Select show torsions from the main menu to monitor the action. You need the new dict.pdb distributed with XtalView version 3.1 for this to work.

    View Window

    This window is used for controlling the viewpoint and for building alternate representations of the model. At the top of the window are the viewpoint matrices at the time when the View button in the main window was selected. It does not update as the model is turned, as this would seriously impede performance. Instead, you must select the View button again to get the current matrices.

    The views can be saved and loaded from a file. The viewpoint is saved as script commands, which can be copied into a script. Also, the Load command actually just runs the script command on the file so that you can add other script commands to the viewpoint file if you wish.

    You can move to a specific x,y,z by entering these into the Translation field and selecting Transform. It is less likely that the rotation matrices can be successfully entered and produce a useful result, as errors will distort things severely. Note that the script commands for the rotation are the same as those used by the program MOLSCRIPT, by P. Kraulis. The translations are of the opposite sign.

    Stereo turns Split Stereo on and off. The stereo can be made either cross-eyed or wall-eyed with the angle slider. The separation can also be controlled. To change the separation, scale the Canvas window width.

    You can also select left- and right-eye-only views. These are used for making stereo slides for photography purposes. If hardware stereo is supported, then there will be a fourth selection available: Hardware. On SGIs this is done using Crystal Eyes or StereoVision glasses. As they do not work well with windows, xfit rearranges the windows to work best with these glasses.

    When the <Escape> key is hit, the window returns to its original position. You can then edit the model, load files, and return to stereo viewing again. The Toolbar and the Canvas menu are available in stereo, so that going in and out of stereo can be minimized. Picking is less reliable in hardware stereo due to perception problems; therefore, it is best done in less crowded views.

    Make Script and Edit Script are used for script commands (see above). Make Script generates a script that returns you to where you are. It will load models and maps and restore the viewpoint. Unfortunately, because the original order in which these operations are done makes a difference, the resulting script file may need to be edited in order to get back what you have. It provides a great starting point, though, for complicated figures. The biggest problem is that loading a model changes the screen center. All model loads should be done before viewpoint commands. The Edit Script window allows you to edit the script and rerun it. To save the script, use the <Menu> mouse button while in the Editing window and select File.Save_New.

    Below this are the controls for "Make vu" and for "Append to Model", which display the model using the selected characteristics. This is a very versatile and useful feature. Select which model you want to build from and between which residues. The default is to use all of the model. Then select one or more options. "Make vu" makes a vu object with the specified options, whereas "Append to Model" applies the options to the model itself. Most of the options can be used with either "Make vu" or "Append to Model", although some (H-bonds, VDW Surface, Unit Cell Box, Thermal Ellipse, Thermal Axes) can be used only with "Make vu". The first invocation of "Append to Model" removes everything from the displayed model except what the options explicitly include; subsequent clicks on "Append to Model" will cause lines to added or re-colored, but not deleted from the display. "Reset Model" causes the model to be re-displayed according to the default options. Get into the habit of clicking "Reset Model" before "Append to Model" whenever you want an option to have its intuitive behavior. (E.g., if "Show if inside radius" is checked", setting the radius to 10 Angstroms, clicking on clicking on "Append to Model", setting the radius to 5 Angstroms, clicking on "Reset Model", and then clicking on "Append to Model" will show you first a 10-Angstrom and then a 5-Angstrom radius; but if you omit "Reset Model", you will see a 10-Angstrom radius both times!)

    The syntax for setting an atom filter is a list of names separated by spaces, such as "C N CA O", which is the same as the mainchain option (actually mainchain also requires a peptide). An asterisk can be used as a wild card, meaning that the rest of the name does not matter; that is, C* matches C, CA, CB, CG1,..., CG* matches CG1, CG2,..., etc. The residue filter similarly takes a list of residues separated by spaces.

    In earlier versions of xfit, the model was never changed for viewing purposes. Instead, a vu object was built and the original model hidden if desired. (Since a vu contains only lines, not atoms, "Model Pick" had to be set to "All Models" in the Controls window to allow picking from the hidden model.) Editing the model with "Append to Model" is a superior approach, since it allows you to pick only what you can see. If you are using vu objects and want to have seven side chains, all different colors, then seven vu objects are built. Up to 200 vu objects can be built. Long lists of vu objects can be saved in a single file and read in as a single vu object later to overcome the 200-object limit.

    Mainchain, Sidechain, and Non-protein draw the normal bonds. "Link CAs" (which does a CA-trace) and Peptide Plane cause oher atoms to be linked. "H-bonds" draws potential hydrogen bonds, "VDW surface" shows the Van Der Waals dot surface for the current atoms, and "Unit Cell Box" draws the unit cell of the crystal. "Show if inside radius:" restricts the viewable part of the model to a sphere with radius in Angstroms specified by the slider. "Clip Lock" restricts visible atoms to those within the current clipping planes. (To do the same for maps, use the "Lock Clipping Planes" button in the Contour window.)

    "Thermal Axes" and "Thermal Ellipse" are for viewing anisotropic B's. They will also work with iotropic B'sl the program converts the B into the equivalent U matrix. With "Thermal Axes", you can see the direction and magnitudes of the thermal vibrations. With "Thermal Ellipse", a probability surface is calculated and made into a vu object. The percent probability is controlled by a slider near these two checkboxes. If no ellipse shows up for an atom, then its U values form a on-positive definite solution and it is ignored. This is fairly common in the beginning stages of an anisotropic refinement but if it doesn't go away it needs to be dealt with. SHELX also lists these atoms in its output. The thermal ellipsoids should change evenly and be correlated along bonded atoms. Using this option, you can quickly spot outliers with a little practice for the eye. It is instructive to see how large the 50% probability ellipse is for a water with a B-value of 100.

    The script command "buildvu" corresponds to these controls. However, if you use a script, you can edit your mistakes without starting over. You can edit the file, run it with "xfit file.script" to find any errors, fix them in the Edit Script window, and rerun the script. To save this, press the <Menu> mouse button while in the Script Editing window and use the Textpane menu.

    The other advantage of the script commands for building vu objects is that you can change the line width between objects. Although you can't see this on the screen, the different widths show up when you plot it. This is very useful for making black-and-white publication figures in which two objects must be clearly distinguished.

    Atoms may be colored one solid color (set in the "Colors" window), by atom type, by B-value, or by residue type; the last option uses a scheme based on Bob Fleterick's Shapely Colors.

    Errors Window

    The Errors window lists residues from a model that xfit's geometry analysis deems to be suspect. It may be accessed from three places: directly from the Main window (if you get to it that way, you can use the "Examine Active Model" button to compare the model to ideal geometry); from the Refine window; and from the View window via the "PhiPsi Plot" button. There is a button to deep-six an error by deleting the residue in question. If the residue is not a water then you are asked if you really want to do this. It can be undone on the Model Window by toggling the delete flag. There is also a Fit Error button to put the residue into fitting mode and let you fix the residue.

    Controls Window

    Several miscellaneous controls are located in this window:

    Mouse damping controls how far the model rotates with a mouse movement.

    There are three mouse event modes: Fast, Jerky, and Skip Contours. Fast assumes the picture can keep up with every mouse event and draws each one. If the computer is taking too long to draw each event, then the model may keep moving after the mouse has stopped. Jerky skips ahead to the latest event, ignoring earlier ones so that the picture "jerks." (This mode does not work well on some SGI machines, and changes with each OS version!) Skip Contours does just that if the picture gets behind, allowing smooth rotation to the desired view and then when the event queue is empty the contours are redrawn. Determining which mode to use depends upon the computer you are using, so some experimentation is in order.

    The checkbox, "Use InsightII Mouse", when checked, causes the mouse buttons to behave as they do with Biosym InsightII.

    The Pick mode defaults to only picking the active model. This allows picking of superimposed models by locking the others out. When in the pick all mode, the closest atom is picked. If two atoms are in the same position, the last one in the display list is chosen. The Pick mode is also controlled by a toggle in the Ridgelines window, which switches the Pick mode from Model to Ridgelines.

    Note: To pick symmetry-related edges, the mode must be All.

    The Symmetry Radius controls the size of the box searched for symmetry-related atoms. Making this very large will slow things considerably, since the volume increases as a power of three. The "Use Screen Radius as Symm Radius" option sets the symmetry radius to fill the entire screen: zoom to the area you want to and then generate the symmetry atoms.

    The Rocking Range and Rocking Rate all are controlled in this window. xfit uses a timer that is supposed to be machine-independent, but it actually isn't; therefore, the rocking rate is different on different machines.

    The Depth-cueing slider controls how thin the back lines are, relative to the front lines when plotting in the Depth-cued mode. It also controls the percent saturation of the back color to the front color when plotting in the Color mode.

    Contacts are also controlled in this pop-up. A contact is a dashed line drawn between two atoms with the distance shown in Ångstroms at the mid-point. You can turn on/off drawing contacts whenever the distance function is used. You can also enable contacts to be drawn for picked atoms. A maximum radius for this search can be set. The mode can be Off, all atoms within the specified radius (All), or only between atoms in a different residue (inter-residue). As the model is fit, these distances will update.

    Echoing of messages to the canvas is now under the control of the "Echo messages to screen" toggle in the Controls window. control for dynamic sliders

    Files Window

    When reading in a PDB file with multiple chains created by X-Plor, you will want to activate the "SegID->ChainID" checkbox. If you do not do this (or if you try to read such a PDB file in on the xfit command line), xfit will not recognize that the chains are distinct, so that, for example, clicking on a residue in the error list may take you to a residue of the same name in a different chain.

    If you have made some of the atoms invisible with the View window's "Append to Model" or with "Turn H's", you can write out only the visible atoms to a PDB file. In the Files window, tick the box "Save visible only" before using the "Save:" menu.

    Labels Window

    Labels can be controlled and edited in the Labels window. (The Controls window contains the control for labeling picked atoms or not.) For an arbitrary label, pick an atom near where you want the label to go and then pick the atom. The new label will show up at the bottom of the list in the Label window. Select the label in the label list. You can then edit the fields for the label string and its offsets in x and y; then select Replace. The offsets in x and y are pixels from the x,y,z coordinates of the label that are independent of the rotation matrix and the scale. To delete a label, select it in the list and click on Delete. To remove all labels, select the appropriate command in the main window.

    To edit a label, select it on the list, edit the field you wish to change, and then select Replace. New labels can be entered here. The current center can be popped and used for an arbitrary label. You can also set the label style and select the point size of the labels when plotted. All labels will have the same size. The pixel offset on x and y is useful for moving labels into clear space so they don't overlap other objects. When labels are plotted, a drop shadow is plotted around them to make them stand out if they do overlap other objects.

    A "contact distance" label changes to reflect the current distance as the model moves. It is not editable. See the section on "Controls Window" for more information.

    Color window

  • Pop up the Color window.
  • Select a color by clicking on it.
  • Select the correct object (if necessary).
  • Apply the color by clicking on the appropriate button. (This sets the object to the current color.)

  • Apply the color by clicking on the appropriate button. (This sets the object to There are two places where the option color C* only is given. This means that only the carbon atoms are colored and the others are colored by atom type in the usual way (i.e., N is blue, O is red, H is white, Fe is brown, S is yellow). In addition, in the View window the option color-by-B-value is given. In this case, the coloring is according to B-value in the same way as described for normalized B-values in the section on colorbyB.

    In the Color window you will see 4 shades of each color. This lets you see the effect of depth-cueing on the color. On 8-bit machines these are the depth-cueing colors. A line is drawn in 4 different intensities, depending upon its average z-value. On 24-bit machines the line is depth-cued by interpolating from the front to back. Colors.dat contains 4 intensities for each color. For instance, for red there are four entries: red, red1, red2, and red3.

    To change the depth-cueing, change the four colors: make red the foreground and red4 the color of the farthest point. This is probably best done by a computer program from a file containing just one entry for each color. Each color display works best with a different amount of depth-cueing.

    PostScript coloring is always done in terms of RGB triples, and the color for the foreground is taken from colors.dat. Depth-cueing is done by multiplying the RGB values by a scale factor from 0.25 to 1. The value 0.25 can be changed in the Controls window. The author has found that different color PostScript devices work best with a different value for the minimum. For instance, the dicomed slide maker needs a value of about 0.1 and the QMS-100 color printer works better with about 0.3.

    Least-Squares Fit window

    This can be used to superimpose two models or portions of the models, as a comparison tool, or to speed up fitting. It "roughs in" the model using edited residues with only CA or CA and CB residues (put these in the dictionary with a type such as CBA). Then, standard protein pieces such as alpha-helices, beta-sheets, tight-turns, etc., are read in as extra models (up to 49 of these, plus your working model), and then least-squares-fit to the markers. Overlaps are deleted and then read out and concatenated to form the whole molecule. The initial geometry will be better, giving a faster refinement.

    To fit a range of residues, pick the end atoms, pick "Expand Top 2" on the main window and then select "Residues" from the Fit menu.

    More complicated fittings that use unconnected segments can be done with the program pdbfit instead, and then loaded into xfit.

    Least-Squares Plane - This command calculates a least-squares plane for all the atoms on the stack. To use it, first clear the stack on the main window and then click on all the atoms to be in the plane. Then issue the command. To get the distance from this plane for any atom, click on the atom to place it in the stack and then issue the Distance From Plane command.

    FFT window

    xfit includes a reworked FFT routine from Lynn Ten Eyck (SDSC) that provides a fast way to calculate electron density and structure factors. The electron density calculation is done with the FFT pop-up, and structure factors are calculated on the sfcalc pop-up. The FFT pop-up can be used to calculate electron density directly from structure factors using coefficients such as Fo, Fc, Fo-Fc, 2Fo-Fc, Fo*fom, 3Fo-2Fc, 5Fo-3Fc, 2mFo-DFc and mFo-Fc. It is usually faster than reading a precalculated map file and lets you redefine the grid and the resolution range at any time. The same phase file can be used to make both an Fo-Fc and a 2Fo-Fc map. It also saves a lot of disk space. Say good-bye to map files! The whole unit cell is available, so there is no need to worry about map boundaries.

    Two map that use Sigma-A coefficients are available: 2mFo-DFc and mFo-Fc. These map types calculate sigma-A coefficients on the fly from Fo and Fc. Thus if you do an omit map calculation the omit map made with mFo-DFc will use the Fc-omit values. We have found the Sigma-A maps better at reducing phase bias than other map types. Using the shake option and sigma-A maps is about as good as it comes in removing phase bias. If you have figure-of-merits in the Fc column then the program will not do the sigma-A calculation as this would be an error. If you have a model you can replace the figure-of-merits with Fc's by using the Calculate All and Scale button on the SfCalc window and then you can use the sigma-A maps.

    Maps may be represented either in the straightforward way where every element contains the density at one point in space, or using a spectral spline approximation to the continuous function giving the density. The spline option makes all references to electron density slower, but makes density interpolation very accurate, allowing accurate contouring on a different grid without re-FFTing, and better-informed refinement. (Large Translation Search is not compatible with the spline option.) To use the spline-based maps, set Splines: to quadratic or cubic in the FFT window (cubic is slower and more accurate than quadratic). The Use Grid: option in the Contour window can then be set to Orthogonal, allowing contour grid spacing to be any desired value in Ångstroms, independent of the FFT grid.

    Note: Make sure the correct crystal is specified beforehand! If it isn't, reload the phase file after correcting.

    If the "Shake to reduce phase bias" option in the sfcalc menu is enabled, the model is "shaken" by a random number between -dmin/6 and +dmin/6, which is added to x, y, and z of each atom as it is sent to the structure factor calculator (the model is left as is). The effect of this is to help remove phase bias built in by overzealous refinement.

    Structure factors can also be calculated by FFT. In this case, the only information needed to make maps are the Fos and the coordinates of the model. Make up a phase file with h k l Fo 0.0 0.0 and read this in (i.e., use the "fake phs" option in xprepfin). Make sure the correct crystal is selected before reading. Then use the sfcalc window and select calculate all and scale. You can now make omit maps and update phases.

    There are two ways to calculate structure factors: FFT and summation. FFT is fast and introduces an error of about 1% typically. In general, this is the way to go. The only time the summation is faster is if you are doing less than about 4 residues.

    The FFT is done in two parts: first, a model of the electron density is built from the atom coordinates and their structure factors; then this map is inverted by FFT. The FFT is very fast, and for the entire model the rho building step takes the longest. However, for a single residue the rho building is very quick.

    The only instances in which summation is needed are when extreme accuracy is needed (given the error in our coordinates, we can't see when this would be needed), and if there isn't enough memory to build the entire unit cell's rho.

    Note: In centered space groups it is common to not calculate the centered symmetry operations to save computer time. If this is done, Fc will be lower than absolute scale. For instance, in C2 the Fc will be half of its correct value. Use the full symmetry operators, as is the case if you use the crystal editor with xtalmgr.

    Omit Maps on the Fly

    To make an omit map, select the atoms to be omitted (see "How to Select") and then select the omit current atoms option in the Structure Factor (sfcalc) window. Structure factors are calculated for the currently selected atoms and subtracted from the model structure factors. Then use FFT to make either an Fo map or a 2Fo-Fc map. This assumes that you have read in some phases and that Fc has been previously calculated on an absolute scale (Fo is scaled to Fc). This can be done using calculate all and scale.

    Note: Partial models (such as missing residues or waters) cannot be used to make omit maps with Fo-Fc or 2Fo-Fc maps because the relative scale of Fo to Fc is incorrect. Instead, use Fo maps. This is also true of models that still have a large amount of error, in which Fc is still inaccurate (i.e., R-factors above about 0.25).

    Updating Phases on the Fly

    As you move the model, its phases change because they are calculated from the atom positions. You can either re-calculate the phases from all of the model using sfcalc.calculate_all_and_scale, or you can update just the portion being fit (which is much faster). In this case, after you move the currently selected atoms you can select sfcalc.update_current and then re-FFT the map. Update all subtracts the old position from the phases and then adds the new position.

    As the residue is moved, you can calculate the corresponding map and compare it. For example, if there are two likely positions for a side chain you can move it to both positions and see which matches its corresponding map best. When you are finished fitting, select update current just before applying the fit to match the map.

    SfCalc window

    Difference Map Gradient

    At the bottom of the sfcalc pop-up is a section used for calculating the gradient of the difference density at an atom. This is represented as an arrow in the direction of the gradient scaled to its steepness or magnitude. It shows the direction an atom will move in the first cycle of a crystallographic refinement.

    The command implements the equations in Stout and Jensen [2nd ed., p. 349]. It is useful for such things as analyzing mutants to look for the direction of movements and to look for concerted movements of groups of atoms. The command works on the currently selected model. It uses a slow summation method if res<3 and uses FFT if res>3, so it can take quite a long time for a large number of atoms. You must first load some phases. The command works on the map currently selected at the top of the window. Set the Deriv vu number to a free vu object. The Sign of Delta is usually Fo-Fc, but to reverse the direction of the arrows, select Fc-Fo. The Scale Arrows x 100 slider sets an arbitrary scale for the length of the arrows. To start the calculation, select the Derivatives of Current Atoms button.

    Refine Window

    The Refine window is split into two parts. The upper part is for real-space refinement and the lower part is geometry refinement. In real space refinement, you select the map to refine the active model against. Real space refinement operates on the currently selected residues, whereas geometry refinement uses the "Start at Residue" and "End at Residue" fields in the Refine window.

    For real space refinement, you can can select any of Rotomer, Torsion, Rotational, Translational, or Large Translational search. Rotomer search refines the selected residues using a general torsion angle search of the sidechains, whereas Torsion Search refines only the currently selected torsion angle (the torsion must be already selected or nothing will happen). Large Translation Search will translate the current fragment to anywhere in the visible contoured density, by superimposing the fragment's center of mass on the center of the density after subtracting the density of the atoms not in the fragment. Because this center is only an approximation of the desired position, Xfit follows the large translation search with a standard translation search (which does a brute-force search of nearby positions for the best density correlation). Three functions of density can be searched on: "Atom centers" (maximizes the sum of electron density at each atom center), "Fo * Fc" (maximizes the product of density from the map and density calculated from the atoms), and "Fo - Fc" (minimizes the difference). Because "Fo * Fc" and "Fo - Fc" examine every grid point where density is, "Atom centers" is by far the fastest among the three fuctions. The checkbox "Update R-density while fitting" causes the rho value to be printed in the left footer of the canvas. The search works well for torsion searches with only one axis (i.e., Phe works well but Arg does not) to search. Translate and Rotate often try to move into density that is connected but already belongs to another atom (i.e., the neighboring residue) and work best for groups of residues.

    Geometry refinement (minimization) can be done in two ways. The entire model can be refined by simply selecting Refine Active Model. Be sure to save the model first, since this cannot be undone (or start xfit with -save to set the autosave mode). In each refinement cycle, minimization is done on the bonds, angles, planes, torsions, and (if applicable) the map. Sliders control the weight accorded each of these.

    The ideal bond distance and angles are taken from the residues in the dictionary file (see below) by using them as guides. This is done to allow different ideal lengths for different refinement packages. Also, this allows one to have all hydrogens, no hydrogens, or partial hydrogens. The residues in the dictionary should be refined by the refinement program you are using. This will then maximize the agreement between xfit and the refinement program as to correct geometry.

    Planes are specified in the geometry file with the PDB extension record PLANE. This specifies the residue type and the atom types in the plane. For example:


    Since planes are supposed to be flat, it is not necessary to specify the ideal value.

    Connectivity is assessed by a variety of criteria. First, if in the original PDB file a TER record was found, this marks a C-terminus and no attempt will be made to form a peptide bond. Second, if the chain id letter changed while scanning the file, this also marks a C-terminus. Third, if the residues have recognizable names such as an amino acid (e.g., ALA, Ala, ala, or A), then a search will be made for the proper atom types for a peptide bond and plane (CA, C, O, +CA, +N, [+H]). If the N and C atom are within 5.0 Å, a peptide bond, angles and plane are formed.

    The algorithm for drawing lines representing bonds is different and less stringent in order to speed up rebuilding of lines for display purposes. If incorrect bonds are drawn on the screen, they will not show up in the refinement.

    The second refinement method is to refine a portion of the model. Click on (or select) an atom in the Model window and put two residues on the stack. Now use each of the pop buttons to get these two residues in the Start At and End At fields (you cannot type these values in). Then select Set Up Refinement Residues and the selected residues will be highlighted on the screen. When you push Refine, a round of refinement will be done. If you select the Refine while Fitting option, then the selected portion will be refined in the background while you fit. You can then select a residue for fitting within the segment being refined, and as you move it around, the rest of the segment will follow along and the geometry will anneal as you fit.


    The dictionary file is simply a PDB file with at least one example of each residue. If the environment variable XFITDICT is set, then this file is loaded upon start-up as the dictionary. The dictionary can also be loaded and appended to in the Files window. This is not used as a geometry file. New residues are found by finding the first residue in the dictionary that has the same name. If there are multiple residues of the same name in the dictionary, they are interpreted as confomers in decreasing order of prevalence. When a residue is replaced, a residue of the same new type is found in the dictionary and least-squares-fit to the old one. The standard dictionary is in $XTALVIEWHOME/data/dict.pdb. The dictionary can be appended to upon loading, or replaced. The append mode allows you to add a prosthetic group without having to mess up the standard dictionary. The first residue in the dictionary is used if there are multiple copies. All of the unique residues in the dictionary appear in the Model window from a pull-down menu button to the right of the residue type field. Selecting one of these names puts this value in the residue type field and can then be accessed with the insert commands.

    A load dictionary feature has been added that allows changing the dictionary without having to remember its name and going to the file window. You can add one of the standard dictionaries: · No H dictionary · Polar H dictionary as in XPLOR · All H dictionary If the conformer function is not working you probably have a dictionary that doesn't match the residue. You can quickly remedy this on the model window now.

    Waters Window

    The Waters Window used to automatically hydrate maps and rename waters according to another model.

    For automatic hydration, first you need a map to add waters to, and a model to which the waters will be appended. The map should be a difference map; other map types can be used but they will take a lot longer to search. The user sets two parameters: the minimum density to consider and the maximum number of waters to add. The water addition algorithm is as follows. First all the peaks in the map in one asymmetric unit are found. These are then sorted by size, largest first. The program looks at each peak in turn and determines if it is not overlapping with the current model or with a symmetry mate of the current model. It then considers if the peak is close enough to the model to hydrogen bond. If all these criteria are met, then a water is added at the end of the model. The added water is then real-space refined. This continues until either the peak list is exhausted or the maximum number of waters to add is reached.

    The "Renumber Waters" button renames the waters in the active model according to the waters in another model. If the active model contains a water close to one in the second model, then the active model water is renamed to match. After all the waters have been looked at, any waters that didn't match are renamed sequentially from the name of the last match found. Use this command to make the names of waters in two models match. This is especially useful for mutant structures. Assume you have just finished adding waters to a mutant protein structure. Load the wild-type model. Make the mutant the active model, and set the Rename As In # field to the number of the wild-type model and issue the command.



    The current canvas can be plotted to a Postscript file or printer using the PostScript Plot winodw (accessed from the Plot menu in the Main window). Enter the name of the printer or file and then select one of the two options in the pull-down menu using the <Menu> mouse button on the Plot button.

    A number of printing options can be set in the Properties window, including Portrait and Landscape. Additional information can be plotted as a second page using the Stats On/Off option. This will add a second page with the viewpoint, the names of the objects used, and the map levels.

    You can select to plot in color mode, black and white, and black and white with depth cueing. In the depth-cueing mode, the width of the line indicates the distance from front to back (objects in back are thinner).

    Color is very useful for making slides that can be sent to a commercial slide service. The advantage is that the exposure is always right and the resolution is usually much higher than on the screen. The disadvantage is that the screen colors and the slide colors may differ substantially. Blue shows up especially dark on slides, so use cyan instead.

    The PostScript file can be edited if desired: it is a list of PostScript commands set up for easy editing. Each object is bracketed by BEGIN type # name and END. You search for each object by looking for the string BEGIN. The most commonly edited field is the line width. You can also edit the SetGray Level field, in which 0 is black, 1 is white, and 0.5 is 50% gray. The labels are at the end of the file.

    It is common to want to move labels around a bit to prevent them from overwriting other objects. Objects in the file are drawn starting from the beginning of the file and going to the end. Thus, a later object overwrites an earlier one. You can change the order in the file if you wish. Labels have a shadow drawn around them so they will be readable even if they fall on an object of the same color.

    The PostScript Plot menu also contains some items useful for photographing the screen: toggles for the ruler, screen cross, and gnomon, and a button for entering photograph mode, in which the canvas is expanded to fill the screen with the borders hidden. The p key is equivalent to this button, and must be used to exit photograph mode. To make stereo photographs, set Stereo to Left in the View menu, then hit p first for the left photo, then for the right view, then to leave photo mode.

    Raster3D Interface

    The second item in the Main Window's Plot menu leads to the Raster3D window. Raster3D is a software package for generating photorealistic images, written originally by David Bacon and now maintained by Ethan Merritt; see . The output generated when the "Send to Raster3D" button is pressed is the input to the Raster3D program "render". The output panel selects the destination for this; this may be a file or command whose name is typed in the top panel, or one of two modes that immediately draw the image on the screen, "xv" and "SGI" (the latter using the SGI-specific program "show"). The size of the image produced may either be "Full Screen" or "same as canvas" (since the xfit canvas is resizable, this allows any size less than full-screen). "Ball & Stick" is the most frequently used picture type; by default, it produces space-filling models (the atom radius sliders is at 115% of CPK, so that the spheres include unified hydrogens). Of course, with a space-filling you won't be able to see much electron density; you should make the atom radius considerably smaller if you actually want a ball-and-stick model. "Distance" controls the perspective. It is the distance of the eye(s) from the center of the picture; the default value, 4.0, makes that distance 4 times the narrow dimension of the described scene. A very large value of Distance will yield a scene with essentially no parallax or perspective. Sliders control the size of the various entities on the xfit screen that are sent to Raster3D: atoms, bonds, maps, vu objects, contact distances, and Van de Waals dots. The primary light source defaults to right shoulder but can be set to any of eight other positions; finer control for this and many other Raster3D parameters can be achieved by editing the Raster3D input file between running xfit and running render. The contribution of the secondary (straight-on) light source may be anywhere between 0% and 100%; making it 100% causes the entire scene to be evenly lit. You may highlight a specific atom by making it the top atom on the xfit stack and then clicking on "Pop Glow Atom"; the light source then appears to be within that atom, and "Glow Radius" controls how far it shines. Setting the Rendering Mode to "Draft" allows faster computation of the image for a quick confirmation of the image, but not all users may need to use it, since even "Anti-aliased" rendering only takes a couple of minutes on many computers. Setting "Header records" to "No" or "Header only" will help in production of composite images (some users may want to combine output from other Raster3D front-ends, such as MolScript).

    Script Commands

    xfit can accept commands from a script file. The script commands can substitute for many of the interactive operations, and some operations can only be done from the script. All script commands can also be placed in an .xfitrc file. On startup, xfit looks for an .xfitrc fie in the current directory, in the user's home directory, and in $XTALVIEWHOME/data in that order, and automatically executes its commands.One use of the script is to return to a given view. The Save View command writes a script file that when run returns xfit to a given viewpoint. Load View is just another method of running this script.

    Another common use is to build complex figures with many parts. The script also gives more control over line-widths, allowing different widths to be set for each object. There are also some animation commands such as roty that rotate the view around y.

    The Script window can be accessed from view.edit_script. Scripts can be run and edited by loading them into the Script window. The script can be altered and then re-run to see the effect of the edits. Every time the script is run, it is first saved and the old script moved to file.script% (the file name with a % added). Scripts can also be loaded from the command line if they have the extension .script or .vp (for viewpoint), at which time they are run. The mouse's <Menu> button brings up a menu that allows loading and saving the contents of the script window to files.

    For example, the command xfit my.pdb save.vp my.map will load the PDB file, switch to the new viewpoint in save.vp, and load and contour the map. The size and location of the canvas can also be saved. A line starting with # is interpreted as a comment.

    The script command language is being expanded to enable saving of more and more of the settings in xfit; the list of script commands in this section may not always be up-to-date. For a complete list of the available script commands to save xfit settings, make a script (click on the "Make Script..." button in the View Window).


    On startup, xfit first reads the $XTALVIEWHOME/data/.xfitrc . It then looks for an .xfitrc file in the current directory, and if it can't find it there, in the user's home directory. The .xfitrc files can contain any command that a script can, plus two additional commands:

    XglInstalled on

    indicates that on SUN workstations, the XGL library is installed. The Accelerated canvas will not be available on SUNs unless this is present.

    AutoSave on

    causes the active model to be automatically written to a back-up file whenever the user changes it -- equiavalent to the "-save" flag on the xfit command line.

    General commands

    crystal value
    loadpdb modelnumber file
    loadpdbcenter modelnumber file
    loadmap mapnumber file

    load fsfour format maps

    loadmap phases mapnumber file

    load map phases (follow with fftapply)

    loadvu file
    loadridge file
    plottofilecolor file
    plottofileb&w file
    plottofileb&wdepthcued file
    plottoprintercolor printer
    plottoprinterb&w printer
    plottoprinterb&wdepthcued printer

    Object building commands

    color value

    value is either the xfit number or a name, e.g., yellow is 56 or "yellow". This sets the current color. buildvu uses the current color to paint its lines, therefore set the color first.

    colormodel modelnumber

    model modelnumber is recolored to current color

    colormodelatom modelnumber

    as above, except that atoms are colored by atom type except C* atoms, which are set to current color

    vulinewidth value

    sets the line width in plotted output for all subsequent buildvu commands

    buildvu key modelnumber vunumber first_res last_res chainid atomfilter

    use * to indicate any

    atomfilter should be separated by commas (e.g., "CA,CB,C,N,O")

    key = one of:

    side = protein sidechains

    main = protein mainchain

    other = non-protein

    all = side, main, and other

    link = link CAs

    peptide = peptide planes

    hbond = H-bonds

    examples: to build the backbone of model 1 and show 2 key residues:

            color red

    Buildvu link 1 1 * * * * links CAs of model 1

    color green

    Buildvu side 1 2 18 18 * * side chain of residue 18 of model 1

    Buildvu side 1 3 218 218 * * side chain of residue 218 in green

    Viewpoint transformation commands

    zoom value

    frontclip value

    backclip value

    translate x y z

    rotation vxx vxy vxz vyx vyy vyz vzx vzy vzz

    the way to get this is view.save to a file and then read in the file to the script editor


    the point of view commands don't take affect until transform is given so that all transformations are applied at once

    rotx value

    roty value

    rotz value

    These take effect immediately - used to make "movies".

    stereo on

    stereo off

    canvasrect left top width height

    This sets the position and size of the canvas window. The first two set the position of the upper left corner of the window and the next two set the width and height. The units are pixels.


    The command to set any of the following toggles is the toggle name followed by "on" or "off":





















    Show and hide objects

    showmap mapnumber

    hidemap mapnumber

    showmodel modelnumber

    hidemodel modelnumber

    showvu vunumber

    hidevu vunumber

    bond modelnumber1 resid1 atomid1 chainid1 modelnumber2 resid2 atomid2 chainid2

    draws a line between two atoms. chainid can be *

    Atom labeling commands:

    labelpoints value

    sets the point size of label in plotted output

    labelstyle value

    sets the label style according to:

    0 = GLU 100 CA

    1 = GLU 100

    2 = GLU

    3 = 100 GLU CA

    4 = 100 GLU

    5 = 100

    6 = CA

    7 = none

    atomlabel modelnumber resid atomid chainid

    forms a label of the type set by labelstyle (default 0)

    Map contouring commands:

    maptocontour mapnumber

    sets the map to contour for all subsequent commands

    a map load will overwrite

    contourlevels value

    levels are turned on and off by adding numbers as follows

    1= level 1

    2= level 2

    4= level 3

    8= level 4

    16=level 5

    thus to turn on levels 1 and 3 only is 1 + 4 = 5.

    contour1level value

    contour2level value

    contour3level value

    contour4level value

    contour5level value

    contour level 5 at value

    contourradius value

    contourcolor value

    set level value of the current map to the current color


    contours current map at current center

    FFT commands:

    resmin value

    resmax value

    coefficients value

    Value is one of the following:











    fftnumber mapnumber

    fftnx value

    fftny value

    fftnz value


    Example 1

    # This script was used to make two electron density maps with and without
    # figure of merit weighting to illustrate the difference
    crystal cvccp
    # Make the model thicker than the map to aid in distinguishing them.
    maplinewidth 0.7
    modellinewidth 3.0
    loadpdb 1 cvccp.topdb.pdb
    # The viewpoint lines are from the save viewpoint option.
    translation 24.965 34.205 68.649
    rotation 0.6916 -0.3000 0.6570 0.6543 0.6455 -0.3941 -0.3059 0.7024 0.6427
    zoom 31.10
    frontclip 4.60
    backclip -3.30
    stereo on
    # Load the map phases and transform.
    loadmapphases 1 cvccp.mir.phs
    resmin 3.0
    coefficients Fo
    # Set the contour options and contour the map.
    contourlevels 1
    contour1level 50
    contourradius 10
    plottofileb&w mir.fo.ps
    # Change the coefficients of the FFT and compute a second map.
    coefficients Fo*fom
    resmin 3.0
    contourlevels 1
    contour1level 50
    contourradius 10
    contourmap 1
    plottofileb&w mir.fofom.ps

    Example 2

    # This example builds up vu objects. A backbone of the A chain is built
    # and then particular side chains are displayed and labeled. If a mistake
    # is made it is much easier to edit the script than to start over in 
    # interactive mode.
    # Also the script can be saved to re-make the figure at a later time.
    stereo on
    loadpdb 1 cvccp.pdb
    labelstyle 1
    hidemodel 1
    color 56
    vulinewidth 2.0
    buildvu side 1 1 * * A *
    buildvu main 1 2 * * A *
    buildvu other 1 3 * * A *
    vulinewidth 0.9
    buildvu side 1 4 * * B *
    buildvu main 1 5 * * B *
    buildvu other 1 6 * * B *
    atomlabel 1 16 CG A
    atomlabel 1 16 CG B
    atomlabel 1 18 CB A
    atomlabel 1 18 CG B
    atomlabel 1 132 C1A A
    atomlabel 1 132 C1C B
    atomlabel 1 21 CD1 B
    atomlabel 1 21 CZ3 A
    translation 30.810 34.796 60.196
    rotation 0.8504 -0.5256 -0.0256 0.5256 0.8507 -0.0075 0.0257 -0.0071 0.9996
    zoom 19.8
    frontclip 2.60
    backclip -8.10


    xfit uses dynamic memory allocation for virtually everything. The only limits are the size of memory available in your machine (including swap space) and the largest number representable by an integer on your machine. If you get "out of memory" or "cannot allocate" errors, close all unused windows. Every open window takes up memory. Next, re-read over objects that are not being used instead of creating new ones and hiding the old ones. Re-FFTing a map with a coarser grid can free up a lot of memory.

    If performance becomes sluggish, suggesting swapping (often you can hear your swap disk chuckling merrily away), then more RAM may be the answer. The cheapest way to speed up your workstation may be to invest in more memory. The author gets good performance with 32 Mb. Less than 16 Mb is not recommended. If you are calculating structure factors by FFT, then at least 32 Mb is needed. Most workstations are set up with small swap spaces, which becomes a liability later. If you have a choice, set up at least a 100 Mb swap space.

    More on Color

    It is advisable to modify only the color shades in ./colors.dat. For instance, red may be modified to add some white. It is possible to customize the colors completely if you have a minimal knowledge of the C language, rewrite colors.h and ./colors.dat, and then recompile. The colors occur in groups of 4, which are used for depth-cueing on 8-bit color systems. To change to degree of depth cueing from front to back, it is possible to change ./colors.dat to give more or less saturation.

    Importing Other File Formats

    vu files Any arbitrary line information can be loaded with a vu file. The format is lines of:

    x1 y1 y2 x2 y2 z2 color

    where x1 y1 z1 and x2 y2 z2 are the end points of a line and color is either an integer to a corresponding entry in colors.dat (see the footer message in the Color window) or an ASCII name such as red, yellow green, or white.

    Hint: break long lines into short segments so that they will not be completely clipped when the viewport is small. A # as the first character in a line is interpreted as a comment.

    MS surface file (.surf) Surf files can be converted to .vu files with awk:

    awk '{print $5,$6,$7,$5,$6,$7, "white"}' file.srf > file.vu

    This command prints the 5th, 6th, and 7th fields of the surface file twice and adds a color. Since the beginning and end of the vector in the vu file are the same, a dot will draw the size of a single pixel at the position of the surface point, making a "dot surface."

    Other 3D Arrays Arbitrary 3D arrays can be loaded into xfit by reformatting them into a map file. These can then be contoured as if they were electron-density maps. A corresponding crystal entry will be needed. To write this array, you will need to use the information in Chapter 4, "Programming XtalView." One limitation is that the map is assumed to start at 0,0,0 and extend for one cell edge in each direction. This may mean making an array bigger than is needed and padding it with 0s.

    PDB Format Extensions

    The extensions to the PDB format use a new keyword as follows.


    PLANE res_type number_in_plane atom_name1 atom_name2 ...

    For example:


    This specifies a group of atoms to be restrained in a plane. The maximum number of atoms in a single plane is 20. If you need more, then use multiple overlapping planes. For convenience the PLANE entry is usually put next to the corresponding residue entry but this is not necessary. An atom name with a leading plus sign means the next residue and a leading minus sign references the previous residue. Thus a peptide plane is specified as:

    PLANE PEP 6 CA C O +N +H +CA


    SYNONYM res_type atom1 atom2

    For example:


    This equivalences two residue names so that you can use either one in the PDB file. The most common example is ILE where CD is often called CD1. In this way you can use either name and not have a conflict with the xfit dictionary.


    TORSION res_type angle_id atom1 atom2 atom3 atom4

    For example:


    This specifies a 4-atom torsion. These are not restrained but are used for identifying torsions in residues for fitting purposes. Note the use of a trailing plus or minus sign to indicate the next and previous residue, respectively.

    All bond and angle information is derived from the coordinates of the residue in standard PDB format. If you have a new cofactor you would generate an ideal example (in a program such as Builder) and then write this out in PDB format, append it to the dictionary as described above. Then add any PLANEs. Xfit recognizes CHI1-CHI5 as special and assigns these to the keys 1-5. They don't have to be real CHIs, so you can specify torsions in the cofactor to be CHI1-5 as you wish and take advantage of the shortcut key. Or you can do torsions by picking two atoms as described elsewhere in the fitting section.


    xfit v3.7 was designed by Duncan McRee and Mark Israel. Alex Shaw is responsible for several of the xfit modules, including the GX modules, the PHIGS modules, the AVS interface, and converting the UNC GRINCH code to work with xfit. The FFT library was supplied by Lynn Ten Eyck, as were the hierarchical molecule data structures, which are responsible for much of xfit's utility. The matrix routines for rotating the screen and the dialbox code were borrowed from FLEX, written by Mike Pique. A number of users have braved many segmentation faults in debugging this code, and the author thanks them for their patience. We want to thank Fred Brooks for letting us use the University of North Carolina's ridgeline technology. Many of the best ideas for features and options came from other programs, such as Alwyn Jones' O and Frodo, and from our loyal users. We also want to thank Marieke Thayer for her many hours of testing and verification, and Ken Steube and Jane Kwon for managing the CCMS help desk and their efforts in porting and maintaining XtalView.