The Extratools manual

The Extratools manual

Ian W. Davis, Vincent B. Chen, and Daniel A. Keedy

Chapter 1
The Tools

This manual describes the KiNG tools available in the 'extratools' and 'rdcvis' packages. It is roughly laid out in order of the tools menu in KiNG, with tools in the main menu in this chapter, and a separate chapter for the 'Data analysis', 'Kin editing', 'Structural biology', 'Export' (File menu), and 'Specialty' tools. Also see the KiNG manual for descriptions of other tools.

1.1  90 Degree Rotations: Seeing precisely

The 90 Degree Rotations plugin provides a simple way to turn your model by 90 degrees around any of the three Cartesian axes. It also provides a shortcut back to the standard kinemage orientation: looking straight down the Z axis from the positive end toward the negative one, with positive X to the right and positive Y at the top of the screen.
This plugin is particularly useful in combination with a trick for setting up simultaneous orthogonal views of a kinemage. Read about it in the section on stereo graphics in the KiNG manual.

Chapter 2
Data analysis

2.1  Data Plotter Tool

The Data plotter tool is for importing high-dimensional (3) data into KiNG, for use with parallel coordinates.

2.1.1  Input files

This tool takes as input delimited, numerical files. The tool will use the first line of the file to determine the number of dimensions to use in the kinemage, as well as the names for each dimension. Also, it will use the first column as the point ID of each point. This allows users to enter identifying information about each row in the first column which will then be used in the kinemage for each point.

2.1.2  Basic usage

When this tool is started, it asks for an input file. Once a file is selected, it asks for the type of delimiter that is used in the file. It will then use the selected delimiter to parse the file. It then pops up a GUI with a number of different options. The different ".. axis" selection lists allow users to pick the initial three dimensions to plot. The bins selection list and the "# of Bins" entry field allows users to divide up the data into different bins (using the selected dimension), which will show up as separate groups in the kinemage. Once the desired axes and/or bins have been chosen, the Plot! button will plot the data into a kinemage. Once plotted, users can use the built-in "Choose viewing axes" and "Parallel coordinates" (under the Views menu) to manipulate the data.

2.2  High-dimensional Sliders

The High-dimensional sliders plugin is for manipulating high-dimensional kinemages. When started, it determines the number of dimensions in the kinemage, and creates a GUI containing a pair of low-high sliders for each dimension. Each slider is named with the corresponding dimension name, if present in the kinemage. Sliding the different sliders will turn off any points with that particular coordinate outside of the range encompased by the two sliders.

Chapter 3
Kin editing

Several new tools have been created that allow kinemages to be more easily edited without having to go back to the original PDB and creating a new kinemage.

3.1  Co-centering Tool

The Co-centeringTool is primarily for use with NMR-derived ensembles of models; it will translate all groups in kinemage onto a single selected point.

3.1.1  Basic Usage

Just middle-click or ctrl-click on an atom in a kinemage to cocenter all the groups of that kinemage onto that point. Click on the "Reset Coordinates" button to reset all atoms to their original coordinates.

3.1.2  Scanning through a structure

This tool includes the ability to scan through a structure one residue at a time, cocentering as it goes. Choose an atom to use as the centering point from the pull-down box, and then hit the left or right arrow buttons on the GUI to cocenter and recenter on the previous or next residue. Select the "Slide to next point" box to smoothly slide to the next or previous point. This can also be activated using the keyboard shortcut shift-j or j (for jump). As with many tools, this functionality is sensitive to the point IDs of the kinemage.

3.1.3  Cocentering on parens

