ICM Manual v.3.8
by Ruben Abagyan,Eugene Raush and Max Totrov
Copyright © 2020, Molsoft LLC
Sep 22 2022

Reference Guide
Command Line User's Guide
  Table expression
  tif files
  transformation vector
PrevICM Language Reference

[ table | Table expression | targa | selftether | tether | tif files | transformation vector ]


an ICM object which unites several other ICM-objects into a spreadsheet with a additional information. It consists of two parts:

A parray, or pointer-array can contain chemical structures (see read table mol command), sequences Parray( seq | sequence ), or molecular objects ( Parray(object .. ) ) . Tables can be read, written, and shown. Tables can also be created by
group table tabName col1 [sColName1] col2 [sColName2] ..

or add column tabName col1 col2 .. [ name= S_names ]
commands (see group table and add column ).

Columns can be further added with

add column table col [ name= s_colname ]


add column t {1 2 3} {2 3 4} #creates table t with two columns
add column t {1 2 3} name="CC"  # adds one more column
group table tt {1 2} "A" {2. 3.} "B" {"xx","yy"} "C"

Some other functions can also return tables,e.g.:

  • Energy(stack) returns a table with energy values for the stack conformations
  • Table(s_out) interprets an output of an HTML form.
  • Find performs search in all entries and returns the matching entries

One can insert empty rows, or duplicate rows or , insert rows from a different table with the add table command.
Table rows with the same columns can be merged with the add table t1 t2 command. dd

Selecting columnsColumns can be selected and copied into another table with the Table( T S_colNames ) ⇒ T_out


add column t {1 2} {2 3} {3 4} # creates A,B,C columns
tt = Table(t,{"B","C"})

Coloring cells in a table column

add column t {"1crn","2ins","1xbb","1abe"} {1.3,3.4,2.2,3.6} name={"cd","res"}
set format t.res color='rainbow="blue/green/yellow"'
set format t.res color="rainbow='#AAFFFF/#FFFFAA,,pinwheel'"
# more advanced specification with the value ranges and 
s_clr = "rainbow='red/white/blue,0:10"  # force the abs range 0 to 10.
set format t.res color=s_clr
s_clr = "rainbow='red/white/blue,100:150,linear/0:0/0.7:0.5/1.:1'"
# using internal function that returns a hex color:
set format t.A color='Icm::Color(A protein)'
See also: set format

Setting actions to table rows and cells

