Running ANSIG

Starting ANSIG

Start up ANSIG by giving the following command, where protein.ctr is the name of your control file: 
	% ansig protein.ctr
It is possible to omit the extension .ctr in the file name; ANSIG will append it automatically to the file name, if it cannot find the file without the extension.

The ANSIG program starts up reading the following files in the given order:

If any error occurs while reading any of these files, then the ANSIG session will most likely not be well set up, and one should quit from ANSIG (command QUIT) and fix the problem before continuing. The error message contains the name of the file and the line and line number where the error occured, so this ought to help in identifying the problem.

Given the dictionary, sequence, spectra and crosspeaks, ANSIG sets up some internal pointers, the assignment table and the NOE list. These tables will be updated after each subsequent change to the crosspeaks made by the user.

If an initialization file has been specified in the control file, then it is read next. If there is any error here, then the setup will be incomplete, but it may be possible to perform some useful operations anyway. If an error occurs, then usually no graphics windows appear. Of course, one should sort out the problem before continuing.

Giving commands

There are basically two ways for the user to give commands to the ANSIG program. Either one types in a command at the ANSIG> prompt in the so-called tty window, or one clicks on a command in the graphics menu window using the middle mouse button.

The first way can be used only when the mode of the ANSIG program is tty input, while the second way is used when ANSIG is in graphics input mode. ANSIG starts up in tty mode.

tty input mode

Test the tty mode by giving some simple commands. For example: 
	ANSIG> SHOW SPECTRUM
outputs a list of all spectra in the spd file, and some info. 
	ANSIG> SHOW VARIABLES
outputs the names and values of all currently defined variables, if any.

The commands given are not case-sensitive; they are converted to upper-case before interpretation. Some arguments to commands (like spectrum names) are case-sensitive, however. Commands can be abbreviated by omitting trailing characters while still remaining unique; some commands can even be abbreviated to one single character.

graphics input mode

To switch from tty mode to graphics mode, give the command GRAPHICS (which may be abbreviated to G). If no graphics windows have been created before, a window will now be created. The mouse pointer can now be used to manipulate the spectra in the graphics window and to give commands using the graphics menu window.

To switch from graphics mode to back to the tty, click on the command tty in the graphics menu window, or hit the T key on the keyboard while the mouse pointer is in an ANSIG graphics window.

A command is activated by picking the item with the mouse pointer: click on it with the middle mouse button. If the command needs arguments, a prompt text will appear in red in the upper part of the menu window. When all prompts have been answered, the command will execute.

If one makes a mistake and gives the wrong command, then one can pick the item abort in the graphics menu window. This will stop the current command, unless it has already started executing. The abort command will work at any point where the ANSIG program asks for input from the graphics. It is not possible to stop the execution of a command once it has started. The single exception to this is the contour calculation, which may be interrupted if the spectrum being contoured is a 3D or 4D spectrum.

The middle mouse button is used to pick objects, for instance the crosspeaks, the rulers, non-plane scroll bars or menu items in the graphics menu window. When picking objects which may overlap, such as crosspeaks or rulers, one must position the pointer so that there is only one pickable object close to it (experiment to get a feeling for how close this is). The ANSIG program cannot decide which object you actually wanted to pick if there is more than one object close to the pointer, and the program will issue a complaint and ask you to pick the intended object again. Scale up the display if you have difficulty positioning the pointer.

Translating and scaling spectra

When the graphics input mode is on, it is possible to view the different areas of the spectra by translating the spectra in a window. Essentially, one shoves around the spectra in a window using the mouse. Place the mouse pointer inside the window, press and hold down the left mouse button, and move the mouse pointer. The spectra will move so that the point at which the mouse pointer was located will stay under the mouse pointer. Release the left mouse button to stop the translation.

To zoom or shrink the spectra in a window, press and hold down the right mouse button, and move it up or down (vertically). The spectra in the window will scale up or down.

Current spectrum area

