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.
616 @node Matrix Overview
621 @dots{}@i{matrix commands}@dots{}
626 The following basic matrix commands are supported:
629 @t{COMPUTE} @i{variable}[(@i{index}[,@i{index}])]=@i{expression}.
630 @t{CALL} @i{procedure}(@i{argument}, @dots{}).
631 @t{PRINT} [@i{expression}]
632 [/@t{FORMAT}=@i{format}]
633 [/@t{TITLE}=@i{title}]
634 [/@t{SPACE}=@{@t{NEWPAGE} @math{|} @i{n}@}]
635 [@{/@t{RLABELS}=@i{string}@dots{} @math{|} /@t{RNAMES}=@i{expression}@}]
636 [@{/@t{CLABELS}=@i{string}@dots{} @math{|} /@t{CNAMES}=@i{expression}@}].
640 The following matrix commands offer support for flow control:
643 @t{DO IF} @i{expression}.
644 @dots{}@i{matrix commands}@dots{}
645 [@t{ELSE IF} @i{expression}.
646 @dots{}@i{matrix commands}@dots{}]@dots{}
648 @dots{}@i{matrix commands}@dots{}]
651 @t{LOOP} [@i{var}=@i{first} @t{TO} @i{last} [@t{BY} @i{step}]] [@t{IF} @i{expression}].
652 @dots{}@i{matrix commands}@dots{}
653 @t{END LOOP} [@t{IF} @i{expression}].
659 The following matrix commands support matrix input and output:
662 @t{READ} @i{variable}[(@i{index}[,@i{index}])]
664 /@t{FIELD}=@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
665 [/@t{SIZE}=@i{expression}]
666 [/@t{MODE}=@{@t{RECTANGULAR} @math{|} @t{SYMMETRIC}@}]
668 [/@t{FORMAT}=@i{format}].
669 @t{WRITE} @i{expression}
670 [/@t{OUTFILE}=@i{file}]
671 /@t{FIELD}=@i{first} @t{TO} @i{last} [@t{BY} @i{width}]
672 [/@t{MODE}=@{@t{RECTANGULAR} @math{|} @t{TRIANGULAR}@}]
674 [/@t{FORMAT}=@i{format}].
675 @t{GET} @i{variable}[(@i{index}[,@i{index}])]
676 [/@t{FILE}=@{@i{file} @math{|} @t{*}@}]
677 [/@t{VARIABLES}=@i{variable}@dots{}]
678 [/@t{NAMES}=@i{expression}]
679 [/@t{MISSING}=@{@t{ACCEPT} @math{|} @t{OMIT} @math{|} @i{number}@}]
680 [/@t{SYSMIS}=@{@t{OMIT} @math{|} @i{number}@}].
681 @t{SAVE} @i{expression}
682 [/@t{OUTFILE}=@{@i{file} @math{|} @t{*}@}]
683 [/@t{VARIABLES}=@i{variable}@dots{}]
684 [/@t{NAMES}=@i{expression}]
685 [/@t{STRINGS}=@i{variable}@dots{}].
686 @t{MGET} [/@t{FILE}=@i{file}]
687 [/@t{TYPE}=@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}].
688 @t{MSAVE} @i{expression}
689 /@t{TYPE}=@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}
690 [/@t{OUTFILE}=@i{file}]
691 [/@t{VARIABLES}=@i{variable}@dots{}]
692 [/@t{SNAMES}=@i{variable}@dots{}]
693 [/@t{SPLIT}=@i{expression}]
694 [/@t{FNAMES}=@i{variable}@dots{}]
695 [/@t{FACTOR}=@i{expression}].
699 The following matrix commands provide additional support:
702 @t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}].
703 @t{RELEASE} @i{variable}@dots{}.
706 @node Matrix Introduction
707 @subsection Introduction
709 @code{MATRIX} and @code{END MATRIX} enclose a special @pspp{}
710 sub-language, called the matrix language. The matrix language does
711 not require an active dataset to be defined and only a few of the
712 matrix language commands work with any datasets that are defined.
713 Each instance of @code{MATRIX}@dots{}@code{END MATRIX} is a separate
714 program whose state is independent of any instance, so that variables
715 declared within a matrix program are forgotten at its end.
717 The matrix language works with matrices, where a @dfn{matrix} is a
718 rectangular array of real numbers. An @math{@var{n}@times{}@var{m}}
719 matrix has @var{n} rows and @var{m} columns. Some special cases are
720 important: a @math{@var{n}@times{}1} matrix is a @dfn{column vector},
721 a @math{1@times{}@var{n}} is a @dfn{row vector}, and a
722 @math{1@times{}1} matrix is a @dfn{scalar}.
724 The matrix language also has limited support for matrices that contain
725 8-byte strings instead of numbers. Strings longer than 8 bytes are
726 truncated, and shorter strings are padded with spaces. String
727 matrices are mainly useful for labeling rows and columns when printing
728 numerical matrices with the @code{MATRIX PRINT} command. Arithmetic
729 operations on string matrices will not produce useful results. The
730 user should not mix strings and numbers within a matrix.
732 The matrix language does not work with cases. A variable in the
733 matrix language represents a single matrix.
735 The matrix language does not support missing values.
737 @node Matrix Operators
738 @subsection Matrix Operators
740 Many matrix commands use expressions. A matrix expression may use the
741 following operators, listed in descending order of operator
742 precedence. Within a single level, operators associate from left to
747 Function call @t{()} and matrix construction @t{@{@}}
753 Unary @t{+} and @t{-}
756 Integer sequence @t{:}
759 Exponentiation @t{**} and @t{&**}
762 Multiplication @t{*} and @t{&*}, and division @t{/} and @t{&/}
765 Addition @t{+} and subtraction @t{-}
768 Relational @t{< <= = >= > <>}
777 Logical @t{OR} and @t{XOR}
780 @xref{Matrix Functions}, for the available matrix functions. The
781 remaining operators are described in more detail below.
783 @node Matrix Construction Operator
784 @subsubsection Matrix Construction Operator @t{@{@}}
786 Use the @t{@{}@t{@}} operator to construct matrices. Within
787 the curly braces, commas separate elements within a row and semicolons
788 separate rows. The following examples show a @math{2@times{}3}
789 matrix, a @math{1@times{}4} row vector, a @math{3@times{}1} column
790 vector, and a scalar.
792 @multitable @columnfractions .4 .05 .4
793 @item @t{@{1, 2, 3; 4, 5, 6@}}
797 @t{[1 2 3] @* [4 5 6]}
800 @math{\left(\matrix{1 & 2 & 3 \cr 4 & 5 & 6}\right)}
803 @item @t{@{3.14, 6.28, 9.24, 12.57@}}
807 [3.14 6.28 9.42 12.57]
810 @math{(\matrix{3.14 & 6.28 & 9.42 & 12.57})}
813 @item @t{@{1.41; 1.73; 2@}}
817 @t{[1.41] @* [1.73] @* [2.00]}
820 @math{(\matrix{1.41 & 1.73 & 2.00})}
828 Curly braces are not limited to holding numeric literals. They can
829 contain calculations, and they can paste together matrices and vectors
830 in any way as long as the result is rectangular. For example, if
831 @samp{m} is matrix @code{@{1, 2; 3, 4@}}, @samp{r} is row vector
832 @code{@{5, 6@}}, and @samp{c} is column vector @code{@{7, 8@}}, then
833 curly braces can be used as follows:
835 @multitable @columnfractions .4 .05 .4
836 @item @t{@{m, c; r, 10@}}
840 @t{[1 2 7] @* [3 4 8] @* [5 6 10]}
843 @math{\left(\matrix{1 & 2 & 7 \cr 3 & 4 & 8 \cr 5 & 6 & 10}\right)}
846 @item @t{@{c, 2 * c, T(r)@}}
850 @t{[7 14 5] @* [8 16 6]}
853 @math{\left(\matrix{7 & 14 & 5 \cr 8 & 16 & 6}\right)}
857 The final example above uses the transposition function @code{T}.
859 @node Matrix Sequence Operator
860 @subsubsection Integer Sequence Operator @samp{:}
862 The syntax @code{@var{first}:@var{last}:@var{step}} yields a row
863 vector of consecutive integers from @var{first} to @var{last} counting
864 by @var{step}. The final @code{:@var{step}} is optional and
865 defaults to 1 when omitted.
867 Each of @var{first}, @var{last}, and @var{step} must be a scalar and
868 should be an integer (any fractional part is discarded). Because
869 @samp{:} has a high precedence, operands other than numeric literals
870 must usually be parenthesized.
872 When @var{step} is positive (or omitted) and @math{@var{end} <
873 @var{start}}, or if @var{step} is negative and @math{@var{end} >
874 @var{start}}, then the result is an empty matrix. If @var{step} is 0,
875 then @pspp{} reports an error.
877 Here are some examples:
879 @multitable @columnfractions .4 .05 .4
880 @item @t{1:6} @tab @result{} @tab @t{@{1, 2, 3, 4, 5, 6@}}
881 @item @t{1:6:2} @tab @result{} @tab @t{@{1, 3, 5@}}
882 @item @t{-1:-5:-1} @tab @result{} @tab @t{@{-1, -2, -3, -4, -5@}}
883 @item @t{-1:-5} @tab @result{} @tab @t{@{@}}
884 @item @t{2:1:0} @tab @result{} @tab (error)
887 @node Matrix Index Operator
888 @subsubsection Index Operator @code{()}
890 The result of the submatrix or indexing operator, written
891 @code{@var{m}(@var{rindex}, @var{cindex})}, contains the rows of
892 @var{m} whose indexes are given in vector @var{rindex} and the columns
893 whose indexes are given in vector @var{cindex}.
895 In the simplest case, if @var{rindex} and @var{cindex} are both
896 scalars, the result is also a scalar:
898 @multitable @columnfractions .4 .05 .4
899 @item @t{@{10, 20; 30, 40@}(1, 1)} @tab @result{} @tab @t{10}
900 @item @t{@{10, 20; 30, 40@}(1, 2)} @tab @result{} @tab @t{20}
901 @item @t{@{10, 20; 30, 40@}(2, 1)} @tab @result{} @tab @t{30}
902 @item @t{@{10, 20; 30, 40@}(2, 2)} @tab @result{} @tab @t{40}
905 If the index arguments have multiple elements, then the result
906 includes multiple rows or columns:
908 @multitable @columnfractions .4 .05 .4
909 @item @t{@{10, 20; 30, 40@}(1:2, 1)} @tab @result{} @tab @t{@{10; 30@}}
910 @item @t{@{10, 20; 30, 40@}(2, 1:2)} @tab @result{} @tab @t{@{30, 40@}}
911 @item @t{@{10, 20; 30, 40@}(1:2, 1:2)} @tab @result{} @tab @t{@{10, 20; 30, 40@}}
914 The special argument @samp{:} may stand in for all the rows or columns
915 in the matrix being indexed, like this:
917 @multitable @columnfractions .4 .05 .4
918 @item @t{@{10, 20; 30, 40@}(:, 1)} @tab @result{} @tab @t{@{10; 30@}}
919 @item @t{@{10, 20; 30, 40@}(2, :)} @tab @result{} @tab @t{@{30, 40@}}
920 @item @t{@{10, 20; 30, 40@}(:, :)} @tab @result{} @tab @t{@{10, 20; 30, 40@}}
923 The index arguments do not have to be in order, and they may contain
924 repeated values, like this:
926 @multitable @columnfractions .4 .05 .4
927 @item @t{@{10, 20; 30, 40@}(@{2, 1@}, 1)} @tab @result{} @tab @t{@{30; 10@}}
928 @item @t{@{10, 20; 30, 40@}(2, @{2; 2; 1@})} @tab @result{} @tab @t{@{40, 40, 30@}}
929 @item @t{@{10, 20; 30, 40@}(2:1:-1, :)} @tab @result{} @tab @t{@{30, 40; 10, 20@}}
932 When the matrix being indexed is a row or column vector, only a single
933 index argument is needed, like this:
935 @multitable @columnfractions .4 .05 .4
936 @item @t{@{11, 12, 13, 14, 15@}(2:4)} @tab @result{} @tab @t{@{12, 13, 14@}}
937 @item @t{@{11; 12; 13; 14; 15@}(2:4)} @tab @result{} @tab @t{@{12; 13; 14@}}
940 When an index is not an integer, @pspp{} discards the fractional part.
941 It is an error for an index to be less than 1 or greater than the
942 number of rows or columns:
944 @multitable @columnfractions .4 .05 .4
945 @item @t{@{11, 12, 13, 14@}(@{2.5, 4.6@})} @tab @result{} @tab @t{@{12, 14@}}
946 @item @t{@{11; 12; 13; 14@}(0)} @tab @result{} @tab (error)
949 @node Matrix Unary Operators
950 @subsubsection Unary Operators
952 The unary operators take a single operand of any dimensions and
953 operate on each of its elements independently. The unary operators
958 Inverts the sign of each element.
964 Logical inversion: each positive value becomes 0 and each zero or
965 negative value becomes 1.
970 @multitable @columnfractions .4 .05 .4
971 @item @t{-@{1, -2; 3, -4@}} @tab @result{} @tab @t{@{-1, 2; -3, 4@}}
972 @item @t{+@{1, -2; 3, -4@}} @tab @result{} @tab @t{@{1, -2; 3, -4@}}
973 @item @t{NOT @{1, 0; -1, 1@}} @tab @result{} @tab @t{@{0, 1; 1, 0@}}
976 @node Matrix Elementwise Binary Operators
977 @subsubsection Elementwise Binary Operators
979 The elementwise binary operators require their operands to be matrices
980 with the same dimensions. Alternatively, if one operand is a scalar,
981 then its value is treated as if it were duplicated to the dimensions
982 of the other operand. The result is a matrix of the same size as the
983 operands, in which each element is the result of the applying the
984 operator to the corresponding elements of the operands.
986 The elementwise binary operators are listed below.
990 The arithmetic operators, for familiar arithmetic operations:
1000 Multiplication, if one operand is a scalar. (Otherwise this is matrix
1001 multiplication, described below.)
1003 @item @code{/} or @code{&/}
1014 The relational operators, whose results are 1 when a comparison is
1015 true and 0 when it is false:
1018 @item @code{<} or @code{LT}
1021 @item @code{<=} or @code{LE}
1024 @item @code{=} or @code{EQ}
1027 @item @code{>} or @code{GT}
1030 @item @code{>=} or @code{GE}
1031 Greater than or equal.
1033 @item @code{<>} or @code{~=} or @code{NE}
1038 The logical operators, which treat positive operands as true and
1039 nonpositive operands as false. They yield 0 for false and 1 for true:
1043 True if both operands are true.
1046 True if at least one operand is true.
1049 True if exactly one operand is true.
1055 @multitable @columnfractions .4 .05 .4
1056 @item @t{1 + 2} @tab @result{} @tab @t{3}
1057 @item @t{1 + @{3; 4@}} @tab @result{} @tab @t{@{4; 5@}}
1058 @item @t{@{66, 77; 88, 99@} + 5} @tab @result{} @tab @t{@{71, 82; 93, 104@}}
1059 @item @t{@{4, 8; 3, 7@} + @{1, 0; 5, 2@}} @tab @result{} @tab @t{@{5, 8; 8, 9@}}
1060 @item @t{@{1, 2; 3, 4@} < @{4, 3; 2, 1@}} @tab @result{} @tab @t{@{1, 1; 0, 0@}}
1061 @item @t{@{1, 3; 2, 4@} >= 3} @tab @result{} @tab @t{@{0, 1; 0, 1@}}
1062 @item @t{@{0, 0; 1, 1@} AND @{0, 1; 0, 1@}} @tab @result{} @tab @t{@{0, 0; 0, 1@}}
1065 @node Matrix Multiplication Operator
1066 @subsubsection Matrix Multiplication Operator @samp{*}
1068 If @code{A} is an @math{@var{m}@times{}@var{n}} matrix and @code{B} is
1069 an @math{@var{n}@times{}@var{p}} matrix, then @code{A*B} is the
1070 @math{@var{m}@times{}@var{p}} matrix multiplication product @code{C}.
1071 @pspp{} reports an error if the number of columns in @code{A} differs
1072 from the number of rows in @code{B}.
1074 The @code{*} operator performs elementwise multiplication (see above)
1075 if one of its operands is a scalar.
1077 No built-in operator yields the inverse of matrix multiplication.
1078 Instead, multiply by the result of @code{INV} or @code{GINV}.
1082 @multitable @columnfractions .4 .05 .4
1083 @item @t{@{1, 2, 3@} * @{4; 5; 6@}} @tab @result{} @tab @t{32}
1084 @item @t{@{4; 5; 6@} * @{1, 2, 3@}} @tab @result{} @tab @t{@{4,@w{ } 8, 12; @*@w{ }5, 10, 15; @*@w{ }6, 12, 18@}}
1087 @node Matrix Exponentiation Operator
1088 @subsubsection Matrix Exponentiation Operator @code{**}
1090 The result of @code{A**B} is defined as follows when @code{A} is a
1091 square matrix and @code{B} is an integer scalar:
1095 For @code{B > 0}, @code{A**B} is @code{A*@dots{}*A}, where there are
1096 @code{B} @samp{A}s. (@pspp{} implements this efficiently for large
1097 @code{B}, using exponentiation by squaring.)
1100 For @code{B < 0}, @code{A**B} is @code{INV(A**(-B))}.
1103 For @code{B = 0}, @code{A**B} is the identity matrix.
1107 @pspp{} reports an error if @code{A} is not square or @code{B} is not
1112 @multitable @columnfractions .4 .05 .4
1113 @item @t{@{2, 5; 1, 4@}**3} @tab @result{} @tab @t{@{48, 165; 33, 114@}}
1114 @item @t{@{2, 5; 1, 4@}**0} @tab @result{} @tab @t{@{1, 0; 0, 1@}}
1115 @item @t{10*@{4, 7; 2, 6@}**-1} @tab @result{} @tab @t{@{6, -7; -2, 4@}}
1118 @node Matrix Functions
1119 @subsection Matrix Functions
1121 The matrix language support numerous functions in multiple categories.
1122 The following subsections document each of the currently supported
1123 functions. The first letter of each parameter's name indicate the
1124 required argument type:
1131 A nonnegative integer scalar. (Non-integers are accepted and silently
1132 rounded down to the nearest integer.)
1135 A row or column vector.
1141 @node Matrix Elementwise Functions
1142 @subsubsection Elementwise Functions
1144 These functions act on each element of their argument independently,
1145 like the elementwise operators (@pxref{Matrix Elementwise Binary
1148 @deffn {Matrix Function} ABS (@var{M})
1149 Takes the absolute value of each element of @var{M}.
1151 @t{ABS(@{-1, 2; -3, 0@}) @result{} @{1, 2; 3, 0@}}
1154 @deffn {Matrix Function} ARSIN (@var{M})
1155 @deffnx {Matrix Function} ARTAN (@var{M})
1156 Computes the inverse sine or tangent, respectively, of each element in
1157 @var{M}. The results are in radians, between @math{-\pi/2} and
1158 @math{+\pi/2}, inclusive.
1160 The value of @math{\pi} can be computed as @code{4*ARTAN(1)}.
1163 @deffn {Matrix Function} COS (@var{M})
1164 @deffnx {Matrix Function} SIN (@var{M})
1165 Computes the cosine or sine, respectively, of each element in @var{M},
1166 which must be in radians.
1169 @deffn {Matrix Function} EXP (@var{M})
1170 Computes @math{e^x} for each element @var{x} in @var{M}.
1173 @deffn {Matrix Function} LG10 (@var{M})
1174 @deffnx {Matrix Function} LN (@var{M})
1175 Takes the logarithm with base 10 or base @math{e}, respectively, of
1176 each element in @var{M}.
1179 @deffn {Matrix Function} MOD (@var{M}, @var{s})
1180 Takes each element in @var{M} modulo nonzero scalar value @var{s},
1181 that is, the remainder of division by @var{s}. The sign of the result
1182 is the same as the sign of the dividend.
1185 @deffn {Matrix Function} RND (@var{M})
1186 @deffnx {Matrix Function} TRUNC (@var{M})
1187 Rounds each element of @var{M} to an integer. @code{RND} rounds to
1188 the nearest integer, with halves rounded to even integers, and
1189 @code{TRUNC} rounds toward zero.
1192 @deffn {Matrix Function} SQRT (@var{M})
1193 Takes the square root of each element of @var{M}, which must not be
1197 @node Matrix Logical Functions
1198 @subsubsection Logical Functions
1200 @deffn {Matrix Function} ALL (@var{M})
1201 Returns a scalar with value 1 if all of the elements in @var{M} are
1202 nonzero, or 0 if at least one element is zero.
1205 @deffn {Matrix Function} ANY (@var{M})
1206 Returns a scalar with value 1 if any of the elements in @var{M} is
1207 nonzero, or 0 if all of them are zero.
1210 @node Matrix Construction Functions
1211 @subsubsection Matrix Construction Functions
1213 @deffn {Matrix Function} BLOCK (@var{M1}, @dots{}, @var{Mn})
1214 Returns a block diagonal matrix with as many rows as the sum of its
1215 arguments' row counts and as many columns as the sum of their columns.
1216 Each argument matrix is placed along the main diagonal of the result,
1217 and all other elements are zero.
1220 @deffn {Matrix Function} IDENT (@var{n})
1221 @deffnx {Matrix Function} IDENT (@var{nr}, @var{nc})
1222 Returns an identity matrix, whose main diagonal elements are one and
1223 whose other elements are zero. The returned matrix has @var{n} rows
1224 and columns or @var{nr} rows and @var{nc} columns, respectively.
1227 @deffn {Matrix Function} MAGIC (@var{n})
1228 Returns an @math{@var{n}@times{}@var{n}} matrix that contains each of
1229 the integers @math{1@dots{}@var{n}} once, in which each column, each
1230 row, and each diagonal sums to @math{n(n^2+1)/2}. There are many
1231 magic squares with given dimensions, but this function always returns
1232 the same one for a given value of @var{n}.
1235 @deffn {Matrix Function} MAKE (@var{nr}, @var{nc}, @var{s})
1236 Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements are
1240 @deffn {Matrix Function} MDIAG (@var{V})
1241 Returns a @math{|@var{V}|@times{}|@var{V}|} matrix whose main diagonal
1242 comes from @var{V} and whose other elements are zero.
1245 @deffn {Matrix Function} RESHAPE (@var{M}, @var{nr}, @var{nc})
1246 Returns an @math{@var{nr}@times{}@var{nc}} matrix whose elements come
1247 from @var{M}, which must have the same number of elements as the new
1248 matrix, copying elements from @var{M} to the new matrix row by row.
1251 @deffn {Matrix Function} T (@var{M})
1252 @deffnx {Matrix Function} TRANSPOS (@var{M})
1253 Returns @var{M} with rows exchanged for columns.
1256 @deffn {Matrix Function} UNIFORM (@var{nr}, @var{nc})
1257 Returns a @math{@var{nr}@times{}@var{nc}} matrix in which each element
1258 is randomly chosen from a uniform distribution of real numbers between
1262 @node Matrix Minimum and Maximum and Sum Functions
1263 @subsubsection Minimum, Maximum, and Sum Functions
1265 @deffn {Matrix Function} CMIN (@var{M})
1266 @deffnx {Matrix Function} CMAX (@var{M})
1267 @deffnx {Matrix Function} CSUM (@var{M})
1268 @deffnx {Matrix Function} CSSQ (@var{M})
1269 Returns a row vector with the same number of columns as @var{M}, in
1270 which each element is the minimum, maximum, sum, or sum of squares,
1271 respectively, of the elements in the same column of @var{M}.
1274 @deffn {Matrix Function} MMIN (@var{M})
1275 @deffnx {Matrix Function} MMAX (@var{M})
1276 @deffnx {Matrix Function} MSUM (@var{M})
1277 @deffnx {Matrix Function} MSSQ (@var{M})
1278 Returns the minimum, maximum, sum, or sum of squares, respectively, of
1279 the elements of @var{M}.
1282 @deffn {Matrix Function} RMIN (@var{M})
1283 @deffnx {Matrix Function} RMAX (@var{M})
1284 @deffnx {Matrix Function} RSUM (@var{M})
1285 @deffnx {Matrix Function} RSSQ (@var{M})
1286 Returns a column vector with the same number of rows as @var{M}, in
1287 which each element is the minimum, maximum, sum, or sum of squares,
1288 respectively, of the elements in the same row of @var{M}.
1291 @deffn {Matrix Function} SSCP (@var{M})
1292 Returns @math{@var{M}^T @times{} @var{M}}.
1295 @deffn {Matrix Function} TRACE (@var{M})
1296 Returns the sum of the elements along @var{M}'s main diagonal,
1297 equivalent to @code{MSUM(DIAG(@var{M}))}.
1301 @node Matrix Property Functions
1302 @subsubsection Matrix Property Functions
1304 @deffn {Matrix Function} NROW (@var{M})
1305 @deffnx {Matrix Function} NCOL (@var{M})
1306 Returns the number of row or columns, respectively, in @var{M}.
1309 @deffn {Matrix Function} DIAG (@var{M})
1310 Returns a column vector containing a copy of @var{M}'s main diagonal.
1311 The vector's length is the lesser of @code{NCOL(@var{M})} and
1312 @code{NROW(@var{M})}.
1315 @node Matrix Rank Ordering Functions
1316 @subsubsection Matrix Rank Ordering Functions
1318 The @code{GRADE} and @code{RANK} functions each take a matrix @var{M}
1319 and return a matrix @var{r} with the same dimensions. Each element in
1320 @var{r} ranges between 1 and the number of elements @var{n} in
1321 @var{M}, inclusive. When the elements in @var{M} all have unique
1322 values, both of these functions yield the same results: the smallest
1323 element in @var{M} corresponds to value 1 in @var{r}, the next
1324 smallest to 2, and so on, up to the largest to @var{n}. When multiple
1325 elements in @var{M} have the same value, these functions use different
1326 rules for handling the ties.
1328 @deffn {Matrix Function} GRADE (@var{M})
1329 Returns a ranking of @var{M}, turning duplicate values into sequential
1330 ranks. The returned matrix always contains each of the integers 1
1331 through the number of elements in the matrix exactly once.
1333 @t{GRADE(@{1, 0, 3; 3, 1, 2; 3, 0, 5@})} @result{} @t{@{3, 1, 6; 7, 4, 5; 8, 2, 9@}}
1336 @deffn {Matrix Function} RNKORDER (@var{M})
1337 Returns a ranking of @var{M}, turning duplicate values into the mean
1338 of their sequential ranks.
1340 @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@}}
1344 One may use @code{GRADE} to sort a vector:
1347 COMPUTE v(GRADE(v))=v. /* Sort v in ascending order.
1348 COMPUTE v(GRADE(-v))=v. /* Sort v in descending order.
1351 @node Matrix Algebra Functions
1352 @subsubsection Matrix Algebra Functions
1354 @deffn {Matrix Function} CHOL (@var{M})
1355 Matrix @var{M} must be an @math{@var{n}@times{}@var{n}} symmetric
1356 positive-definite matrix. Returns an @math{@var{n}@times{}@var{n}}
1357 matrix @var{B} such that @math{@var{B}^T@times{}@var{B}=@var{M}}.
1360 @deffn {Matrix Function} DESIGN (@var{M})
1361 Returns a design matrix for @var{M}. The design matrix has the same
1362 number of rows as @var{M}. Each column @var{c} in @var{M}, from left
1363 to right, yields a group of columns in the output. For each unique
1364 value @var{v} in @var{c}, from top to bottom, add a column to the
1365 output in which @var{v} becomes 1 and other values become 0.
1367 @pspp{} issues a warning if a column only contains a single unique value.
1370 @t{DESIGN(@{1; 2; 3@}) @result{} @{1, 0, 0; 0, 1, 0; 0, 0, 1@}}
1371 @t{DESIGN(@{5; 8; 5@}) @result{} @{1, 0; 0, 1; 1, 0@}}
1372 @t{DESIGN(@{1, 5; 2, 8; 3, 5@})}
1373 @result{} @t{@{1, 0, 0, 1, 0; 0, 1, 0, 0, 1; 0, 0, 1, 1, 0@}}
1374 @t{DESIGN(@{5; 5; 5@})} @result{} (warning)
1378 @deffn {Matrix Function} DET (@var{M})
1379 Returns the determinant of square matrix @var{M}.
1382 @deffn {Matrix Function} EVAL (@var{M})
1383 Returns a column vector containing the eigenvalues of symmetric matrix
1384 @var{M}, sorted in ascending order.
1386 Use @code{CALL EIGEN} (@pxref{CALL EIGEN}) to compute eigenvalues and
1387 eigenvectors of a matrix.
1390 @deffn {Matrix Function} GINV (@var{M})
1391 Returns the @math{@var{k}@times{}@var{n}} matrix @var{A} that is the
1392 @dfn{generalized inverse} of @math{@var{n}@times{}@var{k}} matrix
1393 @var{M}, defined such that
1394 @math{@var{M}@times{}@var{A}@times{}@var{M}=@var{M}} and
1395 @math{@var{A}@times{}@var{M}@times{}@var{A}=@var{A}}.
1399 @deffn {Matrix Function} GSCH (@var{M})
1403 @deffn {Matrix Function} INV (@var{M})
1404 Returns the @math{@var{n}@times{}@var{n}} matrix @var{A} that is the
1405 inverse of @math{@var{n}@times{}@var{n}} matrix @var{M}, defined such
1406 that @math{@var{M}@times{}@var{A} = @var{A}@times{}@var{M} = I}, where
1407 @var{I} is the identity matrix. @var{M} must not be singular, that
1408 is, @math{\det(@var{M}) \ne 0}.
1411 @deffn {Matrix Function} KRONEKER (@var{Ma}, @var{Mb})
1412 Returns the @math{@var{pm}@times{}@var{qn}} matrix @var{P} that is the
1413 @dfn{Kroneker product} of @math{@var{m}@times{}@var{n}} matrix
1414 @var{Ma} and @math{@var{p}@times{}@var{q}} matrix @var{Mb}. One may
1415 view @var{P} as the concatenation of multiple
1416 @math{@var{p}@times{}@var{q}} blocks, each of which is the scalar
1417 product of @var{Mb} by a different element of @var{Ma}. For example,
1418 when @code{A} is a @math{2@times{}2} matrix, @code{KRONEKER(A, B)} is
1419 equivalent to @code{@{A(1,1)*B, A(1,2)*B; A(2,1)*B, A(2,2)*B@}}.
1422 @deffn {Matrix Function} RANK (@var{M})
1423 Returns the rank of matrix @var{M}, a integer scalar whose value is
1424 the dimension of the vector space spanned by its columns or,
1425 equivalently, by its rows.
1428 @deffn {Matrix Function} SOLVE (@var{Ma}, @var{Mb})
1432 @deffn {Matrix Function} SVAL (@var{M})
1436 @deffn {Matrix Function} SWEEP (@var{M}, @var{n})
1443 @deffn {Matrix Function} EOF (@var{file})
1446 @node Matrix CALL command
1447 @subsection The @code{CALL} Command