The basic usage of cocenter only works on structures with identical sequences. For cocentering non-identical structures, we have created a cocenter on parens mode, which uses a new feature of pointIDs. To use this, enter a "(#)" [where the # is an integer] at the beginning of the point ID of the atoms you want to cocenter. With this option selected, the arrow buttons or j shortcut keys will jump through the (#) points by order of the integer. This also allows users to set up various cocentered views, and quickly jump through them, without having to manually find them, or stepping through the whole sequence.

3.1.4  Warnings

This functionality is based on the point ID of the points in the different groups. The tool uses the first 14 characters of the point ID clicked on to search the other groups. If a group does not have a point with the same first 14 characters in the point ID, the group will not get moved. When using the parens points, only groups with a point with the appropriate paren integer will be moved. It's important to note also that this tool only does translation; it does not do any rotations at all. Superpositions of the different models may be necessary before using this tool.

3.2  Paren Tool

The Paren tool provides a convenient way of adding parens (for use with co-centering) to point IDs.
When started, it automatically detects all paren points already defined in the kinemage. Each group of paren points is listed in the list box. Selecting the group from the list will label all the points in that group. To add or remove points to the group, select the group from the list and pick points without numbers to add them, or with number to remove them. You can also add new groups, or delete whole groups.

3.3  Dock 3-on-3: Geometric construction

The three-point docking tool is useful for constructing geometric shapes and figures out of existing pieces in kinemage format. As you start picking points with the mouse, they will be labeled with numbers: first three points in the reference frame, then three in the mobile frame. When you're ready to apply the docking transformation, turn off groups that should remain in place and leave visible those that should move. Then press the Dock button. The first points will be superimposed exactly, the 1-2 axes will be aligned (so that the mobile "points in the direction of" the reference) and the final points are used to determine rotational position (dihedral angle) about the 1-2 axis.
If you'd like to dock several of the same object with respect to each other, remember you can use the copy and paste commands in the hierarchy editor to create duplicate objects.

3.4  Least-Squares Docking: Getting the best fit

The least-squares docking tool is useful for matching up two objects that are similar but not quite the same. As you start picking points with the mouse, they will be labeled with numbers, defining the Reference frame. Once you've selected something to dock onto, you should choose the Mobile frame and add an equal number of points to it. The order matters: 1 will match with 1, 2 with 2, and so on. When you're ready to apply the docking transformation, turn off groups that should remain in place and leave visible those that should move. Then press the Dock button. The matched points will be positioned so as to minimize the sum of the squares of their separation (thus the phrase "least squares").
If you'd like to dock several of the same object with respect to each other, remember you can use the copy and paste commands in the hierarchy editor to create duplicate objects.

3.5  Dock By Picking

The dock by picking tool builds upon the least-squares docking tool, making use of structure connectivity to make the tool easier to use. In this version, you do not have to click on every point that you want to use to dock. Instead, you can click on two points, and almost every point in between will be automatically added to the selected box (reference or mobile). It leaves out points that are off, or are only one atom away (e.g. it ignores hydrogens and carbonyls). This tool requires the same number of points to be selected in the reference and mobile fields. The dock button will move the mobile, and every point connected to the mobile section. There is no need to turn off or on parts of the structure to get them to move.
N.B. Since this tool uses connectivity to determine the points, and the mobile section, it is easy to confuse. For example, it is inconsistent when considering sidechains, or especially rings in structures.

3.6  Extract Loop Tool

This tool is for removing unwanted residues from macromolecular structures.

3.6.1  Basic Usage

Enter the residue number range into the two text boxes and hit the Keep! button. Every residue number in between the range, including the two numbers, will be kept. Multiple ranges can be entered; the ranges that have been entered are shown in the list box. The Remove last button can be used to remove the last range entered. Once the proper ranges have been entered, the Delete rest! button can be used to delete every point without a desired residue number.

3.6.2  Advanced Usage

The LoopTool can read in a comma delimited file and use information in the file to delete residues from a structure. This allows a user to save ranges in a file, and not have to manually input the ranges. The format for the files is as follows: pdbname, lowresnum, highresnum, looplength, looplength, B-Factor (e.g. 1ubq,1,5,4,4,1.0). The two looplength fields are included for legacy reasons, but it is not important to have the correct value in those fields, just a number. B-Factor is used for the order of editing more than one structure (more on this later) but similarly to looplength, the number in this field is not critical. To use this feature, use the Open CSV file button to read in the CSV file. Then, just hit Delete from file to remove residues that aren't in your included ranges.
The LoopTool can also delete residues from multiple structures. In order to use this feature, you need to have a CSV formatted in the same way as described for a single structure, but each line contains a different range. You also need to have a directory containing kinemages of all the different structures, and also a folder called "loops" in that directory. Then, open your CSV file as before, and use the Do ALL from file button to specify the directory of kinemages. The program will open every kinemage as needed, delete unwanted residues, and save the new kin in the loops directory.

3.6.3  Warnings

The LoopTool makes heavy use of the information in the point IDs of the kinemages. If there are mistakes or unexpected information in the point IDs, then this tool will probably function incorrectly. Use kinemages generated from Prekin, Molprobity, or Molikin to ensure the highest rate of success.

3.7  Kinemage Fudging

The KinFudger tool now allows distance and angles between points to be easily adjusted. This is especially useful in modifying bond distances, angles, and dihedrals in macromolecular structures.
The control panel is simple, consisting of options for the parameter you wish to adjust, whether you want to move only one point (and all attached single points-I use this to move an atom and its attached hydrogens), and a button to export your kin to PDB.

3.7.1  Adjusting bond distances, angles, and dihedrals

In order to adjust a parameter, select the parameter you wish to adjust and click on the kinemage points you want to adjust, in order as if you were doing measures. By default, the tool will move the last point you clicked on, plus all the points connected to that point excluding the points "behind" the points you clicked. So for example, if you had a A-B-C-D connection, and you were adjusting the distance between B and C, and you clicked on B first, then C, then the program would move C and D. Likewise, if you clicked on C first, and then B, the program would move A and B. Naturally, the connectivity finding algorithm I use gets confused if you are adjusting with a cyclic structure, so be careful in that situation.
An interesting use I discovered about this tool is that you can use the distance adjusting to do a one-point docking of structures to close gaps.

3.7.2  Moving objects

Under the "Advanced options", users can turn on a mode that lets users use the mouse to move objects within a kinemage. Right-click and drag translates the clicked on point, as well as anything connected to it. Left-click and drag rotates everything connected to the selected point around that point.

3.7.3  Exporting to PDB

The KinFudger also includes an export to PDB functionality. As long as your kinemage PointIDs are formatted in a standard fashion (i.e. from Molikin, MolProbity, or Prekin), the tool will export all active points to a PDB file. So turn off anything you don't want in your PDB. Also, if it encounters an non-standard atom name, it will output "UNK" in the atom field of the PDB. Currently, it only exports protein atoms.

3.8  Recoloring

KiNG now has the ability to easily recolor kinemages. This tool was designed to specifically recolor protein structure kinemages; however, it can probably be used to recolor other kinds of kinemages as well. It allows specific regions of a structure to be recolored. For example, a specific amino acid, a particular alpha helix, or a whole subunit can be highlighted. This tool can also create a table of the amino acids in a structure.
The control panel for this tool has a number of options. The top line contains the color options, the second line contains the area of effect options, and the third line contains info boxes about what you are coloring and some extra control options. Most of the coloring is activated by clicking on the structure. It is important to note that this tool only recolors lists and subgroups, so depending on your kinemage, it is possible to color the sidechains separately from the backbone. Also, this tool only colors by point color.
Usage tip: There seems to be some issues with serine sidechains not being able to be colored. To work around this, try turning on the "Pick Objects" option in the Tools menu, and click directly on a bond in the sidechain.

3.9  Artificial skylighting

This plugin gives additional visual depth cues to CPK space-filling models by doing some fancy lighting calculations for kinemage spheres. It works for balls, too, but looks weird because of the highlights. To use it, just make a CPK kinemage with spheres, and run the tool. Essentially, it darkens the colors of balls closer to the 'inside' of the molecules. It will take a while on large files.
Note that it does obliterate existing point colors, and until we have a mechanism for writing out per-point unique (non-palette) colors, the effect can't be saved. It can, however, be recalculated once some atoms (eg H) are turned off. This plugin

3.10  "Lathe" tool: Just for fun

This is a fun helper that shows what a wide variety of shapes and forms can be constructed from a clever combination of kinemage primitives.
The lathe tool takes a single polyline and sweeps it out around an axis to create a polygonal object. One strip of 64 triangles is created for every line segment. This tool is ideal for creating anything with an axis of symmetry: bottles, vases, lamps, simple cylinders, and so on. The standard axis of rotation is the Y-axis, with rotation centered at the origin, so keep this in mind when drawing a half-profile to use with this tool.

3.11  Making Movies

This is a simple plugin to help users make movies. It allows users to configure various scenes and motions (rock, spin, fly), and exports a series of image files which can be combined (such as by Quicktime Pro) to make a movie. Buttons are included to conveniently resize the KiNG window.
This tool keeps track of objects which are turned on, so different things can be turned on or off during the movie. To do this, make sure the kinemage is set to the desired options and view before hitting the button corresponding to the action you want to do. So, for instance, to fly to a new scene, go to the new view and hit + Fly to have the movie show that action. To insert additional actions, click in the list of current actions before where you want the new action to go.
In practice, I (Vincent) find that it is best to add a short shapshot in between any movement actions in movies. Play with different settings to discover what you prefer.

3.12  Editing Multiple Lists

Authored by Daniel Keedy (daniel.keedy AT duke.edu)
Sometimes it's useful to emphasize or de-emphasize certain elements of a kinemage, e.g. to achieve the proper visual impact for a figure to be published. The Multi-list editor tool can help, by letting you simultaneously edit multiple kinemage lists.
First, use the checkboxes at the top of the control panel to determine what subset of lists will be affected. A list is considered to contain Probe contacts if it has a master tag (dots, vdw contact, small overlap, bad overlap, or H-bonds) generated by the all-atom contact evaluation program Probe. Note that if the "only visible" checkbox at the bottom is unchecked, all selected lists will be adjusted, not just the visible ones (i.e. those turned on in the kinemage hierarchy). Just don't bother changing all human history...
Next, repeatedly click the desired buttons to incrementally adjust the selected lists. For example, "BIGGER" and "smaller" change the width/radius of all points in the selected lists, and "opaquer" and "transparenter" make the lists more opaque (higher alpha value) or more transparent (lower alpha value).

3.13  Select by color

This plugin works with the 'select' kinemage group keyword to manipulate groups of data points.
To use it, make sure the kinemage group to be manipulated has the 'select' keyword set (either via the text, or the hierachy window). Then, select different combinations of 'if' and 'if not' and a color, to work with either one color or all other colors, respectively. Buttons allow points matching the selection to be turned off or on, or extracted into its own list.
This was originally created to work with large datasets, such as the 7 dimensional RNA backbone dihedral angle data, which is displayed using ball points. However, the tool does work with other kinds of points, as long as the 'select' keyword is set for the group.

Chapter 4
Exporting kinemages in other formats

Several facilities are provided that can help get data out of kinemage format and into other forms, either for making figures for publication or for further processing. Due to security restrictions placed on applets, the export features are unavailable when KiNG is running in a web browser.

4.1  Exporting for POV-Ray

KiNG can produce output script files to be fed into the high-quality free raytracing program POV-Ray (www.povray.org). POV-Ray can generate all kinds of "photo-realistic" effects including different materials and lighting schemes, simulated depth of field, etc. It is also very useful for producing digital movies that may be more convenient to use during talks and presentations. (We recommend the inexpensive QuickTime Pro from Apple for stitching together all the output images into a movie.) The POV file is largely complete as written and includes terse hints for rendering, but if you use this feature much you'll probably want to learn something about POV-Ray and tweak the scripts before rendering them. Most of the things you'll want to change are either at the very top (colors, textures, and sizes of things) or at the very bottom (camera viewpoint, depth cueing, lighting).

4.2  Exporting for Raster3D

KiNG can now export scenes, for fancy image-rendering, with the 'render' program of Raster3D.
This option exports most of the major kinemage point types, include balls, vectors, and triangles (ribbons) to .r3d format files for use with render. It also exports information about the points, such as transparency, line width, and color. It also will automatically set the background of the file to match the background of KiNG at the time of export.
There are a few oddities with this function. First, it can't export text labels. Second, the coordinate system doesn't match exactly, so the exported view ends up in the upper left 3/4 corner of the rendered image.

4.3  Deprecated export formats

These features now lag far behind the rest of the program in functionality; they may not work at all. For this reason, they do not appear in the menus by default and must be "enabled" under the Tools menu. If you need any of these capabilities, you are encouraged to contact the author and encourage on-going development.
You can export kinemages in XML format using the Kinetic Image Markup Language by choosing Kin-XML from the File - Export menu. We recommend giving these files the extension .xkn or .xml. At this time, KiNG does not read these files, nor do other kinemage viewers. Also, they may not include all of the information that would be present in a traditional kinemage file. However, for people who would like to operate on the data from a kinemage without having to write a parser for the kinemage format, we expect this will be useful and convenient. Translation from the modified XML back to kinemage format is left as an exercise to the reader ;)
KiNG also has rudimentary abilities to export its 3-D primitives in VRML97 (a.k.a. VRML 2.0) format. At present, only dots and balls are exported, and they are both rendered as spheres. This feature was intended to facilitate the creation of models for rapid prototyping systems. As with XML export, contact the author if further development of this feature would be useful to you.

