The Extratools manual
The Extratools manual
Ian W. Davis, Vincent B. Chen, and Daniel A. Keedy
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.
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.
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.
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.
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.
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.