Insight II

2       Introduction to Insight II

What is Insight II?

Insight II is a comprehensive graphic molecular modeling program. In conjunction with the molecular mechanics/dynamics program Discover, you can use the Insight II program to build and manipulate virtually any class of molecule or molecular system. In conjunction with other MSI products, you can study molecular properties.

Starting Insight II

From the UNIX shell prompt type:

>	insightII 
Note that this command is case-sensitive. If you encounter problems, check with your system manager to be sure that the program has been fully installed and that your UNIX environment variables are properly defined.

Note: For detailed hardware requirements and installation instructions, refer to the Insight II Products System Guide.

Using Insight II

Building, displaying, and studying molecules is done by issuing commands to the Insight II program. Most commands create and affect objects. Further details on the object types in Insight II can be found at the end of this chapter.


Commands can be issued in three ways: from the keyboard, by selecting commands from pulldowns (menus), or by picking icons. Picking an icon is equivalent to selecting a pulldown or a command from a pulldown. Each command has an equivalent typed and menu form.

Typed commands are entered at the Command: prompt located in the bottom of the Insight II program interface window. The box around the command prompt is referred to as the command area (see Command Area and Command Prompt in Figure 1). Typed commands may also be placed in a file which can be executed using the Source_File command.

If a command is presented in pulldown form, it appears along the left of the interface window or along the top of the window (if the number of parameters associated with the command is particularly large).

Certain key pulldowns and commands can be accessed by clicking on icons. When the Insight II program is started, a palette of icons is provided (see Icon Palette in Figure 1). You may define the last five icon positions to execute different commands.

Although some basic commands are self-contained, most commands require you to input more information than just the command name. These additional pieces of information are referred to as parameters for a command. In the menu version of a command, the parameters are presented as boxes to be filled in. In the typed form of the command, the parameters are listed after the command name and are separated by spaces.

When filling in parameter boxes in a menu, first select the parameter using the mouse. You may type in the parameter from the keyboard, and in some instances a value or object for the parameter can be specified using the mouse. For example, if you need to specify the name of one of several molecules that are currently being displayed, you could type in the name, use the mouse to pick the molecule, or choose the molecule name from a list. All picking and choosing is done by placing the cursor at the desired area of the screen, and pressing the left mouse button. Other ways of using the mouse are described later in this chapter.

Many commands output information of interest. This information is presented in one or more of three general areas: the information area, the textport, and the display window. Commands that generate answers that are in the form of a few numbers, or characters, print the information in the bottom of the screen in the information area (see Information Area in Figure 1). Note that this information area can be scrolled.

Commands that generate large amounts of data print the information in the textport (window) that was used to start Insight II. This textport is made visible automatically, and may be put away with the <Textport on/off> key at the bottom of the window. This key can be activated by pressing the function key <F9> on your keyboard, or by toggling the box on the screen with the mouse.

Some commands produce information that changes depending on subsequent operations. This data is presented at the top of the Insight II window. The display of this information is controlled directly through specific commands, and you cannot alter this display.

Figure 1 . Viewer Module


You can access and control objects in Insight II such as molecules, graphs, and grids in commands by their unique name. You can also manipulate objects, such as translating and rotating using the mouse, function keys, physical dial box and the screen dial box. These manipulations act on the connected object. You can also select atoms that are affected by Insight II commands.

Accessing Objects

By Object Name

Each object in Insight II has a unique name. Insight II provides defaults, which you can change with the Object/Rename command. For details about object names, see the Object Names section later in this chapter.

By Object Connection

Either one object or all objects on the screen are "connected" at all times. The connected object is specified immediately after the Conn Obj line at the lower left corner of the Insight II window, by the object's name, or else the word World. The connected object is affected by the mouse, function keys, and dials.

You can change which object is the connected object using any of the following methods:

Details about how to manipulate connected objects are covered on the following pages.

By Atom Selection

Atoms can be selected with the left mouse button. Selected atoms are shown with a white highlight in line mode or with stripes in stick, ball-and-stick, and CPK modes. Selected atoms can be affected by Insight II commands by referring to the ATOM_SELECTION subset (e.g., Color ATOM_SELECTION Blue). Some commands (particularly in the Sketcher product accessible from the Builder module) use selected atoms directly.

Details about atom selection follow.

Manipulating Objects

You can manipulate objects with the mouse, dials, on-screen dials, or function keys.

Note: In the following descriptions of functionality, the x axis is the axis which lies horizontally in the plane of the screen. The y axis is the axis which lies vertically in the plane of the screen. The z axis is perpendicular to the x and y axes.

Mouse Functions

There are two basic actions you perform with the mouse: moving the mouse to move the cursor on the screen, and pressing mouse buttons. These two actions are combined to carry out a variety of functions, such as accessing a pulldown, choosing commands or parameters, picking a molecule or parts of a molecule on the screen, and rotating, translating, or changing the viewing size of a molecule. These functions are described in Figure 2.

Figure 2 . Mouse Functions

Dial Box Functions

Functions such as rotating, scaling, and translating can also be manipulated using a Silicon Graphics dial box. The dial box functions are described in Figure 3. Rotation speed can be scaled by defining the environment variable DIAL_SPEED as a number from 1 to 100, where the higher the number, the faster the rotation. Note that some dials (dials 5 through 8) are dynamically allocated to specific functions, based on the module you are working in or the current function.

Figure 3 . Dial Box Functions

Slab Thickness Dial

The slab thickness dial (dial 8) adjusts the position and thickness of the z clipping planes. Among other things, the thickness of the slab controls depth cueing. When an object spans the entire z depth, it exhibits maximum depth cueing. When an object spans only a small portion of the z depth it exhibits little depth cueing. This dial can be toggled to change the center of the z clipping planes by depressing the function key labeled Slab Pos/Thick (<F12>). Changing the position of the z clipping planes determines what portions of the object are clipped in z space.

Clipping refers to the undisplaying of a region of an object or those portions of the object that are external beyond the limits of the currently defined viewing window. The current thickness and position settings of the z clipping plane are displayed at the lower corner of the menu.

On-Screen Dial Box Icon

The dial box icon is the set of eight small boxes that appears near the lower left corner of the window. The primary purpose of this icon is to show what function is currently assigned to each of the dials. Each box can be used with the mouse as a slider, controlling the function of the corresponding dial.

To activate a dial box slider, move the cursor into the desired box--for example, x rotation--and depress and hold the left mouse button. The object(s) currently connected to the dials should begin to spin around the x axis. Releasing the mouse button stops the rotation. Note that dial box sliders do not switch function when you move the mouse outside of the box that the button was pressed in. The slider stays active for the original function.

The direction and magnitude of the movement depends on where in the box the cursor is relative to the box's center. To the right of center is positive (clockwise turning of the dial) and to the left is negative.

Figure 4 . Using the Mouse as a Dial Box Control

Function Keys

Across the bottom of the Insight II program's interface screen are a row of boxes with words and numbers. These are function keys. Each function key performs a command. You can use a function key in two ways: you can select it on the screen with the mouse, or you can depress it on the keyboard. For example, function key 6 (on the screen) or <F6> (on the keyboard) causes all windows associated with the current Insight II session to pop to the front of the screen. A brief description of each function key follows:

Function Key Descriptions

<F1> Full Screen. Toggle the Insight II program's window so that the black region of the window fills the entire screen.

<F2> Stereo Sep. Toggles the function of the eighth dial so that it can be used to control the stereo separation for split pair stereo

<F3>, <F4>, <F5>
X, Y, Z Rotate. Rotates the connected object 90 degrees.

<F6> Windows Pop. Raise the Insight II windows so that the main window is above all other applications on the desktop and the subwindows are above the main window.

<F7> Next Torsion. Toggles the function of the right-hand side of the dial box when there is one active torsion so you can navigate through the defined torsions to activate the desired one.

<F8> Anim Frame/Speed. Toggles an animation from being automatically updated to manually updated, or vice versa. This function key also toggles the function of the eighth dial from controlling the speed of the animation to which frame is displayed, or vice versa. This key is only enabled when an animation is present.

<F9> Textport on/off. Toggles the display of the textport window from which Insight II was started. The textport displays information that is too lengthy to be displayed in the information area.

