README.flipkins Home Page: Richardsons' Laboratory J. Michael Word - 5/2001



Reduce is a program which adds hydrogen atoms to a Protein DataBank (PDB) format coordinate file. For some hydrogens, a conformational search is performed to determine the optimal hydrogen position. When Reduce is run with the -build and -flip options, this conformational search includes flips of Asn, Gln and His sidechains. You can examine the choices the program Reduce makes when it decides to flip N/Q/ or H sidechains by using the perl script described here to build an animated kinemage, including PROBE contact dots and views of each Asn, Gln or His sidechain.


The flipkins script to make the kinemages is found at:    our website

Contents Of download package:
README.flipkins.txt      this document
flipkin    perl script to create animated NQ or H kinemage

These scripts are designed to be used on a UNIX computer and require perl and several other general UNIX shell programming utilities.

NB: We recommend that you use the perl script for flipkins; but for those of you who do not have perl installed, the older version of flipkins which requires awk is still available from our FTP site. The components of that package is listed at the end of this page.

Un-pack the contents of the tar file and go into the sub-directory the tar creates:

tar xvf flipkinscripts.tar
cd flipkinscripts

Either the flipkinscripts sub-directory needs to be in your command path or you need to move the script to some directory which is. Check that the first line of flipkin is pointing to the location of perl at your installation (it points at /usr/bin/perl originally). Also check that the script is executable.

You may also need the latest versions of Mage, Prekin, Probe and Reduce. Look on our web site and follow the instructions for downloading.



First use Reduce to add hydrogens to the pdb file (e.g. 1xyz):

reduce -build 1xyz >1xyzH

Then, using the Reduce-modified pdb files, create the animated kinemages. For the Asn and Gln residues:

flipkin 1xyzH > 1xyzNQflip.kin

For the His residues:

flipkin -h 1xyzH > 1xyzHflip.kin

Finally, either .kin file can be viewed with Mage:

mage 1xyzNQflip.kin


For each N,Q or H sidechain, the scripts analyzed the header of the the original pdb file REDUCE worked on, generating a command telling Reduce to re-build the hydrogens with these particular sidechains in the OPPOSITE orientation from what the program did the first time. It would be even better if we could do this for each N,Q or H one at a time but, to keep it manageable, we do all the N and Q residues at once or all the H residues at once.

With the two versions of the Reduce output, the scripts build a kinemage of the structure, animating all the adjustable sidechains. For each flippable residue, Probe has added small-probe contact dots to show the atomic interactions. This is basically the same information Reduce used to determine whether or not to flip a sidechain. By default, there is a slight penalty for flipping a sidechain, controlled by the Reduce -penalty#.# option. (To learn more about the options in Reduce, type: reduce -help)

Separate views have been pre-calculated for each N,Q or H sidechain. Pay particular attention to any *'s in the view identifier. The asterisk means that this sidechain was flipped by Reduce in the first step (to produce in our example: 1xyzH). Analyzing the header of the Reduce output and looking at the animations for *'ed residues may help you understand the choice Reduce made to flip the sidechain.

Other Flags

Several flags have been added to control the creation of the 'alternative' or 'flipped' pdbH file with reduce. The flag -v tells reduce to be verbose, to show what it is doing. The flag -limit# limits the number of permutations which reduce searches when optimizing the hydrogen position (eg. -limit500 will leave the orientation in the default orientaiton if 500 or more permutations must be examined).

The flag -fix filename passes in a file containing records to fix the orientation of groups. You can use this to break up groups which take time to optimize by setting one or more groups whose orientation has been determined by inspection. Since flipkins will already fix the orientations of singlets which are not Asn/Gln or His, you only need this for situations where there is a big clique containing an Asn/Gln or His (depending on which you are examining) which will still be too big when the N,Q or H groups have been re-oriented.


The first line of the new perl version of flipkin will probably have to be modified to reflect the location of perl at your installation.

Before they can be run, the programs and scripts all need to be made executable if they are not already (chmod +x ...) and need to be put in a directory listed in your PATH environmental variable. If you aren't sure, ask your UNIX system manager where you should put these executable programs.

Depending on the source of the coordinates, you may also need to convert non-standard atom names to PDB standard. A utility called PDBCNS may be useful (on our ftp site).

Further information

Reduce and the scripts to create these kinemages were developed by Mike Word at Duke University in the laboratory of David and Jane Richardson. Reduce is described in:
Word, et. al. (1999) Asparagine and Glutamine: Using Hydrogen Atom Contacts in the Choice of Side-chain Amide Orientation, J. Mol. Biol. 285, 1733-1747.
Probe, which generates small-probe contact dots, was also written by Mike Word. Prekin and Mage, which help create and display these structures, were written by David Richardson.

J. Michael Word or
David C. Richardson
Biochemistry Department
Duke University
Durham, NC USA 27710

Awk version specifics

Components of the old flipkins scripts (awk version)
flipNQkin    script to create animated Asn/Gln kinemage
flipHkin    script to create animated His kinemage
mkNQflip    utility script used by flipNQkin
mkHISflip    utility script used by flipHkin
qkinNQa    utility script used by flipNQkin
qkinHa    utility script used by flipHkin
viewNQf    utility script used by qkinNQa
viewHf    utility script used by qkinHa

NB: For those using the old awk versions of the scripts: some variants of UNIX provide antique versions of AWK which generate syntax errors when these scripts are run. In this case try replacing all instances of the command "awk" with either "nawk" (new awk) or "gawk" (gnu awk). GAWK is available on the web.