 ICM Manual v.3.8
by Ruben Abagyan,Eugene Raush and Max Totrov
Dec 27 2021

 Prev ICM Language Reference Arithmetics Next

Most of the ICM-objects can be used in arithmetical, logical of comparison expressions. In this section we describe operations defined in the ICM-shell.
Members of the arithmetic, logical and comparison expressions
Abbreviations: integer ( i ), real ( r ), string ( s ), logical ( l ), iarray ( I ), rarray ( R ), sarray ( S ), matrix ( M ), sequence ( seq ), profile ( prf ). alignment ( ali ), map ( m ), graphics object (grob) ( g ), atom selections ( as ), selections of internal coordinates, for example torsion angles, ( vs ) , and table ( T ). Table arrays are abbreviated as T.I, T.R and T.S, depending on the type

Assignment

allows you to assign a value to a variable.
Syntax: ICM-shell-variable-name = Value or expression
If the name is new, a new ICM-shell variable is created , an object of the matching type will be overwritten.

Examples:

a=1            # create new integer variable  a
b=a*a          # create variable b as product a*a
c=a*Sin(45.)   # create new real variable c

Chain assignment for the logical system variables and semi-colon separated commands. Exressions like l_info=l_commands=l_warn=no are allowed for the logical system variables

Also, from version 3.6-1 several semi-colon separated commands can be specified in one line.

Assignment fo selected elements of an array:

array[I_indices] = Value

array[I_indices] = Matching_array_of_values

Several elements in integer, real and string arrays can be assigned at once to a single value , or, element-by-element to a matching array. Example:

a = {1 2 3}
a[{1 3}] = { 3 1 }
a[{1 3}] = 10

Unique name.To find a unique name for a new variable, use the Name( "nameRoot" , unique ) function.

Assignment and operations in place are also possible and it allows to modify an existing variable rather than create a new one. Example:

i += 1  # adds one to i, better than i = i + 1
s += " and more .. "
I //= 15  # append to an iarray
R //= 1.5 # append to an rarray
S //= "one more element" # append to an sarray

Arithmetic operations