Two main methods exist: 1. Adding a double click action to the whole row ( %@ stands for the table name, %# stands for the line number ):

add column t {"1crn","2ins","1xbb"} {"crambin","insulin","kinase"} name={"code","protein"}
add header t "delete a_*. ; read pdb %@.code[%#]; display ribbon" name="doubleClick"

2. Adding an action to a specific cell in a column. Example:

add column t {"1crn","2ins","1xbb"} {"crambin","insulin","kinase"} name={"code","protein"}
set format t.code "<!--icmscript name=\"1\"\n print \"%code\" \n--><a href=#_>%1</a>" # replace print with a macro if needed

Setting the grid and table views

add header t "TABLE"|"GRID"|"GRID1"|"GRID2"|FORM_GRID1|FORM_GRID2|.. name="displayStyle"


  • "TABLE": normal table style
  • "GRID" : grid view with automatic fitting optimal number of columns.
  • "GRID1","GRID2",... : number of grid columns is explicitly specified
  • "FORM_GRID1" : form view

Adding values for the Grid view: displayStyle and gridColumns headers.In a grid view you may want to add a some columns to be displayed below the molecular image. You need to add a header "gridColumns" which contains a string with a comma-separated column names.

add header t s_commaSeparatedColNames name="gridColumns"


add column t Chemical({"CCC", "CCO", "CCN"}) 
add column t Mass(t.mol) name="MW"
add column t Predict(t.mol,"MolLogP") name="MolLogP"
# set a grid view
add header t "GRID" name="displayStyle" 
# add more MW to grid view
add header t "MW,MolLogP" name="gridColumns"
# switch back to the table view
add header t "TABLE" name="displayStyle" 

As an addition to the views above you may open a 'form record view'. (Useful for tables with many columns). To show a form you need to append '_FORM' to the displayStyle header string. For example the most convenient combination is GRID1_FORM.


add header t "GRID1_FORM" name="displayStyle"

Changing the color, format and name of a column
set format t.col s_format [ color=s_color_spec ] [ name=s_displayedColName ]

The format should use the C-format specifications ( e.g. "%s","%.2f", etc.) of "%1" for any data type.

group table t {1 2 3} {2.222 3.333 4.444}
set format t.B "<i>%1</i>" name="Reals" 
set format t.B "<i>%.1f</i>"  # will only show 1 sign. digit

To reset the displayed column name to its true column name, set name= argument to empty string.

Condensing or grouping the table rows by a column

Sometimes a table contains multiple rows with the same value of a particular column (see example). In this case the rows of the table can be condensed to show only one representative row. Left and right arrows would rotate through the rows. The commands leading to that view are the following:

group table tt {3 2 2 2 1 1 1 1} {"a","b","c","d","e","f","g","h"}
set group column tt.A 

Reading and writing ICM tables to a fileICM can read and write tables from and to a variety of formats:

  • .tab : icm text format for tables, it contains the table name, may contain the header information followed by column names and column values. E.g.
    #>T mytabname
    #>-a-b-c----  # dashes optional
    12  c2 c3
    24  c2 c3
  • csv,tsv,bsv,... : comma- , tab-, or vertical bar- separated fields with or without a line with the names of the columns. Example:
  • .icb files for the icm binary formatted table(s).
  • .sdf files for chemical information.
To read and write these formats do the following:

# .tab
write table t "t.tab"
read  table "t.tab"
# .csv
write table t separator="," "t.csv" header  
read table separator="," "t.csv" header   # skip keyword header if your file does not have column names
# .sdf  : chemical tables
write table mol t "t.sdf"
read  table mol "t.sdf"  # to redefine name use name=.. option
# .icb  : icm fast binary format
write binary t "t.icb"
read binary "t.icb"

Pairwise table expressions:

[ Table operations | Table subset | Table plot | Table actions ]

  • !(Table selection) negation
  • T.I_ ? i_ ( ? is one of: ==, !=, <=, >=, <, > )
  • T.R_ ? r_ ( ? is one of: ==, !=, <=, >=, <, > )
  • T.S_ ? s_ ( ? is one of: ==, !=, ~, !~, i.e. exact of fuzzy comparisons )
  • T.S_ ? S_ ( ? is one of: ==, ~, equivalent to T.S_ ? S_[1] | T.S_ ? S_[2] | ... )
  • T.S_ ? S_ ( ? is one of: !=, !~, a complement to what is returned by the T.S_ == S_ or T.S_ ~ S_ comparison, respectively, equivalent to T.S_ ? S_[1] & T.S_ & S_[2] & ... )
The result of the pairwise expression is a subset of the table involved. The pairwise expressions can be further combined with the & (AND) or | (OR) operations. A full expression can be assigned to a new table or used on the fly in a number of commands and functions. String comparison can use patterns (e.g. t.NA=="*_MOUSE"). The pattern may contain more sophisticated \{n,m\} expressions, if the first symbol is '*' or '^'.
The Index( tableExpression ) function will return integer array of selected row-numbers.
 group table t {"a","b","c"} "s" {1 2 3} "i" # arrays t.s, t.i 
 show t 
 show t.s == {"c","a"} # shows the 1st and the 3rd lines 
 show t.s ~ "a*" | t.i < 3 # shows the 1st and the 2nd lines 
 show t.s !~ "a*" & t.i < 3 # shows the 2nd line  
 Index(  t.s ~ "a*" | t.i < 3 ) # returns {1,2} 

Table operations

table subsets:

Table subsets can also be defined explicitly through the three types of index expressions:

  • T[i_element], e.g. t[3]
  • T[i_from:i_to], e.g. t[3:15]
  • T[I_indexArray], e.g. t[{3,14,18}]
Index arrays are returned by some commands or the Index(T) or Index(T selection) function. If you graphically select rows use keyword selection in the Index function. Examples:

add column t {'a','b','c','d','e'} {1 2 3 4 5} 
Index(t)  # {1 2 3 4 5}
Index( t.B<3 ) # returns {1,2}
Index( t selection ) # returns row numberse selected in GUI table view

Look at another example of operations with tables. We read a database of secondary structures foldbank.db dump arrays into a table, add sequence length to a table, extract entries of interest, sort them and save the result.
 read database "foldbank.db"          # load information into arrays  
 LE=Length(SS )                       # create iarray with sequence lengths 
 group table t $s_out LE              # create table t with all info + lengths 
 show t                               # press 'q' otherwise computer will explode 
 show t.NA == {"1gec.i","5pad*"}      # find these entries 
 a=t.RZ < 2.2 & t.ER < 1. & t.LE > 35 # select entries with resolution < 2.5,  
                                      # converted with ER < 1. and longer 
                                      # than 35 residues 
 sort a.LE a.RZ                       # resort entries according to 
                                      # lengths/resolution 
 write database a "SUBSET" 

Plotting table data

The ICM tables can have built-in plots. To add an automatically generated plot to a table, use make plot .

Table headers and actions

Each table may have a header section containing different ICM-shell variables in addition to a set of columns. Example:

add column t {1 2 3} {2 3 4}
add header t "Francis Bacon" name="author"
show t.author
 Francis Bacon

There are header strings with fixed names for three types of actions:

  • cursor these commands are invoked after the cursor position is changed
  • doubleClick these commands are invoked upon double click on a column row
  • set format t.col icmscript actions. There are individual column actions including icm commands and macros.

If this header member exists, the action is executed every time this action is invoked.

The action commands are regular ICM commands, however they can use certain abbreviations to refer to the table and its row number (cursor position):

%#  # row number, e.g. t[%#]
%@  # table name, e.g. '%@' or %@.A[%#] 
%^  # column name e.g: %@.%^[%#]
%1  or %COLNAME  # value of cell from column number 1 and the current row

This example will show how make a selection column actionable (e.g. display and center on it):

# create the table with selection strings:
read pdb "1crn" # if your session is empty
read pdb "1abe"
add column t Name(a_*. full)  # makes column t.A with 'a_1crn.' etc.
add header t name="doubleClick" """
display only %A
display residue label %A & a_*.A
A more sophisticated version will make sure that all the display and -color commands are inside the following block:

GRAPHICS.l_redraw = no
# .. display and color commands
GRAPHICS.l_redraw = yes
display new

So a better .doubleClick header should look like this:

add t name="doubleClick" delete """
GRAPHICS.l_redraw = no  # will prevent blinking
 display only %A
 display residue label %A & a_*.A
GRAPHICS.l_redraw = yes
display new

The previous examples enabled the doubleClick action on a row. You can also set the "cursor" action which acts every time your mouse cursor is on a row (may be annoying, however).

Furthermore you can enable an action only for a cell in a specific column rather than in the entire row. In this case it will appear as link and you need to use the

set format t.A """<!--icmscript name="1"
display only %A
display ribbon %A
--><a href=#_>%1</a>
or type commands interactively in a set column format dialog.

More Examples:

add column t {1 2 3} {"A" "B" "C"}
add header t "print %@.%^[%#]" name="cursor"
add header t "print %@.%^[%#], \"double clicked\" " name="doubleClick"
set format t.B "<!--icmscript name=\"1\"\n print \"%B\" \n--><a href=#_>%1</a>"

Lock action and chemical display

There is another special mechanism that creates a column or buttons and allows one to assign a macro invoked upon clicking on this button (the button will be stored in column L , from lock ). Currently this mechanism is used to display and undisplay chemical structures stored in the .mol column. Prerequisities

  • a table with a chemical column named .mol .

The set property display command will create a new member of the table header called .lockAction . This string will contain the call that will be made upon clicking or unclicking the L button.

set property display t # creates an array of buttons and links them to the call stored in the .lockAction string
Currently the default .lockAction uses the following call

dsChemLock_new "%@" "%@" %#
Here %@ is the table name and %# is the row number. However, if you want to modify the action the .lockAction content can be modified to invoke another macro.


TARGA or TGA format is a format for describing bitmap images, TARGA can represent grey-scale bitmaps, indexed colour, and RGB colour, the format also supports various compression methods.


selftether a target position for an atom in ICM object . It can be set, deleted and used in restrained minimization with the "ts" term.

In contrast to tether that points from an ICM atom to an atom in another object, the selftether does not require any other object. The target positions are stored with the atom.

The selftether can be used in show energy minimize or montecarlo if the "ts" term is activated. Here are some commands and functions operating on selftethers.

  • convert : creates selftethers to the original PDB coordinates
  • set selftether [ as ] [ tether | only ] : sets selftethers from the current coordinates or from tether destination atoms
  • show selftether [ as ] : shows atoms with selftethers and the deviations
  • delete selftether [ as ] : deletes selftethers
  • set term "ts" : sets "ts" term to calculated the energy of harmonic restraints to the target positions
  • show energy , minimize , montecarlo with "ts" : uses selftethers
  • TOOLS.tsWeight : weight of selftethers in the "ts" term calculation
  • TOOLS.tsToleranceRadius : radius around atoms where the deviations from the target are not penalized
  • TOOLS.tsShape and TOOLS.tsShapeData : restrain all non-virtual atoms to stay inside a sphere, spherical layer or a box


build string "ala his trp"
set selftether a_//c* 
set terms only "vw,14,hb,el,to,sf,en,ts"
show selftether
delete selftether 
print "max deviation = " , r_out


a harmonic restraint pulling an atom in the current object to a static point in space. This point is represented by an atom in another object. Typically, it is used to relate the geometry of an ICM molecular object with that of, say, an X-ray structure whose geometry is considered as a target (see also delete tether, minimize tether, show tether, set tether ).
The restraint can also pull an atom to a z-plane (rather than to a point), if you specify tzMethod="z_only"
Atom specific weights can be imposed with tzMethod="weighted" via bfactors.
tzMethod="function" is the most flexible. It allows you to specify different strength, upper and lower boundaries for each tether, establish a flat area in which no penalty is imposed, and even exert constant force. In this case one needs to set atom properties of the "dummy" object to which the "active" atoms are tethered.
Three other types of restraints are selftether (does not need an extra object) , drestraint (distance restraints), and vrestraint (multidimensional variable restraints).

tif files

Tag(ged) Image File Format, used by default in the ICM commands write image and display trajectory. See also: rgb, png, targa .

transformation vector

an elementary space transformation is defined by a rarray where values {a1,a2,...,a12} define 3x3 rotation matrix and translation vector {a4,a8,a12}. The complete augmented affine 4x4 transformation matrix in direct space can be presented as:
   a1  a2  a3  | a4 
   a5  a6  a7  | a8 
   a9  a10 a11 | a12 
   0.  0.  0.  | 1. 
The commands and functions related to transformation vector (referred to as R_tv):
  • transform ms_ R_tv applies transformation to an object;
  • Transform( .. ) function returns one or several concatenated 12-vectors.
  • Transform( i_spaceGroupNumber) returns a chain (R_[1:12*n]) of all n transformation vectors composing the specified space group;
  • Augment( R_tv) converts 12-membered transformation vector into the augmented transformation matrix 4x4;
  • Vector( M_4x4) converts a 4 by 4 transformation matrix into 12-membered transformation vector
  • superimpose as_1 as_2 ... returns R_tv in R_out;
  • Rmsd( as_1 as_2 [ exact]) returns R_tv in R_out;
  • Axis( R_tv ) calculates the rotation axis R_3 of the transformation. Rotation angle is returned in r_out;
  • Rot( R_tv ) extracts the 3x3 rotation matrix;
  • Trans( R_tv ) extracts the translation 3-vector which is applied after rotation.

surface area

Copyright© 1989-2020, Molsoft,LLC - All Rights Reserved. Copyright© 1989-2020, 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.