Insight II

13       Utilities

These utilities are included with the Insight program:

· Contour

· Inplot

In the following descriptions, the Purpose section is a brief description of the function and applications for each utility. The Syntax section describes how to use the utility. Examples demonstrate correct usage. Finally, background and incidental information about each utility is included in a Notes section.

Note that these utilities do not appear on the menus within the Insight II program.
Utilities must be invoked at the UNIX operating system prompt.



The Contour utility allows you to contour two- or three-dimensional grid data, such as electron density. It requires an input file of data to be contoured and produces an output file of contours, using linear interpolation, that can be displayed by Insight II. When the Contour utility is run, you specify the name of the output file first, since information about the input file is stored in a header record within the output file to enforce consistent use of existing contour data. This frees you from repeating setup information when appending to an existing output file.


contour [outputfilename [inputfilename]]

inputfilename Specifies a file containing values at each of the points in the grid. The values may be entered with either x or y as the fastest-varying coordinate. It may also contain other parameters which are necessary to align the contours with the reference molecule. If the necessary alignment parameters are not present in the file, the Contour utility attempts to compute them if possible from the data present within the file. If this is not possible, you are prompted for the necessary parameters interactively. The formats for the grid data are described below.

outputfilename The output file contains the actual coordinates (in fractional space) used to draw the contours. The output file also contains two header records. The first describes how the input data was used to create the output. It contains the input filename, the type of input file (unformatted or formatted), the version and release of the present utility, which contour planes were used, which columns were used, and any alignment parameters that are necessary to contour this input. The second header record contains the cell parameters, the fractional space limits, the number of x, y, and z values, and any existing contour levels which have been calculated during a previous run.

Filenames should be compatible with the operating system being used. Any required files not specified on the command line are prompted for by the Contour utility.


There are essentially five types of input files, three formatted and two unformatted (binary). Unformatted files require less disk storage and can be read in quickly. Formatted files may require more disk storage, but you can use the information in random column order, especially those files created by the put graph command within Insight II or the torsion files created by Discover. Within each of these types there is provision for integer or floating-point values. There are parameters which are used to describe how the data is represented in the input file and additional parameters which are used to position the contour relative to the reference molecule. The parameters vary slightly in their meaning for each of the basic file types.

Formatted Files

The formatted files are either a standard grid file or a torsion file. The first line in a formatted file is a title or comment containing any combination of characters. Formatted header lines may not exceed 132 characters in length.

1. Standard Formatted File

The standard grid file consists of five lines of parameters which precede the actual data. The first line is the title as described above. The second line is a format specifier (in FORTRAN style), enclosed in parentheses. This line must begin in column 1, and specify the number of values on a line in the file as well as the format of those values. An implicit single field causes errors. A single field must include the number 1. For example, (1F10.6).

The third line specifies the unit cell parameters associated with the grid: the cell lengths a, b, and c followed by the cell angles alpha, beta, and gamma. These six values must be floating-point numbers, separated by spaces (no commas). If the grid is not in the context of the molecule's unit cell, a, b, and c may be thought of as the distance the grid spans in each direction, x, y, and z. For example, if the grid spans the space from -20 to +10 in x, then a is entered as 30.0. Alpha, beta, and gamma are entered as 90.0 90.0 90.0.

The fourth line specifies the number of x, y, and z intervals which are actually contained in the file. Note that the width of an interval in x must be equal to the width of an interval in y, which must also be equal to the width of an interval in z; the grid is comprised of cubes. The fourth line also contains an optional set of three integers that describe which directions to contour if two-dimensional contouring is desired. By default, all directions are used. All numbers must be integers separated by spaces (no commas). The contour directions should be either 0 or 1, with 0 meaning no contour in this direction and non-zero (i.e., 1) meaning contour in this direction. The directions are x, then y, then z.

The final parameter line specifies which value, x or y, varies fastest in the file, and the starting and ending intervals in x, y, and z. The first number on the line is entered as a 1 or 3. The digit 1 specifies x is the fastest-varying coordinate. The digit 3 specifies y is the fastest varying coordinate. The next six numbers are entered in the order: x start, x end, y start, y end, z start, z end. The six numbers must be integer numbers, separated by spaces (no commas). Note that lines 3 through 5 are required to uniquely locate the starting and ending coordinates of the grid. The following expressions are used to calculate the starting and ending coordinates of the grid:

