ICM Manual v.3.8
by Ruben Abagyan,Eugene Raush and Max Totrov
Copyright © 2018, Molsoft LLC
Jan 4 2018

Reference Guide
 ICM options
 Alignment Editor
 Cgi programming with icm
 Xml drugbank example
 Tree cluster
 Flow control
 Energy Terms
 Gui programming
 Icm shell functions
Command Line User's Guide
PrevICM Language Reference
String variables

[ s_alignment_rainbow | s_blastdbDir | s_editor | s_entryDelimiter | s_errorFormat | s_fieldDelimiter | s_helpEngine | s_icmhome | s_inxDir | s_icmPrompt | s_imageViewer | s_javaCodeBase | s_labelHeader | s_lib | s_logDir | s_out | s_pdbDir | s_pdbDirFtp | s_pdbDirWeb | s_projectDir | s_printCommand | s_prositeDat | s_psViewer | s_reslib | S_skipMessages | s_sysCp | S_sysLs | s_sysMv | s_sysRm | s_tempDir | s_translateString | s_userDir | S_usrlib | s_webEntrezLink | s_webViewer | s_xpdbDir ]

System string variables are predefined in the shell. New string variables can be created via assignments, e.g.

a = "What took you so long?"
txt = """
Once upon a time some evil dwarfs
filed a patent claiming the right to 
paint shirts blue color
, or the read string command or a function returning a string ( e.g. a = String(2.3) ) or created by a command as one of the output variables, eg s_out.


This variable now controls how alignments are colored automatically by properties like conservation or entropy. For example:

s_alignment_rainbow = "pink/white/white/lightyellow/yellow/yellowgreen/green"

Note: this variable does not influence the consensus-based coloring via tables CONSENSUSCOLOR and CONSENSUS


return directory with Blast-formatted sequence files for ICM sequence searches. By default the directory is set to the $BLASTDB system shell variable. The variable can also be explicitly defined in the user_profile.icm or _startup file. In order to start using the $BLASTDB shell variable, delete explicit assignment of the s_blastdbDir from your _startup file or add

to your ~/.icm/user_startup.icm file.
The find database family of sequence/pattern search commands use the s_blastdbDir directory.


a string to invoke an external editor.
Attention!!! Always use the call to the program which starts the program in the foreground. For example: use "jot -f" rather than just "jot", since the default is running in the background.
 s_editor = "vi"      # good old vi, does not require a separate window 
 s_editor = "jot -f"  # popular SGI editor 
 s_editor = "xedit"   # simple and exists for X on every platform 
 s_editor = "notepad" # exists for PCs 


a string which delimits entries in the database output of a table or a set of arrays, generated by the show database or write database commands. The %i specification at the end will be replaced by the current number of the entry and carriage return.
Default: ("#____________________________ %i")
 s_entryDelimiter="//\n"  # EMBL-database delimiter  
 s_entryDelimiter="\n"    # empty line

See also:


defines the exact appearance of the ICM error messages. Specification %s corresponds to the minimal ICM error message. If %s is missing all error messages are reduced to the specified text. If s_errorFormat is equal to the empty string (""), all error messages will be suppressed. If icm is started in the "web" mode (i.e. with the -w path flag), the variable is automatically set to "<hr><h3>Error: %s</h3><hr>" .
 s_errorFormat=""             # do NOT print error messages 
 s_errorFormat=" Error> %s"   # standard error messages 
 s_errorFormat=" Erreur> %s"  # French version 
                              # html-padding 
 s_errorFormat=" Fehler> der Betrieb ist verboten"    
                              # replace all the messages by this text 


contains characters which are considered as field delimiters by the Field and Split functions, as well as by read column and write table commands. In "Split" and "read table" one can also specify the field delimiter explicitly.
Important. If a character is duplicated in s_fieldDelimiter (e.g. s_fieldDelimiter="::" ), then multiple occurrences of this character will be ignored. Otherwise, EMPTY fields will be created between each pair of identical delimiter characters.
In write table s_fieldDelimiter is honored only if is a one-letter symbol, like "," or "\t".
See also the opposite operation, merging members of string array into one string: Sum( S_, s_separator )
 s_fieldDelimiter="\t"   # "aaa\t\t bbb" splits into "aaa",""," bbb"  
 s_fieldDelimiter="\t\t" # "aaa\t\t bbb" splits into "aaa"," bbb"  
Default ( " \t\t" i.e. two blanks, two tabs, meaning skip multiple blanks or tabs). Another reasonable possibility is " \t\t\n\n" which means skip blanks,tabs and carriage returns.


path to the HTML help file browser program. If you have no HTML browser, the default setting is s_helpEngine="icm", so you can use the simple internal ascii help-file viewer more filter ('q' - to stop, '/' to find a string, 'Enter' - next screen). If the desired help information is not found, just type help and then use '/' plus the search pattern to perform the context search in the whole help file.
 s_helpEngine="mozilla"  # make sure you can start it in the UNIX shell  
 s_helpEngine="icm"      # why would one need more?  


defines the home directory of the ICM program. This directory contains all standard ICM databases, all scripts, examples, documentation, initial configuration files (later users can override them with the files stored in the s_userDir directory.
The Linux icm-rpm package creates s_icmhome in /usr/icm directory.


defines directory from which icm - index files for large sequence or chemical databases are stored. This variable is used by the write index command. By default s_inxDir is set to s_icmhome + "/data/inx/" .
See also: read index , write index .


defines the ICM-prompt string. This string contains text and a bunch of wild cards for:
  • %o - name of the current molecular object
  • %e - list of the active energy terms (see the set terms command)
  • %t - time spent in ICM (may be convenient for scripts)
  • %T - astronomical Time
  • %% - % character
  • %# - icm-command order number
Be smart, see the energy or penalty terms you are using by adding %e to the prompt string.
 s_icmPrompt="%## "                     # for minimalists 
 s_icmPrompt=""                         # for super-minimalists 
 s_icmPrompt="%T> "                     # for anxious paranoiac freaks 
 s_icmPrompt="MY_ICM/%o/%e/%T/%#> "     # for the verbose 
 s_icmPrompt="Hi-hi|%e-^%o+%T>   "      # for the messy 
 s_icmPrompt="Icm command number %#> "  # for the retarded 
 s_icmPrompt="Hey dude, type something" # for dudes 
 s_icmPrompt="%o/%e> "                  # for humble and wise researches 

Default: "icm/%o> "


defines the command to view the image files ( tiff, png, targa and rgb formats) if the display option is specified. An alternative to the default is the "xv" program. See also the write image command.
Default for SGIs ( "imgview").


path to the folder containing java applet class files. Java applets are currently used by the web or write html commands with a chemical table.
Default: "/Java/"


defines a prefix string for all labels. For example, when displaying CPK atoms you may move the label to the right of the atom center by
 s_labelHeader="     " 
Default ( "" - an empty string).


ICM library name root. If you redefine it to say "new", ICM will start to look for the following library files: new.cod, new.bbt, new.bbs, .... etc. in the $ICMHOME directory.
Default ( "icm").


when you quit an icm-session, a _seslog.icm file is automatically stored. If the s_logDir variable is empty, it is stored to the s_userDir + "/log/" directory. However one can redirect it to the current working directory ( "." ) or any other directory.
The same logic applies to the _crashlog.icm file which is created when ICM crashes.
s_logDir = "." # _seslog.icm stored in the current working directory 
s_logDir = ""  # to the current working directory 


a string where some commands store their string/text output. See also: printf read database read string, read table, and read unix,
Default ( "is where the string/text is stored" ).


directory containing the PDB database of 3D structures and defining the location of the pdb files for the pdbDirStyle from 1 to 5 (the ftp and http styles are controlled by a different variable). These files can also be easily downloaded directly from the PDB site if the variables are set as in the example below. PDB distributions can exist in several styles (all files in the same directory, or divided etc.). The style is defined by the pdbDirStyle preference.
The pdb directory also contains the derived_data subdirectory with useful files ( pdb sequences, index files etc. )

Attention! Note that if the pdbDirStyle is set to 6 or 7 this variable is NOT USED. Variables s_pdbDirFtp and s_pdbDirWeb are used instead! (it was hard coded until version 3.5-2)

 s_pdbDir ="ftp://ftp.rcsb.org/pub/pdb/data/structures/divided/pdb/" 
 pdbDirStyle = "ab/pdb1abc.ent.Z" 
 s_pdbDir = "/data/pdb/" 
 read sarray s_pdbDir+"/derived_data/index/source.idx" 
 source = Tolower(Trim(Field(source,1))) 
 for i=1,Nof(source) 
   read pdb source[i] 
#  do some analysis 
   delete a_*. 
Default ( "/data/pdb/"). It is usually redefined in the _startup file.


If pdbDirStyle is set to 6 (for the ftp access), the location of the ftp site is controlled by this variable. Example:

s_pdbDirFtp = "ftp://ftp.rcsb.org/pub/pdb/data/structures/divided/pdb/" # an old site
read pdb "1crn"


If pdbDirStyle is set to 7 (for the http access), the location of the web site and the request format is controlled by this variable. Example:

s_pdbDirWeb = "http://www.rcsb.org/pdb/files/%s.pdb.gz" # an old web site
read pdb "1crn"


a relative path to the directory in which icm-projects (all the icm-objects in a session) are stored. This path is appended to the s_userDir directory.


a command to print text or postscript files. This command is invoked if the print option is specified in the write image postscript or write postscript commands. Customize this string. Default ( "lp -c" ).

 s_printCommand = "lp -c -d ColorPrn22" 
 write image postscript print  # save image and print 


is a file containing the full file name of the prosite database of protein patterns. This file is not large and is distributed with ICM. If you have your own copy of prosite, redefine the variable and delete prosite.dat in the $ICMHOME directory to avoid redundancy.
Default ( "prosite.dat" ). It is usually redefined to s_icmhome+"prosite.dat" in the _startup file.


a PostScript viewer used while you are in ICM session. A command to invoke is to be:
 unix $s_psViewer </tt><i>your PostScript file name</i>  

Default is system specific.


name of the icm residue library that contains discriptions of chemical residues. The file will be loaded from the $ICMHOME directory.

To create a new residue use the write library command.
Default ( "icm").

s_skipMessages : ignore specific error messages

In ICM all error and warning messages are numbered (e.g. " Warning> [123] .. " ). You may specify a set of message numbers which you want to suppress. While the messages are suppressed the error code can still be returned with the Error(number) function.
 a = 1 
 if = 2       # deliberately generate error 
  Error> [2073] illegal IF: wrong condition in  if=2 
 s_skipMessages = "[2073]" 
 if = 2        # now no message is generated 
 if Error(number)==2073  quit 
 a = yes      # generates another error 
  Error> [696] wrong assignment or name conflict   
 s_skipMessages = "[2073][696]" 
 a = yes      # hides the error message 
 Warning> [147] number 2352352532 is too big for an integer (>2147483647)    
 s_skipMessages = "[2073][696][147]"   # suppress the warning 

See also: errorAction , s_errorFormat .
Default ( "[3000][3012]" just to show an example).


automatically filled out string containing the copy file command for the current operating system. It is advised to use this variable in scripts for cross-platform portability.

s_sysLs and s_sysLtt

automatically filled out string containing the list file command (or list files sorted by modification time) for the current operating system. It is advised to use this variable in scripts for cross-platform portability. Example:

sys $s_sysLs   # to list files in the current directory
sys $s_sysLtt   # to list files in the current directory


automatically filled out string containing the move or rename file command for the current operating system. It is advised to use this variable in scripts for cross-platform portability.


automatically filled out string containing the delete or remove file command for the current operating system. It is advised to use this variable in scripts for cross-platform portability.


scratch directory for temporary files ( some montecarlo files will be saved there ).
Default ( "/usr/tmp/").


a set of characters used in the ascii representation of numerical values of arrays, matrices and maps. See also the String function and the show map command.
Default ( ".:*0#" ).


The path to the user directory containing ICM-related and ICM-generated data files.
The suggested _startup file sets this variable to a subdirectory .icm of the user $HOME directory ( $USERPROFILE for Windows), but you may set it anywhere you want.
Default ( "$HOME/.icm/").

s_usrlib (obsolete)

an obsolete variable. The new mechanism to add new icm residue libraries uses the LIBRARY.res sarray. You can generate the entries using the write library command.
Default ( "usr").


defines the NCBI Entrez link.
See also: webEntrezOption, Default ( "http://www3.ncbi.nlm.nih.gov/htbin-post/Entrez/query?db=s&form=6&uid=%s&Dopt=%c").


An obsolete variable. Web browser is defined by OS default.


path to the ICM XPDB database root of compact binary ICM objects which are annotated with the site information. The root directory contains pdb-style subdirectories with named after the 2nd and 3rd character of the four-letter code. The advantage of the XPDB database is the speed of reading and smaller size than PDB. XPDB entries are read about hundred times faster!

Here we compare the execution times for the pdb and xpdb files:

eos:/home/ruben/icm> time ./icm -s -e 'read object "/data/xpdb/1ffk.ob"' 
0.450u 0.090s 0:00.54 100.0%   
eos:/home/ruben/icm> time ./icm -s -e 'read pdb "/data/pdb/ff/pdb1ffk.ent.Z"' 
38.800u 0.430s 0:42.11 93.1%  

An xpdb directory can be in a remote location, e.g.

s_xpdbDir = "http://ablab.ucsd.edu/xpdb/"
read binary pdb "1crn"


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