ICM Manual v.3.8
by Ruben Abagyan,Eugene Raush and Max Totrov
Copyright © 2019, Molsoft LLC
Jun 9 2022

 Scripting Tutorials
Reference Guide
Command Line User's Guide
PrevICM Language Reference
Getting started

[ Shell | Reading ]

Start the GUI (Graphics User Interface) version of ICM by typing icm -g or icm -G and hitting RETURN. This executable will look the $ICMHOME shell variable. The commands of the GUI menu will be taken from $ICMHOME/icm.gui file. Feel free to change it. The GUI is meant to be self-explanatory. In this manual we will mostly focus on the shell commands and function, since in many cases the GUI gives you only limited subset of possibilities.


[ icm-shell-objects ]

ICM-shell is a basic interface between a user and the ICM-program. The shell can be used from the GUI version or directly. This is a powerful and flexible environment for a multitude of versatile tasks ranging from mathematics and statistics to very specialized molecular modeling tasks.
Start ICM by typing:
Make sure that your .cshrc login file contains
 setenv ICMHOME  /whatever/your/ICM/directory/is/ 
Do not forget the slash at the end. It is also useful to add your $ICMHOME directory to your $path since there are some ICM related shell scripts and utilities which you may want to access.
You will see the ICM-prompt inviting you to type a command. The first thing to know is how to get help. You may just type help and use / whatever to find what you want, or use help commands or help functions to find out about the syntax. Now type:
You have just created a new ICM-shell variable aa and assigned a value of 2.4 to it. You can create a variable with a name which is not already in use in the ICM-shell, does not contain space or delimiters like ".","," and starts from a letter (e.g. 1aag is an illegal name, except for sequences). Let us go on:
Now you have created another ICM-shell variable bb and its value is probably 4.8. Find it out by typing:
 print " bb=", bb 
or any of these commands:
 list "b*" 
 list integers 
 show bb 
The next step would be to type a conditional expression like:
 if (bb != 4.8) print "something went wrong" 
or something even more elaborate:
 if (bb != 4.8) then 
   print "something went wrong" 
   print "It really works" 
You can always start a for-loop such as:
 cc={"sushi","sashimi","negi maki","toro","period."} 
 for i=1,Nof(cc)  
# Nof returns the number of elements. 
#  Index i runs from 1 to 5 
   print "*** I just like to eat  ",cc[i] 
