Page Numbers:  Yes  X: 527  Y: -.4  First Page: 43  Not-on-first-page
Margins:  Top: 1.1"  Bottom: 1" Binding: 5
Odd Heading:  Not-on-first-page  y576qj(635)
7.  DATA INPUT AND OUTPUTy763qc(0,14848)\5f1 3f0 2f1 4f0 1f1 3f0 2f1
Even Heading:  Not-on-first-pagey756qj(0,17815)
IDL REFERENCE MANUALy763qc\5f1 9f0 1f1
7.  Data Input and Outputy666e12c(635)\f9b
The material in the preceding chapters assumed that the data to be analyzed already existed as an IDL array.  This chapter considers how data may be entered into an array from an external representation, either from list structure residing in memory or from a sequence of characters on a file.  Functions for converting an array back into an external representation are also described, so that, for example, objects created by IDL computations may be preserved from one session to the next.e36j\98f1 3f0 326f1 3f0
7.1 To and from list structuree18j
The easiest way of entering data is simply to type it in as list structure at the point in the IDL session when it is needed.  Thus, typinge12j\95f1 3f0
X _ '(4 2 6 9 3 11 2 8 31 0)l4233e6j
saves the ten observations as a list in the variable X.  As all IDL functions will convert numeric lists to arrays, X may be used whenever a vector would be appropriate (see section 1.7).  This method has the disadvantages that the conversion would be carried out every time X was used as an array, and the resulting arrays have no labels or titles.  Thus, IDL provides special functions for explicitly constructing arrays from list structure that also includes labelling.e6j\53f1 1f0 10f1 3f0 49f1 1f0 158f1 1f0 81f1 3f0
idlarray[data] returns an array constructed according to the description found in data.  data is a list in the following formatl4233d2999e12j\82b4B3b4B
({title} organization {keeps} {format} elements)l5536e6j\1i7I1i12I1i7I1i8I1i8I
The braces {} indicate that an item is optional and need not be specified.  The title, if present, is simply a string enclosed in double-quotes.  The organization specifies the shape and labelling of the array, and the optional keeps indicates its kept dimensions.  The optional format is either SYMMETRIC or FULL (the default), and elements is a list of the values that will fill up the array in row-major order.l4224e6j\11i2I67i5I65i12I66i5I46i6I11f1 9f0 4f1 4f0 20i8I
The organization is a list containing one sub-list for each dimension of the array.  This is of the forml4224e8j\4i12I
(dim = nlevels {level-labels1 level-labels2 ...} )l5536e6j\1i3I3i7I1i13f1o252 1f0o0I1i12f1o252 1f0o0I4i1I
dim is either the dimension number or the dimension label, nlevels is the number of levels for that dimension, and level-labelsi specifies the level label and, for the value-labelled dimension, the value-labels for level i.  If there are no value-labels, the specification may simply be the atomic level label, or NIL or the level index if the level is unlabelled.  If there are value-labels, then the specification is a list consisting of the level label followed by the codebook for that level.l4224e6j\i3I56i7I49i12f1o252 1f0o0I93i1I92f1 3f0
keeps, if present, is a list of the form (kept k1 k2 ...), where each ki is either a dimension number of label specifying a kept dimension.l4224e6j\i5I42i1f1o252 1f0o0I1i1f1o252 1f0o0I18i1f1o252 1f0o0I
For example, the expressione12j
(IDLARRAY '("Another random matrix"
	((Subject = 4) 
	(Variable  = 3 (SEX (1 MALE) (2 FEMALE)) AGE VOTE))
	(kept Variable)
	(1 24 2 3 31 1 2 28 3 1 25 2)))l4233e6jk50(0,5376)(1,5504)\36t1 1t0 15t2 2t0
produces the matrixe6j(635)
       Another Random Matrix
       Kept:  Variablel4233x2e6jk48(0,65535)(1,65535)
		 Variablel4233e3j
	Subject	SEX	AGE	VOTEl4233j(0,4563)(1,6882)(2,8418)(3,9837)
	1	MALE	24	2l4233j(0,5645)(1,6643)(2,8674)(3,10502)
	2	3	31	1l4233j(1,7364)
	3	FEMALE	28	3l4233j(1,6195)
	4	MALE	25	2l4233j(1,6643)