Chapter 5
Structural biology tools

5.1  RNA Rotator Tool

The RNA rotator tool is for adjusting the various dihedral angles of an RNA suite. It uses the ModelManager system used for by the Backrub and sidechain rotator/mutator tools, which means that RNA rotator uses and changes PDB files. It also can show real-time updatable probe contact dots.
To use RNA rotator, select the tool from the Structural biology menu. Select the PDB file corresponding to the kinemage you are working on. This will load the PDB file into the Model Manager, which allows you to save changes to the PDB file, as well as activate the probe dots analysis. Middle-click or shift-click on a particular RNA residue to select it and the following residue as the active "molten" suite. This will bring up the dihedral angle dialog box, as well as the molten model, which reflects proposed changes being made in the model. Dials are included for all the backbone dihedrals, as well as the base chi angles. Blue highlights are indicated on the dials to indicate the most probable dihedral angles. If installed, suitename will be run to give a real-time "suiteness" score of the current suite. There is also a box to select from the known RNA suite conformers. Selecting a conformer will set the backbone dihedrals, as well as the sugar pucker, to the central dihedral values of the particular conformer. Finally, there is a pair of boxes for selecting which atoms to superimpose the "molten" model on the original.

5.2  RDC Play Plugin

The RDC play plugin allows quick visualization of a set of RDC curves, in fully interactive and rotatable 3D. This plugin allows users to interact with the RDC curves and gain a general understanding of their behavior of RDC data.
Starting the plugin automatically generates a new kinemage with RDC curves drawn. Slider bars are provided to adjust the rhombicity of the curves drawn, the range of the Saupe matrix generating the curves, and for selecting a specific value of RDC to draw, which is only active if the check box to only draw one value is selected. An option for drawing the underlying hyperboloid surfaces the curves come from is provided.

