InKiProM v1.0 User's Manual

Program Invocation

The program can be invoked in two ways: Either by providing the name of an existing PDB file, or by providing the name of a prediction file.

PDB File Manipulation

To manipulate a protein stored in a PDB file, the program is called with the PDB file name as single parameters. The file name must end in the extension ".pdb" to be recognized. A raw PDB file does not contain secondary structure information; to use the program's manipulation features, this information has to be added to a PDB file by hand. Structure information is added by inserting a REMARK line into the PDB file before ATOM line defining the first atom in the first residue in the structure. The REMARK line contains a single keyword denoting the type of the following structure. The keyword must begin on column 12 of the REMARK line.
REMARK COIL
All following residues, until the next REMARK line, belong to the same coil region.
REMARK ALPHA-HELIX
All following residues, until the next REMARK line, belong to the same alpha-helix.
REMARK BETA-STRAND
All following residues, until the next REMARK line, belong to the same beta-strand.
For example, a valid PDB file could look like the following:
REMARK      COIL
ATOM ...
...
ATOM ...
REMARK      BETA-STRAND
ATOM ...
...
ATOM ...
REMARK      COIL
ATOM ...
...
ATOM ...
REMARK      ALPHA-HELIX
ATOM ...
...
PDB files generated by the program will follow this convention to preserve secondary structures information.

The program tries to be as lenient as possible when parsing a given PDB file. Comments will reliably be ignored, but HETATM lines can sometimes cause trouble. In case of doubt, those lines should be removed manually.

Prediction File Manipulation

To create and manipulate a protein from a prediction file, the program is called with the prediction file name as the single parameter. The file name must end in the extension ".pred" to be recognized. A prediction file has to adhere to the following format:
Conf: 999999999999999999999999999999999999999
Pred: CCEEEEEEEECCCEEEEEEEECCHHHHHHCCCCEEEECC
  AA: GGGMMMLLTTSPSAAAVVAAILLAMATISPSTRMMLLGG
The first line defines prediction confidence values ranging from zero to nine (not used by the current program version). The second line defines predicted structures: "C" stands for coil region, "E" stands for beta-strand, and "H" stands for alpha-helix. The third line defines residue types using the standard PDB single letter residue names.

When reading a prediction file, the program will automatically add an ACE residue at the beginning of the protein, and an NME residue at the end. Both residues will be of residue type "Unknown," and will not be affected by any protein manipulations. They will, however, be included in any PDB file written by the program.

Viewing Transformation

To change the rendering viewpoint and zoom in/out, the program uses a trackball interface similar to the one used by SGI's Open Inventor toolkit. Clicking and dragging with the left mouse button will rotate the view around the current view center. If the mouse is still moving when the left mouse button is released, the program will continue spinning the display. The display will stop spinning as soon as a mouse button is pressed inside the main window.

Clicking and dragging with the middle mouse button will pan the display parallel to the viewing plane.

Clicking and dragging up and down with both the left and middle mouse button will dolly out from and in towards the current view center, respectively.

Pressing the "z" hotkey, and subsequently picking any atom with the left mouse button will move the view center to the picked atom.

The view can be reset to show the entire protein by selecting the "Center View" entry from the "View" menu, or by pressing the "Alt-c" hotkey.

Residue Selection

Residues inside the manipulated protein can be selected in one of two ways: Either by clicking on one of the residue's atoms with the left mouse button while holding down the "Alt" key, or by dragging the "Residue index" slider inside the Residue Dialog. The selected residue will be highlighted by rendering its atoms.

The Residue Dialog displays information about the selected residue, and can also be used to randomly assign dihedral angles for coil residues by selecting the "Random Angles" button.

Structure Selection

Secondary structures inside the manipulated protein can be selected in two ways: Either by clicking on one of the structure's atoms with the left mouse button while holding down the "Ctrl" key, or by dragging the "Structure index" slider inside the Structure Dialog. The selected structure will be highlighted by surrounding it with a green semi-transparent box. This box doubles as the main 3D interaction widget for aligning secondary structures.

The Structure Dialog displays information about the selected structure, and can also be used to globally manipulate the dihedral angles of all residues inside alpha-helices or beta-strands.

Structure Manipulation

The program allows to manipulate a protein's conformation in two ways. Complete secondary structures can be aligned with each other by dragging them with the mouse inside the main window, and the shape of selected secondary structures can be adjusted by changing global parameters using the Structure Dialog.

Any structure manipulation will only change dihedral angles of rotatable backbone bonds. Bond distances or angles will never be changed; neither will peptide bond dihedral angles or phi angles of proline residues.

Structure Alignment