Many common operations (such as donwloading contours, or crosspeaks to the graphics display) operate in relation to a parameter called the current spectrum area. This defines the area of the spectra within which such operations should be performed.

On startup, the current spectrum area encompasses the entire chemical-shift range for all expnuclei. Usually, one should not download contours as the first thing after having started up the ANSIG program, since all contours in the entire spectrum would be downloaded. One normally sets the current spectrum area to the area of interest first.

The current spectrum area can be set in several different ways: The command SET AREA can be used in tty input mode. The item current in the graphics menu window can be picked using the mouse middle button while in graphics input mode. Various AL procedures and their calling macros can set the current spectrum area during execution.

The command SHOW AREA outputs the current area. The item area in the graphics menu window forces the area shown in the current window to encompass the current spectrum area.

The notion of a current spectrum area is complicated by the presence of several different expnuclei (1H, 15N, 13C and 31P), of spectra which span different chemical shift spaces, and the ability to display different planes of the spectra in different window. The solution adopted in ANSIG is to define the current spectrum area in terms of a pseudo-nucleus ppm unit, which is converted into the proper expnucleus ppm value when needed. The mapping of the dimensions of each spectrum to the dimensions of a particular graphics window is taken care of automatically by ANSIG.

The current spectrum area is also defined by the current position of the non-plane scroll bars to the right in the window. This is important to understand when contours for 3D and 4D spectra are to be downloaded; the non-plane scroll bars must have been moved and sized to the proper position before one does current; otherwise, the current spectrum area may include a far larger area than one expected. This is a common error for beginners.

Current window

Since it is possible to have several different windows displayed in ANSIG, there is a parameter called the current window, which determines how various actions are to be performed. For instance, if the user downloads the contours within the current spectrum area, then this area is taken to be that shown in the current window. This means that the current spectrum area should be set while the correct window is the current window, or the wrong area of the spectrum may be used.

The current window can be changed simply by clicking any mouse button while within the window that is to be made current. It is also possible to set the current window with the command GRAPHICS WINDOW and from within AL procedures.

The current window is flagged by the text label current in red in its upper right corner.

Contour levels and files

Contours are either computed on the fly from the spectrum matrix, or they are loaded from a precomputed contour file. In the first case, the spectrum matrix must be present. In the second case, the contour file must be present.

In the first case, the contour levels need to be specified. This is usually done in the spectrum description file, although the values can be changed while running ANSIG.

Note, though, that changing the contour level values while inside ANSIG does not change the values in the spd file; when quitting ANSIG, the new values will be lost. Therefore, one should change the values in the spd file immediately, using a text editor.

In the second case contour files must have been computed. This is done with the command CONTOURS, which presupposes that the contour levels have been defined, and that the spectrum matrix file is available.

Loading the contours from contour files becomes more advantageous with increased dimensionality of the spectra: for 2D spectra, it is usually not worth the effort to precompute contour files; for 3D files it usually is, and for 4D files it nearly always is a good idea to precompute contour files. The reason is that the procedure which accesses the spectrum matrices for on-the-fly contouring becomes relatively inefficient for 3D and 4D spectra. Loading contours The downloading of contours for a spectrum in a graphics window requires that the current spectrum area has been set. As a matter of good practice, always define the current spectrum area just before downloading the contours. In this way one minimizes the strange surprises one can get if the current spectrum area is something different from what one needs. In the worst case, ANSIG will try to compute the contours for an entire 4D spectrum if the current spectrum area is badly defined, in which case the computation may take a very, very long time. It is possible to stop a contour calculation by pressing the ESC key while in graphics input mode. It is not possible to stop a contour calculation while in tty mode.

If you have already downloaded contours to a certain area of a spectrum, then avoid downloading contours to the same area. ANSIG cannot discover that the contours are already there, so another copy of the contours will be loaded. This will slow down ANSIG unnecessarily. Usually, one would download the contours to those areas that one wants to work in as one goes along, and when ANSIG becomes too slow, one deletes all contours in the spectrum (or all spectra), and reloads the parts one wants to look at.

