Brain Imaging & Analysis Center

Any command line that begins with a variable, a number, or a function is assumed to be an arithmetic expression. Such expression lines are broken down differently from normal commands. Spaces are ignored. The entire command line must be a meaningful arithmetic expression. In other words, parentheses must be balanced and operators must separate operands in standard “in-fix” notation. (For example, 'a + b' is a valid expression but '+ a b' is invalid.) As long as the line makes sense mathematically you can make arithmetic expressions as complicated as you wish. The parser can handle up to 100 terms, which is more than you are ever likely to need to fit into a single expression.

Arithmetic Operators

CIGAL recognizes normal arithmetic operators in standard expression syntax. Arithmetic operators are evaluated in order of precedence, with the following precedence heirarchy (from highest to lowest):

           ()                   parentheses
           ++,--                Autoincrement, Autodecrement
           -,!                  unary Minus, unary Not
           **                   raise to the power- exponents
           //                   Join
           *,/                  Multiply, Divide
           +,-                  Add, Subtract
           ==,!=,>=,>,<=,<,>>   comparators, and Append (>>)
           &,|,!                And, Or, Not logical operators
           =                    Assign

See [OPERATORS](1) for more information about the meaning of these symbols.

Operands

The arithmetic operators can be used to combine functions, constants, variables, or subsets of variables. In general any of these operands can be used anywhere in an expression. However, constants and functions cannot be the target of an assignment (=), autoincrement (++), or autodecrement (–) operator, as it is impossible to change the value of constants or functions. In CIGAL, constants are either numbers or character strings (see [NUMBERS](1) and [STRINGS](1)).

Variables can be of any type and size (see [VARIABLES](1)). If a variable has more than one element then the operator is applied to all elements of that variable. For example, adding a constant to an array, such as:

           array1 = array2 + 10.35

adds 10.35 to every element of array2 and stores the result in array1. If two variables have different sizes, and neither is a single element, then the extra elements in the larger variable are simply ignored.

If variables are not of the same data type the appropriate type conversion is performed automatically. Values that are outside the range of the target data type are clipped to the nearest legal value. For example, assigning a value greater than 255 to a BYTE type variable is automatically converted to 255 (see [VARIABLES](1)).

Complex expressions that must be evaluated in stages automatically create temporary variables to hold the intermediate results. The temporary variables are normally transparent to the user, except that an error is generated if there is not enough memory available to hold all of the temporary data. If this error occurs it is up to you to break the expression up into simpler steps and make sure you have someplace to store each stage of the calculation. However, since the arithmetic routines have access to all of the program's unused memory space, generally only very large variables risk running out of memory.

Functions

Functions behave as a special class of arithmetic operators. Each function is evaluated independently and the result is either stored directly in the target variable or, in a multi-step expression, the result of the function is stored in a temporary variable. Therefore, functions are treated as pseudo-variable operands by the parser and can appear anywhere in an expression that a variable could appear. For example:

         array1 = sqrt(array2) * log(array1) + mean(array3)

In this case, SQRT, LOG, and MEAN are functions that act as operands for *, +, and =. In general, the size and type of a function will be determined by the size and type of its arguments, although there are exceptions to this rule. See [FUNCTIONS](1) for more information about CIGAL functions.

Arithmetic Expressions Without a Target

If you enter an expression line (i.e., a command line that begins with a constant, variable, or function) that does not explicitly specify here the results of the expression are to be stored, then the results will be printed on the screen (or sent to a file if you are redirecting output (see [FILES](1)). The format of the output is determined by the type and size of the results of the expression. Since an expression can contain a single term, this also provides a simple way to see the value of any variable; simply type the variable name and its value will appear. Seeing the value of variables or expressions in this way is essentially a shorthand form of the TYPE command. (The TYPE command itself is still useful, however, as it provides a more flexible general method for displaying data – see [TYPE](2)).

Arithmetic Expressions as Command Arguments

Finally, arithmetic expressions can also be used as arguments within standard CIGAL command lines or as subscripts to variables (see [SYNTAX](1) and [VARIABLES](1)). Such expressions must produce values that are appropriate for the particular command or variable. There are two limitations in using expressions in this way. First, when an expression appears as a command argument it must not contain any spaces; as spaces are used to separate arguments. Expressions with a space will be treated as two different arguments. Second, an expression appearing within an argument of a function must not call another function. Nested function calls are not currently supported. You must break such expressions into separate operations.

Examples

The following are all valid CIGAL commands (assuming that the data variables have been declared previously – see [DECLARE](1)):

EXPRESSION                                      RESULT
a = b                                          ;assign the value of B to A
23*b                                           ;print the product
a=b/5                                          ;assign quotient
a = sqrt(567)                                  ;assign square root
a*23 * ((b-c*log(d)) + (sin(x)/cos(x)+2))      ;print result
arrayY = m * arrayX - cos(arrayZ) / b          ;do array arithmetic
matrixA = matrixA + mean(arrayB)               ;increment all of matrixA
string1 = 'I want a ' // string2               ;join 2 strings
imageA(a:a+100,b:b+40) = imageB(100:200,50:90) ;copy part of an imageB to A
rotate vecs 20 a/4 b-45                        ;use expressions as arguments

See Also:
CIGAL Home, CIGAL Manual, Topics List, Manual Help