ICM Manual v.3.9
by Ruben Abagyan,Eugene Raush and Max Totrov
Copyright © 2020, Molsoft LLC
Jun 5 2024

Reference Guide
 ICM options
 Alignment Editor
 Cgi programming with icm
 Xml drugbank example
 Tree cluster
 Flow control
 Energy Terms
 Chemical Functions
 Gui programming
 Icm shell functions
Command Line User's Guide
PrevICM Language Reference
Creating your own GUI elements: Programming GUI.

The main menu file of the ICM program is in $ICMHOME/icm.gui. A user can also create his/her own file in their directory, e.g. ~/.icm/user.gui and read it in user_startup.icm file with the read gui command. There are three possibilities to add a new menu or a popup dialog with action (see also set format for table cell actions).
  1. Main menus. Add or modify a section in the icm.gui file, or (preferred) your own file in the same format. To program the main GUI menus and popup dialogs, you can modify a single central file, called icm.gui or create your own .gui file. This main icm.gui file resides in the $ICMHOME directory, while your own additional file can be anywhere else. The icm.gui file contains controls for each menu item. It the menu item requires a dialog, it is automatically generated.
  2. Popup dialogs in tables. Add a header element called cellPopup or tablePopup need to be added to a table, e.g.
    add column t {1 2 3}
    add header t "POPT New Table Item\nSYNT # T_Table\nSYNT # r_Enter_Real (2.)\nSYNT show $1\n" name="tablePopup"
    add header t "POPT New Table Cell Item\nSYNT # r_Enter_Real (2.)\nSYNT print $1 + %@.%^[%#]" name="cellPopup"
    The following shortcuts are allowed:
     %@ is the table name, e.g. %@.%^ is table.column
     %# is the line/row  number, e.g. t.mol[%#]
     %^ is the column name corresponging to the cell.
  3. Popup dialogs in internal html-documents. For those you need to add ths following line:
    so that the dialog looks like this:
    #dialog{"Enter name"}
    # s_name ("Kosmo")
    # ff_file|*.html ("")
    print $1 $2
    #dialog{ "Sample Dialog" }
    # txw_Enter_Text ()
    txt = %s_out   # s_out is not a safe place (might be overwritten)
    print Length(txt)
    Notice underscore containing names like s_ need to be capped with the percent symbol

One icm.gui section consists of the following fields:
MENUDisplay.Advanced.Pocketsthis menu item will be added in the top menu bar
OPTNApplyoptional. Allows to specify special kinds of dialogs.
OPTNConditions and Flags
ICONicon name
SYNTdisplay g_pocketthe ICM-command executed upon pressing 'OK' or 'Apply'.

An example:

MENU Display.Color.White 
SYNT color white 

Many examples of how to program controls for the script arguments can be found in the icm.gui file.

Creating controls for the main input data types.

To create a control for a particular data type one needs to add the following line.

SYNT # t_name ( default1 | default2 ) [ OPTIONS> ]

SYNT # i_enterInt (10) 

The following input types are possible:
type example comment
b_button SYNT # b_Undisplay_distances (delete g_distances) executes the command in () when pressed.
d_directory SYNT # d_PDB_Directory (SYS:s_pdbDir) gives you a dialog to select a directory
ff_fileDialog SYNT # f_Input_file↑*.mol;*.SD*;*.sd* () generates a secondary file dialog
f_fileDialog SYNT # f_Input_file↑*.mol;*.SD*;*.sd* () generates a file dialog first, ignores other arguments
g_grobMesh SYNT # g_Mesh (*) star means show the current list of grobs in icm
i_integer SYNT # i_size (10) also allows one to filter the input, e.g. SYNT #20 i_Angle (360MIN:-360MAX:360)
l_logical SYNT # l_high_res (yes)
o_radioButtons SYNT {o_icmWord1_text_1 o_icmWord2_text_2 ..}
os1_molObjects, ms1_molecules, rs1_residues, as1_atoms
p_preference SYNT # p_ribbonStyle_Ribbon_Style internal name followed by the control title.
r_realVar SYNT # r_temperature (200.)
s_stringVar SYNT # s_name (John) returns quoted "John"
txw_Big_Text_Box SYNT # txw_Description ($s_out) stores edited text in s_out variable. Use %s_out to access the value.
txt_text SYNT # txt_boxName (Text to be displayed) free comment
T_table SYNT # T_Table_Name (*) an asterisk (*) will be substituted with the list of tables
C_columnSYNT # C_Select_Column [TABLE:2,SARRAY] selected a column of the existing table. Works in pair with T_ or X_
ch_CompoundSYNT # ch_Draw_Compound draw compound or type SMILES/SMARTS string