To align secondary structures, the program provides a 3D direct manipulation widget that can be translated and rotated using the mouse. By selecting a secondary structure, it will be enclosed in a semi-transparent green box, and the next coil region towards the beginning or end of the manipulated protein (depending on the current update direction) will become the current update region (highlighted by rendering its backbone (ribbon) in yellow). Any manipulations of the green box will be translated into dihedral angle changes inside the update region, and the program will update the protein atoms' cartesian coordinates interactively.

To manipulate the drag box, a user picks it with the left mouse button while holding down the "Shift" key. Depending on which part of the box was picked, it can subsequently be manipulated in one of three ways:

Translation in a plane
When the box was picked inside on of its faces, the four edges surrounding the picked face will be highlighted in yellow. By dragging the mouse, the box can be translated in the plane parallel to the picked face.
Rotation around a primary axis
When the box was picked on one of its edges, the four edges parallel to the picked one will be highlighted in yellow. By dragging the mouse, the box can be rotated around an axis parallel to the picked edge. The rotation center is set to the first backbone atom of the selected structure towards the update region.
The rotation speed of the drag box depends on mouse motion speed in a non-linear fashion. When the mouse is dragged slowly, the drag box will rotate very slowly; if the mouse is dragged fast, the box will rotate very fast. When the drag box is moved too quickly, the program sometimes loses track of the goal orientation and positions or orients the selected structure in a grossly wrong way. In this event, it is best to release the mouse button and undo the last manipulation.
Rotation around a point
When the box was picked on one of its vertices, all eight box vertices will be highlighted in yellow. By dragging the mouse, the box can be rotated around the rotation center in a trackball-like fashion. The rotation center is set to the first backbone atom of the selected structure towards the update region.
While the left mouse button is held down, the program will continuously change the update region's dihedral angles to best approximate the selected structure's goal orientation, as denoted by the drag box. As soon as the left mouse button is released, the drag box will snap back to the selected structure's current position.

Tip: Sometimes it is helpful to "wiggle" the box a bit during manipulation to help the program find a vector of dihedral angles that approximates the goal orientation well.

For the purposes of undoing/redoing, a complete dragging motion, between mouse button push and mouse button release, will count as an atomic manipulation.

Changing the Update Direction

When a secondary structure is selected, one of its neighbouring coil regions becomes the current update region (which is subsequently affected by manipulating the green box surrounding the selected structure). The update region is found by traversing the protein either to the left or right, i.e., towards the ACE initial or the NME terminal) until the next coil region is encountered. The update direction, i.e., the direction in which the protein is traversed, can be toggled by pressing the "u" hotkey. When the update direction is changed, the new update region is determined immediately and highlighted by rendering its backbone (ribbon) in yellow.

Beta-Strand Adjustment

Structure alignment will only change dihedral angles inside coil regions, but never inside alpha-helices or beta-strands. To change the shape of beta-strands, the program supports adjusting four parameters for each beta-strand independently. Each parameter has a corresponding roller widget inside the Structure Dialog.
Curl
When dragging the curl roller to the right, the program will decrease phi and increase psi for even-numbered residues inside a beta-strand, and increase phi and decrease psi for odd-numbered residues. (Residue numbers inside a beta-strand are zero-based). The absolute angle difference is the same for all dihedral angles, and is proportional to dragging distance.
Twist
When dragging the twist roller to the right, the program will increase phi and psi for all residues inside a beta-strand. In effect, the beta-strand will twist around its main axis. The absolute angle difference is the same for all dihedral angles, and is proportional to dragging distance.
Pleat
When dragging the pleat roller to the right, the program will decrease phi and increase psi for all residues inside a beta-strand. In effect, backbone dipole groups inside the same residue along the beta-strand will move closer to each other. The absolute angle difference is the same for all dihedral angles, and is proportional to dragging distance.
Braid (I made that up)
When dragging the "braid" roller to the right, the program will increase phi and psi for even-numbered residues inside a beta-strand, and decrease phi and psi for odd-numbered residues. (Residue numbers inside a beta-strand are zero-based). The absolute angle difference is the same for all dihedral angles, and is proportional to dragging distance.
The "Reset to Standard" button inside the Structure Dialog's "Beta Strand Shape Adjustment" group can be used to reset an adjusted beta-strand to its natural shape.

Rendering Features

All rendering features are toggled via buttons inside the Drawing Toggles Dialog; the most important are also assigned hotkeys that can be pressed inside the main window. Most parameters can be toggled globally and on a per-structure basis independently. For any given structure, a rendering feature is only enabled if both the global and the per-structure toggle are set. Turning off a global toggle will not affect the per-structure settings for the same feature.

If a feature has an assigned hotkey, pressing the hotkey by itself will toggle the global setting, whereas pressing the hotkey while holding down the "Ctrl" key will toggle the per-structure setting.