x start = - (x cell length) (starting interval in x)
(ending x interval - starting x interval)

x end = -(x cell length)(starting interval in x + number x intervals)
(ending x interval - starting x interval)

Similar computations are done for y and z.

An example of the standard formatted file is included as Example 1, below.

2. Graph-Generated Contour File

A graph-generated contour file is created by Insight with the command put graph . . . contour. The format of this file is similar to that of the standard formatted files, except that the data for each function on the original graph is written into a separate column. Thus there is only one contour value on each line, which may be any of the entries on the line.

3. Torsion File

Torsion files are the result of dihedral angle searches by Discover, initiated with the Discover rotors command. The torsion file consists of nine header lines describing how the data was produced by Discover, followed by columns of data. All lines in a torsion file are only 80 characters long, plus one space for the end-of-line character. Any line longer than this is misinterpreted. The first line is the title as described previously. The next group of lines, seven in number, are individual column headers for the data that follows. Lines starting with the word unassigned, as well as blank lines, are considered empty. The number of non-empty lines, in this group of seven, corresponds to the number of actual torsions defined and therefore corresponds to the number of columns of data (plus one more column for the energy data). The program also computes which is the first full row of data, since it is possible to create a torsion file where the first few rows of data are not complete.

After these column descriptors is a single line used for the column headings. The first word within this line is always ENERGY. This is expected. If it is missing, the program is not able to recognize this file as being a formatted torsion file. The names of the dihedral angles being searched follow the ENERGY keyword. Following the header line are columns of data. The first entry in each column is the energy for a given set of dihedral angles, and is followed by the values for the dihedral angles.

Since there is no information about the grid itself, the required parameters are calculated from the actual data. The first step in any column is used for this calculation, so you are limited to only one stepping function per torsion data column being produced. Also, you may not contour columns that use angles containing common bonds that cause both columns to step at the same time.

An example of a torsion input file is included as Example 2, below.

Unformatted Files

Unformatted files are produced using the FORTRAN write statement with only the logical unit specified.

1. Standard Unformatted

The standard unformatted file contains 2 lines of parameters which precede the actual data. The first line is a title or comment which may be up to 132 characters in length. The data may be 2- or 4-byte integer, or 4-byte floating-point (single precision). Each record in the file must contain all of the x values for a given y, or all of the y values for a given x.

The second line contains the parameters necessary for reading the file and for positioning the map relative to the molecule. The first three entries on this line describe the contents of the file. The first entry is a 4-byte integer. Set to 0, it specifies that x is the fastest-varying coordinate, while set to 1 it specifies that y is the fastest. The second entry is a 4-byte integer giving the size of the data in bytes. Its valid values are 2 or 4. The third entry is also an integer. Set to 0 it specifies that the data is floating-point, while set to 1 it specifies that the data is integer.

The next twelve entries are 4-byte floating-point. The first three are the cell lengths. If the cell lengths do not correspond to the molecule's unit cell, then the cell lengths may be thought of as the distance the grid spans in x, y, and z. Following the three cell lengths are the three cell angles. The next six entries are the fractional starting and ending positions for x, y, and z. The fractional coordinates are calculated by dividing the starting or ending coordinate by the cell length. For example, if the cell length in the x direction is 5 angstroms and the desired starting coordinate in the x direction is -5, then the first fractional entry is -1.0 = (-5/5). The six fractional positions are ordered: x start, x end, y start, y end, z start, z end. The final three entries are 4-byte integers which represent the number of x, y, and z intervals respectively.

The remainder of the file contains the actual data. Each record contains all the x values for a given y, or all the y values for a given x.

2. Non-standard Files

There is a provision for using non-standard unformatted files. In this case, all the required parameters must be supplied interactively. Once this is done, subsequent entries into the output file do not require user input since the information is stored within the output header record.


This utility is invoked by entering:

> contour [outputfile inputfile]

1. The program is run by typing the contour command at the operating system prompt. You are prompted interactively for any required information.