Contours are removed from the graphics window by picking the item clear and then answering contours when the prompt what? appears, and then giving the spectrum. All contours in that spectrum (and in that view) will be cleared. It is not possible to clear only certain parts of the contours in a spectrum.

Loading crosspeaks

Crosspeaks are loaded to the graphics for a spectrum by picking the item crosspeaks in the graphics menu window and then giving the spectrum. The crosspeaks within the current spectrum area will be loaded. In contrast to the contours, the ANSIG program keeps track of which crosspeaks have been loaded and which not, so there is no danger of downloading multiple copies of the same crosspeak.

It is usually a good idea to download all crosspeaks in a spectrum to the area that one is going to work in, especially if one is going to do peak-picking. If one does not download all crosspeaks, there is a risk that one picks a crosspeak on top of another crosspeak, which is present in the database, but which has not been loaded to the graphics. It is very difficult and annoying to try to pick a crosspeak if it is on top of or very close to another crosspeak.

To remove the crosspeaks from display, pick the item clear followed by the item crosspeaks at the what? prompt. All crosspeaks in the spectrum will be removed from display, regardless of view. It is not possible to remove only some crosspeaks from view. Note that removing crosspeaks from view by clear does not affect the presence of the crosspeaks in the database. To actually delete crosspeaks, use the item delete.

Rulers

The rulers can be picked and moved with the middle mouse button: pick the ruler, hold down the middle mouse button and drag the ruler to the new position.

It is possible to connect rulers to each other, so that moving a ruler in one window will move the corresponding ruler in another window. By default, the rulers in windows that have the same expnucleus plane will be connected to each other.

It is not possible to move both rulers at once; if one tries to pick (mistakenly or otherwise) more than one object at once, the ANSIG program will complain, since it cannot decide which object you actually want to pick.

Picking the item ruler in the graphics menu window will output the current position of the rulers in ppm.

3D and 4D graphics

To view 3D and 4D spectra, ANSIG displays the spectra in a view of some given 2D plane out of the spectrum, while allowing quick scrolling of the other, so-called non-plane dimensions. How spectra are viewed in different graphics windows is decided in two steps.

First, one must defined which so-called expnucleus plane is to be viewed in a particular graphics windows. By default, every window has the 1H-1H expnucleus plane, allowing only the 1H-1H plane(s) of spectra to be viewed in it. It is possible to change this using the GRAPHICS PLANE command. The item plane in the graphics menu window can also be used for this.

Second, one chooses the 2D plane in the spectrum to view in the given graphics window. The command GRAPHICS VIEW is used for this, which is available as the command view in the graphics menu window.

The idea is that a graphics window allows access to one particular 2D plane in chemical-shift space, for example 1H-1H (the default), or 1H-13C, or 15N-13C. Within this window it is possible to choose any matching view from any spectrum having such a plane.

Picking crosspeaks

There is currently an automatic crosspeak-pick procedure only for 2D spectra. It is controlled by the noise level set for the spectrum, and by the current spectrum area. A crosspeak is picked if its highest data point value is above the noise level, and if it is inside the current spectrum area. Additionally, the crosspeak must be outside of any masks, which may be of two kinds: Rectangular masks and the diagonal mask.

The interactive crosspeak picking procedure can be used for all spectra. The command is best used when in graphics input mode, and works by picking the pick keyword in the graphics menu, and then the spectrum name for the spectrum in which the crosspeak is, and then one indicates the position in the spectrum by pointing and clicking in a graphics window when the cursor is pointed at the position.

The coordinates of the mouse cursor when the user clicks the middle button on the mouse becomes the coordinates of the new crosspeak. If the spectrum is 3D or 4D, then the coordinate of the new crosspeak in the non-plane dimension(s) is determined by the position of the non-plane scroll bars in the graphics window where the cursor was; the middle of the chemical shift interval displayed in the relevant dimension is used. This means that a good strategy is to reduce the non-plane scroll bars to encompass just the plane in which one wants to crosspeak to be, before one activates the pick item. Note that crosspeaks do not have to be located exactly in a spectrum plane.

