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".
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
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.
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
33 A matrix file's dictionary must have the following variables in the
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.
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.
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.
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.
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.
66 Case weights are ignored in matrix files.
69 @anchor{Matrix File Row Types}
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
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
84 Correlation coefficients.
87 Covariance coefficients.
90 General-purpose matrix.
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:
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:
133 Synonym for @code{STDDEV}.
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.
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}]
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}]
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.
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.
176 @cmd{MATRIX DATA} can read the types of matrix and vector data
177 supported in matrix files (@pxref{Matrix File Row Types}).
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}).
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
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}).
203 The @subcmd{FORMAT} subcommand accepts settings to describe the format
207 @item @code{LIST} (default)
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.
213 @item @code{LOWER} (default)
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
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.
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.
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.
239 @node MATRIX DATA with ROWTYPE_
240 @subsection With @code{ROWTYPE_}
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.
246 @subsubheading Example 1: Defaults with @code{ROWTYPE_}
247 @anchor{MATRIX DATA Example 1}
249 This example shows a simple use of @cmd{MATRIX DATA} with
250 @code{ROWTYPE_} plus 8 variables named @code{var01} through
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.
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.
267 With @code{ROWTYPE_}, the @code{CONTENTS} subcommand is optional and
268 the @code{CELLS} subcommand may not be used.
272 VARIABLES=ROWTYPE_ var01 TO var08.
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
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
288 @subsubheading Example 2: @code{FORMAT=UPPER NODIAGONAL}
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.
297 VARIABLES=ROWTYPE_ var01 TO var08
298 /FORMAT=UPPER NODIAGONAL.
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
313 @subsubheading Example 3: @subcmd{N} subcommand
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.
320 VARIABLES=ROWTYPE_ var01 TO var08
321 /FORMAT=UPPER NODIAGONAL
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
336 @subsubheading Example 4: Split variables
337 @anchor{MATRIX DATA Example 4}
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}.
346 VARIABLES=s1 ROWTYPE_ var01 TO var04
367 @subsubheading Example 5: Factor variables
368 @anchor{MATRIX DATA Example 5}
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.
377 VARIABLES=ROWTYPE_ f1 var01 TO var04
393 @node MATRIX DATA without ROWTYPE_
394 @subsection Without @code{ROWTYPE_}
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.
401 Factor variables without @code{ROWTYPE_} introduce special
402 requirements, illustrated below in Examples 8 and 9.
404 @subsubheading Example 6: Defaults without @code{ROWTYPE_}
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
413 VARIABLES=var01 TO var08
414 /CONTENTS=MEAN SD N CORR.
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
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
430 @subsubheading Example 7: Split variables with explicit values
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
439 VARIABLES=s1 var01 TO var04
442 /CONTENTS=MEAN SD N CORR.
461 @subsubheading Example 8: Split variable with sequential values
462 @anchor{MATRIX DATA Example 8}
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.
473 VARIABLES=var01 TO var04
476 /CONTENTS=MEAN SD N CORR.
495 @subsubsection Factor variables without @code{ROWTYPE_}
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.
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.
513 Without @subcmd{ROWTYPE_}, input lines for pooled data do not include
514 factor values, not even as missing values, but input lines for
517 The following examples aim to clarify this syntax.
519 @subsubheading Example 9: Factor variables, grouping within-cell records by factor
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.
532 VARIABLES=f1 var01 TO var04
535 /CONTENTS=(MEAN SD N) CORR.
550 @subsubheading Example 10: Factor variables, grouping within-cell records by row type
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.
559 VARIABLES=f1 var01 TO var04
562 /CONTENTS=(MEAN) (SD) (N) CORR.
584 [IN(@{@samp{*}|'@var{file}'@})]
585 [OUT(@{@samp{*}|'@var{file}'@})]]
586 [/@{REPLACE,APPEND@}].
589 The @cmd{MCONVERT} command converts matrix data from a correlation
590 matrix and a vector of standard deviations into a covariance matrix,
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
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.
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.
618 @dots{}@i{matrix commands}@dots{}
623 The following basic matrix commands are supported:
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{.}
637 The following matrix commands offer support for flow control:
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{}
645 @dots{}@i{matrix commands}@dots{}]
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{.}
656 The following matrix commands support matrix input and output:
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}@}]
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}@}]
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{.}
696 The following matrix commands provide additional support:
699 @t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}]@t{.}
700 @t{RELEASE} @i{variable}@dots{}@t{.}
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.
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}.
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.
726 The matrix language does not work with cases. A variable in the
727 matrix language represents a single matrix.
729 The matrix language does not support missing values.
731 @code{MATRIX} is a procedure, so it cannot be enclosed inside @code{DO
732 IF}, @code{LOOP}, etc.
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
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
744 @node Matrix Expressions
745 @subsection Matrix Expressions
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
754 Function call @t{()} and matrix construction @t{@{@}}
760 Unary @t{+} and @t{-}
763 Integer sequence @t{:}
766 Exponentiation @t{**} and @t{&**}
769 Multiplication @t{*} and @t{&*}, and division @t{/} and @t{&/}
772 Addition @t{+} and subtraction @t{-}
775 Relational @t{< <= = >= > <>}
784 Logical @t{OR} and @t{XOR}
787 @xref{Matrix Functions}, for the available matrix functions. The
788 remaining operators are described in more detail below.
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}.
797 @node Matrix Construction Operator
798 @subsubsection Matrix Construction Operator @t{@{@}}
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.
806 @multitable @columnfractions .4 .05 .4
807 @item @t{@{1, 2, 3; 4, 5, 6@}}
811 @t{[1 2 3] @* [4 5 6]}
814 @math{\left(\matrix{1 & 2 & 3 \cr 4 & 5 & 6}\right)}
817 @item @t{@{3.14, 6.28, 9.24, 12.57@}}
821 [3.14 6.28 9.42 12.57]
824 @math{(\matrix{3.14 & 6.28 & 9.42 & 12.57})}
827 @item @t{@{1.41; 1.73; 2@}}
831 @t{[1.41] @* [1.73] @* [2.00]}
834 @math{(\matrix{1.41 & 1.73 & 2.00})}
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:
849 @multitable @columnfractions .4 .05 .4
850 @item @t{@{m, c; r, 10@}}
854 @t{[1 2 7] @* [3 4 8] @* [5 6 10]}
857 @math{\left(\matrix{1 & 2 & 7 \cr 3 & 4 & 8 \cr 5 & 6 & 10}\right)}
860 @item @t{@{c, 2 * c, T(r)@}}
864 @t{[7 14 5] @* [8 16 6]}
867 @math{\left(\matrix{7 & 14 & 5 \cr 8 & 16 & 6}\right)}
871 The final example above uses the transposition function @code{T}.
873 @node Matrix Sequence Operator
874 @subsubsection Integer Sequence Operator @samp{:}
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.
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.
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.
891 Here are some examples:
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)
901 @node Matrix Index Operator
902 @subsubsection Index Operator @code{()}
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}.
909 In the simplest case, if @var{rindex} and @var{cindex} are both
910 scalars, the result is also a scalar:
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}
919 If the index arguments have multiple elements, then the result
920 includes multiple rows or columns:
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@}}
928 The special argument @samp{:} may stand in for all the rows or columns
929 in the matrix being indexed, like this:
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@}}
937 The index arguments do not have to be in order, and they may contain
938 repeated values, like this:
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@}}
946 When the matrix being indexed is a row or column vector, only a single
947 index argument is needed, like this:
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@}}
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:
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)
963 @node Matrix Unary Operators
964 @subsubsection Unary Operators
966 The unary operators take a single operand of any dimensions and
967 operate on each of its elements independently. The unary operators
972 Inverts the sign of each element.
978 Logical inversion: each positive value becomes 0 and each zero or
979 negative value becomes 1.
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@}}
990 @node Matrix Elementwise Binary Operators
991 @subsubsection Elementwise Binary Operators
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.
1000 The elementwise binary operators are listed below.
1004 The arithmetic operators, for familiar arithmetic operations:
1014 Multiplication, if one operand is a scalar. (Otherwise this is matrix
1015 multiplication, described below.)
1017 @item @code{/} or @code{&/}
1028 The relational operators, whose results are 1 when a comparison is
1029 true and 0 when it is false:
1032 @item @code{<} or @code{LT}
1035 @item @code{<=} or @code{LE}
1038 @item @code{=} or @code{EQ}
1041 @item @code{>} or @code{GT}
1044 @item @code{>=} or @code{GE}
1045 Greater than or equal.
1047 @item @code{<>} or @code{~=} or @code{NE}
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:
1057 True if both operands are true.
1060 True if at least one operand is true.
1063 True if exactly one operand is true.
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@}}
1079 @node Matrix Multiplication Operator
1080 @subsubsection Matrix Multiplication Operator @samp{*}
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}.
1088 The @code{*} operator performs elementwise multiplication (see above)
1089 if one of its operands is a scalar.
1091 No built-in operator yields the inverse of matrix multiplication.
1092 Instead, multiply by the result of @code{INV} or @code{GINV}.
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@}}
1101 @node Matrix Exponentiation Operator
1102 @subsubsection Matrix Exponentiation Operator @code{**}
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:
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.)
1114 For @code{B < 0}, @code{A**B} is @code{INV(A**(-B))}.
1117 For @code{B = 0}, @code{A**B} is the identity matrix.
1121 @pspp{} reports an error if @code{A} is not square or @code{B} is not
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@}}
1132 @node Matrix Functions
1133 @subsection Matrix Functions
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:
1145 A nonnegative integer scalar. (Non-integers are accepted and silently
1146 rounded down to the nearest integer.)
1149 A row or column vector.
1155 @node Matrix Elementwise Functions
1156 @subsubsection Elementwise Functions
1158 These functions act on each element of their argument independently,
1159 like the elementwise operators (@pxref{Matrix Elementwise Binary
1162 @deffn {Matrix Function} ABS (@var{M})
1163 Takes the absolute value of each element of @var{M}.
1165 @t{ABS(@{-1, 2; -3, 0@}) @result{} @{1, 2; 3, 0@}}
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.
1174 The value of @math{\pi} can be computed as @code{4*ARTAN(1)}.
1176 @t{ARSIN(@{-1, 0, 1@}) @result{} @{-1.57, 0, 1.57@}} (approximately)
1178 @t{ARTAN(@{-5, -1, 1, 5@}) @result{} @{-1.37, -.79, .79, 1.37@}} (approximately)
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.
1186 @t{COS(@{0.785, 1.57; 3.14, 1.57 + 3.14@}) @result{} @{.71, 0; -1, 0@}} (approximately)
1189 @deffn {Matrix Function} EXP (@var{M})
1190 Computes @math{e^x} for each element @var{x} in @var{M}.
1192 @t{EXP(@{2, 3; 4, 5@}) @result{} @{7.39, 20.09; 54.6, 148.4@}} (approximately)
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}.
1200 @t{LG10(@{1, 10, 100, 1000@}) @result{} @{0, 1, 2, 3@}} @*
1201 @t{LG10(0) @result{}} (error)
1203 @t{LN(@{EXP(1), 1, 2, 3, 4@}) @result{} @{1, 0, .69, 1.1, 1.39@}} (approximately) @*
1204 @t{LN(0) @result{}} (error)
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.
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)
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.
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@}}
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@}}
1237 @deffn {Matrix Function} SQRT (@var{M})
1238 Takes the square root of each element of @var{M}, which must not be
1241 @t{SQRT(@{0, 1, 2, 4, 9, 81@}) @result{} @{0, 1, 1.41, 2, 3, 9@}} (approximately) @*
1242 @t{SQRT(-1) @result{}} (error)
1245 @node Matrix Logical Functions
1246 @subsubsection Logical Functions
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.
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}
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.
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}
1268 @node Matrix Construction Functions
1269 @subsubsection Matrix Construction Functions
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.
1278 @t{BLOCK(@{1, 2; 3, 4@}, 5, @{7; 8; 9@}, @{10, 11@}) @result{}
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.
1296 @t{IDENT(1) @result{} 1
1300 IDENT(3, 5) @result{}
1304 IDENT(5, 3) @result{}
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}.
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@}}
1324 @deffn {Matrix Function} MAKE (@var{nr}, @var{nc}, @var{s})
1325 Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements are
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@}}
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.
1338 Use @code{CALL SETDIAG} (@pxref{CALL SETDIAG}) to replace the main
1339 diagonal of a matrix in-place.
1342 @t{MDIAG(@{1, 2, 3, 4@}) @result{}
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.
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{}
1361 RESHAPE(1:12, 3, 4) @result{}
1365 RESHAPE(1:12, 4, 3) @result{}
1373 @deffn {Matrix Function} T (@var{M})
1374 @deffnx {Matrix Function} TRANSPOS (@var{M})
1375 Returns @var{M} with rows exchanged for columns.
1377 @t{T(@{1, 2, 3@}) @result{} @{1; 2; 3@}} @*
1378 @t{T(@{1; 2; 3@}) @result{} @{1, 2, 3@}}
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
1387 The following example shows one possible output, but of course every
1388 result will be different (given different seeds):
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}
1399 @node Matrix Minimum and Maximum and Sum Functions
1400 @subsubsection Minimum, Maximum, and Sum Functions
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}.
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@}}
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}.
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}
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}.
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@}}
1443 @deffn {Matrix Function} SSCP (@var{M})
1444 Returns @math{@var{M}^T @times{} @var{M}}.
1446 @t{SSCP(@{1, 2, 3; 4, 5, 6@}) @result{} @{17, 22, 27; 22, 29, 36; 27, 36, 45@}}
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}))}.
1453 @t{TRACE(MDIAG(1:5)) @result{} 15}
1456 @node Matrix Property Functions
1457 @subsubsection Matrix Property Functions
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}.
1464 @t{NROW(@{1, 0; -2, -3; 3, 3@}) @result{} 3
1465 NROW(1:5) @result{} 1
1467 NCOL(@{1, 0; -2, -3; 3, 3@}) @result{} 2
1468 NCOL(1:5) @result{} 5}
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})}.
1477 @t{DIAG(@{1, 0; -2, -3; 3, 3@}) @result{} @{1; -3@}}
1480 @node Matrix Rank Ordering Functions
1481 @subsubsection Matrix Rank Ordering Functions
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.
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.
1498 @t{GRADE(@{1, 0, 3; 3, 1, 2; 3, 0, 5@})} @result{} @t{@{3, 1, 6; 7, 4, 5; 8, 2, 9@}}
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.
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@}}
1509 One may use @code{GRADE} to sort a vector:
1512 COMPUTE v(GRADE(v))=v. /* Sort v in ascending order.
1513 COMPUTE v(GRADE(-v))=v. /* Sort v in descending order.
1516 @node Matrix Algebra Functions
1517 @subsubsection Matrix Algebra Functions
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}}.
1525 @t{CHOL(@{4, 12, -16; 12, 37, -43; -16, -43, 98@}) @result{}
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.
1539 @pspp{} issues a warning if a column only contains a single unique value.
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)
1550 @deffn {Matrix Function} DET (@var{M})
1551 Returns the determinant of square matrix @var{M}.
1553 @t{DET(@{3, 7; 1, -4@}) @result{} -19}
1556 @deffn {Matrix Function} EVAL (@var{M})
1558 Returns a column vector containing the eigenvalues of symmetric matrix
1559 @var{M}, sorted in ascending order.
1561 Use @code{CALL EIGEN} (@pxref{CALL EIGEN}) to compute eigenvalues and
1562 eigenvectors of a matrix.
1564 @t{EVAL(@{2, 0, 0; 0, 3, 4; 0, 4, 9@}) @result{} @{11; 2; 1@}}
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}}.
1574 @t{GINV(@{1, 2@}) @result{} @{.2; .4@}} (approximately) @*
1575 @t{@{1:9@} * GINV(1:9) * @{1:9@} @result{} @{1:9@}} (approximately)
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.
1584 @t{GSCH(@{3, 2; 1, 2@}) * SQRT(10) @result{} @{3, -1; 1, 3@}} (approximately)
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}.
1594 @t{INV(@{4, 7; 2, 6@}) @result{} @{.6, -.7; -.2, .4@}} (approximately)
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@}}.
1608 @t{KRONEKER(@{1, 2; 3, 4@}, @{0, 5; 6, 7@}) @result{}
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.
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}
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}}.
1637 All of the following examples show approximate results:
1640 @t{SOLVE(@{2, 3; 4, 9@}, @{6, 2; 15, 5@}) @result{}
1643 SOLVE(@{1, 3, -2; 3, 5, 6; 2, 4, 3@}, @{5; 7; 8@}) @result{}
1647 SOLVE(@{2, 1, -1; -3, -1, 2; -2, 1, 2@}, @{8; -11; -3@}) @result{}
1654 @deffn {Matrix Function} SVAL (@var{M})
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.
1661 Use @code{CALL SVD} (@pxref{CALL SVD}) to compute the full singular
1662 value decomposition of a matrix.
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@}}
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}.
1677 If @math{@var{M}_{kk} @ne{} 0}, then:
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}.
1686 If @math{@var{M}_{kk} = 0}, then:
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}.
1693 Given @t{M = @{0, 1, 2; 3, 4, 5; 6, 7, 8@}}, then (approximately):
1696 @t{SWEEP(M, 1) @result{}
1700 SWEEP(M, 2) @result{}
1704 SWEEP(M, 3) @result{}
1712 @subsubsection I/O Function
1714 This function works with files being used on the @code{READ} statement.
1716 @deffn {Matrix Function} EOF (@var{file})
1717 @anchor{EOF Matrix Function}
1719 Given a file handle or file name @var{file}, returns an integer scalar
1720 1 if the last line in the file has been read or 0 if more lines are
1721 available. Determining this requires attempting to read another line,
1722 which means that @code{REREAD} on the next @code{READ} command
1723 following @code{EOF} on the same file will be ineffective.
1726 The @code{EOF} function gives a matrix program the flexibility to read
1727 a file with text data without knowing the length of the file in
1728 advance. For example, the following program will read all the lines
1729 of data in @file{data.txt}, each consisting of three numbers, as rows
1730 in matrix @code{data}:
1735 LOOP IF NOT EOF('data.txt').
1736 READ row/FILE='data.txt'/FIELD=1 TO 1000/SIZE={1,3}.
1737 COMPUTE data={data; row}.
1744 @node Matrix COMPUTE Command
1745 @subsection The @code{COMPUTE} Command
1748 @t{COMPUTE} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]@t{=}@i{expression}@t{.}
1751 The @code{COMPUTE} command evaluates an expression and assigns the
1752 result to a variable or a submatrix of a variable. Assigning to a
1753 submatrix uses the same syntax as the index operator (@pxref{Matrix
1756 @node Matrix CALL command
1757 @subsection The @code{CALL} Command
1759 A matrix function returns a single result. The @code{CALL} command
1760 implements procedures, which take a similar syntactic form to
1761 functions but yield results by modifying their arguments rather than
1764 Output arguments to a @code{CALL} procedure must be a single variable
1767 The following procedures are implemented via @code{CALL} to allow them
1768 to return multiple results. For these procedures, the output
1769 arguments need not name existing variables; if they do, then their
1770 previous values are replaced:
1773 @item @t{CALL EIGEN(@var{M}, @var{evec}, @var{eval})}
1776 Computes the eigenvalues and eigenvector of symmetric
1777 @math{@var{n}@times{}@var{n}} matrix @var{M}. Assigns the
1778 eigenvectors of @var{M} to the columns of
1779 @math{@var{n}@times{}@var{n}} matrix @var{evec} and the eigenvalues in
1780 descending order to @var{n}-element column vector @var{eval}.
1782 Use the @code{EVAL} function (@pxref{EVAL}) to compute just the
1783 eigenvalues of a symmetric matrix.
1785 For example, the following matrix language commands:
1787 CALL EIGEN(@{1, 0; 0, 1@}, evec, eval).
1791 CALL EIGEN(@{3, 2, 4; 2, 0, 2; 4, 2, 3@}, evec2, eval2).
1809 -.6666666667 .0000000000 .7453559925
1810 -.3333333333 -.8944271910 -.2981423970
1811 -.6666666667 .4472135955 -.5962847940
1819 @item @t{CALL SVD(@var{M}, @var{U}, @var{S}, @var{V})}
1822 Computes the singular value decomposition of
1823 @math{@var{n}@times{}@var{k}} matrix @var{M}, assigning @var{S} a
1824 @math{@var{n}@times{}@var{k}} diagonal matrix and to @var{U} and
1825 @var{V} unitary @math{@var{k}@times{}@var{k}} matrices such that
1826 @math{@var{M} = @var{U}@times{}@var{S}@times{}@var{V}^T}. The main
1827 diagonal of @var{Q} contains the singular values of @var{M}.
1829 Use the @code{SVAL} function (@pxref{SVAL}) to compute just the
1830 singular values of a matrix.
1832 For example, the following matrix program:
1835 CALL SVD(@{3, 2, 2; 2, 3, -2@}, u, s, v).
1836 PRINT (u * s * T(v))/FORMAT F5.1.
1849 The final procedure is implemented via @code{CALL} to allow it to
1850 modify a matrix instead of returning a modified version. For this
1851 procedure, the output argument must name an existing variable.
1854 @item @t{CALL SETDIAG(@var{M}, @var{V})}
1855 @anchor{CALL SETDIAG}
1857 Replaces the main diagonal of @math{@var{n}@times{}@var{p}} matrix
1858 @var{M} by the contents of @var{k}-element vector @var{V}. If
1859 @math{@var{k} = 1}, so that @var{V} is a scalar, replaces all of the
1860 diagonal elements of @var{M} by @var{V}. If @math{@var{k} <
1861 \min(@var{n},@var{p})}, only the upper @var{k} diagonal elements are
1862 replaced; if @math{@var{k} > \min(@var{n},@var{p})}, then the
1863 extra elements of @var{V} are ignored.
1865 Use the @code{MDIAG} function (@pxref{MDIAG}) to construct a new
1866 matrix with a specified main diagonal.
1868 For example, this matrix program:
1871 COMPUTE x=@{1, 2, 3; 4, 5, 6; 7, 8, 9@}.
1872 CALL SETDIAG(x, 10).
1877 outputs the following:
1887 @node Matrix PRINT Command
1888 @subsection The @code{PRINT} Command
1891 @t{PRINT} [@i{expression}]
1892 [@t{/FORMAT}@t{=}@i{format}]
1893 [@t{/TITLE}@t{=}@i{title}]
1894 [@t{/SPACE}@t{=}@{@t{NEWPAGE} @math{|} @i{n}@}]
1895 [@{@t{/RLABELS}@t{=}@i{string}@dots{} @math{|} @t{/RNAMES}@t{=}@i{expression}@}]
1896 [@{@t{/CLABELS}@t{=}@i{string}@dots{} @math{|} @t{/CNAMES}@t{=}@i{expression}@}]@t{.}
1899 The @code{PRINT} command is commonly used to display a matrix. It
1900 evaluates the restricted @var{expression}, if present, and outputs it
1901 either as text or a pivot table, depending on the setting of
1902 @code{MDISPLAY} (@pxref{SET MDISPLAY}).
1904 Use the @code{FORMAT} subcommand to specify a format, such as
1905 @code{F8.2}, for displaying the matrix elements. @code{FORMAT} is
1906 optional for numerical matrices. When it is omitted, @pspp{} chooses
1907 how to format entries automatically using @var{m}, the magnitude of
1908 the largest-magnitude element in the matrix to be displayed:
1912 If @math{@var{m} < 10^{11}} and the matrix's elements are all
1913 integers, @pspp{} chooses the narrowest @code{F} format that fits
1914 @var{m} plus a sign. For example, if the matrix is @t{@{1:10@}}, then
1915 @math{m = 10}, which fits in 3 columns with room for a sign, the
1916 format is @code{F3.0}.
1919 Otherwise, if @math{@var{m} @geq{} 10^9} or @math{@var{m} @leq{}
1920 10^{-4}}, @pspp{} scales all of the numbers in the matrix by
1921 @math{10^x}, where @var{x} is the exponent that would be used to
1922 display @var{m} in scientific notation. For example, for
1923 @math{@var{m} = 5.123@times{}10^{20}}, the scale factor is
1924 @math{10^{20}}. @pspp{} displays the scaled values in format
1925 @code{F13.10} and notes the scale factor in the output.
1928 Otherwise, @pspp{} displays the matrix values, without scaling, in
1929 format @code{F13.10}.
1932 The optional @code{TITLE} subcommand specifies a title for the output
1933 text or table, as a quoted string. When it is omitted, the syntax of
1934 the matrix expression is used as the title.
1936 Use the @code{SPACE} subcommand to request extra space above the
1937 matrix output. With a numerical argument, it adds the specified
1938 number of lines of blank space above the matrix. With @code{NEWPAGE}
1939 as an argument, it prints the matrix at the top of a new page. The
1940 @code{SPACE} subcommand has no effect when a matrix is output as a
1943 The @code{RLABELS} and @code{RNAMES} subcommands, which are mutually
1944 exclusive, can supply a label to accompany each row in the output.
1945 With @code{RLABELS}, specify the labels as comma-separated strings or
1946 other tokens. With @code{RNAMES}, specify a single expression that
1947 evaluates to a vector of strings. Either way, if there are more
1948 labels than rows, the extra labels are ignored, and if there are more
1949 rows than labels, the extra rows are unlabeled. For output to a pivot
1950 table with @code{RLABELS}, the labels can be any length; otherwise,
1951 the labels are truncated to 8 bytes.
1953 The @code{CLABELS} and @code{CNAMES} subcommands work for labeling
1954 columns as @code{RLABELS} and @code{RNAMES} do for labeling rows.
1956 When the @var{expression} is omitted, @code{PRINT} does not output a
1957 matrix. Instead, it outputs only the text specified on @code{TITLE},
1958 if any, preceded by any space specified on the @code{SPACE}
1959 subcommand, if any. Any other subcommands are ignored, and the
1960 command acts as if @code{MDISPLAY} is set to @code{TEXT} regardless of
1963 The following syntax demonstrates two different ways to label the rows
1964 and columns of a matrix with @code{PRINT}:
1968 COMPUTE m=@{1, 2, 3; 4, 5, 6; 7, 8, 9@}.
1969 PRINT m/RLABELS=a, b, c/CLABELS=x, y, z.
1971 COMPUTE rlabels=@{"a", "b", "c"@}.
1972 COMPUTE clabels=@{"x", "y", "z"@}.
1973 PRINT m/RNAMES=rlabels/CNAMES=clabels.
1978 With @code{MDISPLAY=TEXT} (the default), this program outputs the
1990 With @samp{SET MDISPLAY=TABLES.} added above @samp{MATRIX.}, the
1991 output becomes the following (twice):
1993 @psppoutput {matrix-print}
1995 @node Matrix DO IF Command
1996 @subsection The @code{DO IF} Command
1999 @t{DO IF} @i{expression}@t{.}
2000 @dots{}@i{matrix commands}@dots{}
2001 [@t{ELSE IF} @i{expression}@t{.}
2002 @dots{}@i{matrix commands}@dots{}]@dots{}
2004 @dots{}@i{matrix commands}@dots{}]
2008 A @code{DO IF} command evaluates its expression argument. If the
2009 @code{DO IF} expression evaluates to true, then @pspp{} executes the
2010 associated commands. Otherwise, @pspp{} evaluates the expression on
2011 each @code{ELSE IF} clause (if any) in order, and executes the
2012 commands associated with the first one that yields a true value.
2013 Finally, if the @code{DO IF} and all the @code{ELSE IF} expressions
2014 all evaluate to false, @pspp{} executes the commands following the
2015 @code{ELSE} clause (if any).
2017 Each expression on @code{DO IF} and @code{ELSE IF} must evaluate to a
2018 scalar. Positive scalars are considered to be true, and scalars that
2019 are zero or negative are considered to be false.
2021 The following matrix language fragment sets @samp{b} to the term
2022 following @samp{a} in the
2023 @url{https://en.wikipedia.org/wiki/Juggler_sequence, Juggler
2027 DO IF MOD(a, 2) = 0.
2028 COMPUTE b = TRUNC(a &** (1/2)).
2030 COMPUTE b = TRUNC(a &** (3/2)).
2034 @node Matrix LOOP and BREAK Commands
2035 @subsection The @code{LOOP} and @code{BREAK} Commands
2038 @t{LOOP} [@i{var}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{step}]] [@t{IF} @i{expression}]@t{.}
2039 @dots{}@i{matrix commands}@dots{}
2040 @t{END LOOP} [@t{IF} @i{expression}]@t{.}
2045 The @code{LOOP} command executes a nested group of matrix commands,
2046 called the loop's @dfn{body}, repeatedly. It has three optional
2047 clauses that control how many times the loop body executes.
2048 Regardless of these clauses, the global @code{MXLOOPS} setting, which
2049 defaults to 40, also limits the number of iterations of a loop. To
2050 iterate more times, raise the maximum with @code{SET MXLOOPS} outside
2051 of the @code{MATRIX} command (@pxref{SET MXLOOPS}).
2053 The optional index clause causes @var{var} to be assigned successive
2054 values on each trip through the loop: first @var{first}, then
2055 @math{@var{first} + @var{step}}, then @math{@var{first} + 2 @times{}
2056 @var{step}}, and so on. The loop ends when @math{@var{var} >
2057 @var{last}}, for positive @var{step}, or @math{@var{var} <
2058 @var{last}}, for negative @var{step}. If @var{step} is not specified,
2059 it defaults to 1. All the index clause expressions must evaluate to
2060 scalars, and non-integers are rounded toward zero. If @var{step}
2061 evaluates as zero (or rounds to zero), then the loop body never
2064 The optional @code{IF} on @code{LOOP} is evaluated before each
2065 iteration through the loop body. If its expression, which must
2066 evaluate to a scalar, is zero or negative, then the loop terminates
2067 without executing the loop body.
2069 The optional @code{IF} on @code{END LOOP} is evaluated after each
2070 iteration through the loop body. If its expression, which must
2071 evaluate to a scalar, is zero or negative, then the loop terminates.
2073 The following computes and prints @math{l(n)}, whose value is the
2074 number of steps in the
2075 @url{https://en.wikipedia.org/wiki/Juggler_sequence, Juggler sequence}
2076 for @math{n}, for @math{n} from 2 to 10 inclusive:
2083 DO IF MOD(a, 2) = 0.
2084 COMPUTE a = TRUNC(a &** (1/2)).
2086 COMPUTE a = TRUNC(a &** (3/2)).
2089 COMPUTE l = @{l; i@}.
2094 @node Matrix BREAK Command
2095 @subsubsection The @code{BREAK} Command
2097 The @code{BREAK} command may be used inside a loop body, ordinarily
2098 within a @code{DO IF} command. If it is executed, then the loop
2099 terminates immediately, jumping to the command just following
2100 @code{END LOOP}. When multiple @code{LOOP} commands nest,
2101 @code{BREAK} terminates the innermost loop.
2103 The following example is a revision of the one above that shows how
2104 @code{BREAK} could substitute for the index and @code{IF} clauses on
2105 @code{LOOP} and @code{END LOOP}:
2113 DO IF MOD(a, 2) = 0.
2114 COMPUTE a = TRUNC(a &** (1/2)).
2116 COMPUTE a = TRUNC(a &** (3/2)).
2123 COMPUTE l = @{l; i@}.
2128 @node Matrix READ and WRITE Commands
2129 @subsection The @code{READ} and @code{WRITE} Commands
2131 The @code{READ} and @code{WRITE} commands perform matrix input and
2132 output with text files. They share the following syntax for
2133 specifying how data is divided among input lines:
2136 @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
2137 [@t{/FORMAT}@t{=}@i{format}]
2140 Both commands require the @code{FIELD} subcommand. It specifies the
2141 range of columns, from @var{first} to @var{last}, inclusive, that the
2142 data occupies on each line of the file. The leftmost column is column
2143 1. The columns must be literal numbers, not expressions. To use
2144 entire lines, even if they might be very long, specify a column range
2145 such as @code{1 TO 100000}.
2147 The @code{FORMAT} subcommand is optional for numerical matrices. For
2148 string matrix input and output, specify an @code{A} format. In
2149 addition to @code{FORMAT}, the optional @code{BY} specification on
2150 @code{FIELD} determine the meaning of each text line:
2154 With neither @code{BY} nor @code{FORMAT}, the numbers in the text file
2155 are in @code{F} format separated by spaces or commas. For
2156 @code{WRITE}, @pspp{} uses as many digits of precision as needed to
2157 accurately represent the numbers in the matrix.
2160 @code{BY @i{width}} divides the input area into fixed-width fields
2161 with the given @i{width}. The input area must be a multiple of
2162 @i{width} columns wide. Numbers are read or written as
2163 @code{F@i{width}.0} format.
2166 @code{FORMAT=@i{count}F} divides the input area into @i{count}
2167 equal-width fields per line. The input area must be a multiple of
2168 @i{count} columns wide. Another format type may be substituted for
2172 @code{FORMAT=F@i{w}}[@code{.@i{d}}] divides the input area into fixed-width
2173 fields with width @i{w}. The input area must be a multiple of @i{w}
2174 columns wide. Another format type may be substituted for @code{F}.
2175 The @code{READ} command disregards @i{d}.
2178 @code{FORMAT=F} specifies format @code{F} without indicating a field
2179 width. Another format type may be substituted for @code{F}. The
2180 @code{WRITE} command accepts this form, but it has no effect unless
2181 @code{BY} is also used to specify a field width.
2184 If @code{BY} and @code{FORMAT} both specify or imply a field width,
2185 then they must indicate the same field width.
2187 @node Matrix READ Command
2188 @subsubsection The @code{READ} Command
2191 @t{READ} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]
2192 [@t{/FILE}@t{=}@i{file}]
2193 @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
2194 [@t{/FORMAT}@t{=}@i{format}]
2195 [@t{/SIZE}@t{=}@i{expression}]
2196 [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{SYMMETRIC}@}]
2200 The @code{READ} command reads from a text file into a matrix variable.
2201 Specify the target variable just after the command name, either just a
2202 variable name to create or replace an entire variable, or a variable
2203 name followed by an indexing expression to replace a submatrix of an
2206 The @code{FILE} subcommand is required in the first @code{READ}
2207 command that appears within @code{MATRIX}. It specifies the text file
2208 to be read, either as a file name in quotes or a file handle
2209 previously declared on @code{FILE HANDLE} (@pxref{FILE HANDLE}).
2210 Later @code{READ} commands (in syntax order) use the previous
2211 referenced file if @code{FILE} is omitted.
2213 The @code{FIELD} and @code{FORMAT} subcommands specify how input lines
2214 are interpreted. @code{FIELD} is required, but @code{FORMAT} is
2215 optional. @xref{Matrix READ and WRITE Commands}, for details.
2217 The @code{SIZE} subcommand is required for reading into an entire
2218 variable. Its restricted expression argument should evaluate to a
2219 2-element vector @code{@{@var{n},@w{ }@var{m}@}} or
2220 @code{@{@var{n};@w{ }@var{m}@}}, which indicates a
2221 @math{@var{n}@times{}@var{m}} matrix destination. A scalar @var{n} is
2222 also allowed and indicates a @math{@var{n}@times{}1} column vector
2223 destination. When the destination is a submatrix, @code{SIZE} is
2224 optional, and if it is present then it must match the size of the
2227 By default, or with @code{MODE=RECTANGULAR}, the command reads an
2228 entry for every row and column. With @code{MODE=SYMMETRIC}, the
2229 command reads only the entries on and below the matrix's main
2230 diagonal, and copies the entries above the main diagonal from the
2231 corresponding symmetric entries below it. Only square matrices
2232 may use @code{MODE=SYMMETRIC}.
2234 Ordinarily, each @code{READ} command starts from a new line in the
2235 text file. Specify the @code{REREAD} subcommand to instead start from
2236 the last line read by the previous @code{READ} command. This has no
2237 effect for the first @code{READ} command to read from a particular
2238 file. It is also ineffective just after a command that uses the
2239 @code{EOF} matrix function (@pxref{EOF Matrix Function}) on a
2240 particular file, because @code{EOF} has to try to read the next line
2241 from the file to determine whether the file contains more input.
2243 @subsubheading Example 1: Basic Use
2245 The following matrix program reads the same matrix @code{@{1, 2, 4; 2,
2246 3, 5; 4, 5, 6@}} into matrix variables @code{v}, @code{w}, and
2250 READ v /FILE='input.txt' /FIELD=1 TO 100 /SIZE=@{3, 3@}.
2251 READ w /FIELD=1 TO 100 /SIZE=@{3; 3@} /MODE=SYMMETRIC.
2252 READ x /FIELD=1 TO 100 BY 1/SIZE=@{3, 3@} /MODE=SYMMETRIC.
2256 given that @file{input.txt} contains the following:
2270 The @code{READ} command will read as many lines of input as needed for
2271 a particular row, so it's also acceptable to break any of the lines
2272 above into multiple lines. For example, the first line @code{1, 2, 4}
2273 could be written with a line break following either or both commas.
2275 @subsubheading Example 2: Reading into a Submatrix
2277 The following reads a @math{5@times{}5} matrix from @file{input2.txt},
2278 reversing the order of the rows:
2281 COMPUTE m = MAKE(5, 5, 0).
2282 LOOP r = 5 TO 1 BY -1.
2283 READ m(r, :) /FILE='input2.txt' /FIELD=1 TO 100.
2287 @subsubheading Example 3: Using @code{REREAD}
2289 Suppose each of the 5 lines in a file @file{input3.txt} starts with an
2290 integer @var{count} followed by @var{count} numbers, e.g.:
2301 Then, the following reads this file into a matrix @code{m}:
2304 COMPUTE m = MAKE(5, 5, 0).
2306 READ count /FILE='input3.txt' /FIELD=1 TO 1 /SIZE=1.
2307 READ m(i, 1:count) /FIELD=3 TO 100 /REREAD.
2311 @node Matrix WRITE Command
2312 @subsubsection The @code{WRITE} Command
2315 @t{WRITE} @i{expression}
2316 [@t{/OUTFILE}@t{=}@i{file}]
2317 @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
2318 [@t{/FORMAT}@t{=}@i{format}]
2319 [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{TRIANGULAR}@}]
2323 The @code{WRITE} command evaluates @i{expression} and writes its value
2324 to a text file in a specified format. Write the expression to
2325 evaluate just after the command name.
2327 The @code{OUTFILE} subcommand is required in the first @code{WRITE}
2328 command that appears within @code{MATRIX}. It specifies the text file
2329 to be written, either as a file name in quotes or a file handle
2330 previously declared on @code{FILE HANDLE} (@pxref{FILE HANDLE}).
2331 Later @code{WRITE} commands (in syntax order) use the previous
2332 referenced file if @code{FILE} is omitted.
2334 The @code{FIELD} and @code{FORMAT} subcommands specify how output
2335 lines are formed. @code{FIELD} is required, but @code{FORMAT} is
2336 optional. @xref{Matrix READ and WRITE Commands}, for details.
2338 By default, or with @code{MODE=RECTANGULAR}, the command writes an
2339 entry for every row and column. With @code{MODE=TRIANGULAR}, the
2340 command writes only the entries on and below the matrix's main
2341 diagonal. Entries above the diagonal are not written. Only square
2342 matrices may be written with @code{MODE=TRIANGULAR}.
2344 Ordinarily, each @code{WRITE} command starts a new line in the output
2345 file. With @code{HOLD}, the next @code{WRITE} command will write to
2346 the same line as the current one. This can be useful to write more
2347 than one matrix on a single output line.
2349 @node Matrix GET Command
2350 @subsection The @code{GET} Command
2353 @t{GET} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]
2354 [@t{/FILE}@t{=}@{@i{file} @math{|} @t{*}@}]
2355 [@t{/VARIABLES}@t{=}@i{variable}@dots{}]
2356 [@t{/NAMES}@t{=}@i{variable}]
2357 [@t{/MISSING}@t{=}@{@t{ACCEPT} @math{|} @t{OMIT} @math{|} @i{number}@}]
2358 [@t{/SYSMIS}@t{=}@{@t{OMIT} @math{|} @i{number}@}]@t{.}
2361 The @code{READ} command reads numeric data from an SPSS system file,
2362 SPSS/PC+ system file, or SPSS portable file into a matrix variable or
2367 To read data into a variable, specify just its name following
2368 @code{GET}. The variable need not already exist; if it does, it is
2369 replaced. The variable will have as many columns as there are
2370 variables specified on the @code{VARIABLES} subcommand and as many
2371 rows as there are cases in the input file.
2374 To read data into a submatrix, specify the name of an existing
2375 variable, followed by an indexing expression, just after @code{GET}.
2376 The submatrix must have as many columns as variables specified on
2377 @code{VARIABLES} and as many rows as cases in the input file.
2380 Specify the name or handle of the file to be read on @code{FILE}. Use
2381 @samp{*}, or simply omit the @code{FILE} subcommand, to read from the
2382 active file. Reading from the active file is only permitted if it was
2383 already defined outside @code{MATRIX}.
2385 List the variables to be read as columns in the matrix on the
2386 @code{VARIABLES} subcommand. The list can use @code{TO} for
2387 collections of variables or @code{ALL} for all variables. If
2388 @code{VARIABLES} is omitted, all variables are read. Only numeric
2389 variables may be read.
2391 If a variable is named on @code{NAMES}, then the names of the
2392 variables read as data columns are stored in a string vector within
2393 the given name, replacing any existing matrix variable with that name.
2394 Variable names are truncated to 8 bytes.
2396 The @code{MISSING} and @code{SYSMIS} subcommands control the treatment
2397 of missing values in the input file. By default, any user- or
2398 system-missing data in the variables being read from the input causes
2399 an error that prevents @code{GET} from executing. To accept missing
2400 values, specify one of the following settings on @code{MISSING}:
2404 Accept user-missing values with no change.
2406 By default, system-missing values still yield an error. Use the
2407 @code{SYSMIS} subcommand to change this treatment:
2411 Skip any case that contains a system-missing value.
2414 Recode the system-missing value to @i{number}.
2418 Skip any case that contains any user- or system-missing value.
2421 Recode all user- and system-missing values to @i{number}.
2424 The @code{SYSMIS} subcommand has an effect only with
2425 @code{MISSING=ACCEPT}.
2427 @node Matrix SAVE Command
2428 @subsection The @code{SAVE} Command
2431 @t{SAVE} @i{expression}
2432 [@t{/OUTFILE}@t{=}@{@i{file} @math{|} @t{*}@}]
2433 [@t{/VARIABLES}@t{=}@i{variable}@dots{}]
2434 [@t{/NAMES}@t{=}@i{expression}]
2435 [@t{/STRINGS}@t{=}@i{variable}@dots{}]@t{.}
2438 The @code{SAVE} matrix command evaluates @i{expression} and writes the
2439 resulting matrix to an SPSS system file. In the system file, each
2440 matrix row becomes a case and each column becomes a variable.
2442 Specify the name or handle of the SPSS system file on the
2443 @code{OUTFILE} subcommand, or @samp{*} to write the output as the new
2444 active file. The @code{OUTFILE} subcommand is required on the first
2445 @code{SAVE} command, in syntax order, within @code{MATRIX}. For
2446 @code{SAVE} commands after the first, the default output file is the
2447 same as the previous.
2449 When multiple @code{SAVE} commands write to one destination within a
2450 single @code{MATRIX}, the later commands append to the same output
2451 file. All the matrices written to the file must have the same number
2452 of columns. The @code{VARIABLES}, @code{NAMES}, and @code{STRINGS}
2453 subcommands are honored only for the first @code{SAVE} command that
2454 writes to a given file.
2456 By default, @code{SAVE} names the variables in the output file
2457 @code{COL1} through @code{COL@i{n}}. Use @code{VARIABLES} or
2458 @code{NAMES} to give the variables meaningful names. The
2459 @code{VARIABLES} subcommand accepts a comma-separated list of variable
2460 names. Its alternative, @code{NAMES}, instead accepts an expression
2461 that must evaluate to a row or column string vector of names. The
2462 number of names need not exactly match the number of columns in the
2463 matrix to be written: extra names are ignored; extra columns use
2466 By default, @code{SAVE} assumes that the matrix to be written is all
2467 numeric. To write string columns, specify a comma-separated list of
2468 the string columns' variable names on @code{STRINGS}.
2470 @node Matrix MGET Command
2471 @subsection The @code{MGET} Command
2474 @t{MGET} [@t{/FILE}@t{=}@i{file}]
2475 [@t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}]@t{.}
2478 The @code{MGET} command reads the data from a matrix file
2479 (@pxref{Matrix Files}) into matrix variables. Specify the name or
2480 handle of the matrix file to be read on the @code{FILE} subcommand; if
2481 it is omitted, then the command reads the active file.
2483 By default, @code{MGET} reads all of the data from the matrix file.
2484 Specify a space-delimited list of matrix types @code{TYPE} to limit the
2485 kinds of data to the one specified:
2492 Correlation coefficient matrix.
2498 Vector of standard deviations.
2501 Vector of case counts.
2507 @code{MGET} reads the entire matrix file and automatically names,
2508 creates, and populates matrix variables using its contents. It
2509 constructs the name of each variable by concatenating the following:
2513 A 2-character prefix that identifies the type of the matrix:
2520 Correlation coefficient matrix.
2526 Vector of standard deviations.
2529 Vector of case counts.
2536 If the matrix file has factor variables, @code{F@i{n}}, where @i{n}
2537 is a number identifying a group of factors: @code{F1} for the first
2538 group, @code{F2} for the second, and so on.
2541 If the matrix file has split file variables, @code{S@i{n}}, where
2542 @i{n} is a number identifying a split group: @code{S1} for the first
2543 group, @code{S2} for the second, and so on.
2546 If @code{MGET} chooses the name of an existing variable, it issues a
2547 warning and does not change the variable.
2549 @node Matrix MSAVE Command
2550 @subsection The @code{MSAVE} Command
2553 @t{MSAVE} @i{expression}
2554 @t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}
2555 [@t{/FACTOR}@t{=}@i{expression}]
2556 [@t{/SPLIT}@t{=}@i{expression}]
2557 [@t{/OUTFILE}@t{=}@i{file}]
2558 [@t{/VARIABLES}@t{=}@i{variable}@dots{}]
2559 [@t{/SNAMES}@t{=}@i{variable}@dots{}]
2560 [@t{/FNAMES}@t{=}@i{variable}@dots{}]@t{.}
2563 The @code{MSAVE} command evaluates the @i{expression} specifies just
2564 after the command name, and writes the resulting matrix to a matrix
2565 file (@pxref{Matrix Files}).
2567 The @code{TYPE} subcommand is required. It specifies the
2568 @code{ROWTYPE_} to write along with this matrix.
2570 The @code{FACTOR} and @code{SPLIT} subcommands are required if and
2571 only if the matrix file has factor or split variables, respectively.
2572 Each one takes an expression that must evaluate to a vector with the
2573 same number of entries as the matrix has factor or split variables,
2574 respectively. Each @code{MSAVE} only writes data for a single
2575 combination of factor and split variables, so many @code{MSAVE}
2576 commands (or one inside a loop) may be needed to write a complete set.
2578 The remaining @code{MSAVE} subcommands define the format of the matrix
2579 file. All of the @code{MSAVE} commands within a given matrix program
2580 write to the same matrix file, so these subcommands are only
2581 meaningful on the first @code{MSAVE} command within a matrix program.
2582 (If they are given again on later @code{MSAVE} commands, then they
2583 must have the same values as on the first.)
2585 The @code{OUTFILE} subcommand specifies the name or handle of the
2586 matrix file to be written. Output must go to an external file, not a
2587 data set or the active file.
2589 The @code{VARIABLES} subcommand specifies a comma-separated list of
2590 the names of the continuous variables to be written to the matrix
2591 file. The @code{TO} keyword can be used to define variables named
2592 with consecutive integer suffixes. These names become column names
2593 and names that appear in @code{VARNAME_} in the matrix file.
2594 @code{ROWTYPE_} and @code{VARNAME_} are not allowed on
2595 @code{VARIABLES}. If @code{VARIABLES} is omitted, then @pspp{} uses
2596 the names @code{COL1}, @code{COL2}, and so on.
2598 The @code{FNAMES} subcommand may be used to supply a comma-separated
2599 list of factor variable names. The default names are @code{FAC1},
2600 @code{FAC2}, and so on.
2602 The @code{SNAMES} subcommand can supply a comma-separated list of
2603 split variable names. The default names are @code{SPL1}, @code{SPL2},
2606 @node Matrix DISPLAY Command
2607 @subsection The @code{DISPLAY} Command
2610 @t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}]@t{.}
2613 The @code{DISPLAY} command makes @pspp{} display a table with the name
2614 and dimensions of each matrix variable. The @code{DICTIONARY} and
2615 @code{STATUS} keywords are accepted but have no effect.
2617 @node Matrix RELEASE Command
2618 @subsection The @code{RELEASE} Command
2621 @t{RELEASE} @i{variable}@dots{}@t{.}
2624 The @code{RELEASE} command accepts a comma-separated list of matrix
2625 variable names. It deletes each variable and releases the memory
2628 The @code{END MATRIX} command releases all matrix variables.