<F10> Connect Object. The dials are connected to the object that is picked immediately after this key is selected. If you need to end the Connect Object command without picking an object, press the function key again.

<F11> Connect World. Automatically connects the dials to world. When the dials are connected to world, all objects on the screen move together.

<F12> Slab Pos/Thick. Toggles the function of the eighth dial from controlling slab thickness to position, or vice versa.

Atom Selection

Atom selection is an interactive, user-defined subset of atoms. This subset is known to the system as ATOM_SELECTION. Refer to the Mouse Graphics figure on page 2-5. The following tools and conventions are used to define this subset.

Box and Lasso

In addition to using the cursor to pick individual atoms, an atom selection can be defined by a box, or by a lasso. A box is defined by clicking and dragging the cursor from one corner of an area to the opposite corner. This method selects all of the atoms, monomers, or molecules within the box. By holding down the <control> key while dragging, a lasso can be used to draw a line around the desired atoms. The Selection_Style icon can be used to toggle whether box or lasso is the default. See Pre-defined Icons on the following pages.

Bond Selection

Clicking on a bond selects both of the atoms connected by the bond.

Toggling Selection

Hold down the <shift> key while selecting to add atoms to, or remove atoms from what you have already selected.

Picking vs. Selecting

Atoms can be selected when no other picking operation is taking place. Other picking operations take precedence when a parameter has focus which has picking associated with it, such as a coordinate parameter. Inking, transforming, and connecting also take precedence over selection. The cursor shape indicates what operation the mouse controls.






NOTE: to make a selection while a picking parameter has focus, hold down the ALT key.


To deselect all atoms, click over empty space.

Selection Levels

Atoms can be selected at three levels, atom, monomer/residue, and molecule. A single click on an atom selects the atom. Double click on an atom to select all the atoms in the residue containing that atom. Triple click to select all the atoms in the molecule.

A default selection level can be set with the Selection_Level icon, discussed on the following pages.

Logging and Playback

Selections are logged so that you can replay logfiles and have the same selections occur. The selection is recorded as a list of values to conserve space in the logfile.

BCL macros can use the ATOM_SELECTION subset, but should not attempt to set selection with the selection playback command.


The Builder module uses selected atoms directly. Select the atoms to be affected and activate the command.

Use the string ATOM_SELECTION in specification parameters such as Molecule Spec to affect selected atoms from commands. ATOM_SELECTION is the subset which holds the selected atoms.


Selected atoms can be moved with the mouse. Position the selection cursor over a selected atom. Next, press and hold the left mouse button until the cursor changes to:


Now you can drag the atoms to their new location. Monitors can be added to help you position the atoms. Note that the movement is in the plane of the screen.


Selected atoms can be deleted by pressing the <Delete> key on the keyboard.

Command Hierarchy

The Insight II program's commands are organized in a hierarchy. At the top of the organization are the modules. Next are the pulldowns, and at the bottom of the hierarchy are the commands.


The base modules are: Viewer, Biopolymer, Builder, Docking, Ampac/Mopac, Analysis, and DeCipher. There are also other modules which may be available depending on your scientific area of interest. Each module is a family of related commands. For example, the Viewer module allows you to view molecules, contours, and other graphical objects in different ways. You can tell what module of commands is active by looking at the window title. Following the Insight II program name and version number is the name of the module (see Current Module Name in Figure 1).


Below modules in the command hierarchy are pulldowns. These are sets of related commands. You can tell which pulldowns exist in the module you are currently in by looking at the top bars of the Insight II program's window. The names of the pulldowns are listed horizontally along these bars (see Pulldowns in Figure 1).

There are more than two dozen pulldowns. Only some of these are present in any one module. For example, only the Analysis module contains the Trajectory pulldown. To execute a command, you must be in a module that includes the pulldown that has that command. For example, if you want to load in atomic trajectory data and animate molecules with it, you must go to the Analysis module. This is required whether you are using menu or typed commands.

The pulldowns listed along the top-most bar are present in every module, and are collectively named the Viewer module. Those along the second menu bar are available in whatever is the current module, but not necessarily in any other module. Some pulldowns are available in more than one module. These appear in the second menu bar whenever you are in those modules.

Several of the most commonly used pulldowns can be accessed either through the menu bar or by picking the appropriate icon from the icon palette. Note that the icon functions do not vary from module to module. The pulldowns (or commands) associated with icons are consistent through all modules.

Figure 5 . Commands in the Molecule Pulldown


Below pulldowns in the command hierarchy are the commands themselves. For example, the Molecule pulldown contains the commands: Get, Put, Set_Defaults, Color, Transparency, Display, Label, Bond_Order, Surface, Render, Ribbon, Color_Ribbon, SecondaryRender, List, Tabulate, and Browse (see Commands in Figure 5). Some commands are unique to only one pulldown, while others may appear in several pulldowns. For example, Transform is the only pulldown containing the Center command (i.e., there is only one Center command in all of the pulldowns). Therefore, when you type in a command that appears in only one pulldown you can always uniquely identify it by just the command name (e.g., Center). A command that appears in more than one pulldown is not guaranteed to be unique. For example, there is a Get command in each of the Molecule, User, and Contour pulldowns (among others). If you want to get a molecule, you use the Get command from the Molecule pulldown, while the Get command from the User pulldown must be specified to get user objects.

Note that the Insight II program provides a default object for each module, and a default object for all modules. The default objects are Molecule and Object. When typing in commands that require an object to uniquely identify the command, the object specification may be omitted if the default object is desired. For example, Get Molecule may be entered as Get. Otherwise, use the command and pulldown name together as in: Get Subset.

Pre-Defined Icons (Icon Palette)

When the Insight II program starts, several icons are defined in the icon palette (see Figure 1). These icons are one of these different types.

Menu Icons

The top six icons (including the MSI logo) access pulldown menus. Clicking one of these icons pops up the specified pulldown. Note the small arrowhead in the lower right corner of most of these icons, to indicate that it accesses a pulldown menu.

accesses the Module menu.

accesses the Spreadsheet menu.

accesses the Graph menu.

accesses the Grid menu.

accesses the Contour menu.

accesses the Forcefield menu.

accesses the Selection_Render menu.

or accesses the Selection_Style menu.

or or accesses the Selection_Level menu.

Atom Selection Icons

The next group of icons act on the current atom selection.

depending on the current selection, measures and reports the position (single atom selected), distance (two atoms), angle (three atoms), or dihedral (four atoms), or suppresses an existing monitor (Measure commands). If a monitor already exists, it is removed.

defines the current selection (two atoms or four atoms) as an active torsion, or deletes the torsion if it already exists. (Torsion).

Subwindow Icons

These icons bring up additional windows.

displays the Text_Browser.

displays the Sideview Window.

Parameter Block Icons

These icons bring up parameter blocks. They are redundant, in that all of these can be brought up from the menu.

Note that on smaller screens, these icons may not appear, to prevent the iconbar from taking up two columns.

bring up the text annotation parameter block (Annotate).

bring up the molecule color parameter block (Color Molecule).

bring up the molecule display parameter block (Display Molecule).

bring up the plot parameter block (Export Plot).

User Definable Icons

numbered buttons are user-definable. See the following section on Customizing Your Environment for more information.

Help Icons

accesses the Pilot online tutorial and training tool (Pilot_Tutorials).

accesses the Insight II Help Viewer (Insight_Help).

Customizing Your Environment

Extensive options are available for modifying your session to best meet your needs. Using commands in the core Viewer module, some of the things you may choose to modify include:

Icon Palette

The Insight II program provides an icon palette which includes buttons for quick access to frequently used commands. The pre-defined icons that automatically appear in Insight II are described in the preceding section. It is easy to substitute your own choices of frequently used commands for the default ones by following these steps:

1.   Use the Session/Button command to override one of the default buttons with your own command. The buttons are numbered from the top, starting with 1. If you would like the icon button press to pop up a parameter block, in the same manner as the default icons, just end the command string with a ^ symbol.

2.   When you override a default button, a new icon appears on that button. Initially, this displays a numeral which corresponds to the button number. If you would like to replace the numeral with an icon of your own, use the following procedure:

a. Create your own insight_data directory. You may already have this. If not, this is accomplished by creating a private directory, then defining
INSIGHT_DATA to point to it. For example:

> mkdir $HOME/insight_data

> setenv INSIGHT_DATA $HOME/insight_data

The Insight program normally finds some data files, including files which define the button icons, in the INSIGHT_DATA directory. If you put your own versions of any of these files in your private INSIGHT_DATA directory, the private versions override the global ones.

b. Create icons (SGI only). The imged tool is a handy way to create an icon. For example, use the following command:

> imged button1.rgb 32 32 -rgb

You can also use other image editing tools such as imgworks to design your icon.

c. Convert the format. To convert from rgb to ximage format (the format which the Insight program reads), use the make_ximage tool. For example:

> make_ximage button1.rgb button1.ximage

This takes button1.rgb as input (the file created with imged) and produces button1.ximage. To replace the numeral icon for a button with your own, put a file called buttonN.ximage, where N is the button number, into your private INSIGHT_DATA directory. For example:

> cp button1.ximage $HOME/insight_data

The next time you start up the Insight program and replace button 1 (you can put the Session/Button command in your startup file) your new icon appears.

Nongraphics Mode

The Insight II program can be run without generating any graphics. At the operating system prompt, the command to run the program unattached is:

>	insightII -at

Backup, Recover, and Autosave Operations

The Session pulldown includes commands that allow you to back up the current objects in the session to a folder in the startup directory. This back up can be performed on demand, or automatically at specified intervals. Similarly, a Recover command is provided for bringing back all previously saved objects (after deleting all existing objects).

Command Logging and Restarting