Atom Rendering

When Atom Rendering is enabled, all atoms of a secondary structure will be rendered as colored shaded spheres. Sphere radii are defined as the respective atoms' van der Waals radii, as taken from A. Bondi, "van der Waals Volumes and Radii", J. Phys. Chem. 68 (1964), pp. 441-451.

This feature can be toggled via the Drawing Toggles Dialog, or via the "a" hotkey.

Sidechain Bond Rendering

This feature renders bonds between all atoms as shaded capped cylinders. The cylinders are colored based on the element types of the two atoms involved in a bond. This feature is useful to get an idea of side chain alignment, and to track down atom intersections when used in combination with the Atom Collision Visualization feature.

This feature can be toggled via the Drawing Toggles Dialog, or via the "b" hotkey.

Backbone Ribbon Rendering

This feature renders a protein's backbone as a single colored shaded spline ribbon. When disabled, the protein's backbone is simply rendered as a colored polyline. The backbone colors are assigned according to secondary structure type: Alpha-helices are colored red-purple, beta-strands are colored blue-purple, and coil regions are colored plain purple.

This feature can be toggled via the Drawing Toggles Dialog, or via the "r" hotkey.

Hydrogen Bond Rendering

This feature renders hydrogen bonds between backbone dipole groups (N-H and C=O) as dotted yellow lines. The decision of when to form hydrogen bonds is based on the distances between two involved dipole groups, and on the angle between their respective bonds. The geometry constraints determining whether two opposite dipole groups will form a hydrogen bond were taken from the main-chain hydrogen bonding histograms on the web page Atlas of Side-Chain and Main-Chain Hydrogen Bonding by Ian McDonald and Janet M. Thornton.

This feature can be toggled via the Drawing Toggles Dialog, or via the "h" hotkey. Hydrogen bond rendering can only be toggled globally, so there is no per-structure toggle button and no "Ctrl-h" hotkey.

Hydrogen Bond Site Rendering

This feature is meant to assist in aligning beta-strands into beta-sheets. It renders backbone dipole groups as colored lines (light blue for N-H, red for C=O). The lines are extrapolated such that they extend half the distance of an average hydrogen bond past their group's minor atom (H and O, respectively). The endpoint of the extended line is also marked by a dot. In effect, to form a "prototypical" hydrogen bond, a user has to align one blue and red line each to be anti-parallel, and overlay their end dots.

This hydrogen bond guide is less precise than Hydrogen Cage Rendering, but it introduces less clutter.

This feature can be toggled via the Drawing Toggles Dialog, or via the "s" hotkey. Since hydrogen bond sites are mostly used to create beta-sheets, they are by default only enabled for beta-strands.

Hydrogen Cage Rendering

This feature aids in aligning beta-strands by displaying hydrogen bond regions around N-H dipole groups. When enabled, it will draw dark-yellow wireframe cages around the valid region for the oxygen atom of a backbone C=O dipole group, and will highlight C=O groups by red lines and dots at the oxygen atom's position. When an oxygen atom is inside this region, and the hydrogen bond angle constraint is satisfied, a hydrogen bond can be formed.

This feature can be toggled via the Drawing Toggles Dialog, or via the "c" hotkey. Since hydrogen cages are mostly used to create beta-sheets, they are by default only enabled for beta-strands.

Large vs. Small Hydrogen Cages

To reduce clutter when drawing hydrogen cages, one can disable rendering of the "inner" shell of the cages.

This feature can be toggled via the Drawing Toggles Dialog, or via the "Ctrl-l" hotkey. Hydrogen cage size can only be toggled per structure, so there is no global toggle button and no "l" hotkey.

Atom Collision Visualization

This feature aids in aligning structures and creating overall protein conformations. When enabled, it will visualize intersecting atoms inside a protein as red shaded spheres of varying radii. When determining intersections, the program considers all N2 pairs of atoms. Even though a spatial data structure is used to reduce collision detection complexity to expected O(N), enabling this feature will slow down interaction and rendering.

Two atoms are considered intersecting if and only if their Euclidean distance is less than 75% of the sum of their respective covalent radii, as taken from http://www.webelements.com. The sphere visualizing an atom intersection is centered at the geometric midpoint of the two affected atoms, and its radius is calculated as the difference of 75% of the sum of covalent radii and the Euclidean atom distance, multiplied by two. In other words, the radius of an intersection sphere is twice the intersection depth.

This feature can be toggled via the Drawing Toggles Dialog, or via the "p" hotkey. Atom collision visualization can only be toggled globally, so there is no per-structure toggle button and no "Ctrl-p" hotkey.

Main Menu Reference

File Menu