2. Once a valid output file has been given, the program determines first, whether the output file exists, and second, whether it contains a valid header record. If there is a header record, you are not prompted for anything except the contour level(s) desired. (In the case of a torsion contour file as input, you are also prompted for information on which columns to contour.) If the specified output file does not exist, you are prompted for some comment to be stored in the new output file. This is displayed on subsequent entries into this file. If the file exists and does not contain a header record (indicating an output file created by previous versions of this program) or if this is a new file, you are then prompted for the input file (if not given in the original command). If the input file is a non-standard unformatted file, you are prompted for missing grid parameters. If the file is a multi-column formatted file (such as a torsion file), you are prompted for which columns of data are to be used and in what order. The default is to contour the data in the first column with a, the fastest-varying coordinate, and b, the second-fastest-varying coordinate following respectively. For torsion files, the default is to contour the data (which is always in the first column and cannot be changed) with a corresponding to the last column, and b and optionally c preceding respectively. Normally these are the fastest-varying columns in the torsion file, assuming standard Discover output. Also, with torsion files it is possible to have columns of data that are not used directly, but that have an effect on the grid location. In other words, these columns need to have fixed angular values to uniquely align the grid within the data file. You are prompted to specify which angle should be fixed within each of these non-data columns. In this case the default is to fix the grid to the first angle in each non-data column. Once the required information has been input, you can specify which contour(s) you want computed.

3. Contouring level specification allows for multiple contour levels to be given by a series of individual contour levels, by automatic stepping based on the starting and stopping contour levels, or by a combination of these two methods. You can step between these boundaries either by giving the number of intervals or by giving the size of each step. In either case, the starting level is always computed and if the number of intervals is given, the stopping level is computed. When specifying the number of intervals, one contour level more than specified is produced. This means that the example input below results in 11 contours, each 0.1 units apart.

> auto 5.0 6.0 number 10

4. Contouring continues until you specify exit (or x), or until 100 contour levels are present within the output file. When using automatic contour level specification, the entire command can be given at one time, as done in the example above, or done in pieces. In the latter case you are prompted for the next piece of information. You are also prompted if an incorrect value is given along the way, such as a stopping contour level that is less than the smallest level within the input file. All information following the incorrect value is lost and must be re-entered.


This example uses a Discover rotors file named acetyl.tor. Prompts provided by the utility are in regular type; required responses are in boldface type:

> contour

> Enter name of output file: acetyl.cnt

> Comment for output file: tor.cnt
Energy (kcal/mol) vs Phi vs Psi for N-acetylalanine-N'-methylamide

> Enter name of the input file: acetyl.tor

> Use default column order (y/n or exit): y

> Each record contains 1 floating point numbers, each having a field width of 9

> Created new contours

> Number of x values (per plane): 37
Number of y values (per plane): 37
Number of z values (planes): 1
Unit cell lengths 360.000000 360.000000 1.000000
Unit cell angles 90.000000 90.000000 90.000000
Fractional limits in x are -0.500 to 0.500
Fractional limits in y are -0.500 to 0.500
Fractional limits in z are -0.500 to 0.500
Loading data for plane 1
The minimum contour value is: -10.327
The maximum contour value is: 9.583

> Enter contour level(s) desired (exit or auto): auto

> Enter starting and stopping contour levels: -10.327 9.583

These responses determine which area of the map is contoured.

> Enter stepping information (number or size): number

> Enter number of intervals: 36

> Direction 0 contains # vectors

> Direction 1 contains # vectors

> Direction 2 contains # vectors

> Enter contour level(s) desired (exit or auto): exit

Example 1: Standard Formatted File

20.00000 1.25 1.25 90.00000 90.00000 90.00000
16 1 1
1 -8 8 -1 0 0 1

-6 14 0 -24 -31 -45 -48 -16 39 102 102 18 -38 -39 -42 -43 -44
-31 -21 -56 -50 -30 17 103 106 107 2 -37 -32 -29 -29 -27 -32 -36
-54 -54 20 95 90 74 62 11 -25 -25 -39 -50 -32 -19 -44 -51 -55
-56 -2 81 110 54 -25 -47 -41 -28 -33 -24 -16 -51 -42 108 215 230

This example specifies that there are 16 intervals in the x direction, 1 interval in the y direction, and 1 interval in the z direction contained in the file. The 16 x intervals span the coordinates -10.0 to 10.0, as calculated from:

20.0 * (-8/(8 - -8))


20.0 * ((-8 + 16)/(8 - -8))

The interval in the y direction spans the coordinates -1.25 to 0.0, as calculated from:

1.25 * (-1/(0 - -1))


1.25 * ((-1 + 1)/(0 - -1))

The interval in the z direction spans the coordinates 0.0 to 1.25, as calculated from:

1.25 * (0/(1 - 0))


1.25 * ((0 + 1)/(1 - 0))

Note that the file contains 68 grid points, since there are 2 z planes, each having 2 y values and 17 x values:

2 * 2 * 17 = 68

Example 2: Torsion Input File


phi ACE 1:C ALA 1:N ALA 1:CA ALA 1:C

psi ALA 2:N ALA 2:CA ALA 2:C N-M 2:N






ENERGY phi psi

15169.1017 0.00

15169.1017 0.00 0.00

60.2420 0.00 120.00

100.2786 0.00 -120.00

15169.1017 0.00 0.00

71.9180 120.00 0.00

62.4917 120.00 120.00

99.2156 120.00 -120.00

71.9180 120.00 0.00

28.7035 -120.00 0.00

15.9646 -120.00 120.00

59.3138 -120.00 -120.00

28.7035 -120.00 0.00

15169.1017 0.00 0.00

60.2420 0.00 120.00

100.2786 0.00 -120.00

15169.1017 0.00 0.00



This procedure creates various device-specific command files from the intermediate plot file (.ipf) created by Insight II (using the Export_Plot command, in the File pulldown). To use this utility, call the Inplot utility from either outside Insight II or by using the Unix command.


inplot device filename [portrait/landscape]
pen# [pen#...]/only pen#]

device Specifies one of the following types of printers:

-Device Default File Extension

postscript .ps

hpgl .hp

eps (encapsulated PostScript) .eps

qms .qms

pict .pict

filename Specifies an input file to be plotted.

portrait, landscape Specifies the orientation of the image on the page. Landscape, the default, puts the x axis of the image along the longest edge of the medium, while portrait places the y axis onto the longest edge. These options are mutually exclusive; only one may be specified in any one command.

scale value Increases the x and y values equally. By default, this value is set to 1.0.

color Creates color (rgb) postscript. This is the default.

gray Creates gray scale postscript. If the gray option is used, all rgb color values are mapped to gray scale. The gray and color options are mutually exclusive; only one may be used in a single command.

pen pen# Remaps the internal pen values to match the plotter, as desired. By default, postscript color is treated as one of these hpgl pens. On hpgl, for example, pen 4 is rgb color red (1.0,0.0,0.0).

only pen# Causes all plotting to be done in the single color corresponding to the pen# given. For example, only 0 causes all plotting to be done in black.

output filename By default, the output filename is the same as the input filename with a different extension, and depends on which device type is selected. The output parameter can be used to override this default value and is useful for trying various combinations of parameters to modify actual results.

banner Creates a single cover page to be printed before the actual image from the input file.

When device is specified as either postscript (which uses a gray scale to approximate coloring) or hpgl (which attempts to duplicate the Insight II color scheme), the pen and only options are valid; the color option is only valid with postscript. Note that the color and gray options are mutually exclusive; only one may be used in a single command. Also note that the pen and only options are mutually exclusive. Specifying hpgl as the device assumes a six-pen plotting device, but this can be overridden either by specifying each pen with values between 0 and 8 (0 meaning pen 1, black) or by specifying only 8. This latter command creates the following default pen scheme for an eight-pen plotter:

Pen # -Color

1 black
2 blue
3 magenta
4 red
5 yellow
6 green
7 cyan
8 black

For six-pen plotters, pen values of 7 or 8 are treated as pen 6.

Postscript uses the Insight II color scheme so that custom coloring is reproduced.


> inplot hpgl figure1 scale .75

> inplot postscript figure1 scale .75 only 8 linewidth 3

> inplot qms figure1 output figure1.plot color



There are two parts to the intermediate file, the header and the body. The header gives information about the number of vectors present within the file, the conversion factor that was used to integerize the vectors, and the Insight II version and release number that created this file. All these fields and their functions are described in more detail later. The body contains pairs of integers telling pen color and line width, and giving the pen up/down commands with the appropriate absolute positions. All this information is stored in binary format to save disk space.