5.3  RDCvis

The RDCvis tool provides a convenient way of adding RDC curves to existing NMR model kinemages.
To use the tool, open a kinemage which needs RDC curves in KiNG. Starting the tool opens a dialog box with several options, as well as boxes for specifying a PDB file containing the NMR model(s), and a NMR data file in XPLOR format (see rdcvis manual or the kinemage website for more details). The 'Draw RDCs' button will then prompt for the type of RDCs to draw, and then draw the selected RDC curves for each residue directly in the kinemage. RDCvis will properly deal with multi-model kinemages, adding RDC curves for each model to the group containing that model.
Several other options are provided on the RDCvis tool GUI. 'Draw error curves' draws an extra set of curves at 2 sigma away for each RDC. 'Draw surfaces' draws representations of the underlying hyperboloid surfaces. 'Use ensemble tensor' calculates the Saupe matrix using the entire ensemble, rather than calculating a separate Saupe matrix for each model. 'Draw curve spheres' draws an RDC curve sphere representative of the Saupe matrix on each residue.

Chapter 6
Specialty/Beta test tools

This chapter covers some of the tools in the Specialty menu. This menu contains tools which are in beta testing or for highly specialized purposes, and thus not recommened for general use.

6.1  "KinImage" tool: Just silly

This cute little utility converts an image file into a kinemage background. The source image can be a local file or a sample from the Richardson Lab website: "Dave the Mage." A new kinemage group is created containing a dotlist with some percentage of the image's pixels. The list uses the "screen" keyword to indicate it is screen-oriented, i.e. impervious to rotations, translations, or zooms. Custom colors are used, and subsequently stored as hsvcolor items at the top of the file if the kinemage is saved.