Load Prediction File
Load PDB File
Save PDB File
Writes the current conformation of the manipulated protein to a PDB file. The PDB file's name can be selected via a standard Fltk file name selection box.
Quit
Selecting the Quit menu entry will close the program after asking for confirmation. Unsaved changes in the manipulated protein will be lost. Selecting this menu entry has the same effect as closing the main window.

Edit Menu

Undo
Undoes the last atomic manipulation. An atomic manipulation as a sequence of dihedral angle updates between pushing the left mouse button and releasing it. For example, a single drag operation during structure alignment and a single roll of the beta-strand adjustment rollers count as atomic manipulations. The shortcut for "Undo" is pressing "Alt-z" inside the main window.
Redo
Redoes the last undone atomic manipulation. The redo buffer is flushed whenever a new atomic manipulation is performed. Therefore, the complete undo buffer is always linear and does not branch. This might be implemented in a future program version. The shortcut for "Redo" is pressing "Alt-x" inside the main window.

View Menu

Center View
Resets the current viewpoint to show the complete protein. The shortcut for "Center View" is pressing "Alt-c" inside the main window.

Windows Menu

Show Residue Dialog
Toggles display of the Residue Dialog. The same can be achieved by pressing "Alt-r" inside the main window.
Show Structure Dialog
Toggles display of the Structure Dialog. The same can be achieved by pressing "Alt-s" inside the main window.
Show Drawing Toggles Dialog
Toggles display of the Drawing Toggles Dialog. The same can be achieved by pressing "Alt-t" inside the main window.

Dialog Window Reference

Residue Dialog

a) b)

Figure 1: Residue Dialog (a) No residue selected. (b) Residue selected.

The Residue Dialog is used to select a residue from the manipulated protein, and display information about it. The "Residue index" slider displays the residue index of the selected residue as taken from the PDB file/prediction file. Dragging the slider selects residues from the protein; pulling it all the way to the left will deselect any residue.

The rest of the dialog is only enabled when a residue is selected. The "Residue type" field displays the selected residue's type, and the "PDB file name" field displays the residue's name from the PDB file/prediction file.

The fields inside the "Dihedral Angles" group display the residue's current dihedral angles phi and psi in degrees. Selecting the "Randomize Angles" button will assign random dihedral angles for a residue inside a coil region.

Structure Dialog

a) b)
c)

Figure 2: Structure Dialog (a) No secondary structure selected. (b) Alpha-helix selected. (c) Beta-strand selected.

The Structure Dialog is an alternative to select a secondary structure from the manipulated protein, display information about it, and adjust its shape. The "Structure index" slider displays the zero-based structure index of the selected structure. Dragging the slider selects secondary structures from the protein; pulling it all the way to the left will deselect any structure.

The rest of the dialog is only enabled when a secondary structure is selected. The "Structure Type" field displays the selected structure's type (coil, alpha-helix or beta-strand).

The rollers and buttons inside the "Beta Strand Shape Adjustment" group are used to adjust a selected beta-strand's shape.

Drawing Toggles Dialog

a) b)

Figure 3: Drawing Toggles Dialog (a) No secondary structure selected. (b) Secondary structure selected.

The Drawing Toggles Dialog is used to toggle global and per-structure rendering features. The per-structure toggle buttons inside the "Structure Parameters" group are only enabled when a secondary structure is selected.

Hotkey Reference

a
Global toggle for atom rendering.
Ctrl-a
Per-structure toggle for atom rendering.
b
Global toggle for sidechain bond rendering.
Ctrl-b
Per-structure toggle for sidechain bond rendering.
c
Global toggle for hydrogen cage rendering.
Ctrl-c
Per-structure toggle for hydrogen cage rendering.
Alt-c
Resets the viewpoint and view direction to show the entire protein.
h
Global toggle for hydrogen bond rendering.
Ctrl-l
Per-structure toggle for large hydrogen cage rendering.
p
Global toggle for atom collision visualization.
Alt-q
Exits the program after asking for confirmation.
r
Global toggle for backbone ribbon rendering.
Ctrl-r
Per-structure toggle for backbone ribbon rendering.
Alt-r
Toggles display of the Residue Dialog.
s
Global toggle for hydrogen bond site rendering.
Ctrl-s
Per-structure toggle for hydrogen bond site rendering.
Alt-s
Toggles display of the Structure Dialog.
Alt-t
Toggles display of the Drawing Toggles Dialog.
u
Toggles the update direction between left (towards the ACE initial) and right (towards the NME terminal).
Alt-x
Redoes the last undone atomic manipulation.
z
The next left mouse button click on any atom will zoom the viewpoint towards that atom.
Alt-z
Undoes the last atomic manipulation.