Notice that anything after a pound sign # in ICM scripts is a comment.
We have just played with a real variable bb and string array cc . They had their unique names and we could create, read, write, delete and rename them.
ICM-shell objects
Furthermore, the ICM-shell can handle many other different types too, namely, it may contain in its memory entities of 16 different types, such as
  • integer , (e.g. a=10, b= -3 )
  • real , (e.g. c = -3.14 )
  • string , (e.g. d = "ICM rules" )
  • logical , (e.g. e = (2 > 43); f = yes )
  • preference , (i.e. fixed multiple choices, try show wireStyle )
  • iarray , (i.e. integer arrays, g={-2,3,-1} )
  • rarray , (i.e. real arrays, h={ -2.3, 3.12, -1.} )
  • sarray , (i.e. string arrays, i={"mek","yerku","erek"} )
  • parray, including array of 0D,2D or 3D chemicals, e.g. chm = Chemical({"CC","CC(=O)O","C1CC1"})
  • matrix , (read from a disk file, e.g. read matrix "def.mat" )
  • sequence , (i.e. amino acid or nucleotide sequences, e.g. a=Sequence("ASDQWE")
  • alignment , (i.e. pairwise or multiple sequence alignments, read from a file)
  • profile , (i.e. protein sequence profiles)
  • map , (i.e. density functions defined on the 3D grid)
  • grob (abbreviation for GRaphic OBject, which is different from molecular graphics objects, and contains dots, lines and solid surfaces; it can be a contoured electron density, 3D plot, an arrow, etc)
  • atomic/molecular objects and related selections of atoms ( a_//ca,c,n ) residues ( a_/2:15 ) molecules ( a_1.b,c/ ) objects ( a_1,2. ) and, finally ..,
  • table , or spreadsheet. Several arrays are linked together in a table. Table can also have a header with some additional data fields. Tables are essentially simple databases which can be manipulated with, sorted and searched with ICM commands.
The more complicated objects, like arrays, sequences, alignments, maps etc., can be read from a disk file (e.g. read sequence "a.seq" ) or created by an ICM command or function (e.g. a=Sequence("ACFASDTRSEEDFFF") or make sequence a_1.1 )
Atomic objects are usually specified by an atom, residue, molecule or object selection which are collectively referred to as selections.
All of the listed entities have their unique names in the ICM-shell and can be read, renamed (e.g. rename myFactors bbb ), deleted (e.g. delete myFactors aaa ), written to a file with a standard type-specific extension (e.g. write aaa "surf" will create file surf.gro , the extension type depends on the object), shown, often printed and displayed graphically.
A number of ICM-variables have reserved names and are used by the program. For example, the mncalls variable always describes the number of molecular energy evaluations during a minimization, s_pdbDir is the path to your pdb files, etc. You may customize some of those ICM-shell variables by redefining them in the system-wide _startup file, and $HOME/.icm/user_startup.icm file. The standard _startup file reads icm.ini file which contains many standard directory and parameter definitions, e.g.
 read all s_icmhome+"icm.ini" # initialize icm variables       

Important: be careful when negative numbers appear in the command line. If not separated from the previous numeric argument by a comma, they will be interpreted by ICM-shell as an expression, i.e. the two arguments will simply be replaced by their difference. For example, the command
 display string "I like crambin" -0.9 -0.3 
is wrong, a comma is needed, otherwise -0.9 -0.3 will be substituted by -1.2. This command will place the string in a point with screen coordinates X=-1.2 and Y=0.0 (the default), not in X=-0.9 and Y=-0.3 as might be expected. The safest way should be to use commas as separators in the argument list in the command line, like the following:
 display string "I like crambin" -0.9 , -0.3   
is correct, the two arguments are separated by comma
Now you can use the mouse to rotate and translate molecules and strings. The left mouse button is associated with rotation, the middle mouse button is translation and the right mouse button clicks are used for drop down menus in GUI and labeling (double click is a residue label). A more detailed list of graphics controls is given below.
As far as the keyboard commands and prompting, try to use the arrow keys for invoking previous commands and TAB for prompting (e.g. atom TAB ) to see the available commands and functions.

The first steps

Your first ICM commands may be the following:
 read pdb "1crn"   # check pdbDirStyle variable for PDB access 
 display ribbon  
or simply
 nice "1est"  
You can also:
 read mol  s_icmhome + "ex_mol"  # or 
 read mol2 s_icmhome + "ex_mol2" # or 
The second way to create a molecular object is building the extended chain given the amino-acid sequence. The simplest way to build a short peptide is to use the build string command. Type
 build string "nter ala his leu tyr cooh"   # or 
 build string "AHLY;AGGAR" # to build two molecules 
 build string "ra rg ru; ra rc ru" # to build two rna chains

In a more complex case create a file, say mymol.se, .se being the standard extension for the object sequence files. The file should contain the names of molecules (field ml) and their sequence (field se) and may look like this:
ml mol1 
se nter ala gly his ser trp cooh 
ml mol2 
se hoh 
ml mol3 
se hoh 
 build "mymol" 
to build the object. Now you can display the three molecular objects you have just loaded, i.e. crambin, the two peptides. We will use the cpk and the xstick graphics representations.
 display a_2.           # a_2. means 'the second object' 
 display cpk a_1./2:10  # a_.. means 'residues 2:10 of the first object' 
 display xstick a_1./16:18 
You can also replace residues with the modify command:
 modify a_2./his "tyr" 
Let us clear the scene and start doing some more fun things:
 delete a_*. # a_*. selects all the objects 
 build "mymol" 
 display     # by default displays everything 
 set vrestraint a_/*  # this command will increase the efficiency 
Of course, there is a more elaborate possible setup for a montecarlo run (see _folding script) and graphics should not be used for a real run. However, the above example is pretty much what you need to do to run the Biased Probability Monte Carlo Minimization to find the global minimum which models the solution structure of this peptide.
Now let us make a quick tour into multiple sequence alignments. First, get your sequence file (most formats will be accepted). The simplest default file format (then you do not need format type specs like: msf, pir, etc) is the fasta format (angular bracket and sequence name followed by the sequence)
> seq1 
> seq2 

There are some example multiple sequence files in the ICM-directory. Let us do the following:
 read sequences s_icmhome+"sh3"   # example sh3.seq file  
 group sequence "*" sh3ali 
 show sequences alignments 
 align sh3ali                     # redo the multiple sequence alignment 
 unix gs sh3ali.eps               # gs is a PostScript previewer 
 show Align(Fyn, Eps8)            # make a pairwise alignment 

If you want to go directly to more elaborate sessions and scripts, or have a "How can I ..." question, you may hop to the User's Guide section.

Scripting Tutorials

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