See also: CROSSPEAKS EXTRACT, SET CURRENT, SET DIAGONAL, SET MASK, SHOW AREA, SHOW DIAGONAL, SHOW MASK and GRAPHICS PICK.

Assigning crosspeaks

The assignment fields of a crosspeak may in principle contain any combination of 4 characters. However, ANSIG expects certain data to be entered into the available assignment fields for each crosspeak. This allows ANSIG to keep and update internal tables such as the assignment (chemical shift) tables, and the NOE list. The effect of misusing the assignment fields of a crosspeak is that the crosspeak will not influence the assignment tables or the NOE list in the way it should.

A crosspeak has three different assignment fields for each F dimension. The first is the sequence field, in which the residue name (=number) of a residue in the sequence should be. The second is the residue field, which should contain the residue type, as specified in the dictionary. The third field is the nucleus (spin) assignment.

An assignment field can be filled in only if it is empty; ANSIG does not allow any change to a non-blank assignment field except a straight deletion of the current content. In order to modify an assignment, one must first delete the old assignment before a new assignment can be filled in. If the other assignment fields for the relevant F dimension have been filled in, then ANSIG will make consistency checks of the new assignment. For example, if the nucleus field contains "HN", then the residue type field may not contain "Pro". Also, if a sequence assignment is made, then the residue type field will be filled in automatically by ANSIG with the corresponding residue type as determined by the sequence.

To fill in an assignment field of a crosspeak, pick either of the items sequence, residue or nucleus depending on which field is to be assigned. Next, define the value to fill into the assignment field. Typically, this is done by picking an appropriate item in the protein sequence scrollable menu in the graphics menu window. It is also possible to type in the value from the keyboard, and finishing the string by . Next, one picks the relevant F dimension item, and finally the crosspeak to assign. If there is a consistency problem, then ANSIG will complain, and the assignment will not be made.

In order to remove an assignment, use the deassign item in the graphics menu. This command will ask for what to deassign (sequence, residue or nucleus) and the F dimensions, and the crosspeak.

Note that both the making and removing of assignments will be transferred along any connections that have been made for the crosspeak.

Assignment list

When the assignment fields in an F dimension contain a complete sequence-specific assignment, then that coordinate of the crosspeak contributes to the assignment lists kept by ANSIG. Incomplete assignments, or assignments that cannot be interpreted by ANSIG as sequence-specific assignments are ignored for this purpose.

ANSIG can keep track of separate assignment lists for defined sets of spectra. For instance, if there are spectra recorded at more than one temperature, then it is possible to set up ANSIG so that one assignment list is kept for all spectra recorded at each temperature. By default, ANSIG sets up one chemical shift table for each spectrum. By using the keyword equivalent in the spectrum description file it is possible to define which spectra are to be included in one single assignment table.

Each crosspeak which has a given sequence-specific assignment will contribute the the chemical shift value of that assignment. The contribution is weighted by the relative intensity of the crosspeak; strong crosspeaks contribute more. ANSIG keeps track of a standard deviation value for each chemical shift value, which is useful to spot errors made in assignments; when the standard deviation value is high, then there is probably a mistake somewhere in the corresponding sequence-specific assignment.

The assignment list is compiled by ANSIG on startup from the contents of the crosspeaks file and the spectrum description file, and is kept up to date during a session.

Connecting crosspeaks

Relations between crosspeaks can be indicated by connecting them in an appropriate way. For instance, two crosspeaks in different spectra may be corresponding crosspeaks (i.e. located at the same place in chemical shift space, and therefore presumably involving the same set of nuclei), or two crosspeaks may be connected in an F dimension indicating that they have one chemical shift (and one nucleus or spin) in common. The main reason for making these types of connections is that ANSIG will propagate assignment along the connections. If one assigns one crosspeak, then ANSIG will automatically transfer those assignments to other crosspeaks according to how they are connected, directly or indirectly, to the first crosspeak.