6.2  RNA Maps: Finding the phosphates (not active by default)

Authored by Vincent Chen (vbc3 AT duke.edu)
This tool (still under development) was designed to aid users in locating potential phosphate positions in the electron density maps of nucleic acids. Similar to the existing electron density viewing plug-in, this tool asks the user to open a map file, and opens a control window containing many of the same controls as the electron density plug-in. In addition to these controls, it has a toggle button to activate/deactivate the poly picking feature and a color selection list. When active, if the user left-clicks on a point in the kinemage, the polyhedron containing that point will be highlighted in the color selected. Next, the tool searches through the map to find the highest electron density value within that selected polyhedron, and places a marker point on that spot, showing an approximate position for the phosphorous.

6.2.1  Current Issues

This tool does not differentiate between a point in the electron density and a point on the actual structure. Clicking on the structure with the poly picking tool active can result in the program searching through the whole structure, which can take a very long time. Be sure to click carefully, and to limit the polyhedra to be selected to a reasonable size (i.e. have the sigma level set high enough that the polyhedra are about the size of a phosphate). Also, once the first polyhedron has been selected, moving the electron density around and selecting a polyhedron may result in an error. If this happens, the program will have to be restarted in order to selected a polyhedron not in the initial set.

6.3  Analyze Geometry Plugin (replaced by Dangle, not active)