Possible values of OPTIONS are:
option name description example
IARRAY,SARRAY,RARRAY,CHEMARRAYnarrow the choice for column selector C_
RDONLYsets control to read-only mode. User can not pick from the list.
REQUIREDinsist that the value is not empty
RESIZEallow resizing of the window [RESIZE]
RIGHT,LEFT,CENTERalignment of the control on the dialog
TABLE:~~i_tableReferenceNumber column selector C_ need a reference to a parent table. This number is found counting prefix_ before the table
SMARTSgenerate SMARTS expression from ch_ input
NOCOORDSdo not include 2D coordinates into result of ch_ input
The i_tableReferenceNumber needs some clarification.

SYNT # T_Table_A (*)  [RDONLY,LMINWIDTH:110] C_by_Column () [TABLE:1,RESIZE,LMINWIDTH:110]
SYNT # { o__inner o_left o_right } [CENTER]
SYNT # T_Table_B (*) [RDONLY,LMINWIDTH:110] C_by_Column () [TABLE:6,RESIZE,LMINWIDTH:110]
Here column selection ( C_by_Column ) for table B (the 3rd line) is refering to table B . T_Table_B has its reference number as 6 (not 4) because this i_tableReferenceNumber counter counts each o__inner o_left o_right as 3 words in contrast to the dollar-argument number .

Conditional options:
VISIBLE s_condition| shows/hides control depending on condition
OPTN s_condition enables/disables control depending on condition

Example of "Extract Ligand" dialog :

MENU Extract Ligand(s)
COMM Extract ligand into chemical table
OPTN !isMini !isPharm
ICON bipm_chemring
SYNT #1 ms1_
SYNT #2 { o_"2D"_as_2D_drawing o_"3D"_keep_3D_coordinates }
SYNT #3 l_append_To_Existing_Table (no) [OPTN:(nChemTable)] X_ (*) [RDONLY,OPTN:($4)]
SYNT if (   $3 ) extractLigand $1 $2 $3 Name( $4 table )
SYNT if ( ! $3 ) extractLigand $1 $2 $3 ""

Example of "Merge Two Sets" dialog:

MENU Chemistry.Merge Two Sets
OPTN nTable>1
SYNT # T_Table_A (*)  [RDONLY,LMINWIDTH:110] C_by_Column () [TABLE:1,RESIZE,LMINWIDTH:110]
SYNT # { o__inner o_left o_right } [CENTER]
SYNT # T_Table_B (*) [RDONLY,LMINWIDTH:110] C_by_Column () [TABLE:6,RESIZE,LMINWIDTH:110]
SYNT # txt_Hint (inner - only molecules present in BOTH A and B tables are kept<br>left - ALL rows of A are kept<br>right - ALL rows of B are kept)
SYNT join $2 $5 $3

Specifying the default values of the arguments

The general syntax of the default value specification is:

( value1 | value2 | ...)

Where default_value can also be one of the following:

  • asterisk, * : lists all values/variables of specified class, e.g. seq_ (*)
  • dynamic condition: expression in extra parenthesis containing filtering condition, e.g. ((isAmino))
  • custom text/string. This is either any text or expression in the form: internal_text@Human_Readable_Text , e.g. (10|0@all) you will see all , but value 0 will be returned.


os1_Select_Object (*)             # lists all objects loaded in current session
os1_SelectObject ((isIcmObj))        # lists all ICM objects
os1_SelectObject (*|Obj(as_graph)@Graphic Selection)        # lists all ICM objects plus 'static choice' of graphic selection

ms1_Select_Molecule ((!isWater))  # will forms a list of all molecules excluding waters
ms1_Select_Molecule ((isAmino)|(isNucl))  # will forms a list of all amino and nucl chain molecules.
ms1_Select_Molecule ((isHet)|(isAmino&nResInMol<10))   # list all ligands plus short amino chains (peptides)

This is a list of internal GUI functions that can be used in dynamic conditions

Functions for the Molecular arguments ( ms1_ .. ):

  • isAmino (lists amino chains)
  • isNucl (lists nucleotide chains)
  • isHet (lists hetero molecules - ligands)
  • isMetal (lists metals)
  • isWater (lists water)
  • isDsMol (lists displayed molecules )
  • isIcmObj (only molecules of ICM objects )
  • isLinkedToAli (lists linked to an alignment molecules)
  • hasSwissID (lists molecules with swiss ID)
  • nResInMol (counts number of residues in molecule)
  • nAtomInMol (counts number of residues in molecule)

Functions for the Object arguments ( os1_ .. ):

  • hasAmino (lists objects with amino chains)
  • hasNucl (lists objects with nucleotide chains)
  • hasHet (lists objects with ligands)
  • hasMetal (lists objects with metals)
  • hasStack (lists objects with attached conformation stack)
  • nMolInObj (counts number of molecules in the object)
  • nResInObj (counts number of residues in the object)
  • nAtomInObj (counts number of atoms in the object)
  • isIcmObj (lists ICM objects)
  • isDsSelObj (lists displayed and selected objects)
  • isDsObj (lists displayed objects)
  • isPharm (lists pharmacophore objects)

Suppressing the automatic interpretation of X_ with the % symbol.

