Page Numbers: Yes X: 527 Y: -.4 First Page: 25 Not-on-first-page
Margins: Top: 1.1" Bottom: 1" Binding: 5
Odd Heading: Not-on-first-page
3. ARITHMETIC AND MATHEMATICAL FUNCTIONS
Even Heading: Not-on-first-page
IDL REFERENCE MANUAL
3. Arithmetic and Mathematical Functions
Interlisp provides a large repertoire of arithmetic and mathematical functions. All of these are available to the IDL user, and many of them have been generalized to handle missing values and extended to expect scalars, so that they will operate elementwise on arbitrary IDL arrays. In addition, IDL defines some commonly used numeric constants and includes a set of arithmetic functions particularly suited to statistical applications.
3.1 Arithmetic operators
There are three sets of basic arithmetic operators in Lisp, those that operate on integers and produce integer values (with names like IPLUS, IMINUS, ITIMES), those that operate on floating point numbers and produce floating values (FPLUS, FMINUS, FTIMES, etc.), and those that operate on mixed integer and floating arguments and produce values whose type depends on their argument types (PLUS, MINUS, TIMES, etc.). In IDL, only the mixed arithmetic operators have been extended and may be used freely on IDL arrays. Though the integer and floating operators exist in the system, they will generate errors if applied to missing data items or multi-element arrays, and their use is discouraged. The CLISP operators +,*,/,– have been bound to the mixed operators PLUS, TIMES, QUOTIENT, DIFFERENCE, and MINUS, so that complicated expressions may be written in abbreviated form. QUOTIENT has been modified so that if its divisor is zero, the result will be NIL.
The simple Lisp functions ABS, MAX, MIN and REMAINDER have also been extended. As well as being extended, MAX and MIN have both been modified so that they ignore NIL arguments. Thus, (MAX –1 NIL –2) is –1, not NIL.
The mixed arithmetic predicates have been modified in IDL so that they provide a reasonable result when applied to a missing data item. These functions have not been extended, however, since they return the truth values T and NIL, which cannot both be stored into an array. The predicates from Lisp are GREATERP, LESSP, EQP, and MINUSP. For convenience, the function PLUSP also exists in IDL and is T for any argument greater than zero. As mentioned in section 1.4, the missing data value compares EQP to NIL. As a somewhat arbitrary choice, necessitated by the binary nature of truth, it compares as if it is zero for the GREATERP and LESSP predicates, and is neither MINUSP nor PLUSP.
scalarp[s] is T if s is a scalar, NIL otherwise.
3.2 Constants
The following variables are initialized to some common mathematical constants. If changed by the user, their values are lost and must be reset.
Eis set to the base of the natural logarithms.
PIis set to p.
3.3 Mathematical and trigonometric functions
The following scalar functions have been extended: SQRT (which returns NIL for negative arguments), LOG (which also returns NIL for negative arguments), ANTILOG, EXPT (with associated CLISP operator ↑), and GCD. These are fully described in Section 13 of the Interlisp Reference Manual (Teitelman, 1978).
Interlisp’s trigonometric functions (SIN, COS, TAN, ARCSIN, ARCCOS, and ARCTAN) have been extended to expect scalars. All these functions have an optional flag argument which if T indicates that all angle sizes are to be interpreted in radians. If the flag is NIL or omitted, arguments and values will be in degrees. Again, see Section 13 of the Interlisp Reference Manual.
3.4 Distribution functions
IDL provides several functions for evaluating the probability of values drawn from certain common statistical distributions.
fprob[f;dfnum;dfden] where dfnum and dfden are the degrees of freedom for the numerator and denominator, respectively, of the F-value f, returns the probability of such an F-value.
nprob[z] where z is a normal deviate, returns the probability of such a normal deviate.
tprob[x;df] where df is the degrees of freedom for t-value x, returns the probability of such a t-value.
At a future date, binomial and x2 distribution functions may be added.
3.5 RAND and RANDN
Uniformly distributed random numbers can be obtained from the Interlisp RAND function, and random normal deviates from the function RANDN. Both are extended to expect scalars.
rand[lower;upper] returns a single pseudo-random number between lower and upper inclusive.
randn[mean;stdev] returns a single floating number, randomly sampled from the normal distribution with mean mean (default 0) and standard deviation stdev (default 1).
The Lisp function RANDSET may be used to initialize the random-number generator that both these functions depend on.
At a future date, generators for random deviates from other distributions may be added.
3.6 ROUND
The function ROUND rounds a number to a specified tolerance.
round[val;interval] for scalar val and interval, returns the nearest integral multiple of interval to val. interval defaults to one, i.e., rounding to the nearest integer.
Thus, (ROUND INCOMES 1000) will round a vector of dollar incomes to the nearest $1000. Note that rounding is to the nearest multiple, as opposed to truncation, so (ROUND 1.4 0.5) is 1.5, not 1.
ROUND is useful for converting a continuous measure into a GROUP classifier.
3.7 SAME
The Lisp comparison functions (EQP, etc.) return either T or NIL. Occasionally, it is useful to have a predicate function return an arithmetic value, so that the results of such a comparison can be assembled into an array. SAME provides this alternative to EQP.
same[a;b] for scalar a and b, returns one if a and b are EQP, else zero.
This is useful when applied to arrays rather than individual scalars, as the result can be manipulated to derive array properties. For example, reducing the result with TIMES or LOGAND will indicate whether two separate arrays have identical elements or which of their rows or columns are the same. Thus, (RTIMES (SAME X Y)) is one if X and Y are the same; (RTIMES (KEEP (SAME X Y) 2)) is a vector indicating which columns are the same.
3.8 TRANSLATE
TRANSLATE provides a table-driven translation facility that is particularly useful for recoding.
translate[s;table;default] where s is a scalar to be translated, table is a translation matrix, and default is an (optional) default value to be used if there is no translation for s in table. TRANSLATE provides three types of translation, depending on the number of columns in table:
One column: If table is an [N,1]-matrix, TRANSLATE returns the smallest row index r of table such that table@’(r 1) is s.
Two columns: If table is an [N,2]-matrix, TRANSLATE returns table@’(r 2) for the smallest r such that table@’(r 1) is s. That is, it returns the second element of the row whose first element matches s.
Three columns: If table is an [N,3]-matrix, TRANSLATE returns table@’(r 3) for the smallest r such that table@’(r 1) < s < table@’(r 2). That is, it returns the third element of the first row such that s is in the interval defined by its first two elements. NIL receives special treatment:
NILNILXtranslates a NIL s to X
NIL YXY not NIL, translates any s < Y to X
 YNILXY not NIL, translates any s > Y to X
In all cases, if no match for s is found in the translation table, default is returned if it was given, otherwise s.
TRANSLATE is extended on all its arguments. Thus, one can translate an entire array, obtain a vector of one scalar translated according to several different translation tables, or both at once (producing a multi-dimensional array). For example, TRANSLATE is commonly used for recoding a variable, represented as a vector or column of a matrix. Because of extension, the output will be an image of s (the variable) with each value mapped into an index (one-column table), a scalar corresponding to the old value (two-column table), or a scalar corresponding to the interval in which the old value lies (three-column table). The latter case is particularly useful for categorizing continuous variables.