[ 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 header which is a set of any ICM-objects and
• a spreadsheet (or a set of columns) composed of iarrays, rarrays, sarrays, or parrays, of the same length. A column can also be a function of other columns (e.g. Sin(A)) (see add column function to create a function column and build column to update )

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

• 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

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

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:

• "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"

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:

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

  
  a,b,c
  12,'c2','c3'
  24,'cc2','cc3'
  

• .icb files for the icm binary formatted table(s).
• .sdf files for chemical information.

# .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"

[ 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] & ... )

 
 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

• split column values
• appending one table to another by a shared column
• grouping table rows by a column
• add/insert table rows
• specifying actions upon clicking on table rows

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}]

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

 
 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" 

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

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>
"""

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 .

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

dsChemLock_new "%@" "%@" %#

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.

• 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

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

 
   a1  a2  a3  | a4 
   a5  a6  a7  | a8 
   a9  a10 a11 | a12 
   ------------+---- 
   0.  0.  0.  | 1. 

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