During each session using the Insight program, a record is kept of the commands you execute. This log is written into a file named WBLOGFILE in your present working directory. When you quit from the program, the WBLOGFILE is renamed to insight.log. If you terminate a session by any means other than using the quit command, the WBLOGFILE is not renamed to insight.log. When you start the Insight program, if the program finds that a WBLOGFILE already exists in your present working directory, it is renamed to and a new WBLOGFILE is created. The WBLOGFILE,, and insight.log files are normal text files that you can look at with any editor or with such UNIX commands as more or cat. The log files contain a history of the commands that were executed in a given session. All commands appear in their typed form, even if they were originally executed from a menu. However, menu commands are denoted by several special characters at the start of the command line in the log file. Once you have started the Insight program, a log file can be replayed by using the Source_File command. By default, this command uses the most recent insight.log file, although you can explicitly specify any other filename (such as WBLOGFILE or

It may be convenient to have a variety of commands executed by the Insight program each and every time you enter the program. For example, you may wish to define aliases, or set the default z-plane clipping automatically.

Each time you enter the Insight program, it checks to see if you have a UNIX environment variable called INSIGHT_INIT_GLOBAL defined. (The program checks for a variety of variables. Refer to the Installation instructions in the System Guide for complete information.) If this variable exists, it should be defined as the name of a file (including the path) that contains any commands to be executed when starting the program. If INSIGHT_INIT_GLOBAL is defined, and corresponds to a file that exists, then those commands are executed. If the file to which it refers does not exist, an error is reported. If INSIGHT_INIT_GLOBAL is not defined, no action is taken.

After checking INSIGHT_INIT_GLOBAL, the variable INSIGHT_INIT_LOCAL is checked. If defined, and if the file to which it refers is present, that file is taken as a source of commands which are then executed.

Each of these variables may be used to refer to more than one file of commands. In this case, each file is executed in order. To define a variable which refers to more than one file, list the files in the definition separated by spaces. For example, the following command defines INSIGHT_INIT_LOCAL for two command files:

>	setenv INSIGHT_INIT_LOCAL "my_startup_file /usr/dept/insight_commands"
When starting the Insight program with this definition of INSIGHT_INIT_LOCAL, the commands in my_startup_file are executed, followed by the commands in /usr/dept/insight_commands.

The paths used in your variable definitions may contain environment variables themselves. For example:

>	setenv INSIGHT_DEPT "/usr/dept"

>	setenv INSIGHT_INIT_GLOBAL "$INSIGHT_DEPT/insight_commands"
In this example, the command insightII executes the commands in
/usr/dept/insight_commands when starting up.

A convenient way to use these startup variables is to define
INSIGHT_INIT_GLOBAL for an entire organization or department and
INSIGHT_INIT_LOCAL for personal startup files.

One of the easiest ways to create a file containing your personal startup commands is to copy and edit the insight.log file. Get into the Insight program and interactively run all of the commands that you want performed automatically at startup, then exit. The insight.log file now contains those commands. Rename that file to something like <yourname>.wbrc and edit the file to remove any commands you do not want done automatically. Finally, edit your .login to define INSIGHT_INIT_LOCAL to your personal startup file.

Parameters, Parameter Blocks, and Value-Aids

As mentioned before, some basic commands are self-contained. However, most commands require you to input more information than just the command name. These additional pieces of information are referred to as parameters for a command. In the pulldown version of a command, the parameters appear in blocks along the left- or right-side of the Insight II program's window (see Parameters in Figure 6). Very large parameter blocks may be placed along the top of the window.

Figure 6 . Color Command in the Molecule Pulldown

Parameter Blocks

A parameter block is labeled on top with the name of the command (see Command Name in Figure 6). Within each parameter block are the various parameter boxes. Each parameter box is labeled with the name of that parameter.

There are different kinds of parameters. The most basic parameter consists of a box that can be filled with a string of characters (see Typable Parameters in Figure 6). The characters may be typed from the keyboard. Some such parameters can also be filled by simply selecting an appropriate object. The parameters Object Name, Molecule Name, Molecule Spec, Subset, Monomer, Residue, and Atom are among the parameters that may be filled by typing or selecting.

Some parameters are filled only by selecting (see Non-Typable Parameters in Figure 6). These parameters appear as a series of choices listed vertically with a box next to each choice (see Enumerated Choice Parameter in Figure 6). To specify a choice for such a parameter, position the cursor over the text or over the little box next to the text and press the right-most mouse button. When you have made such a choice, the little box is blackened. Using the mouse in this way is referred to as selecting or choosing.

In addition to enumerated choice parameters, there are lists (see List Parameter in Figure 7). A list parameter appears as a box within which choices are listed vertically. For long lists, only a portion of the choices are shown within the parameter box. You can view different parts of the list by moving the little scroller box on the right side of the parameter box. The scroller box is controlled by placing the cursor over it and pressing down on the right-most mouse button. To make a selection from a list parameter, place the cursor over the item and press the right-most mouse button.

The final kind of non-typable parameter is one whose value is either on or off. Such a parameter appears in a box containing that parameter name next to the word on or off (see on/off Parameter in Figure 7). To change the value between on and off, place the cursor anywhere in the parameter box and press the picking mouse button. This is sometimes referred to as toggling or toggling a parameter on or off.

As mentioned above, a menu command's parameter block starts with the name of the command (in a box) and is followed by each of that command's possible parameters in separate boxes. Below the parameter boxes are two boxes labeled <Cancel> and <Execute>.

Cancel is used to put a command's parameter block away without performing the command, even if some or all of the command's parameters are filled in. A command may be canceled in any of several ways. The most obvious way of canceling a command is to select the <Cancel> box with the mouse. A command is also canceled when a new command is selected from the menu bar (the current command's parameter block is replaced with the new command's parameter block). Commands are also canceled by picking areas of the menu bars where there are no command pulldowns (in the white region past the last pulldown in the bottom menu bar) or by picking the information area below the command line.

Selecting <Execute> causes a command to execute with whatever parameter values are currently set. If not all required parameters are filled in, the <Execute> box is not highlighted and cannot be selected. It becomes accessible when you have given sufficient information to execute the command.

Figure 7 . Element Command in the Modify Pulldown

For many commands, the command name, the parameters, and the <Cancel> and <Execute> boxes are all that exist in the parameter block. Other commands have extra boxes for what are known as value-aids, because they help you to set values in parameters.


Value-aids are found in the value-aid block near the command's parameter block. If there is room, they are placed below the <Cancel> and <Execute> boxes. If there is not enough room there, the value-aid block is placed to the side of the parameter block.

Each value-aid is directly linked to a particular parameter in the parameter block for a command. This linkage is apparent when you look at a value-aid block because it is labeled with the name of the parameter to which it is linked. Below the name of the parameter to which it is linked are one or more boxes which are labeled in the same fashion as parameter boxes.

The most common value-aid is a list of suggested values. For example, when filling in the value for the Molecule Spec parameter, a value-aid pops up displaying a list of all the molecules that exist in the current session. You can select an entry from this value-aid list, and your choice is automatically placed into the parameter that is linked to the value-aid.

Another common value-aid controls the picking level. Some parameters can be filled in by picking objects from the screen. For example, when coloring atoms in a molecule, you must fill in the Molecule Spec parameter. Although you can type in a value, it may be easier to pick a value by pointing to it with the mouse. Note, however, that whenever you pick an object, you need to specify whether you want the pick resolved to the molecule, a subset of the molecule, the monomer or residue, or the specific atom level. This is an important specification. If you specify the molecule name, then all of the atoms in the molecule are affected. Similarly, if you specify a monomer or residue, then only the atoms in that subunit are affected, and if you pick an atom, then only that atom is affected. So whenever you must fill in a value for the Molecule Spec parameter, a value-aid appears. It offers you a set of choices to determine the picking level: Molecule, Subset, Monomer, Residue, or Atom. Note that Monomer and Residue are equivalent when setting the picking level. (See Value-Aid in Figure 6.)

Another common value-aid is the color palette (see Color Palette in Figure 8). This value-aid appears whenever you are filling in a parameter that specifies a color. Placing the cursor over any one of the pre-assigned colors and pressing the picking mouse button selects this color as the one to be used for the command. Similarly, selecting the blended color in corner of the color palette selects that color for the command. The blend can be customized to any mixture of red, green, and blue. Place the cursor inside one of the horizontal color bars and press and hold down the picking button. If the cursor is in the uncolored (white) portion of the bar, the level rises in that bar and the blend is increasingly influenced by the vertical bar's color. In the same manner, holding down the mouse button in the colored region of the bar de-emphasizes that color in the blend. The blended color is used by picking the box containing the blended color.

Figure 8 . Color Molecule Command Parameter Block


As you fill in parameter values in the menu version of a command, each typable parameter in turn is colored white. The focus is whichever parameter is currently colored yellow. The top-most typable parameter is usually the focus first. The focus parameter is the parameter that currently is affected by typing or picking. If you fill in a value (by typing and hitting <Enter>, by picking an object on the screen, or by using a value-aid), the next typable parameter becomes the focus and now only that parameter can be affected by typing or picking.

Non-typable parameters are never the focus because they cannot be affected by typing or picking objects on the screen (and they never have associated value-aids). You can change values in non-typable parameters at any time without affecting which parameter is the focus.

You can explicitly change the focus at any time by placing the cursor over the desired typable parameter and pressing the picking mouse button.

The black vertical bar (|) is a text cursor showing where text you type is added. You can use the picking mouse button to reposition the cursor. You can also select or edit the region by positioning the mouse, pushing the picking button, and then dragging to the desired location before releasing the mouse. The edit region is highlighted by a black box.

Inactive Parameters

A parameter block includes all of the parameters that can be used for a given command. Depending on the value of some of the parameters, other parameters may not be necessary or appropriate. These parameters are inactive. You can use the Session/Cmd_Display command to control whether inactive parameters are displayed in a light gray color, or are not displayed at all.

For example, consider the Color command in the Molecule pulldown (see Figure 6). It only makes sense to specify R or S chirality when you have chosen Chiral or Pro_Chiral for the Atom_Set enumerated choice parameter. Therefore, unless you first choose Chiral or Pro_Chiral, the R and S boolean parameter boxes are drawn in light gray to indicate that they are inactive.

Parameter Defaults and Suggested Values

Most commands in the Insight II program have default values for some of the parameters. For example, in the Color command in the Molecule pulldown, the default value of the Attribute parameter is Atoms (meaning that, by default, you are coloring atoms rather than Surfaces).

Over the course of a session using the Insight II program, parameters that originally had no defaults may be given default values. For example, when you first start the program, the Molecule Name parameter (common to many commands) does not have any default. But after getting your first molecule (by using commands such as Get in the Molecule pulldown, or by using the commands in the Builder or Biopolymer modules) the Molecule Name parameter is defaulted to the name of the molecule obtained.

As you continue working with the program, the default values for such parameters may change. This is particularly noticeable when you have multiple molecules. The default becomes whatever molecule you used last. Since the same parameter may be used in more than one command, the default propagates from command to command.

At times a parameter may be assigned a default value if the Insight II program can suggest a reasonable value. For example, suppose you are getting the crambin molecule from the Brookhaven library of proteins. In the Get command in the Molecule pulldown, you set the value of the File Name parameter to pdb1crn.ent. When you press <Execute>, the Molecule Name parameter automatically is set to the default value of crn because this is the most common name used for crambin. Naturally, you can change the molecule name to something other than crn if you wish. Such suggested values are intended to make working with the program easier; they are not "written in stone".

The Insight II program makes suggestions at two different times. When you first enter a command's parameter block, your current environment (i.e., what objects exist, etc.) is examined and a first draft of suggestions for parameter values is made. These are the values you find when the parameter block initially appears.

As you fill in parameters (that do not have any value or do not have an acceptable suggested value), more values may be suggested. This is the case in the example described above, where crn was suggested as a value for the Molecule Name parameter in the Get command in the Molecule pulldown. The value crn was derived by your filling in the File Name parameter.

Suggested values are not made for parameters if you type in a command (i.e., you do not use the pulldowns at all). However, if you do not fully type in a command (thus making the Insight II program prompt you for each unfilled parameter) suggested values are presented.

Command Dispatching: Cancel, Execute, and the Trigger Parameter

You can cancel a menu command at any time. To execute a menu command, select the <Execute> button after the parameters are set as you wish.

Some commands automatically execute after you have filled in values for all of the typable parameters. Such commands contain one (and only one) parameter framed by a double-lined box rather than the usual single-lined box. This is the trigger parameter (see Trigger Parameter in Figure 6).

If you have filled in all other typable parameters and you press <Execute> after filling in the trigger parameter, the command automatically executes. You do not have to select the <Execute> box. Therefore, be aware that filling in a value for a trigger parameter may cause the command to execute. Make sure that non-typable parameters are set to the desired values before causing a trigger parameter to execute a command.

Repeat and Activate Modes

After executing certain commands, the menu may reappear. Such a command has entered repeat mode. The Command prompt changes to the word Repeat. You can re-execute the same command (presumably with at least one new parameter value). Or, you can cancel the command.

The execution of some commands (in their menu form) may automatically bring up different but related command menus. Commands which correspond to such secondary menus are referred to as activated commands. While in this mode, the Command prompt changes to the word Activate. Secondary menus are used to step you through a series of commands in a logical fashion. This is done, for example, when creating a graph from atomic trajectory information (with the Construct_Graph command in the Trajectory pulldown). Since creating such a graph involves using several different commands to define axis function data, the logical sequence of commands is activated automatically.

Typed Commands

As mentioned previously, all commands are accessible in a fully typed form. Note that an appropriate module must always be selected before any non-Viewer command can be executed. To select a module by typing, type the name of the module and then the <Enter> key.

There is a direct correspondence between the order of the parameters as they are presented in a parameter block, and the order in which they must be entered when typing in the full command.

When a command is typed in there is no value-aid available to pick choices from. However, the Insight II program prompts for omitted parameters if they are needed, and when available, shows defaults. Default enumerated parameters are immediately followed by the word default, in angle braces: <default>. All other defaults are enclosed in brackets. Pressing <Enter> when defaults are available executes that command using default values.

To execute a command that you have typed, press the <Enter> key. If the parameters necessary to complete the command have been given, the command is executed. If there are missing parameters, the program prompts you for the parameters needed to complete the command. To cancel a typed command before <Enter> has been pressed, you can backspace over each character in the command line. Or, easier still, press the letter u while holding down the <Ctrl> key, or press <Esc>. This clears the command line instantly. You can also use the <Esc> key to cancel a command that is prompting for more input. Commands can be edited in the same way as typable parameters.

If it is not clear to you how to finish a command or how to answer a prompt, you may type a ^ (shift 6) and then hit the enter key. The Insight II program responds by activating a parameter block and setting the values that you have specified up until that point in the command. You may then finish entering the command parameters and execute the command as you normally would for a menu command. The command is logged as a menu command. Note that the ^ must not appear within a quoted string. This procedure does not work for concurrent commands (see next section).

Parameters that were described as "non-typable" in the parameter block description need not be entered in a typed command if the default is desired. However, such parameters must be typed in if a choice other than the default is desired. The three types of parameters that may be omitted when typing in a command are the on/off parameters, the enumerated choice parameters, and the list parameters.

There are basic rules for specifying the different types of parameters described in the parameter blocks.

Parameters must be separated by spaces when entered on a command line. Triplet parameters, which are used to specify three related numbers, such as coordinates (see the Triplet Parameter in Figure 9), must have a comma separating each of the three numbers when they are entered on a command line. There must be no spaces between the numbers and the commas. In the case of a parameter that is text, and where that text includes spaces, all of the text must be enclosed in quotation marks.

For example, suppose you want to label a graph axis as my axis label. The command that you use is Label in the Graph pulldown, and the pertinent parameter is Label Text (see Figure 10). To type in the identical command, you must enclose the label text in quotes. For example:

>	label graph graph1 axis x "my axis label"
where label is the command name, graph is the object, graph1 is the name of the graph or file itself, axis is the value of the Graph Label Level parameter, x is the value of the Graph Axis parameter, and my axis label is the value of the Label Text parameter.

When a command cannot be understood by the Insight II program, the command that was entered is redisplayed in the command area. The program highlights in reverse video the place in the command that it could not match, at which point a new value can be entered. The command itself can be entered at any time by pressing the <Enter> key. Note that it is not necessary to retype the entire command, only the portion causing the error. If you are having difficulty with a typed command, it may be easier to clear the command with <Ctrl>-u, and issue it using the appropriate pulldown.

Concurrent Commands

Concurrent commands allow you to type a command in the command area while a parameter block is active. Concurrent commands are entered by first selecting the command area, then typing the concurrent command. The command area is selected by moving the mouse to the command area and depressing and releasing the picking mouse button. The command area is colored yellow to signal that a command may be typed in. After the command is entered the parameter block becomes active again, and the menu command can then be executed. Any command in the top menu bar, which does not create or delete an object on the screen, can be entered as a concurrent command.

Figure 9 . Center Command in the Transform Pulldown

On/Off Parameters

When specifying an on/off parameter as on, it may be typed as on, or as the name of the parameter itself. When specifying an on/off parameter as off, it may be typed as off, or as the name of the parameter preceded by a dash (-).

For example, the Distance command has the parameter Monitor. When the parameter is on, the distances selected are by default added to the list of atoms monitored as the positions of the atoms change. When this parameter is off, the distance is calculated once, using the current atomic positions, and the atoms specified are not added to the list of monitored atoms.

Figure 10 . Label Command in the Graph Pulldown

The typed forms of the command to enable monitoring of the distance are:

>	distance on 0 10 atom1 atom2

>	distance monitor 0 10 atom1 atom2
The 0 and 10 are the values for the parameter's minimum distance and maximum distance. The typed forms of the command to perform the distance calculation only once are:

>	distance off atom1 atom2

>	distance -monitor atom1 atom2
Atom1 and atom2 must be entered in the proper syntax for atom specification:


Enumerated Parameters

Enumerated parameters are entered by typing the text of the enumerated choice. In the above Distance command example, the Monitor parameter actually controls whether or not an additional enumerated parameter can be specified. The full syntax for the Distance command allows for the addition of atoms to the list of atoms having their distances monitored (using the Add option). The command also allows for the deletion of atoms from the list of atoms having their distances monitored (using the Remove option). Finally, the list of atoms may be cleared entirely (using the Clear option). Depending on the enumerated choice selected, additional parameters may be necessary to completely specify the command. In the case of Add, the parameters for the minimum and maximum distances must also be specified.

Following are examples of the Distance command:

>	distance monitor 0 10 atom1 atom2

>	distance monitor add 0 10 atom1 atom2
These two commands add the specified atoms (atom1 and atom2) to the list of atoms having their distances monitored. Note that Add does not have to be entered since it is the default when Monitor is specified. Also note that the 0 and 10 specify the minimum and maximum distance to be used when monitoring the pair of atoms. These specifications are required only when adding to the list.

>	distance monitor delete atom1 atom2
The above command deletes the specified atoms from the list of atoms having their distances monitored.

>	distance monitor clear
This command clears the list of atoms having their distances monitored. Note that the specification of atoms is not necessary in this form of the command.

List Parameters

List parameters are entered by typing the text of the desired choice from the list.

All Other Parameters

All other parameters are entered by typing their desired values.


In addition to its log file, the Insight II program maintains a history of the most recent commands executed. Both typed and menu-entered commands are stored in the history buffer. Commands can be accessed by typing a built-in history command to the command prompt in the command line. Built-in history commands have the following form:

!! Execute the last command again.

!-n Execute the nth command counting back from the last (last=0).

!string Execute the most recent command starting with string.

&& Bring the last command into the command line for editing.

&-n Bring the nth command counting back from the last into the command line.

&string Bring the most recent command starting with string into the command line.

The & form of these commands allows you to see the command and possibly edit it before it is executed. The command is executed when you hit <return>. You may use <Esc> or <Ctrl>-u to clear the command if you decide not to execute it.

The <up arrow> and <down arrow> keys allow you to move through the history buffer, bringing each command into the command line for edit exactly as if you had typed &-n. If you are at the last command and press <down arrow>, it clears the command line.

Default Objects

Commands can always be uniquely identified by both the command name and the object (pulldown).

For example, Get Molecule, Get Contour, and Get User uniquely identify the proper command, while simply typing Get is too ambiguous for the Insight II program. If Get is entered alone, you are prompted with appropriate choices.

For typed commands, the program is set up to assume a default object if one is not provided. For example, unless you reconfigure the Insight II program, the Molecule object is set up as the default. You can type get pdb pdb1crn.ent crn to get the crambin protein from the Brookhaven library of proteins. You do not have to type get molecule pdb pdb1crn.ent crn, because the default object is set up as Molecule.

Even with a default object, you still might find it cumbersome to have to type in the object for commands that are not included in the default object. For example, if the default object is Molecule, and you want to delete some Object (call it crn), you could type delete object crn. This specifies which Delete command to use, since Delete exists in both the Object and other pulldowns (and is therefore not uniquely named). Because this is cumbersome, two default objects are defined. One default is for all of the modules, while the other is defined on a per-module basis.

Unless you change the defaults, the Insight II program is set up with the Molecule object as the all-module default, while Object is the per-module default object for each module. The result is that you can give the commands get pdb pdb1crn.ent crn and delete crn in all modules, and the program uses defaults to resolve the ambiguities.

If you are interested in exploring the notion of default objects further (and, perhaps, would like to set up your own choices for these defaults), use the Default_Cmd_Object choice for the Command Type parameter, in the Environment command in the Session pulldown.

Object Types

Central to the understanding of the Insight II program is the concept of objects. Objects are unique entities which may be addressed by name within the program. There are several different types of objects, each with its own unique characteristics and properties. Throughout this section, reference is made to other sections of this manual where you can find additional information on defining and manipulating these object types.

Molecular Objects

The primary type of object is the molecule. Molecules can come from a variety of sources, including:

· Molecular fragment files (see Get Fragment in the Fragment pulldown)

· Brookhaven Protein Data Bank (see Get Molecule, PDB option)

· Cambridge Crystal Data Base (see Get Molecule, Cambridge option)

· Energy minimization or dynamics simulations performed by the Discover program (see Get Molecule, Archive option, and Get Trajectory in the Trajectory pulldown in the Analysis module)

· External modeling programs (see Get Molecule, Free_Format option)

· Molecular sketch facility (see the Builder)

Regardless of their source, molecules all have several properties in common. They are composed of monomers/residues, and atoms within those monomers/residues. In the case of PDB input, the monomers/residues are amino acids and, generally, there are many monomers/residues per molecule. In the case of input from the Cambridge database files, there is one monomer/residue per molecule and all atoms are in that monomer/residue. Monomers/residues usually have names that reflect their chemical composition (GLY, TRP), and numbers that denote their relative location within the molecule.

The basic characteristics of atoms include atom names (which reflect the atomic type of the atom, such as CG or ND1), and atomic coordinates. Other information which may be known for atoms of a molecule includes the atomic charge, the potential atom parameter type, and the isotropic temperature factor. Molecules can have van der Waals or solvent accessible surfaces, and in the case of proteins, ribbon representations. Molecules can be assigned crystal cell parameters, which may be used for crystal packing and for generating the unit cell environment. Elemental types are also assigned to each atom when molecules are read into the system.

User Objects

The second type of object is the user object. User objects are composed of dots, vectors, or text. Any given user object is composed of one of these types. A user object has only a name. It does not contain any divisible elements which can be referred to separately. The entire user object color can be changed at one time, but individual pieces cannot be changed. For the vector and text types, there can be only one color for the entire object. For the dots type, each dot has an individually specified color.

For further details on the format of the user object definition files, see the online documentation for the Get User command, in the Viewer module.

Contour Objects

The third type of object is the contour. Contours are used in the solution of molecules via x-ray techniques and in the display of output from ab initio programs such as Ampac, Mopac, and DMol. Contouring may also be used for the display of energy levels (e.g., in the creation of phi/psi maps) and in displaying isopotential surfaces from DelPhi and DMol program output. Commands in the Contour pulldown allow you to create contours from grid data. The contour, like a user vector mode object, can have only a single color. Unlike the user object, however, the contour can have selected portions of the object displayed under user control. The Clip Contour command description describes how to control the display of contours.

Assembly Objects

The fourth type of object is the assembly. An assembly is composed of a collection of one or more other objects (including other assemblies). Operations, such as rotations, applied to assemblies act on each of the components of the assembly, treating the components as if they were a single object. Thus, assembly rotations occur about the assembly's center of rotation just as if all of the objects of which the assembly is composed are a single object.

Assemblies can be composed of a mixture of other object types. An assembly could contain the combination of a molecule, an electron density contour, and a user mode text object. These separate objects could then be treated as a single object for the purpose of rotation, translation, or scaling. Assemblies are created with the Associate command, which is located in the Assembly pulldown.

Graph Objects

The fifth type of object is the graph. Graphs can be created from within several different modules of the Insight II program. Graphs are created by defining properties to plot on each of the axes.

A graph may be manipulated in much the same way as any other type of object. Graphs may be scaled, moved, rotated, blanked, or unblanked. Graphs may also have their axis titles colored or relabeled. Graphs may be coupled directly to an animated molecule or molecular system, but need not be.

Spectrum Objects

The sixth type of object is the spectrum (see Figure 11). Spectrums are created with the Create Spectrum command in the Viewer module. Spectrums are used to map data values to colors in a variety of coloring and data analysis commands. They may specify very complex mappings through the use of multiple subranges, each being either a solid color or a color ramp. Commands in the Spectrum pulldown are available to get, put, edit, manipulate, and list spectrums. Spectrums may also be scaled, positioned, copied, renamed, blanked, and listed using commands in the Transform and Object pulldowns in the Viewer module.

Several spectrums are provided with the Insight II program. For example, CHARGE_SPECTRUM is used to color atoms, surfaces, and CPKs according to their partial charge values. Another, TEMP_FACTOR_SPECTRUM, colors atoms, surfaces, and CPKs according to their temperatures.

Figure 11 . Sample Spectrum

Object Names

In addition to becoming familiar with the various object types, it is important to understand the way the Insight II program uses object names. Throughout the command descriptions in the following chapters it is assumed that you understand the format of the object name and its various components. This section describes each of the components of the overall object name, and looks at the various ways these components can be specified and combined.

Every object must have a name. The name must be unique. Commands should not be used as object names.

Molecule names are composed of up to three components:

1.   Object name

2.   Monomer/residue specification

3.   Atom specification

Only molecules have these three components. All other objects have only an object name.

Object Name

The object name is composed of characters taken from the set of alphabetic characters (a-z), the numbers (0-9), and may also include the dollar sign ($) and underscore (_) characters. An object name can begin with any alphabetic character or the dollar sign. The maximum length of an object name is 19 characters, but since it may typed often, a short name is suggested. These are examples of valid object names:




Note that although the dollar sign is allowed, it is not recommended because in some instances the Insight II program uses the object name to generate external filenames. Since the $ character has special meaning in UNIX, its presence in a filename could cause problems.

These are examples of invalid object names:


(Invalid because of the leading underscore.)


(Invalid because it contains an illegal character, @.)

Object names can also be compound. When an object is part of an assembly (see the Associate command), it can be referred to in the context of the assembly by specifying first the assembly name, then a dot to separate the names, then the name of the primitive object. Thus, the name:


refers to the object named PRIMITIVE in the context of the object named ASSEMBLY.

In the special case of a symmetry-replicated molecule (see the Cell and Symmetry commands in the Assembly pulldown), there is a special syntax for the molecule name which allows you to specify a specific replicate of the molecule. The cell object name is followed by the replicate number in parentheses. For example, to refer to the third replicate of the cell object ABC_CELL, specify the object name as:


Only some commands can operate on replicates. See the command descriptions for details.

Monomer/residue Specification

This portion of the overall name exists only for molecules. For example, with a protein this subunit of the molecule can take several forms:

1.   It can be a specific residue type such as LYS or PHE (you can also use the single letter abbreviations). In addition, the charged species of residues may be referenced by using a P to denote plus (+), or an M to denote minus (-). Examples:

ARGP references ARG+

ASPM references ASP-

Capping residues with neutral sidechains are also matched with their normal names. Examples:

ARG matches ARG, ARGn, ARGN, and ARGC

GLY matches GLY, GLYn, GLYN, and GLYC

2.   It can be a specific residue of a protein, such as A312 (residue 312 of the A-chain).

3.   It can be a range of monomers/residues, specified by typing the first and last monomers/residues (inclusive) separated by a dash, such as A132-A150, or 3-12.

4.   It can be a series of individual monomers/residues separated by commas, such as A132,A140,A150, or 3-12,14,15.

5.   It can be a combination of the above, such as A130-A140,LYS,B12.

6.   Two special names, BEG and END, can be used to refer to the first and last residues or monomers, respectively, in the molecule. Thus the range BEG-END refers to all residues or monomers of the molecule.

An additional syntax is allowed in specification of ranges. If the monomer/residue range is followed by the at sign (@) and a number (n), only every nth residue is used. Thus, A130-A140@2 specifies every second monomer/residue beginning with A130 and ending with A140. For the purpose of this feature, specification of a monomer/residue type (e.g., LYS) is considered a range; LYS@3 is every third lysine in the molecule.

The monomer/residue specification is separated from the object by a colon. Thus, to specify all monomers/residues from A150 to A160 of the object TEST, the proper specification is:


Note that all monomer/residue numbers must be unique within a molecule.

Atom Specification

The next portion of the overall object name is the atom specification. It takes very much the same format as the monomer/residue specification. That is, you are allowed to specify single atoms separated by commas, atom ranges separated by dashes, and atom ranges selecting every nth atom using the @. There are no specific atom types or abbreviations for atoms. The atom specification follows the monomer/residue specification, separated by a colon. If there is no actual atom specification, then the atoms are selected from the molecule in the order of their occurrence in the molecule.

For example, consider a molecule that is comprised of the atoms C1, O2, C3, C4, that has one monomer/residue, and is called TEST. The specification:


selects atom C1, then O2, then C3, and finally C4. The specification:


selects atom C1, then C3, then C4, and finally O2 (that is, this specification identifies all C atoms, then all O atoms). The specification:


selects atom C4, then C3, then O2, and finally C1.

For most commands the actual order in which the atoms are selected is unimportant (for example, with the commands Color and Display). However, in some commands matching or pairing of one specification to another is implied. In these cases, the order of atom specification is critical. An example of an order-dependent command is Superimpose.


Pseudoatoms are defined as the instantaneous average of the coordinates of a set of real atoms. For example, the centroid of a phenyl group could be displayed as a pseudo atom created from the six carbon atoms in the ring. Pseudoatoms are referenced in the same way as atoms; their names may be explicitly specified at the time of their creation, or the names may be generated automatically.

Note that all atom names must be unique within a monomer/residue.

Periodic Atoms

Periodic atoms are used to model periodic systems. They are created by performing symmetry operations or unit cell translations on an asymmetric unit. Periodic atoms have many of a real atom's attributes and operations, such as coordinates, CPK, surface, color, label, clipping, and bonds. They also contain information on the real atom and the symmetry or offsetting operation which created them. This information is reflected in a periodic atom's pick string. This string is obtained when a periodic atom is selected with the mouse during an session using the Insight II program. The format of the pick string is as follows:


where unit_cell is the name of the cell (a concise name for the periodic system), molecule is the parent molecule contained in the cell, res is the residue name, atom is the parent atom, operation is the symmetry operation which the periodic atom was created via, and offset is the x,y,z cell offset of the periodic atom. An example of a periodic atom pick string is:


Periodic atoms have the capability of being grouped into replicate objects when needed by a command. This capability is reflected in the molecule level pick string of a periodic atom. The pick string is as follows:


where unit_cell is the name of the cell object, and replicate_number corresponds to the index of the replicate within the cell. An example of a replicate level pick string is:


The following Insight II program commands support periodic atoms:

· CPK Molecule

· Get Molecule

· Put Molecule

· Distance Measure

· Angle Measure

· Dihedral Measure

· XYZ Measure

· Merge Modify (supported for periodic atoms grouped into replicates)

· Save_Folder File

· Restore_Folder File

Using Parentheses

There is one additional syntax which is allowed in the specification of the monomer/residue and atom portion of the object name. This involves the use of parentheses to control the grouping of atom references with monomers/residues. For example, suppose that you want a command to refer to all of the alpha carbons of residues in the range 1-40 and all of the beta carbons on ALA residues. If the object name is ABC then the specification:


refers to these atoms in a single command. In general, you can use parentheses to specify any valid monomer/residue and atom combination which would ordinarily be allowed. Following the parentheses you are allowed to put one final specification of monomer/residue and atom. For the purposes of parsing the name, the contents of the parentheses are treated as a monomer/residue, and the comma which follows then separates it from the following monomer/residue specification. After a comma, the information in parentheses can be followed by another specification enclosed in parentheses.


There are two types of wildcards which are valid in all portions of the overall name. These are: the question mark (?), which matches any single character; and the asterisk (*), which matches any number of characters. They may be combined to form several combinations of matches. When a field is omitted, it is treated as if it contained an *. Thus the name:


is the same as:


Either expression specifies that all atoms of all monomers/residues of the object TEST are to be referenced.

Wildcards can be used in monomer/residue names and atom names as well. For example, to refer to all monomers/residues in the B chain of the object API, refer to:


Experiment with the use of wildcards for the types of things you like to do. It is the best way to get to know their power and limitations.

Not all commands allow for wildcard specification. Which commands allow wildcards, and in what context, is noted in each command's online description. Generally, when you use a wildcard in an invalid context, the program gives you an error message telling you that the object name specified is invalid and why.


Visualization and analysis in molecular modeling is often a matter of viewing or analyzing properties. Insight II provides a convenient way to use these properties in a variety of ways, including the ability to easily add your own properties using BCL or plug-ins.

These properties are often properties of molecules, residues, or atoms. For example, a property of a molecule is its mass. A property of an amino acid residue is its hydrophobicity. A property of an atom is its element type. Properties have a type and a class. The type indicates the type of value for the property, which may be float, integer, boolean, or string. For example, mass is a float, while sequence number is an integer. The float and integer types are referred to as scalar types since they are numerical and can be used in arithmetic or used in conjunction with a spectrum object to indicate a color. The display status of a molecule, which may either be true or false, is an example of a boolean property, while the name property of atoms is an example of a string property. The Custom/List_properties command may be used to list the set of currently defined properties.

Properties can be used in Insight II in a number of ways to help you understand the system under study. For example:

· atoms, residues, or molecules may be labeled with property values, thus attaching a small piece of text with the object.

· scalar properties may be used to color atoms or molecular surfaces according to a spectrum object

· atoms may be collected into subsets according to property values

· molecule spreadsheets can have property columns added to them which display property values for each molecule in a list.

· property values may be queried in BCL scripts or spreadsheet formulas

While MSI provides a pre-defined set of properties with Insight II, it is easy to add your own properties using macros or "plug in"'s. See the BCL chapter for information on macro properties and the Open Interface manual for information on plug ins.

Predefined Properties

The following table lists the predefined properties in Insight II along with brief descriptions.

Property name (type)

Atom properties:

Formal_charge(string) The partial and formal charge on the atom.

Prochirality_S(string) The various types of atom chirality.

Element(string) The name of the atom's element.

Charge_group(string) The name of the charge group to which the atom belongs.

Hetatm(boolean) True if the atom came from a PDB file and was marked as a HETATM in that file.

Hybrid(string) Hybridization.

Potential(string) Potential type.

Oop(string) Out-of-plane setting.

Switching(boolean) True if a switching atom for a charge group.

Temp_factor(string) Temperature factor.

VDW_radius(float) Van der Waals radius, in angstroms.

Max_valence(float) The maximum valence for the atom.

Head_tail(string) If the atom is a head or tail atom for a monomer (the attachment point for chains of monomers) this string will contain "head" or "tail".

Z_object(float) The x, y, and z coordinates of the atom in the space of
its molecule.

Z_world(float) The x, y, and z coordinates of the atom in world space.

Name(string) The name of the atom.

Connection_count(integer) The number of bonds to the atom.

Mass(float) The mass of the atom.

Valence(float) The common valence for the atom.

Sequence_number(integer) The sequence number of the atom within its molecule.

Sequence_in_monomer(integer) The sequence number of the atom within its monomer.

Monomer properties:

Name(string) The name of the monomer. This is generally a number, although in multi-chain proteins it often includes a chain letter.

Partial_charge(float) The sum of the partial charges of the monomer's atoms.

Type(string) The monomer type. For amino acids, this is the name of the amino acid.

Type_1letter(string) For amino acids, the one letter abbreviation.

Atom_count(integer) The number of atoms in the monomer.

Mass(float) The sum of the masses of the atoms in the monomer.

Sequence_number(integer) The sequence number of the monomer within the molecule.

Hydrophobicity(float) The hydrophobicity of the amino acid monomer. This uses the Engleman-Steitz scale.

Molecule properties:

Name(string) The name of the molecule.

Compound_name(string) If the molecule came from an MDL file and a compound name was specified in that file, this property will contain that name.

Partial_charge(float) The sum of the partial charges on the atoms of the molecule.

Mass(float) The molecular weight of the molecule.

Monomer_count(integer) The number of monomers in the molecule.

Atom_count(integer) The number of atoms in the molecule.

Dials_connected(string) If the dials are connected to the object, this will be "connected"; otherwise it will be a blank string.

Displayed(string) If the object's display status is on, this will be "On", otherwise it will be a blank string.

Use of Color

The Insight II program allows you to set and change the colors for atoms, entire objects, specific residues or monomers, surfaces, and labels. In all of these cases you have three methods by which you can specify the color:

1.   By color name, using one of the six names which the program recognizes.

2.   By color number.

3.   By RGB triplet.

Using methods 1 or 2, a color can be defined by a value from 0 to 360. The color names and their meanings are as follows:

Blue = 0 or 360

Magenta = 60

Red = 120

Yellow = 180

Green = 240

Cyan = 300

You are allowed, whenever a color is required, to specify one of the names given above or a numerical value. The number must be an integer in the range of 0 to 360, and where the number is not one of the values listed above, corresponds to a blend of the colors between which it lies.

In addition to the specification of color or hue, you are allowed to specify, if you choose, a saturation value for the color. The hue is the color quality of the picture. The saturation is the purity of the color. A fully saturated color red is really red. A half-saturated red is pink because the other half is white. All colors at zero saturation are white. Use of both hue and saturation controls in the setting of colors allows you to generate a virtually infinite variety of displayed colors on the screen.

Note that on an SGI, a total of 12 base colors can be simultaneously displayed. These colors include the 7 pre-defined colors blue, magenta, red, green, yellow, cyan, and white, and 5 user-defined colors in color map mode. In RGB mode there are an unlimited number of user colors, but if you switch back to color map mode only 5 of those colors will remain.

To specify the saturation of a color, follow the color name or number with an open parenthesis, a value from 0.0 to 1.0, and a close parenthesis. For example, to specify a pink color use:


This syntax of color (saturation) is valid whenever a color is specified to the program. The default saturation, if none is given, is 1.0 which makes the color strong and pure.

When specifying an RGB triplet, three color values representing red, green, and blue must be specified and separated by commas. Each of the color values may range from 0 to 256. For example:

256,0,0 represents red

0,256,0 represents green

0,0,256 represents blue

0,256,256 represents cyan

256,256,0 represents yellow

256,0,256 represents magenta

256,256,256 represents white

The RGB triplets are used when coloring with the color palette.

RGB vs. Color Table Mode

The Insight II program supports both RGB and color map modes. The mode is selected using the RGB_Mode option in the Environment command under the Session pulldown in the Viewer module. RGB mode is not available on 8-bit Personal Iris systems. In RGB mode the red, green, and blue values are stored directly in the frame buffer which drives the display. Some devices which do not have a full 24 bits of color, such as the Indigo, do hardware level "dithering", where adjacent pixels are painted in slightly different colors so that the result, when blended by the human eye, is approximately the desired color. This can make the picture look somewhat grainy, but otherwise works quite well. In color map mode, the red, green, and blue values are stored in a color map and an index into the color map is stored in the frame buffer.

The default mode for all 24-bit systems is RGB mode, and for all 8-bit systems is color map. RGB mode provides a better lighting model for solid surfaces, so CPK and solid contours look better in RGB mode. However, anti-aliasing on Personal Iris systems requires color map mode (i.e., RGB_Mode off).

Insight II on the Indigo also provides a Single_Buffer option in the Environment command. This switches the hardware from 4-bit double-buffered mode to 8-bit single-buffered mode. The picture looks much better in the 8-bit mode, but flashes as it is moved. The recommended use of this mode is to leave it off while positioning the picture on the screen, and then turn Single_Buffer on to study the picture more closely or take photographs.

Online Help

Insight II Help Viewer

The Insight II program provides a graphical online help facility, the Insight II Help Viewer. This help viewer uses the X Window system to display help for the Insight II program in a graphical, easily accessed manner. Help for various topics can be displayed by choosing items from pop-up menus. The Insight II Help Viewer runs independently from the Insight II program, so you can continue to use the program while the help facility is executing.

Using the Insight II Help Viewer

The Insight II Help Viewer is accessed by picking the Help icon from the icon palette (the icon with the question mark), by executing Session/Help or Help/Insight_Help, or by typing Help help at the Insight II command prompt.

When the Insight II Help Viewer is invoked, a window appears containing a menu bar, a set of navigational buttons, and the help text viewing area.

Top Menu Bar: Options and Help Menus

Under the Options menu, five commands are available: Follow, Go Forward, Go Backward, Print, and Quit Help. Note that keyboard accelerators to some of these commands are available.


This command acts as a toggle to control whether the Insight II Help Viewer follows the Insight II program. If on, help text is displayed in the window whenever you choose a command from within the Insight II program. For example, if you have Follow turned on and you choose the Add command from the Assembly pulldown (in the Insight II window), help text for the Add command is automatically displayed in the Insight II Help Viewer window.

Since the Insight II Help Viewer follows even while hidden, you may want to toggle Follow off if you keep the help window hidden for long periods so that no help processing occurs.

Go Forward, Go Backward:

These commands allow you to navigate through the history of help text since the beginning of your Insight II session.


This command provides you access to a print dialog box. You can choose a print command and set up print options, including the amount of information to be printed.

Quit Help:

Activating this command causes the Insight II Help Viewer to disappear. Picking the Help icon, executing the Session/Help or Help/Insight_Help commands, or typing Help help at the Insight II command prompt causes the window to reappear.

Navigational Buttons.

These buttons are dynamically updated reflecting the hierarchical path to either the module, the menu, the command or the parameter your are getting help for. Note that the right-most button is a pulldown button. You can click on either of these buttons to navigate through the entire hierarchy of Insight II commands.

Help Text Viewing Area

The help text viewing area displays help for the selected topic. If the amount of text exceeds the size of the widget, a scrollbar is displayed at the right edge to permit you to scroll through the text. Use the left mouse button for scrolling.

Figure 12 . Example of Insight II Help Viewer Window


Insight II Pilot is an electronic assistant which can provide interactive training sessions and practical guidance for accomplishing a variety of tasks. Using Pilot, the full functionality of the Insight II modeling system can be navigated. Novice users can complete practical modeling problems from the first time they use the program. More experienced users will appreciate Pilot's ability to access the comprehensive capabilities of the fully integrated Insight II software suite.

Pilot provides a convenient means for organizing modeling information and developing strategies. In-house modeling experts can use Pilot as a convenient means of communicating modeling procedures or even demonstrating worked solutions for internal customers.

An important part of MSI's approach to online information is that its interface should be intuitive, and self-documenting. Pilot is consistent with this design goal. From the Insight II interface, click the Pilot icon in the icon palette:

This opens the Pilot parameter block, where you can choose a directory of Pilot log files. From the next window that opens, choose any tutorial.

Pilot is designed to run in conjunction with Insight II. Starting Insight II and then Pilot ensures that both programs work together. It is possible to run Pilot separately, however. Enter pilot at a UNIX prompt. By default, this launches Pilot displaying information about Pilot itself, and how this powerful tool can be used.

How Errors are Handled

If you make an error, the Insight II program makes every effort to detect the problem and handle it gracefully.

Errors happen for a variety of reasons. Perhaps the most common mistakes are made while issuing a command. If you are typing in a command, you might spell the command name incorrectly. The offending name is enclosed in angle brackets, <>. At this point, you can correct the mistake by retyping the name. Of course, it may be easier to start typing from scratch by first pressing the letter u while holding down the <Ctrl> key.

Another common mistake is to give wrong parameters to a command. If you type the command, you might give too many parameters. This causes the extra parameters to be highlighted by changing them to reverse video (white text against a black background). Again, you can retype to correct the mistake. If you give too few parameter values in a typed command, you are prompted for additional parameter values. If you misspell a parameter value, the program may mistakenly assume you have entered too few or too many parameters. In this case, you may receive a prompt or part of the command may be colored red. The important thing to remember is that if the command does not execute, some kind of error was found and must be corrected.

By using the menu version of commands, you are less prone to common errors. For example, you are not allowed to execute the command if you have not filled in enough parameter values. And, misspelling is less likely because you can use value-aids and can pick objects from the screen or from a list to indicate your choices. Better still, if you try to fill in a value that is inappropriate, the program may be able to immediately draw your attention to the problem with a message.

Not all errors can be detected before a command is issued. For example, you might give an integer parameter a negative number where only a positive number is allowed. In this case, the Insight II program might not recognize the problem in time to stop you from executing the command. Note, however, that the program keeps looking for illegal situations even after a command is issued. In most cases, if it finds a problem while it is trying to complete a command that has been issued, an error box containing red text appears over the Insight II window. It contains a brief message describing what has gone wrong. For all but the most severe errors, you can select the <Explain> button within the error box. This gives you a longer error message that describes the problem in more detail. Note that errors are also echoed to the information area of the window. You can get rid of the message windows by clicking your mouse button anywhere, or by pressing any key.

In most cases, errors are not fatal and the Insight II program cleans up sufficiently to allow you to continue your work. Often, this means simply re-issuing the command with different (correct) parameter values.

In some severe cases, the program does not allow you to continue because internal data has been badly corrupted. In these situations, a diagnostic message is put out to the textport. Please make a note of this message and contact MSI to report the problem. Only in this way can the problem be fixed in future releases.

There is one kind of severe error that can be triggered through no fault of the software: running out of virtual memory. Like all software packages, the Insight II program uses the computer's virtual memory. The amount of virtual computer memory varies depending on the size of the swap file at your site. If the program requires more memory than is available, a severe error is produced. You can recognize this kind of problem by a diagnostic message alluding to memory_alloc, malloc, memory_free, free, or some other keyword that corresponds to memory usage. If this type of error occurs, kill the Insight II program session by killing the process or quitting the graphics window by the usual operating system methods. If you do not know how to do this, contact your system manager or your MSI representative. Once you have completely closed down the Insight II program, you may want to discuss the problem with your system manager to see if more virtual memory can be allocated on your computer.

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