Page Numbers: Yes X: 527 Y: -.4 First Page: 69 Not-on-first-page
Margins: Top: 1.1" Bottom: 1" Binding: 5
Odd Heading: Not-on-first-page
APPENDIX D: SUMMARY LIST OF FUNCTIONS
Even Heading: Not-on-first-page
IDL REFERENCE MANUAL
Appendix D
Summary list of IDL functions
This appendix lists the functions available in the IDL system, giving their arguments and a brief description of their behavior. The functions are described in the notation used in the body of the manual. The annotation "no-spread" means that the function will accept any number of arguments.
adjoin[vector...]
No-spread. Produces a new vector formed by joining its arguments together end to end.
anova[mtable;random;nesting]
Produces a matrix containing a summary table for the analysis of variance of moments array mtable. random, if given, specifies the random factors (dimensions of mtable) and is used for constructing appropriate F-tests. nesting is an optional specification of the nesting relations between the independent variables. It is a list of lists, each of the form (nested-factor nesting-factor1 nesting-factor2 ...).
assign[target;source]
The IDL assignment operator. target must be a selection on some array, and that array will be side-effected. The infix operator ← translates to assign if an array selection expression appears as its left-hand operand.
at[a;sltr]
The IDL selection operator. Produces an array as output which is a window onto the section of a described by sltr. sltr may be a list of length no greater than the number of dimensions of a to specify a selection of a’s values, or a label or code selector. The infix operator @ is associated with at.
code[lev;val]
Constructs a code selector to be given to at. If lev is NIL, the selector can be used to reference the value-labelled dimension of the array to which it is applied by at. Otherwise, if val is NIL, the selector will reference the complete codebook associated with level lev on the array’s value-labelled dimension. If val is a non-NIL literal atom, it will reference the value associated with it on level lev. Finally, if val is a scalar, it will reference the label associated with that value.
copy[x]
The Lisp copy function generalized to copy IDL arrays (which may be the value of x or may appear at arbitrary levels in the list-structure x). Assigning into a copy of an array will not affect the original.
counts[a]
A generic function that returns the sum of the elements of a just like rplus, except that it skips over NIL’s. Often used in conjunction with group to produce contingency tables from data arrays.
covar[a;wt]
Builds the covariation matrix (sums of mean centered cross products) for the columns of matrix a, using wt as a weighting vector. Returns a symmetric matrix, whose last row represents a Constant variable (with value always 1) that has been swept out, so that the last row has the means of the columns of a, and –1/n in the last cell.
deal[n]
Returns a vector containing a random permutation of the integers from 1 to n.
dumpidlarray[a;file]
Writes a symbolic expression on file (primary output file if file is NIL) from which readidlarray can reconstruct an array equivalent to a. If file is not an open file, it is opened, the expression is printed, and then file is closed.
eapply[fn;expects;args]
Extending form of apply. Applies fn to each section of the decomposition of args according to expects, a list which gives, for each argument of fn, the dimensionality expected of that argument.
eapply*[fn;expects;args...]
No-spread. Extending form of apply*. Applies fn to each section of the decomposition of args according to expects.
elementtype[a]
Returns the type (INTEGER or FLOATING) of the elements of the array a.
ems[nlevels;random;nesting]
Produces an expected mean squares coefficient table for an analysis of variance design with factor levels given by nlevels, the factors in random considered random, and the nesting relationships given by nesting. nlevels can be the moments table itself, or just the shape of its classification space.
extend[fn;expects]
Modifies the function fn so that it will automatically extend across array arguments according to expects.
format[a]
Returns the format (either FULL or SYMMETRIC) of array a.
fprob[f;dfnum;dfden]
Returns the probability of F-value f, with degrees of freedom dfnum, dfden.
genvec[initial;end]
Generates a vector of the numbers from initial to end. If initial is a two element vector, it is taken as the first two terms of the series (i.e., it specifies an increment). Thus, (GENVEC ’(3 5) 11) generates the odd integers from 3 to 11.
group[attribs;values;dim]
Constructs an array of m+n dimensions, where m is the number of columns of the matrix attribs, and n the dimensionality of values. dim indicates which dimension of values is to be nested within the classification induced by attribs. The values in each row of attribs are used as a subscript for an m-dimensional array whose extents are given by the number of distinct values found in the corresponding column of attribs. The output is formed by grouping all dim dimension planes of values corresponding to equal rows of attribs in the m-space location addressed by that row. In effect, group places the dim dimension planes of values within the cells of the classification design represented by attribs. If values is an integer, it is interpreted as a constant vector of that integer with length the number of rows of attribs. If NIL, it is considered to be one, which produces an object from which counts will compute a contingency table.
hist[v;file]
Prints a histogram for v, a vector, to the primary output file, or to file if given. Suppresses multiple identical lines whenever their number exceeds the value of HISTRPTLINES. If file is not an open file, it is opened, the histogram is printed, and then file is closed.
idlarray[data]
Produces an IDL array of arbitrary dimensionality from a list-structure description of its properties. The list data begins with an optional title followed by a representation of its shape and labelling, an optional format, and a list of values to be filled into the array in row-major order.
idlarrayp[a]
Returns T if a is an IDL array, otherwise returns NIL.
idlmatrix[data]
Produces a two-dimensional IDL array from data, a list structure describing its labels and values. data is a list each element of which is a list representing one row of the output matrix. The row specifications may be optionally preceded by one list of the form (TITLES title-string dimension1-label dimension2-label), and another of the form (LABELS level1-labels level2-labels ...). The level labels are for levels on the second dimension of the output. Each row-list is a sequence of data values optionally preceded by the labels for that first-dimension level. The labels for a non-codebook level consist simply of a literal atom; a codebook is specified in the format (level-label codepair1 codepair2 ...).
invert[m]
Produces the matrix inverse of m. Equivalent to –(SWEEP M ALL).
keep[a;dims...]
No-spread. Produces a copy of a with dims added to its kept dimensions. If dims is the literal ALL, then all the dimensions of a will be kept. If no dims are specified, a vector of the currently kept dimensions is returned.
label[dim;lev]
Constructs a label selector to be given to at that will reference the label for dimension dim (if lev is NIL) or the label for level lev on dimension dim.
leave[a;dims...]
No-spread. Produces a new array from a with dims removed from its kept dimensions. If the first of dims is the literal ALL, then all of its kept dimensions will be eliminated.
listarray[a]
Converts IDL array a into a list structure from which idlarray can reconstruct the original.
listmatrix[m]
Converts IDL matrix m into a list structure from which idlmatrix can reconstruct the original.
mprod[a;b]
Matrix product of a and b. If they are vectors, mprod coerces them in the obvious way.
moments[a;wt;m]
Returns a vector of length m+1 containing the number of non-NIL values (moment 0) and the first m moments of array a, using wt as a weighting array. The first moment is the mean, the second is the variance, the third is closely related to the skew, etc. If m is NIL, it is defaulted to two and the N, mean, and variance are computed.
norm[m]
Norms matrix m by dividing each entry by the square root of the product of its basis (diagonal) elements.
nprob[z]
Returns the one-tailed probability of a normal deviate of size z.
order[v;cfn]
Returns a permutation vector which will order vector v by comparison function cfn. If cfn is not specified, lessp is used.
pairn[a;wt]
Returns a matrix of the pairwise N corresponding to a covariation matrix on a, using wt as a weighting vector.
plot[y;x;file]
Plots the vector y against the vector x (one through length y, if not given) on the primary output file, or file if specified. The axes are scaled so that they are approximately the same size. This scaling is controlled by the global variable PLOT.AXIS.RATIO. If file is not an open file, it is opened, the plot is printed, and then file is closed.
plusp[x]
A predicate which is T if the scalar x is greater than zero.
pool[mtable]
Collapses mtable into a 3-vector of the pooled cell N, mean, and variance. Effectively removes factors from a moments array.
ppa[a;file]
Prints the array a on the primary output file, or file if specified. If file is not an open file, it is opened, the array is printed, and then file is closed. The precision of numbers in the table is determined by the global variable PRECISION, a list specifying the number of digits to appear to the right and left of the decimal point. The initial setting is (4 3) so that numbers are printed in the format rrrr.lll. The global variable ROWLABELWIDTH is an integer determining the number of columns to leave for the labels on rows (initially 8).
randn[mean;stdev]
Returns a single number randomly sampled from the normal distribution with mean mean (default 0) and standard deviation stdev (default 1).
rank[a]
Ranks the array a in ascending order. Result will be integer unless floating is necessary to resolve ties. Cells containing NIL are ignored in computing the ranks, and the corresponding cells in the value will be NIL.
readidlarray[file]
Constructs an IDL array from an expression read from file (primary input file if file is NIL). If file is not an open file, it is opened, the expression is read, and then file is closed. dumpidlarray produces an expression of the appropriate form.
reduce[a;fn;startval]
Applies function fn left associatively to the elements of a. If startval is given, fn is first applied to startval and a1, otherwise to a1 and a2. Thus, (REDUCE ARY ’NCONC1 NIL) returns a list of the elements of ARY. reduce distinguishes the situation where startval is specified as NIL from the case where it is not specified at all, so (REDUCE ARY ’NCONC1) will ignore a1 as it is not a list.
reshape[a;newshape;newformat]
Reshapes a to an array of shape newshape and format newformat (optional, default FULL). The elements of a are put into the new array in rowmajor order. If newshape is NIL, a is simply flattened into a vector.
round[val;interval]
Rounds val to the nearest integral multiple of interval. Thus, (ROUND 1.45 .5)=1 and (ROUND –785 100)=–800.
rplus[a]
Equivalent to reduce[a;quote[plus];0].
rtimes[a]
Equivalent to reduce[a;quote[times];1].
same[a;b]
Returns one if eqp[a;b], zero otherwise.
scalarp[s]
Returns T if s is a scalar, otherwise NIL.
seek[sought;vec]
sought can be a vector or a one argument function. Returns the (ordered) vector of indices of elements of vec which are found in, or which satisfy, sought.
shape[a]
Returns a vector giving the shape of array a.
shift[v;shift;fill]
Returns the vector formed by shifting vector v shift places (positive shifts right; negative shifts left) shifting in elements from the opposite end of fill to replace moved elements. fill can be a scalar or a vector. If fill is omitted, v is "rotated", i.e., the element shifted out one end is shifted in at the other.
sweep[m;outvars;invars]
Sweeps out variance components of matrix m corresponding to outvars (a selector for the second dimension of m); then sweeps in components corresponding to invars.
title[]
Returns a selector that can be given to at to reference the title of an array.
tprob[x;df]
Returns the probability of a t-value of x with degrees of freedom df.
translate[s;table;default]
Translates the scalar s according to the matrix table. If table has one column (or is a vector), the index of (the first) s in table is returned. If it has two columns, the second element of the row whose first element is s is returned. If three columns, the third element of the row such that s is between the first and second elements is returned. In the three-column case, a NIL in the first two columns only matches a NIL s; otherwise, a NIL in column 1 is interpreted as –# while a NIL in column 2 is interpreted as +#. If no match is found, default is returned if it is specified; otherwise the value is s itself.
transpose[a;perm]
Transposes a by mapping each of its dimensions onto the dimension of the output given by the corresponding element of perm. Two dimensions that are mapped onto the same dimension of the output are represented by their joint diagonal. If perm is not given, the dimensions are reversed.
In addition to the above, the mixed-arithmetic operators plus, times, etc., and most of the other arithmetic functions in Interlisp have been extended to apply element-wise across arrays. The infix operators +,*,–,/ have been mapped onto the mixed-arithmetic operators instead of the integer operators as in standard Interlisp.
IDL implements a new kind of Lisp function, an ELAMBDA, to simplify the task of defining extended functions. The key-word ELAMBDA is used instead of LAMBDA in the function definition, and the size of the expected object can be associated with each argument name. For example,
[DEFINEQ (FOO (ELAMBDA ((M MATRIX) (V VECTOR)) (ADJOIN M (KEEP V 1]
which adds V as a new column to M, is equivalent to
[DEFINEQ (FOO (LAMBDA (M V) (EAPPLY* ’(LAMBDA (M V) (ADJOIN M (KEEP V 1)))
’(MATRIX VECTOR)
M V].
The IDL system defines the file package command IDLARRAYS for dumping IDL arrays via makefile onto ordinary Lisp files in load-able format. (The Lisp ARRAYS command only dumps regular Lisp arrays.)
IDL automatically opens a Lisp DRIBBLE file at the beginning of each session, which maintains a transcript of all interactions with the system. This file is named IDL.TYPESCRIPT on the login directory. It is a temporary file, and will disappear when the user logs off Tenex; it must be explicitly renamed or copied to another file if the contents are to be preserved.
Finally, the facilities of <LISPUSERS>SHOW are included in IDL. Thus, the command SHOW may be given to the Interlisp executive to cause the value of the last expression typed in to be pretty-printed. This augmentation to the Lisp system greatly improves the convenience of IDL interactions. For more details, see <LISPUSERS>SHOW.TTY.