This plugin is for automatically analyzing the backbone geometry of protein structures. It uses the updated Engh and Huber (International Tables for Crystallography (2001). Vol. F, ch. 18.3, pp. 382-392) geometry data to flag bond lengths or angles which are at least 4 standard deviations away from their mean values. It also flags peptide dihedral angles that are more than 20 degrees off of 180. In order to use this tool, simply have a mainchain protein kinemage open in KiNG, and select Analyze Current from the menu. It will also output a list containing all flagged issues to the command line.
This tool will also analyze all the files within a directory. Select Analyze All from the menu, and select the directory containing the kinemages. This mode will only output the errors to the command line.

6.3.1  Issues

As with many of the tools dealing with protein residues, this tool is sensitive to the pointIDs in your kinemage. It also has trouble dealing with insertion codes, since it is often unable to figure out the order of the residues in kinemages with insertion codes.

6.4  Fill-Gap Plugin (replaced by JiffiLoop, not active)

This plugin makes it easy to automatically fill in gaps in protein models. It scans through a protein structure kin for gaps, analyzes the framing peptides of that gap, searches through a quality filtered database of loops for matches, finds kins of those matches, and superimposes them in the kinemage. It requires a database of loop frame information, and a directory of protein kinemages, both of which are quite large, and as of Feb 2007 are not publicly available. Eventually I plan to make them available on kinemage.biochem.duke.edu.

Chapter 7
Copyright & acknowledgments

7.1  Copyright

The Extratools code and all its associated original resources and documentation are copyright (C) 2002-2010 by Ian W. Davis, Vincent B. Chen, and Daniel A. Keedy.

7.2  Revision status

This manual was last updated 14 Dec 2010 by VBC for Extratools version 2.22.


File translated from TEX by TTHgold, version 4.00.
On 15 Dec 2010, 16:50.