PREKIN

@text

PREKIN is a utility program which prepares trial kinemages from Brookhaven Protein Data Bank format coordinate files. An early version is briefly described in the Richardson & Richardson article in the first issue of Protein Science (Jan. '92). The kinemage format is defined in that article, and although there are now more keywords and parameters (see list at end of this file), the basic definitions have been stable. Kin. 2 of Demo2_4b.kin describes and then gives the complete example of a short kinemage file, to compare with what shows up on the screen. PREKIN is under continual development to increase its capabilities; use the latest version available. Each version is identified, i.e. PREKIN x.y is "PKIN_x_y.EXE" on the PC and "PREKIN_x.y" on the Macintosh, where "x.y" is the version number. This file is a guide to the process of using PREKIN to make your own kinemages.

USING PREKIN version 2.5 (for MAGE version 2.5):

First, the PREKIN application should be copied to your hard disk or to a diskette with room for coordinate files, scratch files, and output .kin files. (If you ever get a partial output file, check space available.) You will need a word processor to edit the .kin files, and MAGE to look at them. To try out this process, you can use any Brookhaven Data Bank coordinate file you have available. The easiest way to get PDB files is over the electronic network, from the anonymous FTP directory 130.199.144.1, using either ftp from a UNIX system or Fetch or Gopher from a Mac. Alternatively, you can use the CDROM distributed once a year by Protein Science, or order magnetic tapes or a CDROM directly from Brookhaven (Brookhaven Protein Data Bank, Brookhaven National Lab, Upton, Long Island, NY 11973), or find someone at your institution who keeps the files on line.

The PREKIN interface uses a succession of dialog boxes to define the kinemage; there is a menu of built-in scripts in an early dialog box that allows easy selection of several useful kinemage layouts. Multiple passes through PREKIN can build a kinemage with complicated groupings. PREKIN output is intended to be edited using a word processor program to regroup, rename, and delete unnecessary items. However, PREKIN output can always be immediately viewed and evaluated on MAGE.

Both PREKIN and MAGE can handle fairly large Brookhaven files, but to make an intelligible kinemage you will need to edit quite drastically at some stage of the process - a kinemage should have less than 500 vectors on the screen at one time, and 200-300 is definitely preferable, both for comprehensibility and for smooth rotation on these small computers. For a small structure it is reasonable to run PREKIN using an inclusive range with mc, sc, ca, hb, and ht specified, display the result in MAGE, and then edit it. For a medium-sized structure, use the range controls in PREKIN to select a generous set, and then do the final editing after looking at it. For very large structures, it may be easiest to cut down or split up the coordinate file before running PREKIN at all. The program works on nucleic acids and carbohydrates as well as on proteins, but those facilities are not as complete or well tested.

There are five types of control specifications in a PREKIN run, done through a series of dialog boxes.

  1. File selection for input and output is done immediately when PREKIN is started.

  2. Choice of operation either from a menu of built-in scripts, from an external script (written on an earlier run of PREKIN), or by specifying ranges, focus, etc. individually. Built-in scripts presently include the following:
    • all Calphas, plus disulfides and non-water het groups;
    • all mainchain, with Hbonds;
    • sidechains by residue number;
    • all sidechains, grouped by residue type;
    • mainchain, sidechain, Calphas, any hydrogens and non-H2O hets; and
    • ribbon (suggest using one strand, without 'onewidth', as in ProTour7.kin).

    The scripts are designed either for use in "browsing" PDB files, or as starting points for an author. If in doubt, script a) is always a plausible choice. The script-vs-range-vs-focus dialog box ("rangestart") can be returned to from many of the following dialog boxes for a fresh start.

    For nucleic acids, script a) gives a virtual-bond pseudo-backbone drawn between P, c4', and c1' atoms; you can easily add a line to symbolize each base-pair, by using the drawline function in MAGE (suggest shortening lines by 1.3A) to connect the proper c1' atom pairs. Script d) gives the pseudo-backbone, plus the bases, grouped and color-coded. Script e) gives all-atom backbone, sugars, and bases. H-bonds are not calculated between base pairs, but it is easy to add them in MAGE.

    For carbohydrates, which are treated as "hetatoms" in PDB files, PREKIN will look for all possible connections between sugar residues if you set that option under "kludges" in the initial "rangestart" dialog box. It is slow, so use it only when needed.

  3. Subunit selection: controls which subunits will be considered (recognized by the "chainID" field between aa name and residue number in the PDB file, or by a line starting with "MODEL n", as in multiple NMR structures). Each subunit will be put into a new group of display objects. The default for built-in scripts is sometimes just the first subunit in the file, but you can change that in the dialog box to specifiy either all subunits, or just the first, or those within a specified range. For nucleic acids, remember to ask for enough subunits to get both strands of a DNA duplex.

  4. Range controls: if you asked for ranges, you are given a range-control dialog box. For each range you specify the starting and ending residue numbers and/or residue type ('res': e.g., lys) to set the extent of the range. Then you check the box for each kind of display object you want produced for that range (mc=mainchain, sc=sidechain, hb=backbone H-bonds, hy=hydrogens, ca=Calphas, ht= non-water heterogens, wa=waters, at=atom markers, lb=labels). Then you click to accept that range, either going on to the next range, or ending the range set, or ending and writing a script file. (If Prekin doesn't find the hets or waters you expected, look in the coordinate file to make sure the beginning of the lines say "HETATM", rather than "ATOM ", and also check which subunit chainID they have).

    For example, to make a kinemage showing a beta hairpin you might enter the following two ranges:
    14 to 35: mc, hb
    24 to 25, sc
    That will produce vectors connecting mainchain N, Calpha, C, and O atoms, plus mainchain H-bonds for residues 14-35, and sidechains for residues 24-25.

    As another example, you could produce sidechain vectors and atom markers at the S for just the Cys residues in a protein, plus all Calphas, with the following ranges:
    -999 to 9999: sc, at, cys
    -999 to 9999: ca

  5. Focus controls: used to make a display list of things within some radius of a specified point. The x, y, z of the focus point can either be typed in, read from a file made by MAGE (see below), or PREKIN can find the center point of a given-numbered residue to serve as the focus point. PREKIN will then ask for radii within which it will output sidechains, mainchain, Calphas, waters, and non-water het groups; the default values for those radii are 8, 10, 15, 10, and 10 . The radius is tested at each atom of the target sidechain, mainchain, etc., which is then all included if any atom is inside.

    After all the above items have been specified or defaulted, PREKIN will go to work and print messages about its progress, ending with a count of the number of triples written out and a message to select 'Quit' or 'New Pass' from the file menu. A new pass allows you to do another run through script, menu, or focus selections, using the same input coordinate file and writing onto the end of the same output file.

    If you do not know residue numbers for the parts you want, then do an initial PREKIN run asking for only ca or for choice a) on the menu of scripts (plus, perhaps, a second range specifying a single active-site side chain or a bound heterogen); then look at the resulting *.kin file in MAGE and pick atoms to identify the parts you want, to decide how to set up a second run of PREKIN. The focus option in PREKIN works from x,y,z coordinates; you can either look these up in the Brookhaven file, or in MAGE you can pick the atom and use 'write focus' under the 'Other' menu to write a focus file that PREKIN can read.

    Text and captions - PREKIN writes short default text and caption fields, and it assigns default colors to each display list; usually you will want to change these. Don't make the text longer than 32K, and be concise and compact, since the amount of text visible in the window at one time is small. The caption window is even smaller; that is the place to explain color-coding, since it can be seen at the same time as the image, identify the subject and note anything special like an animation, but leave background explanations to the text window. If you are preparing a kinemage for a journal, refer to some distributed files for format, especially for standard headers such as title and list of kinemages. Both text and captions should be typed into your word-processor in "wraparound" mode, with carriage returns only at the end of paragraphs, and the file saved as "generic" text; this allows MAGE to resize windows as needed. However, if you want to Email a kinemage file, then save a copy as the kind of text file with returns at the ends of all the lines. MAGE is capable of safely ignoring many formatting controls, but some will cause trouble, therefore remember always to SAVE a *.kin file AS A TEXT FILE, never as a formatted word-processor file!

    The kinemages in a file should be numbered uniquely, and usually consecutively, so that the 'Next' and 'Choose' functions on the 'Kinemage' pulldown menu will work as expected. They should be listed by number, with a one-line description, at the top of the text, so readers know what they can find in the file without needing to scroll through the text.

    Keywords that control overall options should go between the caption and the first view, so they can be found easily. For small kinemages, you may want depth-cuing by line width (just delete the '@onewidth' keyword), and for extremely large ones or multiple superpositions you can use '@thinline'. The use of '@compare' is described below, under animation. 'Multibin i' improves the hidden-line removal process, at some loss in speed; if you notice a line drawn in front that should be behind another one, try setting multibins to 3. This is still needed in 2.5 but should become unnnecessary soon, because we have discovered an efficient way to use more bins all the time and will change as soon as it has been adequately tested.

    The other overall keywords are applicable only under special circumstances. For a 3-D plot, or an image with many parallel or perpendicular lines, you may want '@perspective' and/or '@whitebkg'. The preference keywords '@keepstereo', '@stereoangle' (-6 gives cross-eye stereo), '@keepthinline' (improves rotation performance on the PC), and "@keepperspective" should not be used for distribution kinemages, but may be very helpful in ones for your own use, to avoid resetting values to your preferred style inside MAGE; they are the only keywords whose effect lasts for more than one kinemage (until the program is quit). The same effect can be produced by a user of the program by typing single keys on the keyboard (which act as on-off toggles): 's' to keep stereo, 'c' to switch between normal and cross-eye stereo, 't' for thinline, and 'p' for perspective. '@noscale' jumpers out MAGE's initial process of centering and scaling the input coordinates - use at your own risk. The effect of '@plotonly' depends on its position within the kinemage. If it is before all display objects it disables rotation, for an image to stay strictly in 2-D; the limit of 3500 points in a kinemage is also then ignored. If it is placed at the end, after all display objects, it disables screen erase, producing a "kaleidoscope" image that smears across the screen as you rotate it. (What plotonly actually does inside the program is to stop both the storage of input points into the array and also the clearance of the offscreen bitmap each cycle.)

    Views - An important early step in the editing process is to choose one or more good views in MAGE (including adjusting the zoom and zslab, and recentering, if appropriate). Use 's' on the keyboard to toggle in and out of stereo, and try to choose a size and orientation that is satisfactorily large in mono and that keeps all critically-important parts of the picture inside the frame in stereo. Use the 'save view' function on the 'Other' pulldown menu, first to accumulate your trial views as 1, 2, 3, etc. and then to write them out; then paste the four lines of each view into the .kin file between the caption and the first display object. For the second (third, etc., up to 9) viewpoint specified, edit in a '2' ('3', etc.) into the keywords, such as '@2zoom' or '@2matrix' ('@3matrix', etc.), and those will be applied when 'View2' (View3, etc.) is selected by the reader. See Kin. 2 of Demo2_4b.kin for a simple example. See below for using 'moview' to change views in the steps of an animation.

    Although you need not know the underlying process to set views, what happens is that when bringing in a new kinemage MAGE centers (separately for x, y, and z) and scales the coordinates to fit reasonably into the window; that defines the default zoom factor of 1.0 and the default center. If no view is specified (as, for instance, in a new file from PREKIN), those defaults are used. '@zoom' factors are multipliers of that first scaling. '@center' values are in original x,y,z's, however, so you can calculate your own or put in the coordinates of an atom you want in the center. '@zslab' is in arbitrary pixel-equivalents, where the width of the normal graphics window is 400 pixels; its default value is 200. Most kinemages using '@onewidth' can benefit from reducing the slab a bit to improve depth-cuing, but be sure you try rotating the image to be sure some critical line doesn't disappear immediately. When 'onewidth' is omitted, for line-width depth-cuing, it is often good to increase the zslab significantly. The 9 numbers following '@matrix' are a normal 3x3 orientation matrix specifying a rotation around the center. Default is the identity matrix, which produces a view down the original z axis (not usually especially illuminating).

    Adding lines and/or labels - If you want to add other vectors to the display that are not calculated by PREKIN, you can use the 'Draw new' feature in MAGE (on the 'Other' menu), which enables four different tools for drawing new lines or labels. In the 'draw new' dialog box, you can choose which tool is first turned on, you can choose to shorten or lengthen the lines by some specified amount (for instance, reasonable-looking Hbonds can be drawn with lines shortened by .7A), and/or you can choose to have the ends of the new line unpickable (usually desirable if you shorten or lengthen them).

    When 'drawline' is turned on, it will draw a line between each pair of points selected. The 'construct' tool works like the inverse of 'measures'; that is, you pick a succession of 3 points and are then given a dialog box in which to specify the length, angle, and dihedral of the line to be added, going to a new 4th point. 'Dragline' lets you click on a point and drag out a line in any direction within the plane of the screen. It is useful for placing labels, or for recentering in general positions. 'Labels' will place a label (initially the pointID, but of course it can be edited later) at any point you pick.

    You can undo these lines or labels successively by clicking the 'eraselast' button, and any of the tools can be turned off temporarily (without losing lines) by clicking its button. Once you have a set of lines and/or labels that you like, they can be written to a file by choosing the 'Draw new' menu item again and clicking its 'Write file' option. To delete all new lines and labels, turn off 'draw new' in its dialog box. Refer to the tutorial in Kin. 5 of Demo2_4a.kin for further details about using 'measures' and 'draw new'.

    Groups, subgroups, and lists - Although PREKIN will automatically produce some useful groupings, you will probably want to rearrange or add display objects to get across the point of your kinemage. For instance, you may want a separate button, and a different color, for one or more significant side chains. Copy and paste an @subgroup and an @vectorlist line onto the end of your file, and cut and copy those sidechain vectors below them. Then edit the names in curly braces and the color name on the vectorlist line. Refer to Kin. 1 of Demo2_4b.kin to see the appearance and names of the colors, and for suggestions on color usage. If you don't want a second button to appear for the vectorlist, then add 'dominant' to the @group or @subgroup line. The parameter 'nobutton' blocks creation of a button for that display object. Use both 'nobutton' and 'dominant' to do animation among more groups than you want on the button panel (up to the limit of 50 groups). If you want either a whole group or a particular vectorlist to be turned off when the kinemage first comes up, then add an 'off' parameter (there will be a button, but it will not be checked).

    Master buttons - Although the basic heirarchy for MAGE display objects has only three levels (group; subgroup; and vectorlist, dotlist, or labellist), it is possible to set up button controls for display objects organized in groupings orthogonal to that basic heirarchy. That is done by adding the parameter "master= {masterbuttonname}" to the first line of every group, subgroup, or vectorlist (or dotlist or labellist) you want included in that grouping; MAGE will create a master button for each masterbuttonname and add them to the bottom of the button panel. From the reader's point of view, such master buttons act just like any other buttons, with the exception that under some conditions you may need to click them off and on again before their display object appears. Master buttons work for lists that are hidden under a dominant group or subgroup, which can reduce clutter on the button panel as well as allow, for example, the sidechains on all animatable groups to be turned on and off with a single button-click. Master buttons are used in many of the kinemages in Demo2_4a.kin and Demo2_4b.kin.

    To set up an animation, add the parameter 'animate' on the keyword line of each group to be animated. Other groups without that parameter will be shown throughout the animation if they are turned on. Animation will cycle through up to 50 groups so designated, but remember that the total number of point triples displayed cannot exceed 3500 in a kinemage for general distribution. (For your own purposes, it is possible to increase that limit if you are using a fast machine, by a choice in the initial dialog box when running MAGE.) A second, separate animation can be specified with the parameter '2animate' for each of its groups.

    Animation steps can change view, by including the parameter 'moview= i' on the first line of the animated group; View i will then be used to show that group. Kin. 3 of Demo2_4b.kin is an example of this sort of animated tour using moview. Remember that if a moview animation has been set up, then an individual group may not appear on screen if it is turned on from the button panel (which does not change the view).

    If the keyword '@compare' is included in the kinemage, then the first two animate groups will be shown side-by-side (in a divided window that looks much like the stereo setup), and mouse rotations will move the two in equivalent ways. If there are more than two such groups, then the 'switch' button will allow them to be compared two at a time, successively. 'Compare' can also be turned on inside MAGE, on the Kludges submenu. The stereo and compare functions are incompatible, so when one is turned on the other cannot be.

    Instances - For complex animations that repeat many display objects, instancing can be used to avoid repeating all those coordinate triples. A new list (vectorlist, dotlist, or labellist), subgroup, or group may include a parameter 'instance= {objname}', where objname is exactly the same character string that appeared in curly brackets for the previous display object that you now want to repeat. The objname must be unique - that is, if you are instancing a list, then one and only one list can have that objname, including the new one; an extra space is enough to give uniqueness. This new display object cannot have any coordinate triples under it, and it is not possible to instance more than one object on a single line. Kin. 3 of Demo2_4b.kin uses instancing in an animation sequence. Normally instances "inherit" the color and master button of their original, but instancing can also be used to repeat a display object but with a new color, by giving a new color parameter.

    Comments - It is possible to add comments, that can give information to someone editing the file but are completely ignored by MAGE. They are enclosed by < >, and must be all on one line. PREKIN generates a comment for each Hbond, giving its length. Some uses of author comments might be to flag what was shown in each view, or to give the residue number in a labellist that writes { G} next to each Gly Calpha as a substitute for a sidechain. A comment should preferably be located before the point triple it refers to, in order to be handled correctly by the journal utility program that strips out redundant characters from kinemage files. (If you want a copy of that utility, called Procrust, let us know.)

    Local rotations - For showing symmetry-related pieces of structure, it is possible to use '@localrotation' (a 3x3 rotation matrix) and '@localcenter' (coord. of rotation axis) applied to a second copy of the original coordinates (instancing cannot be used in this case), rather than calculating the new coordinates outside the program. For example, the matrices given in PDB file headers for most virus coat proteins can be used to show multiple subunits in MAGE; the virus case does not need a localcenter, because that center is at 0,0,0 in their coordinate system. If something else follows the rotated group, then use '@endlocalrotation' to separate them. If '@localcenter' is used by itself, then it just acts as a translation operation. Its scope is ended with '@endlocalcenter'.

    In general, keep looking at your kinemage in MAGE and re-editing the file until it suits you. Look at other *.kin files as examples for how to achieve particular effects.

    LIST OF KEYWORDS for MAGE:

    (dot in @.text and @.kinemage inserted, so they won't do anything here)
    ('i' stands for an integer, 'f' for a floating-point number)

    • @.text what follows is put in text window, until @.kinemage or EOF
    • @.kinemage i starts a new kinemage; numbers should be unique and monotonic
    • @caption what follows goes in caption window, until another keyword
    • @onewidth makes all lines 2 pixels wide (if omitted, width depends on z)
    • @thinline makes all lines 1 pixel wide
    • @perspective replaces normal orthographic projection
    • @whitebkg white background, not black (uses alternate colors)
    • @compare makes side-by-side comparison of animate groups
    • @multibin i improves fineness of hidden-line removal
    • @keepstereo invokes stereo, for rest of session (can be turned off manually)
    • @stereoangle f change stereo angle (default is 6 degrees, wall-eye stereo)
    • @keepthinline invokes thinline, for rest of session (speeds rotation, esp. on PC)
    • @keepperspective invokes perspective, for rest of session
    • @noscale initial scaling and centering will not be done (watch out!)
    • @plotonly disables rotation, so stays in 2-D
    • @zoom f scaling for startup view (1.0 nearly fills window)
    • @2zoom f scaling for View2
    • @9zoom f
    • @zslab i zslab (depth of window in and out of screen) in startup view
    • @2zslab i zslab for View2
    • @9zslab i
    • @center f f f x, y, and z of center of rotation and placement (in orig. coords.)
    • @2center f f f center for View2
    • @9center f f f
    • @matrix f f f f f f f f f 3x3 orientation matrix for startup view
    • @2matrix f f f f f f f f f 3x3 orientation matrix for View2
    • @9matrix f f f f f f f f f
    • @plotonly (before all points) gives 2-D plot with no rotation, no point limit
    • @plotonly (after all points) gives no-erase "kaleidoscope" image; rotation smears
    • @localrotation f f f f f f f f f rotation matrix applied just to part of file
    • @endlocalrotation ends part to be rotated or rot. & cen., if more follow in kin.
    • @localcenter f f f with rot: vector to axis, - before and + after rot; alone: just +
    • @endlocalcenter ends part to be translated, if localcenter used without rot.
    • @group { } high-level display object (button name in {}, up to 11 char.)
    • @subgroup { } mid-level display object (button name in {}, up to approx. 10 char.)
    • @vectorlist { } list of lines, low-level (button name in {}, up to approx. 9 char.)
    • { } P x, y, z { } L x, y, z individual vectorlist entry (pointID in {}, shown on pick)
    • @dotlist { } list of dots
    • { } x, y, z individual dotlist entry (pointID in {}, shown when point picked)
    • @labellist { } list of labels
    • { } x, y, z individual labellist entry (label in {} written on screen at that point)

      LIST OF (optional) PARAMETERS that MODIFY KEYWORDS, for MAGE:
      (in any order, between keyword and line end, for groups, subgroups, and lists)

    • color= c (only for lists) c value is color name: see Kin.1 of Demo2_4b.kin
    • master= { } master button will control all objects with same {} in master param.
    • off object will start out turned off
    • dominant no buttons for objects below it in heirarchy (for groups or subgroups)
    • nobutton no button for this object (esp. for groups)
    • animate group in an animation series (only for groups; button shows *)
    • 2animate group in 2nd animated series (only for groups; button shows %)
    • moview= i use view i (only for animate groups)
    • instance= { } repeats the list, subgroup, or group that had unique exact name in { }
    • < > ignored comment (also OK on coordinate line, before a point triple)