Reference Manual
Table of Contents
Vince is started by typing "Vince" at the shell prompt (provided that Vince resides in one of the directories specified in your PATH environment variable). Once it is running, commands are issued to Vince via pull-down menus.
Vince requires X-Windows to be running. If your display and the system where Vince is to run are different, the environment variable DISPLAY must be set to the current display. For example, if you are connected to vp4.med.harvard.edu via rlogin or a telnet connection from odin.med.harvard.edu, the DISPLAY environment variable should be set to odin.med.harvard.edu:0.
Furthermore, Vince requires a copy of the file Residues.dat to reside in the current working directory. A version that contains residue definitions for the twenty common amino acids can be found in the Rowland NMR Toolkit executable (exe) directory (where the Vince program resides).
If you do not like Vince's default colors, you can change its appearance. The easiest way is to place entries specifying the foreground and background colors in the .Xdefaults or .Xresources file in your home directory on the computer where Vince is displayed. A reasonable color scheme could be given by:
Vince*background: wheat3 Vince*foreground: black
Changes to the .Xdefaults file do not normally take effect until the next time you start up X-Windows. But you can force them to take effect immediately by typing the command "xrdb -merge ~/.Xdefaults" in a window running on your local display computer.
The Input pull-down menu provides commands for reading a protein sequence from a Protein Data Bank (PDB) file, reading chemical shift data, reading NOE data, and resetting or exiting the program.
2.1 Read Sequence
Choosing Read Sequence from the Input menu invokes a File Selection Dialog requesting the name of the file to read. Vince scans the file for lines conforming to the ATOM records and SS_BOND records of Protein Data Bank (PDB) files. Vince looks only at the residue number, residue name, and chain identifier in order to extract the sequence; consequently a "fake" PDB file consisting of only one atom record per residue can be used to input the sequence. Each time Vince encounters a new residue, it searches through the Residues.dat file to see if it knows the type of residue that was read. If not, it marks that residue in the sequence as unknown. A summary of the sequence can be displayed using the "Display Sequence Summary" command on the Gallery Menu.
Reset should be selected from the Input Menu if another sequence file is to be read; otherwise both data files will be stored at once, with unpredictable results.
Vince can also capture the protein sequence from certain types of NOE input files (see Read NOE).
Choosing Read Chemical Shift File invokes a File Selection Dialog requesting the name of the Shift File to read. Vince can handle EASY and XEASY shift files; it is able to distinguish between the two formats automatically. After reading the shift data, Vince calculates the chemical shift indices (Wishart and Sykes, Journal of Biomolecular NMR, v4, 171-180, 1994) where appropriate.
Reset the data before you enter in a different Chemical Shift file.
Vince uses reference shifts and ranges stored in the file Residues.dat to compute the CSI. If a shift is greater than the range of reference shifts the CSI is one; if it is less the CSI is minus one. If the shift is within the range the CSI is zero. If the residue is a CYS, then the CA, CB, and CO shifts are adjusted for the presence of a disulfide bond.
Offsets for the proton chemical shifts and for the carbon chemical shifts, which can be set using the Preferences Menu, are added to the chemical shifts before they are compared for the CSI range checking. (The default offsets are zero.) The offsets are useful when non-standard or secondary chemical shift referencing has been used.
Consensus CSIs are calculated for each of the residues in the sequence. Vince first checks to see how many different types of chemical shift data (amide proton, alpha proton, or alpha carbon) were read from the shift file. If there are not more than two different types of shift data present, the consensus defaults to zero. Otherwise, it's 2 out of 3, or 3 out of 4, required to get a consensus of one or minus one.
2.3 Read NOE File
Choosing Read NOE File invokes a File Selection Dialog requesting the format of the NOE file. Vince currently supports XPLOR, DG2, SYBYL, and DIANA formats. After selecting a format, another File Selection Dialog is invoked requesting the filename.
Perform a Reset before you enter in a different NOE file, or the data from both files will be stored at once.
If the format is DG2, SYBYL, or DIANA, Vince will check to see if a sequence has been read in. If not, then Vince will read in the sequence from the NOE file. Thus, these formats allow the sequence and the NOEs to be read in without having a PDB file.
Simple error checking is performed on NOE data. First the atoms are checked to ensure that they belong in their residue type, and then the atoms are checked to see if an individual proton of a methyl group has been referenced. The file Residues.dat is consulted for the atom names belonging to a particular residue; the file contains common synonyms belonging to different atom naming conventions.
2.4 Reset
Choosing Reset will erase the stored sequence, NOEs, and chemical shifts. Do this before entering in new data. Preference and Layout settings are not affected by a Reset.
2.5 Quit
Use this command to terminate execution of Vince.
Display Sequence Summary produces a summary of the current sequence. Residues that Vince does not recognize (i.e., those not present in the file Residues.dat) will be ignored in any sequence summary calculations.
Contents of the sequence summary:
Atoms mentioned in an NOE, but which do not belong to the residue given in the sequence are listed in the Invalid Atom section of the summary. Any individual protons in a methyl group which have been included in an NOE are listed in the Invalid Methyl Proton section of the summary. Residue types which do not occur in Residues.dat are listed in the Unknown Residues section of the summary. These sections will only appear in the summary if there are errors to report.
This command invokes a File Selection Dialog requesting the name of the PostScript file to be written. Vince creates a PostScript file that will reproduce the current graph which is seen when Preview Graph is chosen.
Note that there will be slight differences between the PostScript graph and the screen preview. This is due to differences between X-Windows and PostScript. For example, the PostScript version of an alpha helix is smoother than the version that is seen on screen. However, these variations are very slight.
The program Pspreview, in the Rowland NMR Toolkit, can be used to convert a PostScript file to an Encapsulated PostScript file for use in a variety of Macintosh word processing programs.
3.3 Preview Graph
Once a script file has been read, or data files have been read in and the preferences have been set, the graph can be previewed on screen. You can inspect the graph and make modifications or enter additional data by clicking on various portions of the graph. When a satisfactory graph has been obtained, you should write a PostScript output file. In addition, a script file can be written to save the current graph, so that it can be reloaded during another session.
3.3.1 Modifying the Graph and Interactive Data Entry
Once a preview of the graph has been displayed, many of the characteristics of the graph can be changed interactively by clicking on the part of the graph you wish to modify. Note that while the sequence, the NOEs, and the chemical shifts can be read in from data files, the only way to enter J coupling, secondary structure, hydrogen exchange, or user defined data is interactively or via a script file.
3.3.1.1 Changing the Protein Sequence
When you click on a residue's one letter code along the top of the graph, a selection box will be posted requesting a new one letter code for that residue. Vince will then change that residue in the sequence if the new code is defined in Residues.dat. Otherwise, the new one letter code is ignored.
Note that any data stored for that residue will be erased, since the residue type has changed. You will have to re-enter this data.
3.3.1.2 Modifying a Line of Data
Each line of data has a text label along the left side of the graph, indicating the type of the data. To enter or modify data, you must first select the line to be modified by clicking on the text label. The line's text label will change color to indicate that it has been selected.
Next, select the residue that is to be modified, and a dialog box appropriate for the type of data will appear, allowing you to enter the new data. To select a residue, you may click on the sequence number of the residue along the top of the graph, or click on the graph itself in the space where the data for that residue should be graphed. The graph will then be redrawn to reflect the changes.
NOE data lines are graphed using boxes to represent their strength. The strong NOE boxes are the tallest, and the weak NOE boxes are the shortest. If the NOE spans two or more residues in the sequence, for example daN(i, i+2), the graph will contain stacked lines of staggered boxes. Vince automatically arranges the boxes in a neat staggered format.
You can choose to change an NOE that Vince has read from an NOE file. To enter a different NOE from what is currently shown on the screen, click on the bar depicting the NOE after first selecting the NOE line by clicking on the text label. The Erase option in the NOE dialog will delete any previous NOE value that was entered interactively, revealing the value that Vince read from the NOE data file.
The selection box for NOE modification includes a No NOE option. This choice will cause Vince to leave that residue's NOE box blank in the PostScript output. On screen, a suppressed NOE is represented by a dashed line.
The Undefined option in the selection box for NOE modification is used to indicate that an NOE has special characteristics, for example that it could not be observed due to overlap. This is represented on the graph by an empty outline of a box.
You can write text in the space set aside for an NOE box. This is done by choosing Symbol in the selection box for NOE modification. Another selection box will appear, asking for the text to insert. When the text has been entered, choose the button that is labeled with the desired font, either symbol font or normal.
3.3.1.2.2 CSI Lines
The CSIs are graphed with an axis down the middle of the line. Short boxes are drawn above the center line to indicate a CSI of +1, or below the center line to indicate a CSI of -1. The selection box for CSI modification requests the new CSI for the selected residue: zero, one, or minus one.
3.3.1.2.3 J Coupling Data Lines
J coupling data uses four different types of representations based on the strength of the coupling: an empty box, a filled box, or a one-third or two-thirds filled box. The selection box for J coupling data modification contains each of these choices. Simply click the button labeled with the desired representation.
3.3.1.2.4 Secondary Structure Lines
Secondary structure is represented by cartoons. A coil is drawn where alpha helices are specified, and arrows are drawn where beta sheets are specified. The selection box for secondary structure modification allows the type of secondary structure to be entered residue by residue.
3.3.1.2.5 Hydrogen Exchange Lines
Hydrogen exchange data are graphed with open circles for slow exchange, half filled for medium, and filled circles for fast exchange. The selection box for hydrogen exchange modification allows you to enter the exchange rate for each residue.
3.3.1.2.6 User Defined Lines
User defined lines allow you to include a bar graph of arbitrary data. After you create a user defined line in the Layout Menu, the default text will appear in the label field of the appropriate line. To complete the setup of a user defined line, you need to specify the actual text label to use, the name of a file containing the data, and parameters specifying how the data will be plotted. Do this by clicking on the default text label (for example "User Defined Line 1"). A dialog box will appear, which contains fields for the text label, the data file name, and other parameters.
The first field in the dialog box is for the text string to use for the label. The second field is for the name of the file containing the user data. The format of the file is one residue number and one data value per line, for example:
1 2.01 2 4.23 3 6.24 4 10.67 5 2.19
The dialog box also contains a button for selecting the type of graph. There are two types of bar graphs to choose from. A Centered graph has an axis down the middle to represent zero, with both positive and negative values graphed. An Uncentered graph has boxes aligned along the bottom, with heights proportional to the data values.
The size of the boxes is determined by the Upper and Lower Bounds, which you can set in the dialog box. If the user defined line is of Centered type, then the height of each box is proportional to the absolute value of the data, up to a maximum height defined by the larger of the absolute values of the two bounds. If the user defined line is not Centered, then the height of each box is proportional to (data value - Lower Bound) / (Upper Bound - Lower Bound). Values lower than the Lower Bound have no box, and values greater than or equal to the Upper Bound have the largest height possible.
When you click on Process File in the selection box, Vince will scan the data file for the maximum and minimum data values. These values are displayed in the selection box. If the Upper and Lower Bounds have not already been set, they are automatically set to the maximum and minimum data values found in the file.
You can change the values for the upper and lower bounds, and whether the graph is Centered, whenever you like. Just click on the line's text label when you want to alter its setup.
Vince features a scripting language which can be used to generate a customized graph. All of the commands that can be issued interactively via the menus can be executed via a script. The contents of a script file are case-insensitive (i.e., they can be typed in either upper- or lower-case), except for file names.
4.1 Read Script File
This command invokes a File Selection Dialog requesting the name of the script file to be executed. Commands in the script file are executed immediately.
This command invokes a File Selection Dialog requesting the name of an ouput script file. Vince will create the output file, containing the commands necessary to automatically produce the current graph. All of the preferences and layouts are stored, as well as the name of the last data file of each type that was read in, and any modifications (overrides) to the data that were made. (However, no Preview Graph or Write PostScript File commands are stored; you will need to add them by hand or perform the operations manually.) Note that when the script is used later, the data files must reside in the same positions relative to the working directory as they did at the time the script was saved.
4.3 Script Language Definition
4.3.1 Read File Commands
Read File commands are used at the beginning of a script file to tell Vince where to find sequence, NOE, and chemical shift data. Because the script language allows individual data items to be specified in the script file, a script file does not necessarily have to contain any Read File commands, but if it does, they should appear at the begining of the script. A sequence file, if one is used, should be read before NOE or chemical shift files.
Syntax:
The command line begins with "READ", followed by one of "SEQ", "SHIFT" or "NOE". If the type is "NOE", then the format must be indicated by "XPLOR", "SYBYL", "DG2", or "DIANA". Following those tokens is the file name.
Examples:
READ SEQ DataFiles/SEQ.dat READ SHIFT DataFiles/SHIFT.dat READ NOE XPLOR DataFiles/NOE.dat
4.3.2 J Coupling Data Commands
These commands are used to specify the value of J coupling data for one of four types: JaN, JaB, JBG, or JGD. The letters stand for the remoteness indicators, alpha, amide, beta, gamma, and delta. The type of box that should appear on the graph for each coupling can be specified in the command.
Syntax:
The command line begins with either "JaB", "JaN", "JBG",or "JGD". If the molecule has multiple chains, the next token is the keyword "CHAIN", followed by the chain designator. Next is the type of representation desired, either "WHITE", "LTGREY", "DKGREY", or "BLACK". LTGREY produces a box that is 1/3 filled, and DKGREY produces a box that is 2/3 filled. At the end of the command line comes the list of residue numbers that should be represented by a box of that type.
Examples:
JBG CHAIN A LTGREY 4 8 9 10 12 JaB WHITE 1 3 6 9
4.3.3 Secondary Structure Commands
These commands are used to specify the beginning and ending residues of any alpha helices or beta sheets that exist in the molecule.
Syntax:
The command line begins with SECONDARY, followed by either "HELIX" or "SHEET". If the molecule has multiple chains, the next token is the keyword "CHAIN", followed by the chain designator. At the end of the line are two residue numbers that represent the beginning and end of the helix or sheet.
Examples:
SECONDARY HELIX CHAIN A 23 25 SECONDARY SHEET 20 30
4.3.4 Hydrogen Exchange Commands
These commands are used to specify the amide hydrogen exchange rate for each residue (fast, medium, or slow).
Syntax:
The command line begins with "EXCHANGE". If the molecule has multiple chains, the next token is the keyword "CHAIN", followed by the chain designator. The next token is "FAST", "SLOW", or "MEDIUM", followed by a list of the residues which exhibit that type of exchange.
Examples:
EXCHANGE CHAIN B SLOW 1 2 45 34 EXCHANGE MEDIUM 7 12 3 4 6 8
4.3.5 CSI Commands
These commands are used to specify the value of the Chemical Shift Index for individual residues. If a chemical shift file command is present at the beginning of the script, then the CSIs entered using this command will override the values calculated by Vince from the chemical shift data in the file. If a new chemical shift file is read in later in the script, or subsequent to executing the script, the CSIs computed from the new file data will override the script file.
Syntax:
The command line begins with "CSI". If the molecule has multiple chains, the next token is the keyword "CHAIN", followed by the chain designator. The next token is the type of CSI, which can be: "HA", "CA", "CO", "CB" or "CONSENSUS". Then follows the CSI value, in parentheses, which will be set for all of the residues listed on the line. Lastly is a list of the residue numbers which have that value of the CSI.
Examples:
CSI CHAIN A HA( 1 ) 2 3 56 57 62 CSI CONSENSUS( -1 ) 3 5 7 8 9
These commands are used to specify the strength of NOEs, overriding strengths read in from an NOE file.
The NOEs set explicitly by the script file are not overridden if a new NOE file is read in. Vince stores NOEs that are read from a file seperately from those entered via a script or by interactive modification of an NOE line. The values entered via script or interactive data entry can be "erased" by choosing the Erase option in the NOE modification dialog box. Then the NOE vaue from the last NOE file read operation will be graphed.
There are several types of NOEs that can be set: aN, NN, BN, and aB. The representation that should be plotted for each type of NOE can also be set, and text can also be placed in an NOE box.
Syntax:
The command line begins with type of NOE, which can be "daN", "dBN", "dNN", or "daB". Then follows the remoteness, in parentheses, which specifies the distance in position between the residues of the NOE. For example, daN(3) signifies daN(i,i+3). If the molecule has multiple chains, the next token is the keyword "CHAIN", followed by the chain designator. The following token gives the representation to be used for the NOEs, one of "STRONG", "MEDIUM", "WEAK", "NONE", "UNDEF", or "TEXT". Unless the representation is TEXT, the remainder of the line contains a list of residues. For TEXT representations, the "TEXT" token is followed by the residue number and the text in quotes. If the text should appear in symbol font, follow the quoted text with the token "SYMBOL".
Examples:
In the last example, a Greek letter alpha will appear in the NOE box.
These commands are used to specify all of the characteristics of the graph that can be set from the Preference Menu.
Syntax:
The command line begins with "PREF". The next token is the type of preference to be specified, followed by the value. The preference types and values are:
Examples:
These commands specify the types of data to be graphed and the graph organization. All of the options on the Layout Preferences Menu can be set using these commands.
Syntax:
The command line begins with "LINE" followed by the number of the line to be defined (1 - 10). The next few tokens indicate the type of data to graph on the line. The choices are:
4.3.6 NOE Commands
daN(1) CHAIN A STRONG 1 2 4 6 8 9
daN(2) WEAK 3 4 8
daB(3) CHAIN B UNDEF 6 14 23
daB(1) CHAIN A TEXT 1 "I am a big, strong NOE"
daN(4) TEXT 24 "a" SYMBOL
4.3.7 Preference Commands
PointSize is: 8, 10, 12, or 14
PREF FONT Helvetica 12
PREF SPACING 3/2
PREF MARGIN 1/4
PREF ORIENT LANDSCAPE
PREF STRONG 2.8
PREF MEDIUM 3.4
PREF CHAIN A
PREF RESIDUES 15
PREF MULTI ON
PREF SECONDARY 0.4
4.3.8 Graph Layout Commands
| daN( 1 ) | daN( 2 ) | daN( 3 ) | daN( 4 ) | dBN( 1 ) |
| dNN( 1 ) | daB( 1 ) | daB( 3 ) | HA CSI | CA CSI |
| CB CSI | CO CSI | CONSENSUS CSI | JaB | JaN |
| JBG | JGD | SECONDARY | EXCHANGE | None |
The number in parentheses following an NOE data type indicates the remoteness. For example, dNN(1) signifies a dNN(i,i+1) NOE.
Examples:
LINE 1 daN( 3 ) LINE 2 dNN( 1 ) LINE 3 HA CSI LINE 4 SECONDARY LINE 5 JaB LINE 6 EXCHANGE LINE 7 None
4.3.9 User Defined Line Commands
These commands are used to specify the contents of the User Defined Lines.
Syntax:
The command line begins with USER followed by the number of the line to be defined (1, 2 or 3). The next token is the name of the file that contains the data. Then comes the label for the line (which must be enclosed in quotes). The optional token CENTER indicates that the plot should be of Centered type; if it is not specified then the plot will be aligned at the bottom. The last two tokens are the lower and upper bounds that define the range of data values to plot.
Examples:
USER 1 UserTest "User One" CENTER 12 26 USER 3 UserTest "Data Values" 0 12.456
4.3.10 Preview Graph Command
This command causes Vince to produce a screen preview of the graph. Note that Vince will in any case automatically produce a preview of the graph when the script is finished.
Syntax:
The command PREVIEW has no arguments.
4.3.11 Write PostScript File Command
This command causes Vince to create a PostScript file containing the current graph.
Syntax:
The only argument to the POSTSCRIPT command is the name of the output file.
Example:
POSTSCRIPT MyGraph.ps
5.1 NOE Preferences (click here for an image of the menu)
This menu allows you to define the NOE distance restraints that correspond to the designations strong, medium, and weak. Vince uses these settings to assign a descriptor when reading in an NOE file. For example, any NOE distance restraint that is less than the upper bound setting for a strong NOE will be defined to be strong. If it is greater than this value but less than the upper bound seting for a medium NOE, then it is defined to be medium. An NOE distance restraint that is greater then the medium NOE upper bound setting is defined to be weak.
If the molecule contains multiple chains, this menu will contain a row of radio buttons, one for each chain. The chain that is chosen is the only chain that will be graphed.
5.2 Page Preferences (click here for an image of the menu)
This menu is used to adjust the spatial arrangement of the graph. The Font, Margins, and Orientation sections are self-explanatory.
The graph consists of one to ten lines of data for each residue in the sequence of the selected chain. Since there may be too many residues to fit across the page, you can break the graph up into several areas, each of which contains all of the lines of data for a portion of the residues in the sequence.
The Residues per Line setting determines how many residues are plotted in each area. The Spacing setting determines how much space separates the areas from each other. If this is set to Automatic, then Vince will adjust the spacing so that the areas fill the entire page. Note that if the graph takes up more space than is available on one page, then Automatic spacing will cause the areas to overlap on the page. Alternatively, the PostScript output file could be scaled to manually to fit on one page, or you could reduce the number of lines on the graph, put more residues on each row, or choose a smaller font to try to get the graph to fit. Vince does not produce multi-page output.
Multiline Output gives you the option to have the NOEs represented by boxes or by letters. When this setting is turned off, the NOE plot requires only one line for each of the NOE types, instead of the multiple lines required for stacked NOE boxes.
The Secondary Structure Scale Height determines the relative height of the secondary structure cartoons. At maximum setting, the cartoons will take up three lines.
5.3 Layout Preferences (click here for an image of the menu)
This menu allows you to choose the types of data to be included in the graph. Together, the box of text on the left and in the middle show the current layout. Vince can graph up to ten lines of data. A layout must be defined before you can perform interactive data entry.
The default layout is "None" for each of the ten available lines. To choose or modify the layout, click on the line number that you would like to change, and click on the new content for that line from the list in the box at the far right of the dialog box. The type of data you select will appear on the corresponding line of the graph.
This command invokes a dialog showing the current setting for the offset of proton chemical shifts or carbon chemical shifts. The values are added to all chemical shifts for the appropriate nucleus when calculating the CSIs. The default for protons and carbon is zero (relative to TSP).
When Vince starts up, it reads the tables stored in the file Residues.dat in the current directory. The default version of the file contains the data for the standard twenty amino acids. You should add data for any unusual residues that occur in the sequence. The instructions for the format of the file can be found in the Residues.dat file itself. You can get a copy of the defult file by clicking here.
