ICM Manual

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

table

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 ]

Examples: 

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.:


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

E.g. 

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"

Where:

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"

Example: 

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.

Example: 

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:

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 ]

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.
Example: 
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: 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:

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
%3

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


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

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

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.

Example: 

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

tether

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):