The following operations are defined in the ICM-shell:
• addition ( + ) :
• i+i returns i (e.g. 2+3 returns 5),
• i+r, r+i, r+r return r (e.g. 2+3. returns 5),
• I+I returns I (e.g. 1,2+{2,3} returns 3,5),
• I+R, R+I, R+R return R (element by element),
• s+s, s+i, s+r return s (i.e. "what" + "If" returns "whatIf","file"+2 return "file2"),
• S+S, S+I, S+R return S (the above three operations for each element),
• M+M returns M of the same dimensions (element by element addition),
• prf+prf returns prf,
• grob + R3 return grob with coordinates translated by R3,
• map+map, map+i, map+r, i+map, r+map returns map of the same dimensions.
• subtraction ( - ) :
• i-i returns i,
• i-r, r-i, r-r return r,
• I-I returns I,
• I-R, R-I, R-R returns R (element by element),
• M-M returns M of the same dimensions (element by element subtraction),
• map-map, map-i, map-r, i-map, r-map returns map of the same dimensions.
• multiplication ( * ) :
• i*i returns i,
• i*r, r*i, r*r returns r,
• I*I returns I (element by element, e.g. {1,2}*{3,4} returns 3,8),
• I*R, R*I, R*R return R (element by element). The scalar product is returned by Sum(R_1,R_2), and the vector product is returned by Vector(R_1,R_2) (two 3D vectors)
• M*M returns a matrix product of the two matrices (M[nk]*M[km]==>M[nm]),
• M*R, R*M returns R,
• prf*prf returns prf,
• map*r, map*i, i*map, r*map, map*map return map (operations on each element),
• grob*r, grob*i, r*grob, i*grob return grob with transformed coordinates.
• division ( / ) :
• i/i returns i (integer division, e.g. 3/4 returns 0),
• i/r, r/i, r/r return r (real division, e.g. 3/4. returns 0.75),
• I/I returns I (integer division of elements),
• I/R, R/I, R/R return R (real division of elements),
• map/r, map/i return map (operations on each element),
• grob/r, grob/i return grob with transformed coordinates.
* concatenation, appending into array ( // ) :
• i//i returns I (e.g. 2//3 returns 2,3 ),
• r//r returns R (e.g. 2.2//3.3 returns 2.2,3.3 ),
• s//s returns S (e.g. "a"//"b" returns "a","b" ),
• I//i returns I[n+1] extended by the integer (e.g. 1,2//3 returns 1,2,3 ),
• I//I returns I[n+m] (e.g. 1,2//{3,4} returns 1,2,3,4 ),
• R//r returns R[n+1] extended by the real (e.g. 1.,2.//3. returns 1.,2.,3.),
• R//R returns R[n+m] (e.g. 1.,2.//{3.,4.} returns 1.,2.,3.,4. ),
• S//s returns S[n+1] extended by the string (e.g. "a","b"//"c" returns "a","b","c"),
• S//S returns Sn+m (e.g. "a","b"//{"c","d"} returns "a","b","c","d" ),
• M[n,m]//M[n,k] returns M[n,m+k] (matrix concatenation row by row ),
• seq//seq returns concatenated seq (similar to s+s);
• prf//prf returns concatenated prf;
• grob//grob returns concatenated grob (similar to s+s);
• parray//parray returns concatenated parray; (this applies to different types of pointer arrays, e.g. chem_array//chem_array )
* ali1//ali2 returns projected alignment. Projected concatenation of two alignments sharing the same sequence. The shared sequence serves as a ruler for merging the two alignments. The alignments can be of arbitrary size and number of sequences. In the simplest case of three sequences a, b, c and alignments ab and bc, the operation ab//bc will create an alignment of three sequences a b c . The function Align(ab//bc,{1,3}) will extract the, so called, projected alignment of a and c through b. Example:

ali1    //    ali2  returns   Projected ali.
a VYRWA-W     b FK-WG--KW     a  VYR-WA---W
b -FKWGKW     c AKGWAPGKW     b  -FK-WG--KW
c  -AKGWAPGKW

Additionally, character arrays (strings) can be projected from sequence to alignment and back with the String (..) function and numerical residue properties can be projected from sequence via alignment with the Rarray (..) function.

Logical operations

Logical operations with table arrays are described separately (see table in Glossary).
• and ( & ):
• l & l returns logical, e.g. yes & no returns no
• as & as returns selection as with objects molecules residues present in both initial selections, (e.g. a_2//ca & a_//T returns the tethered Ca atoms of the 2nd molecule),
• as & s, multiplication by a string mask, e.g. a_//ca & "x-" returns the odd Ca atoms.
• as & seq returns residue sub-selection of as with the matching sequence, e.g. a_*. & 1crn_m returns residues matching the crambin sequence.
• as & R returns atom sub-selection with coordinates within a six dimensional box array R (see also function Box) , e.g.

display ribbon
color ribbon green Res( a_//* & {0.,0.,0.,9.,9.,9.} )

More types of selections are returned by the Select, Sphere, and Acc functions.
• vs & vs returns selection vs of internal coordinates present in both initial selections, (do not forget that v_ are free variables, and V_ are all variables);
• vs & as returns subset of initial variables vs which is related to selection as, e.g. side-chain torsion angles in the sphere around loop 14:18 can be selected as follows:

V_//xi* & Sphere( a_/14:18 )

multiplication comments on logical multiplication of two selections below.
• or ( | ) :
• l|l returns l (e.g. yes|no returns yes ),
• as|as returns as with members of both selections (e.g. a_/4:6 | a_//ca )
• vs|vs returns vs with variables from both selections (e.g. v_//phi,psi | v_/3 )
• vs|as returns vs is equivalent to vs | (V_//* & as)
• not ( !) :
• !l returns logical negation to the argument (e.g. !yes returns no ),
• !as returns aselection of the same level with members not included in the selection argument (e.g. !a_//ca )
• !vs returns vselection with variables not included in the selection argument (e.g. ! v_//phi,psi )
Negation can also be applied to each section between slashes of as_ or vs_. E.g. a_//!h* (all non-hydrogens).

In place operations.

ICM-shell variables can be modified in place by using the following operators:
operatorfunctiondata typesexample
-=subtract in placei,rr -= 2.2
*=multiply in placei,rr *= 2.
/=divide in placei,rr /= 2.
//=append an element to an arrayI,R,S,Pt.Name //= "Jack"

If a variable does not exist yet, this operation will create the variable and assign a type according to the right-hand operand.

Comparison operators

Most of them are true comparison operators and return logical yes or no. In comparisons of table arrays or string arrays with strings, the comparison returns a subtable or subarray, respectively. Comparison operations with the table arrays are described separately (see table in Glossary).
• equal ( ==):
• i==i, i==r, r==i, r==r, s==s, I==I, R==R, S==S, M==M, as==as, vs==vs, exact equality of two objects;
• p==i, p==s return l. Test the value of an ICM-shell preference . Example:

if(wireStyle==1) print "int. or string is ok" # or
if(wireStyle=="chemistry") print "double bonds"

• S==sreturns S, a sub-sarray of elements exactly matching s (e.g. "aa","b","aa","c"=="aa" returns "aa","aa", see also S ~ s),
• not equal ( !=) :
• i != i, i != r, r != i, r != r, s != s, I != I, R != R, S != S, M != M, as != as, vs != vs inequality of two objects;
• p!=i, p!=s return l. Test an ICM-shell preference . Example:

if(wireStyle != 2) print "No chemistry, sorry"

• S!=s returns S, a sub-sarray of elements not matching s (e.g. "aa","b","aa","c"!="aa" returns "b","c", see also S !~ s).
• greater than ( > ) :
• i > i, i > r, r > i, r > r
• s > s lexicographic comparison for sorting ("apple" < "orange")
• less than ( < ) :
• i < i, i < r, r < i, r < r, s < s
• greater or equal ( >= ) :
• i >= i, i >= r, r >= i, r >= r, s >= s
• less or equal ( <= ) :
• i <= i, i <= r, r <= i, r <= r, s <= s
* fuzzy-equality, inclusion or pattern matching ( ~ ):
• s~sreturns logical yes if string matches a pattern.
• S~sreturns S of sarray elements matching the pattern s. This comparison is similar to the UNIX grep command; it returns a subarray of lines matching the pattern rather than yes or no. Do not forget to add flanking asterisks (*) if the pattern occurs in the middle of a string. Example:

show {"abc","bcd","ee"} ~ "*[be]?"
# Another example
# sarray SE contains sequences
CxCseqs = SE ~ "*C?C*" # all strings containing C?C pattern

• fuzzy-not-equal ( !~ ) :
• s !~ s returns logical yes if string does not match a pattern s.
• S !~ s returns S of sarray elements not matching the pattern s. S!~s is similar to the UNIX grep -v command; it returns a subarray of lines not matching the pattern.

1. Integers are automatically converted to reals in binary operations containing both integers and reals. However, in expressions like integer1 / integer2 (the same for iarrays) they are not converted into reals and the result will be different from what you might expect. For example, 3/4 returns 0, but 3/4. returns 0.75.
2. In s+i, s+r, S+I, S+R expression numbers are automatically converted into strings. In the s+s expression the second string is simply appended to the first one. Examples:

show "one " + "two"  # result: "one two"
file = "aa"+ 4       # result: "aa4"
show {"a","bb"} + {1.2,3.2}  # result: {"a1.2","bb3.2"}

3. Selection arithmetics. The level of the expression as_1 & as_2 & as_3 ... or as_1 | as_2 | ... (the same with vs_ ) is defined by the lowest level selection in the chain ( atoms - the lowest < residues < molecules < objects ). For example, in an expression a_/10 | a_2/15/cg the second selection is an atom-level-selection and the first one is a residue-level one. The result is the atom selection of all atoms of residue 10 plus Cg atom from residue 15.
4. Selection logically multiplied by string, array, or mask Multiplication of a selection to a string-mask or sequence. The resultant selection inherits level of the first argument. The mask is applied periodically to switch off some of the selected elements. For example mask "0001111" will switch off the first three elements in every seven. The 'switch off' characters may be the following: ' ' (space),'-','0'. Example masks to switch off the third element of five: "xx xx", "11011", "++-++" . Operations upon the sequence will select only the fragment with the specified sequence from the original selection. Multiplication by an array of 6 numbers {x,y,z,X,Y,Z} selects atoms within the specified box. Example:

rs_ = a_/11:15      # define residue selection rs_
rs_ = rs_ & "xx xx" # switch off the third element (res. 13)
display cpk a_//* & {1. 0. 1. 5. 7. 6.} " # a box

5. Transitional (or projected) alignment Projected concatenation of two alignments sharing the same sequence. If two-sequence alignments share the same sequence, they may be merged with the shared sequence as a ruler. In the simplest case of three sequences a, b, c and alignments ab and bc, the operation ab//bc will create an alignment of three sequences a b c. The function Align(ab//bc,{1,3}) will extract the, so called, projected alignment of a and c through b.

Examples of expressions:

i = i1/i2 + (i3-r4)*2.5/Pi

l_results=(l_beer & l_wine & !l_snacks) | l_vodka
if (l_results & n_glasses >= 4) print "Hangover.."

for i=1,215        # list streets of Manhattan north from Houston
print "Street " + i
endfor

prices = { 25. 6. 12.6 }
tips   = { 4.  1. 2.   }
print prices + tips        # the result is { 29. 7. 14.6 }

 PrevTree representatives HomeUp NextFlow control