This means that it is in principle enough to make a given sequence-specific assignment only once. It is then possible to transfer that assignment to other crosspeaks simply by connecting them to the first crosspeak (directly or indirectly) in the appropriate way. Conversely, if one discovers that an assignment was incorrect, then it can be corrected for all crosspeaks at once by removing it for one crosspeak; the other crosspeaks connected to it will have the relevant assignment removed automatically by ANSIG.

The three possible types of connections that can be made are:

F dimension.
This is used to connect crosspeaks that have one or more chemical shift coordinates equal, indicating that the same nucleus (or spin) is involved in that F dimension. The item connect in the graphics menu is used for making this connection. The ANSIG program figures out which F dimenion(s) are to be connected, based on the chemical shifts of the crosspeaks, and the tolerance values set for the relevant expnuclei. It is possible, but not recommended, to connect crosspeaks in different spectra with each other.

Corresponding spectra.
This is used to indicate crosspeaks in different spectra which are located in the same place in chemical-shift space, and which therefore presumably involve the same set of nuclei (or spins) in all F dimensions. The item correspond in the graphics menu is used for making this connection. The crosspeaks that have been set as corresponding are viewed as a set, and at most one crosspeak from each spectrum may be a member in each set, and one crosspeak can be a member of at most one set of corresponding crosspeaks.

Symmetry relation.
Crosspeaks in the same spectrum located in places in chemical-shift space that are related by global spectral symmetry can be connected to indicate this. This involved explicit symmetry relations for each spectrum, and ANSIG allows only such symmetry connections to be made which satisfy the symmetry relations set for the spectrum in the spectrum description file. The item symmetry in the graphics menu is used for making this connection.

NOE list

When a crosspeak in a NOESY spectrum has been given a complete sequence-specific assignment, then it will contribute to the NOE list managed by ANSIG. The NOE list contains one entry for each pair of sequence-specific nuclei which has at least one NOE assigned to them in a spectrum. If that single NOE is removed (say, by removing the assignment of that crosspeak), then the corresponding entry in the NOE list is removed. If more than one crosspeak contributes to an NOE, then the intensity value of the NOE is an average of the involved crosspeaks. The crosspeak relative intensity value is used for this.

The NOE list is used for the commands that output NOE restraint files. In order to convert the intensity value of an NOE to distance restraints used in some of the restraints files, it is necessary to define intensity classes (typically weak, medium and strong), and then to map these intensity classes to distance intervals. The commands are NOE CLASS and NOE DISTANCE. This is typically done in the "a href="initialization_file.html">initialization file.

Only crosspeaks in spectra which have one experiment defined as NOESY in the spectrum description file are used for the NOE list compilation. It is possible to explicitly exclude given spectra from the NOE list compilation.

The NOE list is compiled by ANSIG on startup from the contents of the crosspeaks file and the spectrum description file, and is kept up to date during a session.

General advice

Keep the crosspeak file, the spectrum matrices and any contour files on a local disk on the machine you are using: ANSIG requires fast access to these files, and there may be unnecessarily annoying delays for the user if the access has to go via the net (using NFS).

Align the spectra carefully before starting picking crosspeaks and assigning them. Although it is possible to fix alignment problems even after having finished the assignments, it is usually messy, and strange errors may appear. Also, the assignment process becomes a lot easier if the spectra are properly aligned from the very start.

Set the backup parameter to 100: this is a small enough value to avoid losing too much work in case of a fatal crash, and large enough to avoid too many delays when the backup crosspeak file is being written. Usually, the writing of the backup crosspeak file is fast, but depending on the file size, the hardware, and other parameters, it may become slower.

Per Kraulis 10 Apr 1996.