The inverse of IDLARRAY is also provided:e12j(635)\15f1 8f0
listarray[a] produces a list-structure description of the array a in the form outlined above.  This can be given back to IDLARRAY to reconstruct an array equivalent to the original.  l4233d2999e12j\64b1B56f1 8f0
Usually, data is collected and initially entered in the form of a subjects by variables matrix.  These arrays can be described in the format above, but, for convenience, a more perspicuous list-structure representation is also allowed for such arrays.  This representation groups the rows into individual lists and permits the row-labels to be specified next to the corresponding data values.  The functions IDLMATRIX and LISTMATRIX process this special form of description.e12j\408f1 9f0 5f1 10f0
idlmatrix[data] returns a matrix constructed according to the instructions and data found in data.  data is a list each element of which is a list representing one row of the output.  The list is a sequence of data values optionally preceded by the level label for that row.  Before the row specifications there may be one list of the forml4233d2999e12j\93b4B3b4B
(TITLE title-string dimension1-label dimension2-label)l5536e6j\7i12I1i9f1o252 1f0o0 6I1i9f1o252 1f0o0 6I
and another of the form l4224e6j
(LABELS level1-labels level2-labels ...)l5536e6j\8i5f1o252 1f0o0 7I1i5f1o252 1f0o0 7I
These level labels are for levels on the second dimension of the result, and each one may be NIL (meaning no level label), a non-NIL literal atom which provides a level label but no codebook for the corresponding level, or a list of the forml4224e6j\93f1 3f0 33f1 3f0
(level-label codepair1 codepair2 ...)  l5536e6j\1i11I1i8f1o252 1f0o0I1i8f1o252 1f0o0I
For example, an array with two subjects, John, a 32 year old male, and Susan, a 27 year old female, could be created bye12j
(IDLMATRIX '( (TITLE "An array with two subjects" Subjects Variables)
(LABELS (Sex (1 Male)(2 Female)) Age)
(John  1  32)
(Susan 2  27) ))l6976d4233e6j
The function LISTMATRIX is the inverse of IDLMATRIX.  It produces the list structure corresponding to an IDL matrix:e12j\13f1 10f0 19f1 9f0 54f1 3f0
listmatrix[m] returns a list structure representing the elements and labels of the IDL matrix m.  This structure can be passed to IDLMATRIX to reconstruct a matrix equivalent to m.   l4233d2999e8j\83f1 3f0 8b1B35f1 9f0 39b1B
List-structure descriptions can be written on files and read back in to form arrays, and this is one way of preserving arrays.  However, the functions described below achieve the same effect without allocating intermediate list-structure and are thus more efficient.  The main advantage of list structure representations is that they can be manipulated by the large number of Lisp list-processing functions, including the powerful editor (see Teitelman, 1978). e12j
7.2 To and from filese18j
Data can be stored on files in either the full-array format or the special matrix format.  Arrays or matrices can be read into memory by reading the appropriate expression from the file to form the list structure, and then giving that structure to either IDLARRAY or IDLMATRIX.  For example, suppose the file MYDATA contained only expressions representing the matrix form of an array, inserted by means of a text-editor familiar to the user.  The data could be formed into an IDL matrix and bound to the variable D by means of the following expression:e12j\255f1 8f0 4f1 9f0 33f1 6f0 161f1 3f0 34f1 1f0
D _ (IDLMATRIX (READFILE 'MYDATA))l6976d4233e6j
The Lisp function READFILE opens a file, reads all the expressions from it and forms them into a list structure, closes the file,  and returns that list structure.  For this example, the file MYDATA must not have the outer parentheses enclosing the titles and rows of the matrix, since READFILE will itself insert those.e6j\18f1 8f0 166f1 6f0 88f1 8f0
If the more general form of description is on the file, the function IDLARRAY may be used instead of IDLMATRIX to construct the array.  However, it is more efficient to use the function READIDARRAY, for this constructs the array in one step, without building the intervening list structure:e12j\69f1 8f0 24f1 9f0 76f1 11f0
readidlarray[file] constructs an IDL array from an IDLARRAY-type expression read from file (or the Lisp 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.l4233d2999e8j\33f1 3f0 15f1 8f0 27b4B36b4B4f1 4f0 6b4B69b4B
The information in arrays may be saved on a file by first converting it to list structure and then using any of the Lisp printing functions PRIN2, PRINT, PRINTDEF, etc. to print the structure on the open file.  For the general array format, the function DUMPIDLARRAY may be used instead:e12j\140f1 5f0 2f1 5f0 2f1 8f0 92f1 12f0
dumpidlarray[a;file] writes an IDLARRAY-type list expression on file (or the Lisp primary output file if file is NIL) from which an array equivalent to a can be constructed.  If file is not an open file, it is opened, the expression is printed, and then file is closed.l4233d2999e8j\31f1 8f0 25b4B37b4B4f1 4f0 35b1B25b4B72b4B
The Lisp file package command IDLARRAYS can be used to dump and restore IDL arrays on LOADable files, via DUMPIDLARRAY and READIDLARRAY.  This permits arrays to be saved on the same files as functions, variables, and other information, and to be restored by the simple Lisp function LOAD.  The appropriate dumping and reading functions are automatically supplied.  To include an array on a LOADable file SURVEYINFO, the Lisp variable SURVEYINFOCOMS must be a list of commands one of whose elements begins with IDLARRAYS and specifies the name of a variable whose value is the array to be dumped.  Other commands might specify other objects to be saved.  For example, if SURVEYINFOCOMS were bound to the command liste12j\30f1 9f0 33f1 3f0 11f1 4f0 16f1 12f0 5f1 12f0 148f1 4f0 103f1 4f0 10f1 10f0 20f1 14f0 62f1 9f0 151f1 14f0
((VARS X Y) (IDLARRAYS SDATA) (FNS RECODE))l6976d4233e6j
then the expressione6j
(MAKEFILE 'SURVEYINFO)l6976d4233e6j
would save on the file SURVEYINFO the values of the (non-array) variables X and Y, the array bound to SDATA, and the user function named RECODE.  If in another IDL session the expressione6j\23f1 10f0 41f1 1f0 5f1 1f0 21f1 5f0 30f1 6f0 17f1 3f0
(LOAD 'SURVEYINFO)l6976d4233e6j
were evaluated, the variable values and function would be restored.  The Interlisp Reference Manual (Teitelman, 1978) has a very extensive discussion of file commands, MAKEFILE, and LOAD.e6j\168f1 8f0 6f1 4f0
Rather than saving particular arrays from one session to be used in another, it is also possible to preserve the complete state of the current session on a file.  This file can be run at a later time to resume the suspended analysis session.  The Lisp function SYSOUT moves the state of the current session to a file:e12j\261f1 6f0
sysout[file] saves the state of the current IDL session on file.  If file does not include an extension in its name, the extension SAV will be supplied by default.l4233d2999e8j\44f1 3f0 12b4B6b4B58f1 3f0
A SYSOUT file may be resumed simply by running that file instead of IDL to start the session.  For details, see Teitelman (1978).e6j\2f1 6f0 60f1 3f0