hiding source categories
[pspp] / doc / matrices.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020, 2021 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
9 @c
10 @node Matrices
11 @chapter Matrices
12
13 Some @pspp{} procedures work with matrices by producing numeric
14 matrices that report results of data analysis, or by consuming
15 matrices as a basis for further analysis.  This chapter documents the
16 format of data files that store these matrices and commands for
17 working with them, as well as @pspp{}'s general-purpose facility for
18 matrix operations.
19
20 @node Matrix Files
21 @section Matrix Files
22 @vindex Matrix file
23
24 A matrix file is an SPSS system file that conforms to the dictionary
25 and case structure described in this section.  Procedures that read
26 matrices from files expect them to be in the matrix file format.
27 Procedures that write matrices also use this format.
28
29 Text files that contain matrices can be converted to matrix file
30 format.  @xref{MATRIX DATA}, for a command to read a text file as a
31 matrix file.
32
33 A matrix file's dictionary must have the following variables in the
34 specified order:
35
36 @enumerate
37 @item
38 Zero or more numeric split variables.  These are included by
39 procedures when @cmd{SPLIT FILE} is active.  @cmd{MATRIX DATA} assigns
40 split variables format F4.0.
41
42 @item
43 @code{ROWTYPE_}, a string variable with width 8.  This variable
44 indicates the kind of matrix or vector that a given case represents.
45 The supported row types are listed below.
46
47 @item
48 Zero or more numeric factor variables.  These are included by
49 procedures that divide data into cells.  For within-cell data, factor
50 variables are filled with non-missing values; for pooled data, they
51 are missing.  @cmd{MATRIX DATA} assigns factor variables format F4.0.
52
53 @item
54 @code{VARNAME_}, a string variable.  Matrix data includes one row per
55 continuous variable (see below), naming each continuous variable in
56 order.  This column is blank for vector data.  @cmd{MATRIX DATA} makes
57 @code{VARNAME_} wide enough for the name of any of the continuous
58 variables, but at least 8 bytes.
59
60 @item
61 One or more numeric continuous variables.  These are the variables
62 whose data was analyzed to produce the matrices.  @cmd{MATRIX DATA}
63 assigns continuous variables format F10.4.
64 @end enumerate
65
66 Case weights are ignored in matrix files. 
67
68 @subheading Row Types
69 @anchor{Matrix File Row Types}
70
71 Matrix files support a fixed set of types of matrix and vector data.
72 The @code{ROWTYPE_} variable in each case of a matrix file indicates
73 its row type.  
74
75 The supported matrix row types are listed below.  Each type is listed
76 with the keyword that identifies it in @code{ROWTYPE_}.  All supported
77 types of matrices are square, meaning that each matrix must include
78 one row per continuous variable, with the @code{VARNAME_} variable
79 indicating each continuous variable in turn in the same order as the
80 dictionary.
81
82 @table @code
83 @item CORR
84 Correlation coefficients.
85
86 @item COV
87 Covariance coefficients.
88
89 @item MAT
90 General-purpose matrix.
91
92 @item N_MATRIX
93 Counts.
94
95 @item PROX
96 Proximities matrix.
97 @end table
98
99 The supported vector row types are listed below, along with their
100 associated keyword.  Vector row types only require a single row, whose
101 @code{VARNAME_} is blank:
102
103 @table @code
104 @item COUNT
105 Unweighted counts.
106
107 @item DFE
108 Degrees of freedom.
109
110 @item MEAN
111 Means.
112
113 @item MSE
114 Mean squared errors.
115
116 @item N
117 Counts.
118
119 @item STDDEV
120 Standard deviations.
121 @end table
122
123 Only the row types listed above may appear in matrix files.  The
124 @cmd{MATRIX DATA} command, however, accepts the additional row types
125 listed below, which it changes into matrix file row types as part of
126 its conversion process:
127
128 @table @code
129 @item N_VECTOR
130 Synonym for @cmd{N}.
131
132 @item SD
133 Synonym for @code{STDDEV}.
134
135 @item N_SCALAR
136 Accepts a single number from the @code{MATRIX DATA} input and writes
137 it as an @code{N} row with the number replicated across all the
138 continuous variables.
139 @end table
140
141 @node MATRIX DATA
142 @section MATRIX DATA
143 @vindex MATRIX DATA
144
145 @display
146 MATRIX DATA
147         VARIABLES=@var{variables}
148         [FILE=@{'@var{file_name}' | INLINE@}
149         [/FORMAT=[@{LIST | FREE@}]
150                  [@{UPPER | LOWER | FULL@}]
151                  [@{DIAGONAL | NODIAGONAL@}]]
152         [/SPLIT=@var{split_vars}]
153         [/FACTORS=@var{factor_vars}]
154         [/N=@var{n}]
155
156 The following subcommands are only needed when ROWTYPE_ is not
157 specified on the VARIABLES subcommand:
158         [/CONTENTS=@{CORR,COUNT,COV,DFE,MAT,MEAN,MSE,
159                     N_MATRIX,N|N_VECTOR,N_SCALAR,PROX,SD|STDDEV@}]
160         [/CELLS=@var{n_cells}]
161 @end display
162
163 The @cmd{MATRIX DATA} command convert matrices and vectors from text
164 format into the matrix file format (@xref{Matrix Files}) for use by
165 procedures that read matrices.  It reads a text file or inline data
166 and outputs to the active file, replacing any data already in the
167 active dataset.  The matrix file may then be used by other commands
168 directly from the active file, or it may be written to a @file{.sav}
169 file using the @cmd{SAVE} command.
170
171 The text data read by @cmd{MATRIX DATA} can be delimited by spaces or
172 commas.  A plus or minus sign, except immediately following a @samp{d}
173 or @samp{e}, also begins a new value.  Optionally, values may be
174 enclosed in single or double quotes.
175
176 @cmd{MATRIX DATA} can read the types of matrix and vector data
177 supported in matrix files (@pxref{Matrix File Row Types}).
178
179 The @subcmd{FILE} subcommand specifies the source of the command's
180 input.  To read input from a text file, specify its name in quotes.
181 To supply input inline, omit @subcmd{FILE} or specify @code{INLINE}.
182 Inline data must directly follow @code{MATRIX DATA}, inside @cmd{BEGIN
183 DATA} (@pxref{BEGIN DATA}).
184
185 @subcmd{VARIABLES} is the only required subcommand.  It names the
186 variables present in each input record in the order that they appear.
187 (@cmd{MATRIX DATA} reorders the variables in the matrix file it
188 produces, if needed to fit the matrix file format.)  The variable list
189 must include split variables and factor variables, if they are present
190 in the data, in addition to the continuous variables that form matrix
191 rows and columns.  It may also include a special variable named
192 @code{ROWTYPE_}.
193
194 Matrix data may include split variables or factor variables or both.
195 List split variables, if any, on the @subcmd{SPLIT} subcommand and
196 factor variables, if any, on the @subcmd{FACTORS} subcommand.  Split
197 and factor variables must be numeric.  Split and factor variables must
198 also be listed on @subcmd{VARIABLES}, with one exception: if
199 @subcmd{VARIABLES} does not include @code{ROWTYPE_}, then
200 @subcmd{SPLIT} may name a single variable that is not in
201 @subcmd{VARIABLES} (@pxref{MATRIX DATA Example 8}).
202
203 The @subcmd{FORMAT} subcommand accepts settings to describe the format
204 of the input data:
205
206 @table @asis
207 @item @code{LIST} (default)
208 @itemx @code{FREE}
209 LIST requires each row to begin at the start of a new input line.
210 FREE allows rows to begin in the middle of a line.  Either setting
211 allows a single row to continue across multiple input lines.
212
213 @item @code{LOWER} (default)
214 @itemx @code{UPPER}
215 @itemx @code{FULL}
216 With LOWER, only the lower triangle is read from the input data and
217 the upper triangle is mirrored across the main diagonal.  UPPER
218 behaves similarly for the upper triangle.  FULL reads the entire
219 matrix.
220
221 @item @code{DIAGONAL} (default)
222 @itemx @code{NODIAGONAL}
223 With DIAGONAL, the main diagonal is read from the input data.  With
224 NODIAGONAL, which is incompatible with FULL, the main diagonal is not
225 read from the input data but instead set to 1 for correlation matrices
226 and system-missing for others.
227 @end table
228
229 The @subcmd{N} subcommand is a way to specify the size of the
230 population.  It is equivalent to specifying an @code{N} vector with
231 the specified value for each split file.
232
233 @cmd{MATRIX DATA} supports two different ways to indicate the kinds of
234 matrices and vectors present in the data, depending on whether a
235 variable with the special name @code{ROWTYPE_} is present in
236 @code{VARIABLES}.  The following subsections explain @cmd{MATRIX DATA}
237 syntax and behavior in each case.
238
239 @node MATRIX DATA with ROWTYPE_
240 @subsection With @code{ROWTYPE_}
241
242 If @code{VARIABLES} includes @code{ROWTYPE_}, each case's
243 @code{ROWTYPE_} indicates the type of data contained in the row.
244 @xref{Matrix File Row Types}, for a list of supported row types.
245
246 @subsubheading Example 1: Defaults with @code{ROWTYPE_}
247 @anchor{MATRIX DATA Example 1}
248
249 This example shows a simple use of @cmd{MATRIX DATA} with
250 @code{ROWTYPE_} plus 8 variables named @code{var01} through
251 @code{var08}.
252
253 Because @code{ROWTYPE_} is the first variable in @subcmd{VARIABLES},
254 it appears first on each line. The first three lines in the example
255 data have @code{ROWTYPE_} values of @samp{MEAN}, @samp{SD}, and
256 @samp{N}.  These indicate that these lines contain vectors of means,
257 standard deviations, and counts, respectively, for @code{var01}
258 through @code{var08} in order.
259
260 The remaining 8 lines have a ROWTYPE_ of @samp{CORR} which indicates
261 that the values are correlation coefficients.  Each of the lines
262 corresponds to a row in the correlation matrix: the first line is for
263 @code{var01}, the next line for @code{var02}, and so on.  The input
264 only contains values for the lower triangle, including the diagonal,
265 since @code{FORMAT=LOWER DIAGONAL} is the default.
266
267 With @code{ROWTYPE_}, the @code{CONTENTS} subcommand is optional and
268 the @code{CELLS} subcommand may not be used.
269
270 @example
271 MATRIX DATA
272     VARIABLES=ROWTYPE_ var01 TO var08.
273 BEGIN DATA.
274 MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
275 SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
276 N       92    92    92    92    92    92    92    92
277 CORR  1.00
278 CORR   .18  1.00
279 CORR  -.22  -.17  1.00
280 CORR   .36   .31  -.14  1.00
281 CORR   .27   .16  -.12   .22  1.00
282 CORR   .33   .15  -.17   .24   .21  1.00
283 CORR   .50   .29  -.20   .32   .12   .38  1.00
284 CORR   .17   .29  -.05   .20   .27   .20   .04  1.00
285 END DATA.
286 @end example
287
288 @subsubheading Example 2: @code{FORMAT=UPPER NODIAGONAL}
289
290 This syntax produces the same matrix file as example 1, but it uses
291 @code{FORMAT=UPPER NODIAGONAL} to specify the upper triangle and omit
292 the diagonal.  Because the matrix's @code{ROWTYPE_} is @code{CORR},
293 @pspp{} automatically fills in the diagonal with 1.
294
295 @example
296 MATRIX DATA
297     VARIABLES=ROWTYPE_ var01 TO var08
298     /FORMAT=UPPER NODIAGONAL.
299 BEGIN DATA.
300 MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
301 SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
302 N       92    92    92    92    92    92    92    92
303 CORR         .17   .50  -.33   .27   .36  -.22   .18
304 CORR               .29   .29  -.20   .32   .12   .38
305 CORR                     .05   .20  -.15   .16   .21
306 CORR                           .20   .32  -.17   .12
307 CORR                                 .27   .12  -.24
308 CORR                                      -.20  -.38
309 CORR                                             .04
310 END DATA.
311 @end example
312
313 @subsubheading Example 3: @subcmd{N} subcommand
314
315 This syntax uses the @subcmd{N} subcommand in place of an @code{N}
316 vector.  It produces the same matrix file as examples 1 and 2.
317
318 @example
319 MATRIX DATA
320     VARIABLES=ROWTYPE_ var01 TO var08
321     /FORMAT=UPPER NODIAGONAL
322     /N 92.
323 BEGIN DATA.
324 MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
325 SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
326 CORR         .17   .50  -.33   .27   .36  -.22   .18
327 CORR               .29   .29  -.20   .32   .12   .38
328 CORR                     .05   .20  -.15   .16   .21
329 CORR                           .20   .32  -.17   .12
330 CORR                                 .27   .12  -.24
331 CORR                                      -.20  -.38
332 CORR                                             .04
333 END DATA.
334 @end example
335
336 @subsubheading Example 4: Split variables
337 @anchor{MATRIX DATA Example 4}
338
339 This syntax defines two matrices, using the variable @samp{s1} to
340 distinguish between them.  Notice how the order of variables in the
341 input matches their order on @subcmd{VARIABLES}.  This example also
342 uses @code{FORMAT=FULL}.
343
344 @example
345 MATRIX DATA
346     VARIABLES=s1 ROWTYPE_  var01 TO var04
347     /SPLIT=s1
348     /FORMAT=FULL.
349 BEGIN DATA.
350 0 MEAN 34 35 36 37
351 0 SD   22 11 55 66
352 0 N    99 98 99 92
353 0 CORR  1 .9 .8 .7
354 0 CORR .9  1 .6 .5
355 0 CORR .8 .6  1 .4
356 0 CORR .7 .5 .4  1
357 1 MEAN 44 45 34 39
358 1 SD   23 15 51 46
359 1 N    98 34 87 23
360 1 CORR  1 .2 .3 .4
361 1 CORR .2  1 .5 .6
362 1 CORR .3 .5  1 .7
363 1 CORR .4 .6 .7  1
364 END DATA.
365 @end example
366
367 @subsubheading Example 5: Factor variables
368 @anchor{MATRIX DATA Example 5}
369
370 This syntax defines a matrix file that includes a factor variable
371 @samp{f1}.  The data includes mean, standard deviation, and count
372 vectors for two values of the factor variable, plus a correlation
373 matrix for pooled data.
374
375 @example
376 MATRIX DATA
377     VARIABLES=ROWTYPE_ f1 var01 TO var04
378     /FACTOR=f1.
379 BEGIN DATA.
380 MEAN 0 34 35 36 37
381 SD   0 22 11 55 66
382 N    0 99 98 99 92
383 MEAN 1 44 45 34 39
384 SD   1 23 15 51 46
385 N    1 98 34 87 23
386 CORR .  1
387 CORR . .9  1
388 CORR . .8 .6  1
389 CORR . .7 .5 .4  1
390 END DATA.
391 @end example
392
393 @node MATRIX DATA without ROWTYPE_
394 @subsection Without @code{ROWTYPE_}
395
396 If @code{VARIABLES} does not contain @code{ROWTYPE_}, the
397 @subcmd{CONTENTS} subcommand defines the row types that appear in the
398 file and their order.  If @subcmd{CONTENTS} is omitted,
399 @code{CONTENTS=CORR} is assumed.
400
401 Factor variables without @code{ROWTYPE_} introduce special
402 requirements, illustrated below in Examples 8 and 9.
403
404 @subsubheading Example 6: Defaults without @code{ROWTYPE_}
405
406 This example shows a simple use of @cmd{MATRIX DATA} with 8 variables
407 named @code{var01} through @code{var08}, without @code{ROWTYPE_}.
408 This yields the same matrix file as Example 1 (@pxref{MATRIX DATA
409 Example 1}).
410
411 @example
412 MATRIX DATA
413     VARIABLES=var01 TO var08
414    /CONTENTS=MEAN SD N CORR.
415 BEGIN DATA.
416 24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
417  5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
418   92    92    92    92    92    92    92    92
419 1.00
420  .18  1.00
421 -.22  -.17  1.00
422  .36   .31  -.14  1.00
423  .27   .16  -.12   .22  1.00
424  .33   .15  -.17   .24   .21  1.00
425  .50   .29  -.20   .32   .12   .38  1.00
426  .17   .29  -.05   .20   .27   .20   .04  1.00
427 END DATA.
428 @end example
429
430 @subsubheading Example 7: Split variables with explicit values
431
432 This syntax defines two matrices, using the variable @code{s1} to
433 distinguish between them.  Each line of data begins with @code{s1}.
434 This yields the same matrix file as Example 4 (@pxref{MATRIX DATA
435 Example 4}).
436
437 @example
438 MATRIX DATA
439     VARIABLES=s1 var01 TO var04
440     /SPLIT=s1
441     /FORMAT=FULL
442     /CONTENTS=MEAN SD N CORR.
443 BEGIN DATA.
444 0 34 35 36 37
445 0 22 11 55 66
446 0 99 98 99 92
447 0  1 .9 .8 .7
448 0 .9  1 .6 .5
449 0 .8 .6  1 .4
450 0 .7 .5 .4  1
451 1 44 45 34 39
452 1 23 15 51 46
453 1 98 34 87 23
454 1  1 .2 .3 .4
455 1 .2  1 .5 .6
456 1 .3 .5  1 .7
457 1 .4 .6 .7  1
458 END DATA.
459 @end example
460
461 @subsubheading Example 8: Split variable with sequential values
462 @anchor{MATRIX DATA Example 8}
463
464 Like this previous example, this syntax defines two matrices with
465 split variable @code{s1}.  In this case, though, @code{s1} is not
466 listed in @subcmd{VARIABLES}, which means that its value does not
467 appear in the data.  Instead, @cmd{MATRIX DATA} reads matrix data
468 until the input is exhausted, supplying 1 for the first split, 2 for
469 the second, and so on.
470
471 @example
472 MATRIX DATA
473     VARIABLES=var01 TO var04
474     /SPLIT=s1
475     /FORMAT=FULL
476     /CONTENTS=MEAN SD N CORR.
477 BEGIN DATA.
478 34 35 36 37
479 22 11 55 66
480 99 98 99 92
481  1 .9 .8 .7
482 .9  1 .6 .5
483 .8 .6  1 .4
484 .7 .5 .4  1
485 44 45 34 39
486 23 15 51 46
487 98 34 87 23
488  1 .2 .3 .4
489 .2  1 .5 .6
490 .3 .5  1 .7
491 .4 .6 .7  1
492 END DATA.
493 @end example
494
495 @subsubsection Factor variables without @code{ROWTYPE_}
496
497 Without @subcmd{ROWTYPE_}, factor variables introduce two new wrinkles
498 to @cmd{MATRIX DATA} syntax.  First, the @subcmd{CELLS} subcommand
499 must declare the number of combinations of factor variables present in
500 the data.  If there is, for example, one factor variable for which the
501 data contains three values, one would write @code{CELLS=3}; if there
502 are two (or more) factor variables for which the data contains five
503 combinations, one would use @code{CELLS=5}; and so on.
504
505 Second, the @subcmd{CONTENTS} subcommand must distinguish within-cell
506 data from pooled data by enclosing within-cell row types in
507 parentheses.  When different within-cell row types for a single factor
508 appear in subsequent lines, enclose the row types in a single set of
509 parentheses; when different factors' values for a given within-cell
510 row type appear in subsequent lines, enclose each row type in
511 individual parentheses.
512
513 Without @subcmd{ROWTYPE_}, input lines for pooled data do not include
514 factor values, not even as missing values, but input lines for
515 within-cell data do.
516
517 The following examples aim to clarify this syntax.
518
519 @subsubheading Example 9: Factor variables, grouping within-cell records by factor
520
521 This syntax defines the same matrix file as Example 5 (@pxref{MATRIX
522 DATA Example 5}), without using @code{ROWTYPE_}.  It declares
523 @code{CELLS=2} because the data contains two values (0 and 1) for
524 factor variable @code{f1}.  Within-cell vector row types @code{MEAN},
525 @code{SD}, and @code{N} are in a single set of parentheses on
526 @subcmd{CONTENTS} because they are grouped together in subsequent
527 lines for a single factor value.  The data lines with the pooled
528 correlation matrix do not have any factor values.
529
530 @example
531 MATRIX DATA
532     VARIABLES=f1 var01 TO var04
533     /FACTOR=f1
534     /CELLS=2
535     /CONTENTS=(MEAN SD N) CORR.
536 BEGIN DATA.
537 0 34 35 36 37
538 0 22 11 55 66
539 0 99 98 99 92
540 1 44 45 34 39
541 1 23 15 51 46
542 1 98 34 87 23
543    1
544   .9  1
545   .8 .6  1
546   .7 .5 .4  1
547 END DATA.
548 @end example
549
550 @subsubheading Example 10: Factor variables, grouping within-cell records by row type
551
552 This syntax defines the same matrix file as the previous example.  The
553 only difference is that the within-cell vector rows are grouped
554 differently: two rows of means (one for each factor), followed by two
555 rows of standard deviations, followed by two rows of counts.
556
557 @example
558 MATRIX DATA
559     VARIABLES=f1 var01 TO var04
560     /FACTOR=f1
561     /CELLS=2
562     /CONTENTS=(MEAN) (SD) (N) CORR.
563 BEGIN DATA.
564 0 34 35 36 37
565 1 44 45 34 39
566 0 22 11 55 66
567 1 23 15 51 46
568 0 99 98 99 92
569 1 98 34 87 23
570    1
571   .9  1
572   .8 .6  1
573   .7 .5 .4  1
574 END DATA.
575 @end example
576
577 @node MCONVERT
578 @section MCONVERT
579 @vindex MCONVERT
580
581 @display
582 MCONVERT
583     [[MATRIX=]
584      [IN(@{@samp{*}|'@var{file}'@})]
585      [OUT(@{@samp{*}|'@var{file}'@})]]
586     [/@{REPLACE,APPEND@}].
587 @end display
588
589 The @cmd{MCONVERT} command converts matrix data from a correlation
590 matrix and a vector of standard deviations into a covariance matrix,
591 or vice versa.
592
593 By default, @cmd{MCONVERT} both reads and writes the active file.  Use
594 the @cmd{MATRIX} subcommand to specify other files.  To read a matrix
595 file, specify its name inside parentheses following @code{IN}.  To
596 write a matrix file, specify its name inside parentheses following
597 @code{OUT}.  Use @samp{*} to explicitly specify the active file for
598 input or output.
599
600 When @cmd{MCONVERT} reads the input, by default it substitutes a
601 correlation matrix and a vector of standard deviations each time it
602 encounters a covariance matrix, and vice versa.  Specify
603 @code{/APPEND} to instead have @cmd{MCONVERT} add the other form of
604 data without removing the existing data.  Use @code{/REPLACE} to
605 explicitly request removing the existing data.
606
607 The @cmd{MCONVERT} command requires its input to be a matrix file.
608 Use @cmd{MATRIX DATA} to convert text input into matrix file format.
609 @xref{MATRIX DATA}, for details.
610
611 @node MATRIX
612 @section MATRIX
613 @vindex MATRIX
614 @vindex END MATRIX
615
616 @display
617 @t{MATRIX.}
618 @dots{}@i{matrix commands}@dots{}
619 @t{END MATRIX.}
620 @end display
621
622 @noindent
623 The following basic matrix commands are supported:
624
625 @display
626 @t{COMPUTE} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]@t{=}@i{expression}@t{.}
627 @t{CALL} @i{procedure}@t{(}@i{argument}@t{,} @dots{}).
628 @t{PRINT} [@i{expression}]
629       [@t{/FORMAT}@t{=}@i{format}]
630       [@t{/TITLE}@t{=}@i{title}]
631       [@t{/SPACE}@t{=}@{@t{NEWPAGE} @math{|} @i{n}@}]
632       [@{@t{/RLABELS}@t{=}@i{string}@dots{} @math{|} @t{/RNAMES}@t{=}@i{expression}@}]
633       [@{@t{/CLABELS}@t{=}@i{string}@dots{} @math{|} @t{/CNAMES}@t{=}@i{expression}@}]@t{.}
634 @end display
635
636 @noindent
637 The following matrix commands offer support for flow control:
638
639 @display
640 @t{DO IF} @i{expression}@t{.}
641   @dots{}@i{matrix commands}@dots{}
642 [@t{ELSE IF} @i{expression}@t{.}
643   @dots{}@i{matrix commands}@dots{}]@dots{}
644 [@t{ELSE}
645   @dots{}@i{matrix commands}@dots{}]
646 @t{END IF}@t{.}
647
648 @t{LOOP} [@i{var}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{step}]] [@t{IF} @i{expression}]@t{.}
649   @dots{}@i{matrix commands}@dots{}
650 @t{END LOOP} [@t{IF} @i{expression}]@t{.}
651
652 @t{BREAK}@t{.}
653 @end display
654
655 @noindent
656 The following matrix commands support matrix input and output:
657
658 @display
659 @t{READ} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]
660      [@t{/FILE}@t{=}@i{file}]
661      @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
662      [@t{/FORMAT}@t{=}@i{format}]
663      [@t{/SIZE}@t{=}@i{expression}]
664      [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{SYMMETRIC}@}]
665      [@t{/REREAD}]@t{.}
666 @t{WRITE} @i{expression}
667       [@t{/OUTFILE}@t{=}@i{file}]
668       @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
669       [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{TRIANGULAR}@}]
670       [@t{/HOLD}]
671       [@t{/FORMAT}@t{=}@i{format}]@t{.}
672 @t{GET} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]
673     [@t{/FILE}@t{=}@{@i{file} @math{|} @t{*}@}]
674     [@t{/VARIABLES}@t{=}@i{variable}@dots{}]
675     [@t{/NAMES}@t{=}@i{expression}]
676     [@t{/MISSING}@t{=}@{@t{ACCEPT} @math{|} @t{OMIT} @math{|} @i{number}@}]
677     [@t{/SYSMIS}@t{=}@{@t{OMIT} @math{|} @i{number}@}]@t{.}
678 @t{SAVE} @i{expression}
679      [@t{/OUTFILE}@t{=}@{@i{file} @math{|} @t{*}@}]
680      [@t{/VARIABLES}@t{=}@i{variable}@dots{}]
681      [@t{/NAMES}@t{=}@i{expression}]
682      [@t{/STRINGS}@t{=}@i{variable}@dots{}]@t{.}
683 @t{MGET} [@t{/FILE}@t{=}@i{file}]
684      [@t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}]@t{.}
685 @t{MSAVE} @i{expression}
686       @t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}
687       [@t{/OUTFILE}@t{=}@i{file}]
688       [@t{/VARIABLES}@t{=}@i{variable}@dots{}]
689       [@t{/SNAMES}@t{=}@i{variable}@dots{}]
690       [@t{/SPLIT}@t{=}@i{expression}]
691       [@t{/FNAMES}@t{=}@i{variable}@dots{}]
692       [@t{/FACTOR}@t{=}@i{expression}]@t{.}
693 @end display
694
695 @noindent
696 The following matrix commands provide additional support:
697
698 @display
699 @t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}]@t{.}
700 @t{RELEASE} @i{variable}@dots{}@t{.}
701 @end display
702
703 @code{MATRIX} and @code{END MATRIX} enclose a special @pspp{}
704 sub-language, called the matrix language.  The matrix language does
705 not require an active dataset to be defined and only a few of the
706 matrix language commands work with any datasets that are defined.
707 Each instance of @code{MATRIX}@dots{}@code{END MATRIX} is a separate
708 program whose state is independent of any instance, so that variables
709 declared within a matrix program are forgotten at its end.
710
711 The matrix language works with matrices, where a @dfn{matrix} is a
712 rectangular array of real numbers.  An @math{@var{n}@times{}@var{m}}
713 matrix has @var{n} rows and @var{m} columns.  Some special cases are
714 important: a @math{@var{n}@times{}1} matrix is a @dfn{column vector},
715 a @math{1@times{}@var{n}} is a @dfn{row vector}, and a
716 @math{1@times{}1} matrix is a @dfn{scalar}.
717
718 The matrix language also has limited support for matrices that contain
719 8-byte strings instead of numbers.  Strings longer than 8 bytes are
720 truncated, and shorter strings are padded with spaces.  String
721 matrices are mainly useful for labeling rows and columns when printing
722 numerical matrices with the @code{MATRIX PRINT} command.  Arithmetic
723 operations on string matrices will not produce useful results.  The
724 user should not mix strings and numbers within a matrix.
725
726 The matrix language does not work with cases.  A variable in the
727 matrix language represents a single matrix.
728
729 The matrix language does not support missing values.
730
731 @code{MATRIX} is a procedure, so it cannot be enclosed inside @code{DO
732 IF}, @code{LOOP}, etc.
733
734 Macros may be used within a matrix program, and macros may expand to
735 include entire matrix programs.  The @code{DEFINE} command may not
736 appear within a matrix program.  @xref{DEFINE}, for more information
737 about macros.
738
739 The following sections describe the details of the matrix language:
740 first, the syntax of matrix expressions, then each of the supported
741 commands.  The @code{COMMENT} command (@pxref{COMMENT}) is also
742 supported.
743
744 @node Matrix Expressions
745 @subsection Matrix Expressions
746
747 Many matrix commands use expressions.  A matrix expression may use the
748 following operators, listed in descending order of operator
749 precedence.  Within a single level, operators associate from left to
750 right.
751
752 @itemize @bullet
753 @item
754 Function call @t{()} and matrix construction @t{@{@}}
755
756 @item
757 Indexing @t{()}
758
759 @item
760 Unary @t{+} and @t{-}
761
762 @item
763 Integer sequence @t{:}
764
765 @item
766 Exponentiation @t{**} and @t{&**}
767
768 @item
769 Multiplication @t{*} and @t{&*}, and division @t{/} and @t{&/}
770
771 @item
772 Addition @t{+} and subtraction @t{-}
773
774 @item
775 Relational @t{< <= = >= > <>}
776
777 @item
778 Logical @t{NOT}
779
780 @item
781 Logical @t{AND}
782
783 @item
784 Logical @t{OR} and @t{XOR}
785 @end itemize
786
787 @xref{Matrix Functions}, for the available matrix functions.  The
788 remaining operators are described in more detail below.
789
790 @cindex restricted expressions
791 Expressions appear in the matrix language in some contexts where there
792 would be ambiguity whether @samp{/} is an operator or a separator
793 between subcommands.  In these contexts, only the operators with
794 higher precedence than @samp{/} are allowed outside parentheses.
795 Later sections call these @dfn{restricted expressions}.
796
797 @node Matrix Construction Operator
798 @subsubsection Matrix Construction Operator @t{@{@}}
799
800 Use the @t{@{}@t{@}} operator to construct matrices.  Within
801 the curly braces, commas separate elements within a row and semicolons
802 separate rows.  The following examples show a @math{2@times{}3}
803 matrix, a @math{1@times{}4} row vector, a @math{3@times{}1} column
804 vector, and a scalar.
805
806 @multitable @columnfractions .4 .05 .4
807 @item @t{@{1, 2, 3; 4, 5, 6@}}
808 @tab @result{}
809 @tab
810 @ifnottex
811 @t{[1  2  3] @* [4  5  6]}
812 @end ifnottex
813 @iftex
814 @math{\left(\matrix{1 & 2 & 3 \cr 4 & 5 & 6}\right)}
815 @end iftex
816 @
817 @item @t{@{3.14, 6.28, 9.24, 12.57@}}
818 @tab @result{}
819 @tab
820 @ifnottex
821 [3.14  6.28  9.42  12.57]
822 @end ifnottex
823 @iftex
824 @math{(\matrix{3.14 & 6.28 & 9.42 & 12.57})}
825 @end iftex
826 @
827 @item @t{@{1.41; 1.73; 2@}}
828 @tab @result{}
829 @tab
830 @ifnottex
831 @t{[1.41] @* [1.73] @* [2.00]}
832 @end ifnottex
833 @iftex
834 @math{(\matrix{1.41 & 1.73 & 2.00})}
835 @end iftex
836 @
837 @item @t{@{5@}}
838 @tab @result{}
839 @tab 5
840 @end multitable
841
842 Curly braces are not limited to holding numeric literals.  They can
843 contain calculations, and they can paste together matrices and vectors
844 in any way as long as the result is rectangular.  For example, if
845 @samp{m} is matrix @code{@{1, 2; 3, 4@}}, @samp{r} is row vector
846 @code{@{5, 6@}}, and @samp{c} is column vector @code{@{7, 8@}}, then
847 curly braces can be used as follows:
848
849 @multitable @columnfractions .4 .05 .4
850 @item @t{@{m, c; r, 10@}}
851 @tab @result{}
852 @tab
853 @ifnottex
854 @t{[1 2  7] @* [3 4  8] @* [5 6 10]}
855 @end ifnottex
856 @iftex
857 @math{\left(\matrix{1 & 2 & 7 \cr 3 & 4 & 8 \cr 5 & 6 & 10}\right)}
858 @end iftex
859 @
860 @item @t{@{c, 2 * c, T(r)@}}
861 @tab @result{}
862 @tab
863 @ifnottex
864 @t{[7 14 5] @* [8 16 6]}
865 @end ifnottex
866 @iftex
867 @math{\left(\matrix{7 & 14 & 5 \cr 8 & 16 & 6}\right)}
868 @end iftex
869 @end multitable
870
871 The final example above uses the transposition function @code{T}.
872
873 @node Matrix Sequence Operator
874 @subsubsection Integer Sequence Operator @samp{:}
875
876 The syntax @code{@var{first}:@var{last}:@var{step}} yields a row
877 vector of consecutive integers from @var{first} to @var{last} counting
878 by @var{step}.  The final @code{:@var{step}} is optional and
879 defaults to 1 when omitted.
880
881 Each of @var{first}, @var{last}, and @var{step} must be a scalar and
882 should be an integer (any fractional part is discarded).  Because
883 @samp{:} has a high precedence, operands other than numeric literals
884 must usually be parenthesized.
885
886 When @var{step} is positive (or omitted) and @math{@var{end} <
887 @var{start}}, or if @var{step} is negative and @math{@var{end} >
888 @var{start}}, then the result is an empty matrix.  If @var{step} is 0,
889 then @pspp{} reports an error.
890
891 Here are some examples:
892
893 @multitable @columnfractions .4 .05 .4
894 @item @t{1:6}      @tab @result{} @tab @t{@{1, 2, 3, 4, 5, 6@}}
895 @item @t{1:6:2}    @tab @result{} @tab @t{@{1, 3, 5@}}
896 @item @t{-1:-5:-1} @tab @result{} @tab @t{@{-1, -2, -3, -4, -5@}}
897 @item @t{-1:-5}    @tab @result{} @tab @t{@{@}}
898 @item @t{2:1:0}    @tab @result{} @tab (error)
899 @end multitable
900
901 @node Matrix Index Operator
902 @subsubsection Index Operator @code{()}
903
904 The result of the submatrix or indexing operator, written
905 @code{@var{m}(@var{rindex}, @var{cindex})}, contains the rows of
906 @var{m} whose indexes are given in vector @var{rindex} and the columns
907 whose indexes are given in vector @var{cindex}.
908
909 In the simplest case, if @var{rindex} and @var{cindex} are both
910 scalars, the result is also a scalar:
911
912 @multitable @columnfractions .4 .05 .4
913 @item @t{@{10, 20; 30, 40@}(1, 1)} @tab @result{} @tab @t{10}
914 @item @t{@{10, 20; 30, 40@}(1, 2)} @tab @result{} @tab @t{20}
915 @item @t{@{10, 20; 30, 40@}(2, 1)} @tab @result{} @tab @t{30}
916 @item @t{@{10, 20; 30, 40@}(2, 2)} @tab @result{} @tab @t{40}
917 @end multitable
918
919 If the index arguments have multiple elements, then the result
920 includes multiple rows or columns:
921
922 @multitable @columnfractions .4 .05 .4
923 @item @t{@{10, 20; 30, 40@}(1:2, 1)} @tab @result{} @tab @t{@{10; 30@}}
924 @item @t{@{10, 20; 30, 40@}(2, 1:2)} @tab @result{} @tab @t{@{30, 40@}}
925 @item @t{@{10, 20; 30, 40@}(1:2, 1:2)} @tab @result{} @tab @t{@{10, 20; 30, 40@}}
926 @end multitable
927
928 The special argument @samp{:} may stand in for all the rows or columns
929 in the matrix being indexed, like this:
930
931 @multitable @columnfractions .4 .05 .4
932 @item @t{@{10, 20; 30, 40@}(:, 1)} @tab @result{} @tab @t{@{10; 30@}}
933 @item @t{@{10, 20; 30, 40@}(2, :)} @tab @result{} @tab @t{@{30, 40@}}
934 @item @t{@{10, 20; 30, 40@}(:, :)} @tab @result{} @tab @t{@{10, 20; 30, 40@}}
935 @end multitable
936
937 The index arguments do not have to be in order, and they may contain
938 repeated values, like this:
939
940 @multitable @columnfractions .4 .05 .4
941 @item @t{@{10, 20; 30, 40@}(@{2, 1@}, 1)} @tab @result{} @tab @t{@{30; 10@}}
942 @item @t{@{10, 20; 30, 40@}(2, @{2; 2; 1@})} @tab @result{} @tab @t{@{40, 40, 30@}}
943 @item @t{@{10, 20; 30, 40@}(2:1:-1, :)} @tab @result{} @tab @t{@{30, 40; 10, 20@}}
944 @end multitable
945
946 When the matrix being indexed is a row or column vector, only a single
947 index argument is needed, like this:
948
949 @multitable @columnfractions .4 .05 .4
950 @item @t{@{11, 12, 13, 14, 15@}(2:4)} @tab @result{} @tab @t{@{12, 13, 14@}}
951 @item @t{@{11; 12; 13; 14; 15@}(2:4)} @tab @result{} @tab @t{@{12; 13; 14@}}
952 @end multitable
953
954 When an index is not an integer, @pspp{} discards the fractional part.
955 It is an error for an index to be less than 1 or greater than the
956 number of rows or columns:
957
958 @multitable @columnfractions .4 .05 .4
959 @item @t{@{11, 12, 13, 14@}(@{2.5, 4.6@})} @tab @result{} @tab @t{@{12, 14@}}
960 @item @t{@{11; 12; 13; 14@}(0)} @tab @result{} @tab (error)
961 @end multitable
962
963 @node Matrix Unary Operators
964 @subsubsection Unary Operators
965
966 The unary operators take a single operand of any dimensions and
967 operate on each of its elements independently.  The unary operators
968 are:
969
970 @table @code
971 @item -
972 Inverts the sign of each element.
973
974 @item +
975 No change.
976
977 @item NOT
978 Logical inversion: each positive value becomes 0 and each zero or
979 negative value becomes 1.
980 @end table
981
982 Examples:
983
984 @multitable @columnfractions .4 .05 .4
985 @item @t{-@{1, -2; 3, -4@}} @tab @result{} @tab @t{@{-1, 2; -3, 4@}}
986 @item @t{+@{1, -2; 3, -4@}} @tab @result{} @tab @t{@{1, -2; 3, -4@}}
987 @item @t{NOT @{1, 0; -1, 1@}} @tab @result{} @tab @t{@{0, 1; 1, 0@}}
988 @end multitable
989
990 @node Matrix Elementwise Binary Operators
991 @subsubsection Elementwise Binary Operators
992
993 The elementwise binary operators require their operands to be matrices
994 with the same dimensions.  Alternatively, if one operand is a scalar,
995 then its value is treated as if it were duplicated to the dimensions
996 of the other operand.  The result is a matrix of the same size as the
997 operands, in which each element is the result of the applying the
998 operator to the corresponding elements of the operands.
999
1000 The elementwise binary operators are listed below.
1001
1002 @itemize @bullet
1003 @item
1004 The arithmetic operators, for familiar arithmetic operations:
1005
1006 @table @asis
1007 @item @code{+}
1008 Addition.
1009
1010 @item @code{-}
1011 Subtraction.
1012
1013 @item @code{*}
1014 Multiplication, if one operand is a scalar.  (Otherwise this is matrix
1015 multiplication, described below.)
1016
1017 @item @code{/} or @code{&/}
1018 Division.
1019
1020 @item @code{&*}
1021 Multiplication.
1022
1023 @item @code{&**}
1024 Exponentiation.
1025 @end table
1026
1027 @item
1028 The relational operators, whose results are 1 when a comparison is
1029 true and 0 when it is false:
1030
1031 @table @asis
1032 @item @code{<} or @code{LT}
1033 Less than.
1034
1035 @item @code{<=} or @code{LE}
1036 Less than or equal.
1037
1038 @item @code{=} or @code{EQ}
1039 Equal.
1040
1041 @item @code{>} or @code{GT}
1042 Greater than.
1043
1044 @item @code{>=} or @code{GE}
1045 Greater than or equal.
1046
1047 @item @code{<>} or @code{~=} or @code{NE}
1048 Not equal.
1049 @end table
1050
1051 @item
1052 The logical operators, which treat positive operands as true and
1053 nonpositive operands as false.  They yield 0 for false and 1 for true:
1054
1055 @table @code
1056 @item AND
1057 True if both operands are true.
1058
1059 @item OR
1060 True if at least one operand is true.
1061
1062 @item XOR
1063 True if exactly one operand is true.
1064 @end table
1065 @end itemize
1066
1067 Examples:
1068
1069 @multitable @columnfractions .4 .05 .4
1070 @item @t{1 + 2} @tab @result{} @tab @t{3}
1071 @item @t{1 + @{3; 4@}} @tab @result{} @tab @t{@{4; 5@}}
1072 @item @t{@{66, 77; 88, 99@} + 5} @tab @result{} @tab @t{@{71, 82; 93, 104@}}
1073 @item @t{@{4, 8; 3, 7@} + @{1, 0; 5, 2@}} @tab @result{} @tab @t{@{5, 8; 8, 9@}}
1074 @item @t{@{1, 2; 3, 4@} < @{4, 3; 2, 1@}} @tab @result{} @tab @t{@{1, 1; 0, 0@}}
1075 @item @t{@{1, 3; 2, 4@} >= 3} @tab @result{} @tab @t{@{0, 1; 0, 1@}}
1076 @item @t{@{0, 0; 1, 1@} AND @{0, 1; 0, 1@}} @tab @result{} @tab @t{@{0, 0; 0, 1@}}
1077 @end multitable
1078
1079 @node Matrix Multiplication Operator
1080 @subsubsection Matrix Multiplication Operator @samp{*}
1081
1082 If @code{A} is an @math{@var{m}@times{}@var{n}} matrix and @code{B} is
1083 an @math{@var{n}@times{}@var{p}} matrix, then @code{A*B} is the
1084 @math{@var{m}@times{}@var{p}} matrix multiplication product @code{C}.
1085 @pspp{} reports an error if the number of columns in @code{A} differs
1086 from the number of rows in @code{B}.
1087
1088 The @code{*} operator performs elementwise multiplication (see above)
1089 if one of its operands is a scalar.
1090
1091 No built-in operator yields the inverse of matrix multiplication.
1092 Instead, multiply by the result of @code{INV} or @code{GINV}.
1093
1094 Some examples:
1095
1096 @multitable @columnfractions .4 .05 .4
1097 @item @t{@{1, 2, 3@} * @{4; 5; 6@}} @tab @result{} @tab @t{32}
1098 @item @t{@{4; 5; 6@} * @{1, 2, 3@}} @tab @result{} @tab @t{@{4,@w{ } 8, 12; @*@w{ }5, 10, 15; @*@w{ }6, 12, 18@}}
1099 @end multitable
1100
1101 @node Matrix Exponentiation Operator
1102 @subsubsection Matrix Exponentiation Operator @code{**}
1103
1104 The result of @code{A**B} is defined as follows when @code{A} is a
1105 square matrix and @code{B} is an integer scalar:
1106
1107 @itemize @bullet
1108 @item
1109 For @code{B > 0}, @code{A**B} is @code{A*@dots{}*A}, where there are
1110 @code{B} @samp{A}s.  (@pspp{} implements this efficiently for large
1111 @code{B}, using exponentiation by squaring.)
1112
1113 @item
1114 For @code{B < 0}, @code{A**B} is @code{INV(A**(-B))}.
1115
1116 @item
1117 For @code{B = 0}, @code{A**B} is the identity matrix.
1118 @end itemize
1119
1120 @noindent
1121 @pspp{} reports an error if @code{A} is not square or @code{B} is not
1122 an integer.
1123
1124 Examples:
1125
1126 @multitable @columnfractions .4 .05 .4
1127 @item @t{@{2, 5; 1, 4@}**3} @tab @result{} @tab @t{@{48, 165; 33, 114@}}
1128 @item @t{@{2, 5; 1, 4@}**0} @tab @result{} @tab @t{@{1, 0; 0, 1@}}
1129 @item @t{10*@{4, 7; 2, 6@}**-1} @tab @result{} @tab @t{@{6, -7; -2, 4@}}
1130 @end multitable
1131
1132 @node Matrix Functions
1133 @subsection Matrix Functions
1134
1135 The matrix language support numerous functions in multiple categories.
1136 The following subsections document each of the currently supported
1137 functions.  The first letter of each parameter's name indicate the
1138 required argument type:
1139
1140 @table @var
1141 @item s
1142 A scalar.
1143
1144 @item n
1145 A nonnegative integer scalar.  (Non-integers are accepted and silently
1146 rounded down to the nearest integer.)
1147
1148 @item V
1149 A row or column vector.
1150
1151 @item M
1152 A matrix.
1153 @end table
1154
1155 @node Matrix Elementwise Functions
1156 @subsubsection Elementwise Functions
1157
1158 These functions act on each element of their argument independently,
1159 like the elementwise operators (@pxref{Matrix Elementwise Binary
1160 Operators}).
1161
1162 @deffn {Matrix Function} ABS (@var{M})
1163 Takes the absolute value of each element of @var{M}.
1164
1165 @t{ABS(@{-1, 2; -3, 0@}) @result{} @{1, 2; 3, 0@}}
1166 @end deffn
1167
1168 @deffn {Matrix Function} ARSIN (@var{M})
1169 @deffnx {Matrix Function} ARTAN (@var{M})
1170 Computes the inverse sine or tangent, respectively, of each element in
1171 @var{M}.  The results are in radians, between @math{-\pi/2} and
1172 @math{+\pi/2}, inclusive.
1173
1174 The value of @math{\pi} can be computed as @code{4*ARTAN(1)}.
1175
1176 @t{ARSIN(@{-1, 0, 1@}) @result{} @{-1.57, 0, 1.57@}} (approximately)
1177
1178 @t{ARTAN(@{-5, -1, 1, 5@}) @result{} @{-1.37, -.79, .79, 1.37@}} (approximately)
1179 @end deffn
1180
1181 @deffn {Matrix Function} COS (@var{M})
1182 @deffnx {Matrix Function} SIN (@var{M})
1183 Computes the cosine or sine, respectively, of each element in @var{M},
1184 which must be in radians.
1185
1186 @t{COS(@{0.785, 1.57; 3.14, 1.57 + 3.14@}) @result{} @{.71, 0; -1, 0@}} (approximately)
1187 @end deffn
1188
1189 @deffn {Matrix Function} EXP (@var{M})
1190 Computes @math{e^x} for each element @var{x} in @var{M}.
1191
1192 @t{EXP(@{2, 3; 4, 5@}) @result{} @{7.39, 20.09; 54.6, 148.4@}} (approximately)
1193 @end deffn
1194
1195 @deffn {Matrix Function} LG10 (@var{M})
1196 @deffnx {Matrix Function} LN (@var{M})
1197 Takes the logarithm with base 10 or base @math{e}, respectively, of
1198 each element in @var{M}.
1199
1200 @t{LG10(@{1, 10, 100, 1000@}) @result{} @{0, 1, 2, 3@}} @*
1201 @t{LG10(0) @result{}} (error)
1202
1203 @t{LN(@{EXP(1), 1, 2, 3, 4@}) @result{} @{1, 0, .69, 1.1, 1.39@}} (approximately) @*
1204 @t{LN(0) @result{}} (error)
1205 @end deffn
1206
1207 @deffn {Matrix Function} MOD (@var{M}, @var{s})
1208 Takes each element in @var{M} modulo nonzero scalar value @var{s},
1209 that is, the remainder of division by @var{s}.  The sign of the result
1210 is the same as the sign of the dividend.
1211
1212 @t{MOD(@{5, 4, 3, 2, 1, 0@}, 3) @result{} @{2, 1, 0, 2, 1, 0@}} @*
1213 @t{MOD(@{5, 4, 3, 2, 1, 0@}, -3) @result{} @{2, 1, 0, 2, 1, 0@}} @*
1214 @t{MOD(@{-5, -4, -3, -2, -1, 0@}, 3) @result{} @{-2, -1, 0, -2, -1, 0@}} @*
1215 @t{MOD(@{-5, -4, -3, -2, -1, 0@}, -3) @result{} @{-2, -1, 0, -2, -1, 0@}} @*
1216 @t{MOD(@{5, 4, 3, 2, 1, 0@}, 1.5) @result{} @{.5, 1.0, .0, .5, 1.0, .0@}} @*
1217 @t{MOD(@{5, 4, 3, 2, 1, 0@}, 0) @result{}} (error)
1218 @end deffn
1219
1220 @deffn {Matrix Function} RND (@var{M})
1221 @deffnx {Matrix Function} TRUNC (@var{M})
1222 Rounds each element of @var{M} to an integer.  @code{RND} rounds to
1223 the nearest integer, with halves rounded to even integers, and
1224 @code{TRUNC} rounds toward zero.
1225
1226 @t{RND(@{-1.6, -1.5, -1.4@}) @result{} @{-2, -2, -1@}} @*
1227 @t{RND(@{-.6, -.5, -.4@}) @result{} @{-1, 0, 0@}} @*
1228 @t{RND(@{.4, .5, .6@} @result{} @{0, 0, 1@}} @*
1229 @t{RND(@{1.4, 1.5, 1.6@}) @result{} @{1, 2, 2@}}
1230
1231 @t{TRUNC(@{-1.6, -1.5, -1.4@}) @result{} @{-1, -1, -1@}} @*
1232 @t{TRUNC(@{-.6, -.5, -.4@}) @result{} @{0, 0, 0@}} @*
1233 @t{TRUNC(@{.4, .5, .6@} @result{} @{0, 0, 0@}} @*
1234 @t{TRUNC(@{1.4, 1.5, 1.6@}) @result{} @{1, 1, 1@}}
1235 @end deffn
1236
1237 @deffn {Matrix Function} SQRT (@var{M})
1238 Takes the square root of each element of @var{M}, which must not be
1239 negative.
1240
1241 @t{SQRT(@{0, 1, 2, 4, 9, 81@}) @result{} @{0, 1, 1.41, 2, 3, 9@}} (approximately) @*
1242 @t{SQRT(-1) @result{}} (error)
1243 @end deffn
1244
1245 @node Matrix Logical Functions
1246 @subsubsection Logical Functions
1247
1248 @deffn {Matrix Function} ALL (@var{M})
1249 Returns a scalar with value 1 if all of the elements in @var{M} are
1250 nonzero, or 0 if at least one element is zero.
1251
1252 @t{ALL(@{1, 2, 3@} < @{2, 3, 4@}) @result{} 1} @*
1253 @t{ALL(@{2, 2, 3@} < @{2, 3, 4@}) @result{} 0} @*
1254 @t{ALL(@{2, 3, 3@} < @{2, 3, 4@}) @result{} 0} @*
1255 @t{ALL(@{2, 3, 4@} < @{2, 3, 4@}) @result{} 0}
1256 @end deffn
1257
1258 @deffn {Matrix Function} ANY (@var{M})
1259 Returns a scalar with value 1 if any of the elements in @var{M} is
1260 nonzero, or 0 if all of them are zero.
1261
1262 @t{ANY(@{1, 2, 3@} < @{2, 3, 4@}) @result{} 1} @*
1263 @t{ANY(@{2, 2, 3@} < @{2, 3, 4@}) @result{} 1} @*
1264 @t{ANY(@{2, 3, 3@} < @{2, 3, 4@}) @result{} 1} @*
1265 @t{ANY(@{2, 3, 4@} < @{2, 3, 4@}) @result{} 0}
1266 @end deffn
1267
1268 @node Matrix Construction Functions
1269 @subsubsection Matrix Construction Functions
1270
1271 @deffn {Matrix Function} BLOCK (@var{M1}, @dots{}, @var{Mn})
1272 Returns a block diagonal matrix with as many rows as the sum of its
1273 arguments' row counts and as many columns as the sum of their columns.
1274 Each argument matrix is placed along the main diagonal of the result,
1275 and all other elements are zero.
1276
1277 @format
1278 @t{BLOCK(@{1, 2; 3, 4@}, 5, @{7; 8; 9@}, @{10, 11@}) @result{}
1279    1   2   0   0   0   0
1280    3   4   0   0   0   0
1281    0   0   5   0   0   0
1282    0   0   0   7   0   0
1283    0   0   0   8   0   0
1284    0   0   0   9   0   0
1285    0   0   0   0  10  11}
1286 @end format
1287 @end deffn
1288
1289 @deffn {Matrix Function} IDENT (@var{n})
1290 @deffnx {Matrix Function} IDENT (@var{nr}, @var{nc})
1291 Returns an identity matrix, whose main diagonal elements are one and
1292 whose other elements are zero.  The returned matrix has @var{n} rows
1293 and columns or @var{nr} rows and @var{nc} columns, respectively.
1294
1295 @format
1296 @t{IDENT(1) @result{} 1
1297 IDENT(2) @result{}
1298   1  0
1299   0  1
1300 IDENT(3, 5) @result{}
1301   1  0  0  0  0
1302   0  1  0  0  0
1303   0  0  1  0  0
1304 IDENT(5, 3) @result{}
1305   1  0  0
1306   0  1  0
1307   0  0  1
1308   0  0  0
1309   0  0  0}
1310 @end format
1311 @end deffn
1312
1313 @deffn {Matrix Function} MAGIC (@var{n})
1314 Returns an @math{@var{n}@times{}@var{n}} matrix that contains each of
1315 the integers @math{1@dots{}@var{n}} once, in which each column, each
1316 row, and each diagonal sums to @math{n(n^2+1)/2}.  There are many
1317 magic squares with given dimensions, but this function always returns
1318 the same one for a given value of @var{n}.
1319
1320 @t{MAGIC(3) @result{} @{8, 1, 6; 3, 5, 7; 4, 9, 2@}} @*
1321 @t{MAGIC(4) @result{} @{1, 5, 12, 16; 15, 11, 6, 2; 14, 8, 9, 3; 4, 10, 7, 13@}}
1322 @end deffn
1323
1324 @deffn {Matrix Function} MAKE (@var{nr}, @var{nc}, @var{s})
1325 Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements are
1326 all @var{s}.
1327
1328 @t{MAKE(1, 2, 3) @result{} @{3, 3@}} @*
1329 @t{MAKE(2, 1, 4) @result{} @{4; 4@}} @*
1330 @t{MAKE(2, 3, 5) @result{} @{5, 5, 5; 5, 5, 5@}}
1331 @end deffn
1332
1333 @deffn {Matrix Function} MDIAG (@var{V})
1334 @anchor{MDIAG} Given @var{n}-element vector @var{V}, returns a
1335 @math{@var{n}@times{}@var{n}} matrix whose main diagonal is copied
1336 from @var{V}.  The other elements in the returned vector are zero.
1337
1338 Use @code{CALL SETDIAG} (@pxref{CALL SETDIAG}) to replace the main
1339 diagonal of a matrix in-place.
1340
1341 @format
1342 @t{MDIAG(@{1, 2, 3, 4@}) @result{}
1343   1  0  0  0
1344   0  2  0  0
1345   0  0  3  0
1346   0  0  0  4}
1347 @end format
1348 @end deffn
1349
1350 @deffn {Matrix Function} RESHAPE (@var{M}, @var{nr}, @var{nc})
1351 Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements come
1352 from @var{M}, which must have the same number of elements as the new
1353 matrix, copying elements from @var{M} to the new matrix row by row.
1354
1355 @format
1356 @t{RESHAPE(1:12, 1, 12) @result{}
1357    1   2   3   4   5   6   7   8   9  10  11  12
1358 RESHAPE(1:12, 2, 6) @result{}
1359    1   2   3   4   5   6
1360    7   8   9  10  11  12
1361 RESHAPE(1:12, 3, 4) @result{}
1362    1   2   3   4
1363    5   6   7   8
1364    9  10  11  12
1365 RESHAPE(1:12, 4, 3) @result{}
1366    1   2   3
1367    4   5   6
1368    7   8   9
1369   10  11  12}
1370 @end format
1371 @end deffn
1372
1373 @deffn {Matrix Function} T (@var{M})
1374 @deffnx {Matrix Function} TRANSPOS (@var{M})
1375 Returns @var{M} with rows exchanged for columns.
1376
1377 @t{T(@{1, 2, 3@}) @result{} @{1; 2; 3@}} @*
1378 @t{T(@{1; 2; 3@}) @result{} @{1, 2, 3@}}
1379 @end deffn
1380
1381 @deffn {Matrix Function} UNIFORM (@var{nr}, @var{nc})
1382 Returns a @math{@var{nr}@times{}@var{nc}} matrix in which each element
1383 is randomly chosen from a uniform distribution of real numbers between
1384 0 and 1.  Random number generation honors the current seed setting
1385 (@pxref{SET SEED}).
1386
1387 The following example shows one possible output, but of course every
1388 result will be different (given different seeds):
1389
1390 @format
1391 @t{UNIFORM(4, 5)*10 @result{}
1392   7.71  2.99   .21  4.95  6.34
1393   4.43  7.49  8.32  4.99  5.83
1394   2.25   .25  1.98  7.09  7.61
1395   2.66  1.69  2.64   .88  1.50}
1396 @end format
1397 @end deffn
1398
1399 @node Matrix Minimum and Maximum and Sum Functions
1400 @subsubsection Minimum, Maximum, and Sum Functions
1401
1402 @deffn {Matrix Function} CMIN (@var{M})
1403 @deffnx {Matrix Function} CMAX (@var{M})
1404 @deffnx {Matrix Function} CSUM (@var{M})
1405 @deffnx {Matrix Function} CSSQ (@var{M})
1406 Returns a row vector with the same number of columns as @var{M}, in
1407 which each element is the minimum, maximum, sum, or sum of squares,
1408 respectively, of the elements in the same column of @var{M}.
1409
1410 @t{CMIN(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{1, 2, 3@}} @*
1411 @t{CMAX(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{7, 8, 9@}} @*
1412 @t{CSUM(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{12, 15, 18@}} @*
1413 @t{CSSQ(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{66, 93, 126@}}
1414 @end deffn
1415
1416 @deffn {Matrix Function} MMIN (@var{M})
1417 @deffnx {Matrix Function} MMAX (@var{M})
1418 @deffnx {Matrix Function} MSUM (@var{M})
1419 @deffnx {Matrix Function} MSSQ (@var{M})
1420 Returns the minimum, maximum, sum, or sum of squares, respectively, of
1421 the elements of @var{M}.
1422
1423 @t{MMIN(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} 1} @*
1424 @t{MMAX(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} 9} @*
1425 @t{MSUM(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} 45} @*
1426 @t{MSSQ(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} 285}
1427 @end deffn
1428
1429 @deffn {Matrix Function} RMIN (@var{M})
1430 @deffnx {Matrix Function} RMAX (@var{M})
1431 @deffnx {Matrix Function} RSUM (@var{M})
1432 @deffnx {Matrix Function} RSSQ (@var{M})
1433 Returns a column vector with the same number of rows as @var{M}, in
1434 which each element is the minimum, maximum, sum, or sum of squares,
1435 respectively, of the elements in the same row of @var{M}.
1436
1437 @t{RMIN(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{1; 4; 7@}} @*
1438 @t{RMAX(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{3; 6; 9@}} @*
1439 @t{RSUM(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{6; 15; 24@}} @*
1440 @t{RSSQ(@{1, 2, 3; 4, 5, 6; 7, 8, 9@} @result{} @{14; 77; 194@}}
1441 @end deffn
1442
1443 @deffn {Matrix Function} SSCP (@var{M})
1444 Returns @math{@var{M}^T @times{} @var{M}}.
1445
1446 @t{SSCP(@{1, 2, 3; 4, 5, 6@}) @result{} @{17, 22, 27; 22, 29, 36; 27, 36, 45@}}
1447 @end deffn
1448
1449 @deffn {Matrix Function} TRACE (@var{M})
1450 Returns the sum of the elements along @var{M}'s main diagonal,
1451 equivalent to @code{MSUM(DIAG(@var{M}))}.
1452
1453 @t{TRACE(MDIAG(1:5)) @result{} 15}
1454 @end deffn
1455
1456 @node Matrix Property Functions
1457 @subsubsection Matrix Property Functions
1458
1459 @deffn {Matrix Function} NROW (@var{M})
1460 @deffnx {Matrix Function} NCOL (@var{M})
1461 Returns the number of row or columns, respectively, in @var{M}.
1462
1463 @format
1464 @t{NROW(@{1, 0; -2, -3; 3, 3@}) @result{} 3
1465 NROW(1:5) @result{} 1
1466
1467 NCOL(@{1, 0; -2, -3; 3, 3@}) @result{} 2
1468 NCOL(1:5) @result{} 5}
1469 @end format
1470 @end deffn
1471
1472 @deffn {Matrix Function} DIAG (@var{M})
1473 Returns a column vector containing a copy of @var{M}'s main diagonal.
1474 The vector's length is the lesser of @code{NCOL(@var{M})} and
1475 @code{NROW(@var{M})}.
1476
1477 @t{DIAG(@{1, 0; -2, -3; 3, 3@}) @result{} @{1; -3@}}
1478 @end deffn
1479
1480 @node Matrix Rank Ordering Functions
1481 @subsubsection Matrix Rank Ordering Functions
1482
1483 The @code{GRADE} and @code{RANK} functions each take a matrix @var{M}
1484 and return a matrix @var{r} with the same dimensions.  Each element in
1485 @var{r} ranges between 1 and the number of elements @var{n} in
1486 @var{M}, inclusive.  When the elements in @var{M} all have unique
1487 values, both of these functions yield the same results: the smallest
1488 element in @var{M} corresponds to value 1 in @var{r}, the next
1489 smallest to 2, and so on, up to the largest to @var{n}.  When multiple
1490 elements in @var{M} have the same value, these functions use different
1491 rules for handling the ties.
1492
1493 @deffn {Matrix Function} GRADE (@var{M})
1494 Returns a ranking of @var{M}, turning duplicate values into sequential
1495 ranks.  The returned matrix always contains each of the integers 1
1496 through the number of elements in the matrix exactly once.
1497
1498 @t{GRADE(@{1, 0, 3; 3, 1, 2; 3, 0, 5@})} @result{} @t{@{3, 1, 6; 7, 4, 5; 8, 2, 9@}}
1499 @end deffn
1500
1501 @deffn {Matrix Function} RNKORDER (@var{M})
1502 Returns a ranking of @var{M}, turning duplicate values into the mean
1503 of their sequential ranks.
1504
1505 @t{RNKORDER(@{1, 0, 3; 3, 1, 2; 3, 0, 5@})} @*@w{ }@result{} @t{@{3.5, 1.5, 7; 7, 3.5, 5; 7, 1.5, 9@}}
1506 @end deffn
1507
1508 @noindent
1509 One may use @code{GRADE} to sort a vector:
1510
1511 @example
1512 COMPUTE v(GRADE(v))=v.   /* Sort v in ascending order.
1513 COMPUTE v(GRADE(-v))=v.  /* Sort v in descending order.
1514 @end example
1515
1516 @node Matrix Algebra Functions
1517 @subsubsection Matrix Algebra Functions
1518
1519 @deffn {Matrix Function} CHOL (@var{M})
1520 Matrix @var{M} must be an @math{@var{n}@times{}@var{n}} symmetric
1521 positive-definite matrix.  Returns an @math{@var{n}@times{}@var{n}}
1522 matrix @var{B} such that @math{@var{B}^T@times{}@var{B}=@var{M}}.
1523
1524 @format
1525 @t{CHOL(@{4, 12, -16; 12, 37, -43; -16, -43, 98@}) @result{}
1526   2  6 -8
1527   0  1  5
1528   0  0  3}
1529 @end format
1530 @end deffn
1531
1532 @deffn {Matrix Function} DESIGN (@var{M})
1533 Returns a design matrix for @var{M}.  The design matrix has the same
1534 number of rows as @var{M}.  Each column @var{c} in @var{M}, from left
1535 to right, yields a group of columns in the output.  For each unique
1536 value @var{v} in @var{c}, from top to bottom, add a column to the
1537 output in which @var{v} becomes 1 and other values become 0.
1538
1539 @pspp{} issues a warning if a column only contains a single unique value.
1540
1541 @format
1542 @t{DESIGN(@{1; 2; 3@}) @result{} @{1, 0, 0; 0, 1, 0; 0, 0, 1@}}
1543 @t{DESIGN(@{5; 8; 5@}) @result{} @{1, 0; 0, 1; 1, 0@}}
1544 @t{DESIGN(@{1, 5; 2, 8; 3, 5@})}
1545  @result{} @t{@{1, 0, 0, 1, 0; 0, 1, 0, 0, 1; 0, 0, 1, 1, 0@}}
1546 @t{DESIGN(@{5; 5; 5@})} @result{} (warning)
1547 @end format
1548 @end deffn
1549
1550 @deffn {Matrix Function} DET (@var{M})
1551 Returns the determinant of square matrix @var{M}.
1552
1553 @t{DET(@{3, 7; 1, -4@}) @result{} -19}
1554 @end deffn
1555
1556 @deffn {Matrix Function} EVAL (@var{M})
1557 @anchor{EVAL}
1558 Returns a column vector containing the eigenvalues of symmetric matrix
1559 @var{M}, sorted in ascending order.
1560
1561 Use @code{CALL EIGEN} (@pxref{CALL EIGEN}) to compute eigenvalues and
1562 eigenvectors of a matrix.
1563
1564 @t{EVAL(@{2, 0, 0; 0, 3, 4; 0, 4, 9@}) @result{} @{11; 2; 1@}}
1565 @end deffn
1566
1567 @deffn {Matrix Function} GINV (@var{M})
1568 Returns the @math{@var{k}@times{}@var{n}} matrix @var{A} that is the
1569 @dfn{generalized inverse} of @math{@var{n}@times{}@var{k}} matrix
1570 @var{M}, defined such that
1571 @math{@var{M}@times{}@var{A}@times{}@var{M}=@var{M}} and
1572 @math{@var{A}@times{}@var{M}@times{}@var{A}=@var{A}}.
1573
1574 @t{GINV(@{1, 2@}) @result{} @{.2; .4@}} (approximately) @*
1575 @t{@{1:9@} * GINV(1:9) * @{1:9@} @result{} @{1:9@}} (approximately)
1576 @end deffn
1577
1578 @deffn {Matrix Function} GSCH (@var{M})
1579 @var{M} must be a @math{@var{n}@times{}@var{m}} matrix, @math{@var{m}
1580 @geq{} @var{n}}, with rank @var{n}.  Returns an
1581 @math{@var{n}@times{}@var{n}} orthonormal basis for @var{M}, obtained
1582 using the Gram-Schmidt process.
1583
1584 @t{GSCH(@{3, 2; 1, 2@}) * SQRT(10) @result{} @{3, -1; 1, 3@}} (approximately)
1585 @end deffn
1586
1587 @deffn {Matrix Function} INV (@var{M})
1588 Returns the @math{@var{n}@times{}@var{n}} matrix @var{A} that is the
1589 inverse of @math{@var{n}@times{}@var{n}} matrix @var{M}, defined such
1590 that @math{@var{M}@times{}@var{A} = @var{A}@times{}@var{M} = I}, where
1591 @var{I} is the identity matrix.  @var{M} must not be singular, that
1592 is, @math{\det(@var{M}) @ne{} 0}.
1593
1594 @t{INV(@{4, 7; 2, 6@}) @result{} @{.6, -.7; -.2, .4@}} (approximately)
1595 @end deffn
1596
1597 @deffn {Matrix Function} KRONEKER (@var{Ma}, @var{Mb})
1598 Returns the @math{@var{pm}@times{}@var{qn}} matrix @var{P} that is the
1599 @dfn{Kroneker product} of @math{@var{m}@times{}@var{n}} matrix
1600 @var{Ma} and @math{@var{p}@times{}@var{q}} matrix @var{Mb}.  One may
1601 view @var{P} as the concatenation of multiple
1602 @math{@var{p}@times{}@var{q}} blocks, each of which is the scalar
1603 product of @var{Mb} by a different element of @var{Ma}.  For example,
1604 when @code{A} is a @math{2@times{}2} matrix, @code{KRONEKER(A, B)} is
1605 equivalent to @code{@{A(1,1)*B, A(1,2)*B; A(2,1)*B, A(2,2)*B@}}.
1606
1607 @format
1608 @t{KRONEKER(@{1, 2; 3, 4@}, @{0, 5; 6, 7@}) @result{}
1609    0   5   0  10
1610    6   7  12  14
1611    0  15   0  20
1612   18  21  24  28}
1613 @end format
1614 @end deffn
1615
1616 @deffn {Matrix Function} RANK (@var{M})
1617 Returns the rank of matrix @var{M}, a integer scalar whose value is
1618 the dimension of the vector space spanned by its columns or,
1619 equivalently, by its rows.
1620
1621 @format
1622 @t{RANK(@{1, 0, 1; -2, -3, 1; 3, 3, 0@}) @result{} 2
1623 RANK(@{1, 1, 0, 2; -1, -1, 0, -2@}) @result{} 1
1624 RANK(@{1, -1; 1, -1; 0, 0; 2, -2@}) @result{} 1
1625 RANK(@{1, 2, 1; -2, -3, 1; 3, 5, 0@}) @result{} 2
1626 RANK(@{1, 0, 2; 2, 1, 0; 3, 2, 1@}) @result{} 3}
1627 @end format
1628 @end deffn
1629
1630 @deffn {Matrix Function} SOLVE (@var{Ma}, @var{Mb})
1631 @var{Ma} must be an @math{@var{n}@times{}@var{n}} matrix, with
1632 @math{\det(@var{Ma}) @ne{} 0}, and @var{Mb} an
1633 @math{@var{n}@times{}@var{k}} matrix.  Returns an
1634 @math{@var{n}@times{}@var{k}} matrix @var{X} such that @math{@var{Ma}
1635 @times{} @var{X} = @var{Mb}}.
1636
1637 All of the following examples show approximate results:
1638
1639 @format
1640 @t{SOLVE(@{2, 3; 4, 9@}, @{6, 2; 15, 5@}) @result{}
1641    1.50    .50
1642    1.00    .33
1643 SOLVE(@{1, 3, -2; 3, 5, 6; 2, 4, 3@}, @{5; 7; 8@}) @result{}
1644  -15.00
1645    8.00
1646    2.00
1647 SOLVE(@{2, 1, -1; -3, -1, 2; -2, 1, 2@}, @{8; -11; -3@}) @result{}
1648    2.00
1649    3.00
1650   -1.00}
1651 @end format
1652 @end deffn
1653
1654 @deffn {Matrix Function} SVAL (@var{M})
1655 @anchor{SVAL}
1656
1657 Given @math{@var{n}@times{}@var{k}} matrix @var{M}, returns a
1658 @math{\min(@var{n},@var{k})}-element column vector containing the
1659 singular values of @var{M} in descending order.
1660
1661 Use @code{CALL SVD} (@pxref{CALL SVD}) to compute the full singular
1662 value decomposition of a matrix.
1663
1664 @format
1665 @t{SVAL(@{1, 1; 0, 0@}) @result{} @{1.41; .00@}
1666 SVAL(@{1, 0, 1; 0, 1, 1; 0, 0, 0@}) @result{} @{1.73; 1.00; .00@}
1667 SVAL(@{2, 4; 1, 3; 0, 0; 0, 0@}) @result{} @{5.46; .37@}}
1668 @end format
1669 @end deffn
1670
1671 @deffn {Matrix Function} SWEEP (@var{M}, @var{nk})
1672 Given @math{@var{r}@times{}@var{c}} matrix @var{M} and integer scalar
1673 @math{k = @var{nk}} such that @math{1 @leq{} k @leq{}
1674 \min(@var{r},@var{c})}, returns the @math{@var{r}@times{}@var{c}}
1675 sweep matrix @var{A}.
1676
1677 If @math{@var{M}_{kk} @ne{} 0}, then:
1678
1679 @display
1680 @math{@var{A}_{kk} = 1/@var{M}_{kk}},
1681 @math{@var{A}_{ik} = -@var{M}_{ik}/@var{M}_{kk} @r{for} i @ne{} k},
1682 @math{@var{A}_{kj} = @var{M}_{kj}/@var{M}_{kk} @r{for} j @ne{} k, @r{and}}
1683 @math{@var{A}_{ij} = @var{M}_{ij} - @var{M}_{ik}@var{M}_{kj}/@var{M}_{kk} @r{for} i @ne{} k @r{and} j @ne{} k}.
1684 @end display
1685
1686 If @math{@var{M}_{kk} = 0}, then:
1687
1688 @display
1689 @math{@var{A}_{ik} = @var{A}_{ki} = 0 @r{and}}
1690 @math{@var{A}_{ij} = @var{M}_{ij}, @r{for} i @ne{} k @r{and} j @ne{} k}.
1691 @end display
1692
1693 Given @t{M = @{0, 1, 2; 3, 4, 5; 6, 7, 8@}}, then (approximately):
1694
1695 @format
1696 @t{SWEEP(M, 1) @result{}
1697    .00   .00   .00
1698    .00  4.00  5.00
1699    .00  7.00  8.00
1700 SWEEP(M, 2) @result{}
1701   -.75  -.25   .75
1702    .75   .25  1.25
1703    .75 -1.75  -.75
1704 SWEEP(M, 3) @result{}
1705  -1.50  -.75  -.25
1706   -.75  -.38  -.63
1707    .75   .88   .13}
1708 @end format
1709 @end deffn
1710
1711 @node Matrix Statistical Distribution Functions
1712 @subsubsection Matrix Statistical Distribution Functions
1713
1714 The matrix language can calculate several functions of standard
1715 statistical distributions using the same syntax and semantics as in
1716 @pspp{} transformation expressions.  @xref{Statistical Distribution
1717 Functions}, for details.
1718
1719 The matrix language extends the PDF, CDF, SIG, IDF, NPDF, and NCDF
1720 functions by allowing the first parameters to each of these functions
1721 to be a vector or matrix with any dimensions.  In addition,
1722 @code{CDF.BVNOR} and @code{PDF.BVNOR} allow either or both of their
1723 first two parameters to be vectors or matrices; if both are non-scalar
1724 then they must have the same dimensions.  In each case, the result is
1725 a matrix or vector with the same dimensions as the input populated
1726 with elementwise calculations.
1727
1728 @node Matrix EOF Function
1729 @subsubsection EOF Function
1730
1731 This function works with files being used on the @code{READ} statement.
1732
1733 @deffn {Matrix Function} EOF (@var{file})
1734 @anchor{EOF Matrix Function}
1735
1736 Given a file handle or file name @var{file}, returns an integer scalar
1737 1 if the last line in the file has been read or 0 if more lines are
1738 available.  Determining this requires attempting to read another line,
1739 which means that @code{REREAD} on the next @code{READ} command
1740 following @code{EOF} on the same file will be ineffective.
1741 @end deffn
1742
1743 The @code{EOF} function gives a matrix program the flexibility to read
1744 a file with text data without knowing the length of the file in
1745 advance.  For example, the following program will read all the lines
1746 of data in @file{data.txt}, each consisting of three numbers, as rows
1747 in matrix @code{data}:
1748
1749 @verbatim
1750 MATRIX.
1751 COMPUTE data={}.
1752 LOOP IF NOT EOF('data.txt').
1753   READ row/FILE='data.txt'/FIELD=1 TO 1000/SIZE={1,3}.
1754   COMPUTE data={data; row}.
1755 END LOOP.
1756 PRINT data.
1757 END MATRIX.
1758
1759 @end verbatim
1760
1761 @node Matrix COMPUTE Command
1762 @subsection The @code{COMPUTE} Command
1763
1764 @display
1765 @t{COMPUTE} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]@t{=}@i{expression}@t{.}
1766 @end display
1767
1768 The @code{COMPUTE} command evaluates an expression and assigns the
1769 result to a variable or a submatrix of a variable.  Assigning to a
1770 submatrix uses the same syntax as the index operator (@pxref{Matrix
1771 Index Operator}).
1772
1773 @node Matrix CALL command
1774 @subsection The @code{CALL} Command
1775
1776 A matrix function returns a single result.  The @code{CALL} command
1777 implements procedures, which take a similar syntactic form to
1778 functions but yield results by modifying their arguments rather than
1779 returning a value.
1780
1781 Output arguments to a @code{CALL} procedure must be a single variable
1782 name.
1783
1784 The following procedures are implemented via @code{CALL} to allow them
1785 to return multiple results.  For these procedures, the output
1786 arguments need not name existing variables; if they do, then their
1787 previous values are replaced:
1788
1789 @table @asis
1790 @item @t{CALL EIGEN(@var{M}, @var{evec}, @var{eval})}
1791 @anchor{CALL EIGEN}
1792
1793 Computes the eigenvalues and eigenvector of symmetric
1794 @math{@var{n}@times{}@var{n}} matrix @var{M}.  Assigns the
1795 eigenvectors of @var{M} to the columns of
1796 @math{@var{n}@times{}@var{n}} matrix @var{evec} and the eigenvalues in
1797 descending order to @var{n}-element column vector @var{eval}.
1798
1799 Use the @code{EVAL} function (@pxref{EVAL}) to compute just the
1800 eigenvalues of a symmetric matrix.
1801
1802 For example, the following matrix language commands:
1803 @example
1804 CALL EIGEN(@{1, 0; 0, 1@}, evec, eval).
1805 PRINT evec.
1806 PRINT eval.
1807
1808 CALL EIGEN(@{3, 2, 4; 2, 0, 2; 4, 2, 3@}, evec2, eval2).
1809 PRINT evec2.
1810 PRINT eval2.
1811 @end example
1812
1813 @noindent
1814 yield this output:
1815
1816 @example
1817 evec
1818   1  0
1819   0  1
1820
1821 eval
1822   1
1823   1
1824
1825 evec2
1826   -.6666666667   .0000000000   .7453559925
1827   -.3333333333  -.8944271910  -.2981423970
1828   -.6666666667   .4472135955  -.5962847940
1829
1830 eval2
1831   8.0000000000
1832  -1.0000000000
1833  -1.0000000000
1834 @end example
1835   
1836 @item @t{CALL SVD(@var{M}, @var{U}, @var{S}, @var{V})}
1837 @anchor{CALL SVD}
1838
1839 Computes the singular value decomposition of
1840 @math{@var{n}@times{}@var{k}} matrix @var{M}, assigning @var{S} a
1841 @math{@var{n}@times{}@var{k}} diagonal matrix and to @var{U} and
1842 @var{V} unitary @math{@var{k}@times{}@var{k}} matrices such that
1843 @math{@var{M} = @var{U}@times{}@var{S}@times{}@var{V}^T}.  The main
1844 diagonal of @var{Q} contains the singular values of @var{M}.
1845
1846 Use the @code{SVAL} function (@pxref{SVAL}) to compute just the
1847 singular values of a matrix.
1848
1849 For example, the following matrix program:
1850
1851 @example
1852 CALL SVD(@{3, 2, 2; 2, 3, -2@}, u, s, v).
1853 PRINT (u * s * T(v))/FORMAT F5.1.
1854 @end example
1855
1856 @noindent
1857 yields this output:
1858
1859 @example
1860 (u * s * T(v))
1861    3.0   2.0   2.0
1862    2.0   3.0  -2.0
1863 @end example
1864 @end table
1865
1866 The final procedure is implemented via @code{CALL} to allow it to
1867 modify a matrix instead of returning a modified version.  For this
1868 procedure, the output argument must name an existing variable.
1869
1870 @table @asis
1871 @item @t{CALL SETDIAG(@var{M}, @var{V})}
1872 @anchor{CALL SETDIAG}
1873
1874 Replaces the main diagonal of @math{@var{n}@times{}@var{p}} matrix
1875 @var{M} by the contents of @var{k}-element vector @var{V}.  If
1876 @math{@var{k} = 1}, so that @var{V} is a scalar, replaces all of the
1877 diagonal elements of @var{M} by @var{V}.  If @math{@var{k} <
1878 \min(@var{n},@var{p})}, only the upper @var{k} diagonal elements are
1879 replaced; if @math{@var{k} > \min(@var{n},@var{p})}, then the 
1880 extra elements of @var{V} are ignored.
1881
1882 Use the @code{MDIAG} function (@pxref{MDIAG}) to construct a new
1883 matrix with a specified main diagonal.
1884
1885 For example, this matrix program:
1886
1887 @example
1888 COMPUTE x=@{1, 2, 3; 4, 5, 6; 7, 8, 9@}.
1889 CALL SETDIAG(x, 10).
1890 PRINT x.
1891 @end example
1892
1893 @noindent
1894 outputs the following:
1895
1896 @example
1897 x
1898   10   2   3
1899    4  10   6
1900    7   8  10
1901 @end example
1902 @end table
1903
1904 @node Matrix PRINT Command
1905 @subsection The @code{PRINT} Command
1906
1907 @display
1908 @t{PRINT} [@i{expression}]
1909       [@t{/FORMAT}@t{=}@i{format}]
1910       [@t{/TITLE}@t{=}@i{title}]
1911       [@t{/SPACE}@t{=}@{@t{NEWPAGE} @math{|} @i{n}@}]
1912       [@{@t{/RLABELS}@t{=}@i{string}@dots{} @math{|} @t{/RNAMES}@t{=}@i{expression}@}]
1913       [@{@t{/CLABELS}@t{=}@i{string}@dots{} @math{|} @t{/CNAMES}@t{=}@i{expression}@}]@t{.}
1914 @end display
1915
1916 The @code{PRINT} command is commonly used to display a matrix.  It
1917 evaluates the restricted @var{expression}, if present, and outputs it
1918 either as text or a pivot table, depending on the setting of
1919 @code{MDISPLAY} (@pxref{SET MDISPLAY}).
1920
1921 Use the @code{FORMAT} subcommand to specify a format, such as
1922 @code{F8.2}, for displaying the matrix elements.  @code{FORMAT} is
1923 optional for numerical matrices.  When it is omitted, @pspp{} chooses
1924 how to format entries automatically using @var{m}, the magnitude of
1925 the largest-magnitude element in the matrix to be displayed:
1926
1927 @enumerate
1928 @item
1929 If @math{@var{m} < 10^{11}} and the matrix's elements are all
1930 integers, @pspp{} chooses the narrowest @code{F} format that fits
1931 @var{m} plus a sign.  For example, if the matrix is @t{@{1:10@}}, then
1932 @math{m = 10}, which fits in 3 columns with room for a sign, the
1933 format is @code{F3.0}.
1934
1935 @item
1936 Otherwise, if @math{@var{m} @geq{} 10^9} or @math{@var{m} @leq{}
1937 10^{-4}}, @pspp{} scales all of the numbers in the matrix by
1938 @math{10^x}, where @var{x} is the exponent that would be used to
1939 display @var{m} in scientific notation.  For example, for
1940 @math{@var{m} = 5.123@times{}10^{20}}, the scale factor is
1941 @math{10^{20}}.  @pspp{} displays the scaled values in format
1942 @code{F13.10} and notes the scale factor in the output.
1943
1944 @item
1945 Otherwise, @pspp{} displays the matrix values, without scaling, in
1946 format @code{F13.10}.
1947 @end enumerate
1948
1949 The optional @code{TITLE} subcommand specifies a title for the output
1950 text or table, as a quoted string.  When it is omitted, the syntax of
1951 the matrix expression is used as the title.
1952
1953 Use the @code{SPACE} subcommand to request extra space above the
1954 matrix output.  With a numerical argument, it adds the specified
1955 number of lines of blank space above the matrix.  With @code{NEWPAGE}
1956 as an argument, it prints the matrix at the top of a new page.  The
1957 @code{SPACE} subcommand has no effect when a matrix is output as a
1958 pivot table.
1959
1960 The @code{RLABELS} and @code{RNAMES} subcommands, which are mutually
1961 exclusive, can supply a label to accompany each row in the output.
1962 With @code{RLABELS}, specify the labels as comma-separated strings or
1963 other tokens.  With @code{RNAMES}, specify a single expression that
1964 evaluates to a vector of strings.  Either way, if there are more
1965 labels than rows, the extra labels are ignored, and if there are more
1966 rows than labels, the extra rows are unlabeled.  For output to a pivot
1967 table with @code{RLABELS}, the labels can be any length; otherwise,
1968 the labels are truncated to 8 bytes.
1969
1970 The @code{CLABELS} and @code{CNAMES} subcommands work for labeling
1971 columns as @code{RLABELS} and @code{RNAMES} do for labeling rows.
1972
1973 When the @var{expression} is omitted, @code{PRINT} does not output a
1974 matrix.  Instead, it outputs only the text specified on @code{TITLE},
1975 if any, preceded by any space specified on the @code{SPACE}
1976 subcommand, if any.  Any other subcommands are ignored, and the
1977 command acts as if @code{MDISPLAY} is set to @code{TEXT} regardless of
1978 its actual setting.
1979
1980 The following syntax demonstrates two different ways to label the rows
1981 and columns of a matrix with @code{PRINT}:
1982
1983 @example
1984 MATRIX.
1985 COMPUTE m=@{1, 2, 3; 4, 5, 6; 7, 8, 9@}.
1986 PRINT m/RLABELS=a, b, c/CLABELS=x, y, z.
1987
1988 COMPUTE rlabels=@{"a", "b", "c"@}.
1989 COMPUTE clabels=@{"x", "y", "z"@}.
1990 PRINT m/RNAMES=rlabels/CNAMES=clabels.
1991 END MATRIX.
1992 @end example
1993
1994 @noindent
1995 With @code{MDISPLAY=TEXT} (the default), this program outputs the
1996 following (twice):
1997
1998 @example
1999 m
2000                 x        y        z
2001 a               1        2        3
2002 b               4        5        6
2003 c               7        8        9
2004 @end example
2005
2006 @noindent
2007 With @samp{SET MDISPLAY=TABLES.} added above @samp{MATRIX.}, the
2008 output becomes the following (twice):
2009
2010 @psppoutput {matrix-print}
2011
2012 @node Matrix DO IF Command
2013 @subsection The @code{DO IF} Command
2014
2015 @display
2016 @t{DO IF} @i{expression}@t{.}
2017   @dots{}@i{matrix commands}@dots{}
2018 [@t{ELSE IF} @i{expression}@t{.}
2019   @dots{}@i{matrix commands}@dots{}]@dots{}
2020 [@t{ELSE}
2021   @dots{}@i{matrix commands}@dots{}]
2022 @t{END IF}@t{.}
2023 @end display
2024
2025 A @code{DO IF} command evaluates its expression argument.  If the
2026 @code{DO IF} expression evaluates to true, then @pspp{} executes the
2027 associated commands.  Otherwise, @pspp{} evaluates the expression on
2028 each @code{ELSE IF} clause (if any) in order, and executes the
2029 commands associated with the first one that yields a true value.
2030 Finally, if the @code{DO IF} and all the @code{ELSE IF} expressions
2031 all evaluate to false, @pspp{} executes the commands following the
2032 @code{ELSE} clause (if any).
2033
2034 Each expression on @code{DO IF} and @code{ELSE IF} must evaluate to a
2035 scalar.  Positive scalars are considered to be true, and scalars that
2036 are zero or negative are considered to be false.
2037
2038 The following matrix language fragment sets @samp{b} to the term
2039 following @samp{a} in the
2040 @url{https://en.wikipedia.org/wiki/Juggler_sequence, Juggler
2041 sequence}:
2042
2043 @example
2044 DO IF MOD(a, 2) = 0.
2045   COMPUTE b = TRUNC(a &** (1/2)).
2046 ELSE.
2047   COMPUTE b = TRUNC(a &** (3/2)).
2048 END IF.
2049 @end example
2050
2051 @node Matrix LOOP and BREAK Commands
2052 @subsection The @code{LOOP} and @code{BREAK} Commands
2053
2054 @display
2055 @t{LOOP} [@i{var}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{step}]] [@t{IF} @i{expression}]@t{.}
2056   @dots{}@i{matrix commands}@dots{}
2057 @t{END LOOP} [@t{IF} @i{expression}]@t{.}
2058
2059 @t{BREAK}@t{.}
2060 @end display
2061
2062 The @code{LOOP} command executes a nested group of matrix commands,
2063 called the loop's @dfn{body}, repeatedly.  It has three optional
2064 clauses that control how many times the loop body executes.
2065 Regardless of these clauses, the global @code{MXLOOPS} setting, which
2066 defaults to 40, also limits the number of iterations of a loop.  To
2067 iterate more times, raise the maximum with @code{SET MXLOOPS} outside
2068 of the @code{MATRIX} command (@pxref{SET MXLOOPS}).
2069
2070 The optional index clause causes @var{var} to be assigned successive
2071 values on each trip through the loop: first @var{first}, then
2072 @math{@var{first} + @var{step}}, then @math{@var{first} + 2 @times{}
2073 @var{step}}, and so on.  The loop ends when @math{@var{var} >
2074 @var{last}}, for positive @var{step}, or @math{@var{var} <
2075 @var{last}}, for negative @var{step}.  If @var{step} is not specified,
2076 it defaults to 1.  All the index clause expressions must evaluate to
2077 scalars, and non-integers are rounded toward zero.  If @var{step}
2078 evaluates as zero (or rounds to zero), then the loop body never
2079 executes.
2080
2081 The optional @code{IF} on @code{LOOP} is evaluated before each
2082 iteration through the loop body.  If its expression, which must
2083 evaluate to a scalar, is zero or negative, then the loop terminates
2084 without executing the loop body.
2085
2086 The optional @code{IF} on @code{END LOOP} is evaluated after each
2087 iteration through the loop body.  If its expression, which must
2088 evaluate to a scalar, is zero or negative, then the loop terminates.
2089
2090 The following computes and prints @math{l(n)}, whose value is the
2091 number of steps in the
2092 @url{https://en.wikipedia.org/wiki/Juggler_sequence, Juggler sequence}
2093 for @math{n}, for @math{n} from 2 to 10 inclusive:
2094
2095 @example
2096 COMPUTE l = @{@}.
2097 LOOP n = 2 TO 10.
2098   COMPUTE a = n.
2099   LOOP i = 1 TO 100.
2100     DO IF MOD(a, 2) = 0.
2101       COMPUTE a = TRUNC(a &** (1/2)).
2102     ELSE.
2103       COMPUTE a = TRUNC(a &** (3/2)).
2104     END IF.
2105   END LOOP IF a = 1.
2106   COMPUTE l = @{l; i@}.
2107 END LOOP.
2108 PRINT l.
2109 @end example
2110
2111 @menu
2112 * Matrix BREAK Command::
2113 @end menu
2114
2115 @node Matrix BREAK Command
2116 @subsubsection The @code{BREAK} Command
2117
2118 The @code{BREAK} command may be used inside a loop body, ordinarily
2119 within a @code{DO IF} command.  If it is executed, then the loop
2120 terminates immediately, jumping to the command just following
2121 @code{END LOOP}.  When multiple @code{LOOP} commands nest,
2122 @code{BREAK} terminates the innermost loop.
2123
2124 The following example is a revision of the one above that shows how
2125 @code{BREAK} could substitute for the index and @code{IF} clauses on
2126 @code{LOOP} and @code{END LOOP}:
2127
2128 @example
2129 COMPUTE l = @{@}.
2130 LOOP n = 2 TO 10.
2131   COMPUTE a = n.
2132   COMPUTE i = 1.
2133   LOOP.
2134     DO IF MOD(a, 2) = 0.
2135       COMPUTE a = TRUNC(a &** (1/2)).
2136     ELSE.
2137       COMPUTE a = TRUNC(a &** (3/2)).
2138     END IF.
2139     DO IF a = 1.
2140       BREAK.
2141     END IF.
2142     COMPUTE i = i + 1.
2143   END LOOP.
2144   COMPUTE l = @{l; i@}.
2145 END LOOP.
2146 PRINT l.
2147 @end example
2148
2149 @node Matrix READ and WRITE Commands
2150 @subsection The @code{READ} and @code{WRITE} Commands
2151
2152 The @code{READ} and @code{WRITE} commands perform matrix input and
2153 output with text files.  They share the following syntax for
2154 specifying how data is divided among input lines:
2155
2156 @display
2157 @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
2158 [@t{/FORMAT}@t{=}@i{format}]
2159 @end display
2160
2161 Both commands require the @code{FIELD} subcommand.  It specifies the
2162 range of columns, from @var{first} to @var{last}, inclusive, that the
2163 data occupies on each line of the file.  The leftmost column is column
2164 1.  The columns must be literal numbers, not expressions.  To use
2165 entire lines, even if they might be very long, specify a column range
2166 such as @code{1 TO 100000}.
2167
2168 The @code{FORMAT} subcommand is optional for numerical matrices.  For
2169 string matrix input and output, specify an @code{A} format.  In
2170 addition to @code{FORMAT}, the optional @code{BY} specification on
2171 @code{FIELD} determine the meaning of each text line:
2172
2173 @itemize @bullet
2174 @item
2175 With neither @code{BY} nor @code{FORMAT}, the numbers in the text file
2176 are in @code{F} format separated by spaces or commas.  For
2177 @code{WRITE}, @pspp{} uses as many digits of precision as needed to
2178 accurately represent the numbers in the matrix.
2179
2180 @item
2181 @code{BY @i{width}} divides the input area into fixed-width fields
2182 with the given @i{width}.  The input area must be a multiple of
2183 @i{width} columns wide.  Numbers are read or written as
2184 @code{F@i{width}.0} format.
2185
2186 @item
2187 @code{FORMAT=@i{count}F} divides the input area into @i{count}
2188 equal-width fields per line.  The input area must be a multiple of
2189 @i{count} columns wide.  Another format type may be substituted for
2190 @code{F}.
2191
2192 @item
2193 @code{FORMAT=F@i{w}}[@code{.@i{d}}] divides the input area into fixed-width
2194 fields with width @i{w}.  The input area must be a multiple of @i{w}
2195 columns wide.  Another format type may be substituted for @code{F}.
2196 The @code{READ} command disregards @i{d}.
2197
2198 @item
2199 @code{FORMAT=F} specifies format @code{F} without indicating a field
2200 width.  Another format type may be substituted for @code{F}.  The
2201 @code{WRITE} command accepts this form, but it has no effect unless
2202 @code{BY} is also used to specify a field width.
2203 @end itemize
2204
2205 If @code{BY} and @code{FORMAT} both specify or imply a field width,
2206 then they must indicate the same field width.
2207
2208 @node Matrix READ Command
2209 @subsubsection The @code{READ} Command
2210
2211 @display
2212 @t{READ} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]
2213      [@t{/FILE}@t{=}@i{file}]
2214      @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
2215      [@t{/FORMAT}@t{=}@i{format}]
2216      [@t{/SIZE}@t{=}@i{expression}]
2217      [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{SYMMETRIC}@}]
2218      [@t{/REREAD}]@t{.}
2219 @end display
2220
2221 The @code{READ} command reads from a text file into a matrix variable.
2222 Specify the target variable just after the command name, either just a
2223 variable name to create or replace an entire variable, or a variable
2224 name followed by an indexing expression to replace a submatrix of an
2225 existing variable.
2226
2227 The @code{FILE} subcommand is required in the first @code{READ}
2228 command that appears within @code{MATRIX}.  It specifies the text file
2229 to be read, either as a file name in quotes or a file handle
2230 previously declared on @code{FILE HANDLE} (@pxref{FILE HANDLE}).
2231 Later @code{READ} commands (in syntax order) use the previous
2232 referenced file if @code{FILE} is omitted.
2233
2234 The @code{FIELD} and @code{FORMAT} subcommands specify how input lines
2235 are interpreted.  @code{FIELD} is required, but @code{FORMAT} is
2236 optional.  @xref{Matrix READ and WRITE Commands}, for details.
2237
2238 The @code{SIZE} subcommand is required for reading into an entire
2239 variable.  Its restricted expression argument should evaluate to a
2240 2-element vector @code{@{@var{n},@w{ }@var{m}@}} or
2241 @code{@{@var{n};@w{ }@var{m}@}}, which indicates a
2242 @math{@var{n}@times{}@var{m}} matrix destination.  A scalar @var{n} is
2243 also allowed and indicates a @math{@var{n}@times{}1} column vector
2244 destination.  When the destination is a submatrix, @code{SIZE} is
2245 optional, and if it is present then it must match the size of the
2246 submatrix.
2247
2248 By default, or with @code{MODE=RECTANGULAR}, the command reads an
2249 entry for every row and column.  With @code{MODE=SYMMETRIC}, the
2250 command reads only the entries on and below the matrix's main
2251 diagonal, and copies the entries above the main diagonal from the
2252 corresponding symmetric entries below it.  Only square matrices
2253 may use @code{MODE=SYMMETRIC}.
2254
2255 Ordinarily, each @code{READ} command starts from a new line in the
2256 text file.  Specify the @code{REREAD} subcommand to instead start from
2257 the last line read by the previous @code{READ} command.  This has no
2258 effect for the first @code{READ} command to read from a particular
2259 file.  It is also ineffective just after a command that uses the
2260 @code{EOF} matrix function (@pxref{EOF Matrix Function}) on a
2261 particular file, because @code{EOF} has to try to read the next line
2262 from the file to determine whether the file contains more input.
2263
2264 @subsubheading Example 1: Basic Use
2265
2266 The following matrix program reads the same matrix @code{@{1, 2, 4; 2,
2267 3, 5; 4, 5, 6@}} into matrix variables @code{v}, @code{w}, and
2268 @code{x}:
2269
2270 @example
2271 READ v /FILE='input.txt' /FIELD=1 TO 100 /SIZE=@{3, 3@}.
2272 READ w /FIELD=1 TO 100 /SIZE=@{3; 3@} /MODE=SYMMETRIC.
2273 READ x /FIELD=1 TO 100 BY 1/SIZE=@{3, 3@} /MODE=SYMMETRIC.
2274 @end example
2275
2276 @noindent
2277 given that @file{input.txt} contains the following:
2278
2279 @example
2280 1, 2, 4
2281 2, 3, 5
2282 4, 5, 6
2283 1
2284 2 3
2285 4 5 6
2286 1
2287 23
2288 456
2289 @end example
2290
2291 The @code{READ} command will read as many lines of input as needed for
2292 a particular row, so it's also acceptable to break any of the lines
2293 above into multiple lines.  For example, the first line @code{1, 2, 4}
2294 could be written with a line break following either or both commas.
2295
2296 @subsubheading Example 2: Reading into a Submatrix
2297
2298 The following reads a @math{5@times{}5} matrix from @file{input2.txt},
2299 reversing the order of the rows:
2300
2301 @example
2302 COMPUTE m = MAKE(5, 5, 0).
2303 LOOP r = 5 TO 1 BY -1.
2304   READ m(r, :) /FILE='input2.txt' /FIELD=1 TO 100.
2305 END LOOP.
2306 @end example
2307
2308 @subsubheading Example 3: Using @code{REREAD}
2309
2310 Suppose each of the 5 lines in a file @file{input3.txt} starts with an
2311 integer @var{count} followed by @var{count} numbers, e.g.:
2312
2313 @example
2314 1 5
2315 3 1 2 3
2316 5 6 -1 2 5 1
2317 2 8 9
2318 3 1 3 2
2319 @end example
2320
2321 @noindent
2322 Then, the following reads this file into a matrix @code{m}:
2323
2324 @example
2325 COMPUTE m = MAKE(5, 5, 0).
2326 LOOP i = 1 TO 5.
2327   READ count /FILE='input3.txt' /FIELD=1 TO 1 /SIZE=1.
2328   READ m(i, 1:count) /FIELD=3 TO 100 /REREAD.
2329 END LOOP.
2330 @end example
2331
2332 @node Matrix WRITE Command
2333 @subsubsection The @code{WRITE} Command
2334
2335 @display
2336 @t{WRITE} @i{expression}
2337       [@t{/OUTFILE}@t{=}@i{file}]
2338       @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
2339       [@t{/FORMAT}@t{=}@i{format}]
2340       [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{TRIANGULAR}@}]
2341       [@t{/HOLD}]@t{.}
2342 @end display
2343
2344 The @code{WRITE} command evaluates @i{expression} and writes its value
2345 to a text file in a specified format.  Write the expression to
2346 evaluate just after the command name.
2347
2348 The @code{OUTFILE} subcommand is required in the first @code{WRITE}
2349 command that appears within @code{MATRIX}.  It specifies the text file
2350 to be written, either as a file name in quotes or a file handle
2351 previously declared on @code{FILE HANDLE} (@pxref{FILE HANDLE}).
2352 Later @code{WRITE} commands (in syntax order) use the previous
2353 referenced file if @code{FILE} is omitted.
2354
2355 The @code{FIELD} and @code{FORMAT} subcommands specify how output
2356 lines are formed.  @code{FIELD} is required, but @code{FORMAT} is
2357 optional.  @xref{Matrix READ and WRITE Commands}, for details.
2358
2359 By default, or with @code{MODE=RECTANGULAR}, the command writes an
2360 entry for every row and column.  With @code{MODE=TRIANGULAR}, the
2361 command writes only the entries on and below the matrix's main
2362 diagonal.  Entries above the diagonal are not written.  Only square
2363 matrices may be written with @code{MODE=TRIANGULAR}.
2364
2365 Ordinarily, each @code{WRITE} command writes complete lines to the
2366 output file.  With @code{HOLD}, the final line written by @code{WRITE}
2367 will be held back for the next @code{WRITE} command to augment.  This
2368 can be useful to write more than one matrix on a single output line.
2369
2370 @subsubheading Example 1: Basic Usage
2371
2372 This matrix program:
2373
2374 @example
2375 WRITE @{1, 2; 3, 4@} /OUTFILE='matrix.txt' /FIELD=1 TO 80.
2376 @end example
2377
2378 @noindent
2379 writes the following to @file{matrix.txt}:
2380
2381 @example
2382  1 2
2383  3 4
2384 @end example
2385
2386 @subsubheading Example 2: Triangular Matrix
2387
2388 This matrix program:
2389
2390 @example
2391 WRITE MAGIC(5) /OUTFILE='matrix.txt' /FIELD=1 TO 80 BY 5 /MODE=TRIANGULAR.
2392 @end example
2393
2394 @noindent
2395 writes the following to @file{matrix.txt}:
2396
2397 @example
2398     17
2399     23    5
2400      4    6   13
2401     10   12   19   21
2402     11   18   25    2    9
2403 @end example
2404
2405 @node Matrix GET Command
2406 @subsection The @code{GET} Command
2407
2408 @display
2409 @t{GET} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]
2410     [@t{/FILE}@t{=}@{@i{file} @math{|} @t{*}@}]
2411     [@t{/VARIABLES}@t{=}@i{variable}@dots{}]
2412     [@t{/NAMES}@t{=}@i{variable}]
2413     [@t{/MISSING}@t{=}@{@t{ACCEPT} @math{|} @t{OMIT} @math{|} @i{number}@}]
2414     [@t{/SYSMIS}@t{=}@{@t{OMIT} @math{|} @i{number}@}]@t{.}
2415 @end display
2416
2417 The @code{READ} command reads numeric data from an SPSS system file,
2418 SPSS/PC+ system file, or SPSS portable file into a matrix variable or
2419 submatrix:
2420
2421 @itemize @bullet
2422 @item
2423 To read data into a variable, specify just its name following
2424 @code{GET}.  The variable need not already exist; if it does, it is
2425 replaced.  The variable will have as many columns as there are
2426 variables specified on the @code{VARIABLES} subcommand and as many
2427 rows as there are cases in the input file.
2428
2429 @item
2430 To read data into a submatrix, specify the name of an existing
2431 variable, followed by an indexing expression, just after @code{GET}.
2432 The submatrix must have as many columns as variables specified on
2433 @code{VARIABLES} and as many rows as cases in the input file.
2434 @end itemize
2435
2436 Specify the name or handle of the file to be read on @code{FILE}.  Use
2437 @samp{*}, or simply omit the @code{FILE} subcommand, to read from the
2438 active file.  Reading from the active file is only permitted if it was
2439 already defined outside @code{MATRIX}.
2440
2441 List the variables to be read as columns in the matrix on the
2442 @code{VARIABLES} subcommand.  The list can use @code{TO} for
2443 collections of variables or @code{ALL} for all variables.  If
2444 @code{VARIABLES} is omitted, all variables are read.  Only numeric
2445 variables may be read.
2446
2447 If a variable is named on @code{NAMES}, then the names of the
2448 variables read as data columns are stored in a string vector within
2449 the given name, replacing any existing matrix variable with that name.
2450 Variable names are truncated to 8 bytes.
2451
2452 The @code{MISSING} and @code{SYSMIS} subcommands control the treatment
2453 of missing values in the input file.  By default, any user- or
2454 system-missing data in the variables being read from the input causes
2455 an error that prevents @code{GET} from executing.  To accept missing
2456 values, specify one of the following settings on @code{MISSING}:
2457
2458 @table @asis
2459 @item @code{ACCEPT}
2460 Accept user-missing values with no change.
2461
2462 By default, system-missing values still yield an error.  Use the
2463 @code{SYSMIS} subcommand to change this treatment:
2464
2465 @table @asis
2466 @item @code{OMIT}
2467 Skip any case that contains a system-missing value.
2468
2469 @item @i{number}
2470 Recode the system-missing value to @i{number}.
2471 @end table
2472
2473 @item @code{OMIT}
2474 Skip any case that contains any user- or system-missing value.
2475
2476 @item @i{number}
2477 Recode all user- and system-missing values to @i{number}.
2478 @end table
2479
2480 The @code{SYSMIS} subcommand has an effect only with
2481 @code{MISSING=ACCEPT}.
2482
2483 @node Matrix SAVE Command
2484 @subsection The @code{SAVE} Command
2485
2486 @display
2487 @t{SAVE} @i{expression}
2488      [@t{/OUTFILE}@t{=}@{@i{file} @math{|} @t{*}@}]
2489      [@t{/VARIABLES}@t{=}@i{variable}@dots{}]
2490      [@t{/NAMES}@t{=}@i{expression}]
2491      [@t{/STRINGS}@t{=}@i{variable}@dots{}]@t{.}
2492 @end display
2493
2494 The @code{SAVE} matrix command evaluates @i{expression} and writes the
2495 resulting matrix to an SPSS system file.  In the system file, each
2496 matrix row becomes a case and each column becomes a variable.
2497
2498 Specify the name or handle of the SPSS system file on the
2499 @code{OUTFILE} subcommand, or @samp{*} to write the output as the new
2500 active file.  The @code{OUTFILE} subcommand is required on the first
2501 @code{SAVE} command, in syntax order, within @code{MATRIX}.  For
2502 @code{SAVE} commands after the first, the default output file is the
2503 same as the previous.
2504
2505 When multiple @code{SAVE} commands write to one destination within a
2506 single @code{MATRIX}, the later commands append to the same output
2507 file.  All the matrices written to the file must have the same number
2508 of columns.  The @code{VARIABLES}, @code{NAMES}, and @code{STRINGS}
2509 subcommands are honored only for the first @code{SAVE} command that
2510 writes to a given file.
2511
2512 By default, @code{SAVE} names the variables in the output file
2513 @code{COL1} through @code{COL@i{n}}.  Use @code{VARIABLES} or
2514 @code{NAMES} to give the variables meaningful names.  The
2515 @code{VARIABLES} subcommand accepts a comma-separated list of variable
2516 names.  Its alternative, @code{NAMES}, instead accepts an expression
2517 that must evaluate to a row or column string vector of names.  The
2518 number of names need not exactly match the number of columns in the
2519 matrix to be written: extra names are ignored; extra columns use
2520 default names.
2521
2522 By default, @code{SAVE} assumes that the matrix to be written is all
2523 numeric.  To write string columns, specify a comma-separated list of
2524 the string columns' variable names on @code{STRINGS}.
2525
2526 @node Matrix MGET Command
2527 @subsection The @code{MGET} Command
2528
2529 @display
2530 @t{MGET} [@t{/FILE}@t{=}@i{file}]
2531      [@t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}]@t{.}
2532 @end display
2533
2534 The @code{MGET} command reads the data from a matrix file
2535 (@pxref{Matrix Files}) into matrix variables.
2536
2537 All of @code{MGET}'s subcommands are optional.  Specify the name or
2538 handle of the matrix file to be read on the @code{FILE} subcommand; if
2539 it is omitted, then the command reads the active file.
2540
2541 By default, @code{MGET} reads all of the data from the matrix file.
2542 Specify a space-delimited list of matrix types on @code{TYPE} to limit
2543 the kinds of data to the one specified:
2544
2545 @table @code
2546 @item COV
2547 Covariance matrix.
2548
2549 @item CORR
2550 Correlation coefficient matrix.
2551
2552 @item MEAN
2553 Vector of means.
2554
2555 @item STDDEV
2556 Vector of standard deviations.
2557
2558 @item N
2559 Vector of case counts.
2560
2561 @item COUNT
2562 Vector of counts.
2563 @end table
2564
2565 @code{MGET} reads the entire matrix file and automatically names,
2566 creates, and populates matrix variables using its contents.  It
2567 constructs the name of each variable by concatenating the following:
2568
2569 @itemize @bullet
2570 @item
2571 A 2-character prefix that identifies the type of the matrix:
2572
2573 @table @code
2574 @item CV
2575 Covariance matrix.
2576
2577 @item CR
2578 Correlation coefficient matrix.
2579
2580 @item MN
2581 Vector of means.
2582
2583 @item SD
2584 Vector of standard deviations.
2585
2586 @item NC
2587 Vector of case counts.
2588
2589 @item CN
2590 Vector of counts.
2591 @end table
2592
2593 @item
2594 If the matrix file has factor variables, @code{F@i{n}}, where @i{n} is
2595 a number identifying a group of factors: @code{F1} for the first
2596 group, @code{F2} for the second, and so on.  This part is omitted for
2597 pooled data (where the factors all have the system-missing value).
2598
2599 @item
2600 If the matrix file has split file variables, @code{S@i{n}}, where
2601 @i{n} is a number identifying a split group: @code{S1} for the first
2602 group, @code{S2} for the second, and so on.
2603 @end itemize
2604
2605 If @code{MGET} chooses the name of an existing variable, it issues a
2606 warning and does not change the variable.
2607
2608 @node Matrix MSAVE Command
2609 @subsection The @code{MSAVE} Command
2610
2611 @display
2612 @t{MSAVE} @i{expression}
2613       @t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}
2614       [@t{/FACTOR}@t{=}@i{expression}]
2615       [@t{/SPLIT}@t{=}@i{expression}]
2616       [@t{/OUTFILE}@t{=}@i{file}]
2617       [@t{/VARIABLES}@t{=}@i{variable}@dots{}]
2618       [@t{/SNAMES}@t{=}@i{variable}@dots{}]
2619       [@t{/FNAMES}@t{=}@i{variable}@dots{}]@t{.}
2620 @end display
2621
2622 The @code{MSAVE} command evaluates the @i{expression} specified just
2623 after the command name, and writes the resulting matrix to a matrix
2624 file (@pxref{Matrix Files}).
2625
2626 The @code{TYPE} subcommand is required.  It specifies the
2627 @code{ROWTYPE_} to write along with this matrix.
2628
2629 The @code{FACTOR} and @code{SPLIT} subcommands are required on the
2630 first @code{MSAVE} if and only if the matrix file has factor or split
2631 variables, respectively.  After that, their values are carried along
2632 from one @code{MSAVE} command to the next in syntax order as defaults.
2633 Each one takes an expression that must evaluate to a vector with the
2634 same number of entries as the matrix has factor or split variables,
2635 respectively.  Each @code{MSAVE} only writes data for a single
2636 combination of factor and split variables, so many @code{MSAVE}
2637 commands (or one inside a loop) may be needed to write a complete set.
2638
2639 The remaining @code{MSAVE} subcommands define the format of the matrix
2640 file.  All of the @code{MSAVE} commands within a given matrix program
2641 write to the same matrix file, so these subcommands are only
2642 meaningful on the first @code{MSAVE} command within a matrix program.
2643 (If they are given again on later @code{MSAVE} commands, then they
2644 must have the same values as on the first.)
2645
2646 The @code{OUTFILE} subcommand specifies the name or handle of the
2647 matrix file to be written.  Output must go to an external file, not a
2648 data set or the active file.
2649
2650 The @code{VARIABLES} subcommand specifies a comma-separated list of
2651 the names of the continuous variables to be written to the matrix
2652 file.  The @code{TO} keyword can be used to define variables named
2653 with consecutive integer suffixes.  These names become column names
2654 and names that appear in @code{VARNAME_} in the matrix file.
2655 @code{ROWTYPE_} and @code{VARNAME_} are not allowed on
2656 @code{VARIABLES}.  If @code{VARIABLES} is omitted, then @pspp{} uses
2657 the names @code{COL1}, @code{COL2}, and so on.
2658
2659 The @code{FNAMES} subcommand may be used to supply a comma-separated
2660 list of factor variable names.  The default names are @code{FAC1},
2661 @code{FAC2}, and so on.
2662
2663 The @code{SNAMES} subcommand can supply a comma-separated list of
2664 split variable names.  The default names are @code{SPL1}, @code{SPL2},
2665 and so on.
2666
2667 @node Matrix DISPLAY Command
2668 @subsection The @code{DISPLAY} Command
2669
2670 @display
2671 @t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}]@t{.}
2672 @end display
2673
2674 The @code{DISPLAY} command makes @pspp{} display a table with the name
2675 and dimensions of each matrix variable.  The @code{DICTIONARY} and
2676 @code{STATUS} keywords are accepted but have no effect.
2677
2678 @node Matrix RELEASE Command
2679 @subsection The @code{RELEASE} Command
2680
2681 @display
2682 @t{RELEASE} @i{variable}@dots{}@t{.}
2683 @end display
2684
2685 The @code{RELEASE} command accepts a comma-separated list of matrix
2686 variable names.  It deletes each variable and releases the memory
2687 associated with it.
2688
2689 The @code{END MATRIX} command releases all matrix variables.