The header is a single record of format given below (C language description):

struct head_t {
int number_of_records;
int conversion_factor;
int version_number;
int release_number;
int filler[16]; /* for later possible information */
} head_type;

The number_of_records field tells how many vectors have been put into the body of this file, making termination of reading independent of end-of-file (eof) markers. Since the vectors are normalized to a range of 0.0 to 1.0 before being written to the intermediate file, integerization simply means multiplying this normalized value by the conversion_factor (which is one quarter the maximum value for a short integer, 16384). The version_number and the release_number are stored so that these intermediate files may be used by later versions of Insight II. The filler is reserved for later use.

Within the body, information is stored compacted to a single integer storage size containing an x,y pair. The format is given below:

struct body_t {
short x;
short y;
} body_type;

The x and y values are the pen position in short integer format. Pen up and down commands are encoded by giving pen down pairs a negative y value, while pen up does not. Since all vectors are positive this can be done without ambiguity. The color and linewidth information are given special negative x control values, with the y value specifying the color and linewidth values. This format allows the same record type to be used for all commands within the body of the file. The control values (negative x) are given below:

-1 end card

-2 pen value card

-3 linewidth card

-4 RGB color card

-5 string control card

RGB Color Card

This diagram describes the use of the x and y pair stored in the .ipf file. The numbers indicate the number of bits used and the letters are the field descriptors. This usage is mainly for the RGB control card, although other control cards must conform within x. A, B, and C make up the x storage value, and D and E make up the y value. The following table describes the usage of these fields.

Field #bits Usage

A 1 If set, indicates this is control card.
B 8 Holds red color value of RGB system.
C 7 Positive value of control card.
D 8 Holds green color value of RGB system.
E 8 Holds blue color value of RGB system.

The individual RGB values range from 0 to 255, with 0 indicating no color and
255 indicating full saturation.

Examples Using RGB Card

x, y Values Meaning

(-32644, -1) RGB(0,255,255), indicates cyan color
(-4, -256) RGB(255,255,0), indicates yellow color
(-4, 255) RGB(255,0,255), indicates magenta color

There is no range of y values that is enforced upon the control values, but the pen values have an effective range of 0 to 8.

String Control Card

In order to allow fonted text from Insight II to be printed by devices that can and those that cannot handle fonted text, the .ipf file currently contains two representations of fonted character strings. Fonted character strings are stored as ASCII characters and as a series of move commands. The move commands represent the strokes required to produce the characters in the standard inplot font, and consist of records as described above.

This allows drivers for devices capable of plotting with fonts to use the ASCII string and ignore the stroked character data. Likewise, drivers for devices that do not handle fonted text can skip the ASCII string and process the stroke commands.

The string control card contains two control values. The x value is always -5, indicating a string control card. The y value can be -1, -2, or -3, as shown in the table below.

x y Usage

-5 -1 Begin character data
-5 -2 End character data/begin stroked data.
-5 -3 End stroked data.

The first record after the begin character data control card contains string length, font, and point size data encoded as follows:

where field A is the number of characters, field B represents the font, and field C is the point size. Each field is a positive number.

Field B contains a font code. The current Insight II fonts are Courier (B = 1), Helvetica (B = 2), and Times (B = 3).

The following records contain bytes of ASCII codes packed four to a record, with the last record being padded with null characters if necessary.

The -5, -2 string control card indicates the end of ASCII records and the start of stroked data. The end of stroked data is indicated by the -5, -3 control card.

For example, the string "Hello!" in Courier with a point size of 15 is represented by the following (x,y) pairs:

(-5,-1)(2049,15)(18533,27756)(28449,0)(-5,-2)...stroked data...(-5,-3)

Intermediate Plot File Format Examples

> 1000,1000

Moves to position 1000,1000 with the pen down.

> 1000,-1000

Moves to position 1000,1000 with the pen up.

> -2, 4

Changes pen to number 4.

> -3, 2

Changes linewidth to 2.

> -1, --

Indicates end of file; y value does not matter. There should only be one of these per file.

Last updated December 17, 1998 at 04:28PM PST.
Copyright © 1998, Molecular Simulations Inc. All rights reserved.