Note, that the GUI dialogs and controls are generated automatically every time the program finds a letter followed by underscore. For that reason if you want to suppress that action, use the percent symbol, e.g.

SYNT print  %s_out # do not want to generate a text dialog.
SYNT display %as_graph # here you do not want to generate an as_ selection dialog
SYNT if Nof(g_distances)==0 delete  %g_distances

Specifying MIN and MAX values, or adding other controls.

SYNT #20 i_Angle        (360|MIN:-360|MAX:360)

Specifying objects, molecules, residues and atoms

More detailed examples.

SYNT # f_Input_file|*.mol;*.SD*;*.sd* () # generates a file dialog
SYNT # r_Sphere ( 3. ) # here r_ is the type; 3. is the default value
SYNT # r_Resolution_Increase (1.2|1.5|1.75|2|2.5|3) # you can provide popular choices
SYNT # r_Ribbon_Width   (SYS:GRAPHICS.ribbonWidth) # that is how a system variable is redefined

The actual icm commands that use those arguments refer to them as $1 $2 .. , e.g.

# choose a mesh and save it to a file
SYNT # g_mesh (*) 
SYNT # f_file 
SYNG write $1 $2 

Layout issues

Layout defines how various input elements are arranged on the page. ICM arranges all controls in a single line horizontally. Each new line in the dialog definition starts a new horizontal layout. In some cases you need to arrange controls as a grid. BEGINGRID and ENDGRID options should be used to do this:


# l_Anilines (yes) [BEGINFRAME:Options,BEGINGRID] l_Nitro (yes)
# l_Metals (yes) l_Carboxylic_Acid (yes)
# l_Hologen_Hydrides (yes) l_Aldehydes (yes)
# l_Alkyl_halides (yes) l_Acid_halides (yes) [ENDGRID,ENDFRAME]

Radio-buttons can be also arranged in a several rows/columns.


# { o_1_Option_11 [HORIZONTAL:2] o_2_Option_12 o_2_Option_13 o_2_Option_14 o_2_Option_15 } 
# { o_1_Option_11 [VERTICAL:2] o_2_Option_12 o_2_Option_13 o_2_Option_14 o_2_Option_15 } 

Creating a dialog with tabs.

Each page (tab) should be started with '%%%Page_Name' line. Then follows a page declaration.


MENU &File.Tabs Example
SYNT %%%Page1
SYNT # s_Text_1 ("aaa") [REQUIRED]
SYNT print $1
SYNT %%%Page2
SYNT # s_Text_2 ("bbb") [REQUIRED]
SYNT print $1
SYNT %%%Page3
SYNT # s_Text_3 ("ccc") [REQUIRED]
SYNT print $1

Creating a wizard dialog.

You may easily convert your tab dialog into wizard dialog by replacing '%%%' with '^'.


MENU &File.Wizard Example
SYNT ^^^Page1
SYNT # s_Text_1 ("aaa") [REQUIRED]
SYNT print $1
SYNT ^^^Page2
SYNT # s_Text_2 ("bbb") [REQUIRED]
SYNT print $1
SYNT ^^^Page3
SYNT # s_Text_3 ("ccc") [REQUIRED]
SYNT print $1
See also: Askg

Adding custom user functions to 'Insert Column'

This section contains description of the syntax to custom function for Insert Column dialog.


CFUN newgroup.Ligand_Strain
SYNT # (X)->r
SYNT funcLigStrain(%1)

Each column function start with CFUN which contains dot separated path in the form of folder1.folder2.funcname

Existing folders ID are:

  • creat : "New"
  • trans : "Transformations"
  • arith : "Arithmetical"
  • math : "Mathematical"
  • search : "Find"
  • str : "Text"
  • chem : "Chemical"

For example to add new function into 'New' folder the path should look like: creat.MyNewFunc

The SYNT section should contain one or more template description. Each template description line start with '#'

Template describes the type of arguments and the result type.

The syntax:

(<arguments>)->(<result>), brackets are optional
arguments: space or comma-separated values in format: 
Types combination of: i r s l w I R S X (Uppercase: array, lowcase: constant)
  "I" will accept both integer column (Iarray) and integer constant
  1I 1R 1S 1IR 1IRSX .. -- no constants allowed (only arrays) 


  • (r r)->r # takes to real columns or two real values and return real column as a result
  • (X r:curoff=0.5)->r # takes chemical and optional real argument with default 0.5

The line in the SYNT section which does not start with '#' will be treated as an arithmetic expression which calculates the column value. It may contain any arithmetic operators, constants, shell functions and user functions.

See add column function for details.


Copyright© 1989-2024, Molsoft,LLC - All Rights Reserved. Copyright© 1989-2024, Molsoft,LLC - All Rights Reserved. This document contains proprietary and confidential information of Molsoft, LLC. The content of this document may not be disclosed to third parties, copied or duplicated in any form, in whole or in part, without the prior written permission from Molsoft, LLC.