X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fmatrices.texi;h=1f650c773c83f55b08865d4cb9eb2c0df3cf3083;hb=5f379b736b5797b0583e99652d51a35a23ba38f8;hp=83eccb8d62a7edde2361e2adbb3addb04d31b97c;hpb=45c2e0a826edbc00a4ea916338668271d5d2edf2;p=pspp diff --git a/doc/matrices.texi b/doc/matrices.texi index 83eccb8d62..1f650c773c 100644 --- a/doc/matrices.texi +++ b/doc/matrices.texi @@ -613,9 +613,6 @@ Use @cmd{MATRIX DATA} to convert text input into matrix file format. @vindex MATRIX @vindex END MATRIX -@node Matrix Overview -@subsection Overview - @display @t{MATRIX.} @dots{}@i{matrix commands}@dots{} @@ -626,86 +623,83 @@ Use @cmd{MATRIX DATA} to convert text input into matrix file format. The following basic matrix commands are supported: @display -@t{COMPUTE} @i{variable}[(@i{index}[,@i{index}])]=@i{expression}. -@t{CALL} @i{procedure}(@i{argument}, @dots{}). +@t{COMPUTE} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]@t{=}@i{expression}@t{.} +@t{CALL} @i{procedure}@t{(}@i{argument}@t{,} @dots{}). @t{PRINT} [@i{expression}] - [/@t{FORMAT}=@i{format}] - [/@t{TITLE}=@i{title}] - [/@t{SPACE}=@{@t{NEWPAGE} @math{|} @i{n}@}] - [@{/@t{RLABELS}=@i{string}@dots{} @math{|} /@t{RNAMES}=@i{expression}@}] - [@{/@t{CLABELS}=@i{string}@dots{} @math{|} /@t{CNAMES}=@i{expression}@}]. + [@t{/FORMAT}@t{=}@i{format}] + [@t{/TITLE}@t{=}@i{title}] + [@t{/SPACE}@t{=}@{@t{NEWPAGE} @math{|} @i{n}@}] + [@{@t{/RLABELS}@t{=}@i{string}@dots{} @math{|} @t{/RNAMES}@t{=}@i{expression}@}] + [@{@t{/CLABELS}@t{=}@i{string}@dots{} @math{|} @t{/CNAMES}@t{=}@i{expression}@}]@t{.} @end display @noindent The following matrix commands offer support for flow control: @display -@t{DO IF} @i{expression}. +@t{DO IF} @i{expression}@t{.} @dots{}@i{matrix commands}@dots{} -[@t{ELSE IF} @i{expression}. +[@t{ELSE IF} @i{expression}@t{.} @dots{}@i{matrix commands}@dots{}]@dots{} [@t{ELSE} @dots{}@i{matrix commands}@dots{}] -@t{END IF}. +@t{END IF}@t{.} -@t{LOOP} [@i{var}=@i{first} @t{TO} @i{last} [@t{BY} @i{step}]] [@t{IF} @i{expression}]. +@t{LOOP} [@i{var}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{step}]] [@t{IF} @i{expression}]@t{.} @dots{}@i{matrix commands}@dots{} -@t{END LOOP} [@t{IF} @i{expression}]. +@t{END LOOP} [@t{IF} @i{expression}]@t{.} -@t{BREAK}. +@t{BREAK}@t{.} @end display @noindent The following matrix commands support matrix input and output: @display -@t{READ} @i{variable}[(@i{index}[,@i{index}])] - [/@t{FILE}=@i{file}] - /@t{FIELD}=@i{first} @t{TO} @i{last} [@t{BY} @i{width}] - [/@t{SIZE}=@i{expression}] - [/@t{MODE}=@{@t{RECTANGULAR} @math{|} @t{SYMMETRIC}@}] - [/@t{REREAD}] - [/@t{FORMAT}=@i{format}]. +@t{READ} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}] + [@t{/FILE}@t{=}@i{file}] + @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}] + [@t{/FORMAT}@t{=}@i{format}] + [@t{/SIZE}@t{=}@i{expression}] + [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{SYMMETRIC}@}] + [@t{/REREAD}]@t{.} @t{WRITE} @i{expression} - [/@t{OUTFILE}=@i{file}] - /@t{FIELD}=@i{first} @t{TO} @i{last} [@t{BY} @i{width}] - [/@t{MODE}=@{@t{RECTANGULAR} @math{|} @t{TRIANGULAR}@}] - [/@t{HOLD}] - [/@t{FORMAT}=@i{format}]. -@t{GET} @i{variable}[(@i{index}[,@i{index}])] - [/@t{FILE}=@{@i{file} @math{|} @t{*}@}] - [/@t{VARIABLES}=@i{variable}@dots{}] - [/@t{NAMES}=@i{expression}] - [/@t{MISSING}=@{@t{ACCEPT} @math{|} @t{OMIT} @math{|} @i{number}@}] - [/@t{SYSMIS}=@{@t{OMIT} @math{|} @i{number}@}]. + [@t{/OUTFILE}@t{=}@i{file}] + @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}] + [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{TRIANGULAR}@}] + [@t{/HOLD}] + [@t{/FORMAT}@t{=}@i{format}]@t{.} +@t{GET} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}] + [@t{/FILE}@t{=}@{@i{file} @math{|} @t{*}@}] + [@t{/VARIABLES}@t{=}@i{variable}@dots{}] + [@t{/NAMES}@t{=}@i{expression}] + [@t{/MISSING}@t{=}@{@t{ACCEPT} @math{|} @t{OMIT} @math{|} @i{number}@}] + [@t{/SYSMIS}@t{=}@{@t{OMIT} @math{|} @i{number}@}]@t{.} @t{SAVE} @i{expression} - [/@t{OUTFILE}=@{@i{file} @math{|} @t{*}@}] - [/@t{VARIABLES}=@i{variable}@dots{}] - [/@t{NAMES}=@i{expression}] - [/@t{STRINGS}=@i{variable}@dots{}]. -@t{MGET} [/@t{FILE}=@i{file}] - [/@t{TYPE}=@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}]. + [@t{/OUTFILE}@t{=}@{@i{file} @math{|} @t{*}@}] + [@t{/VARIABLES}@t{=}@i{variable}@dots{}] + [@t{/NAMES}@t{=}@i{expression}] + [@t{/STRINGS}@t{=}@i{variable}@dots{}]@t{.} +@t{MGET} [@t{/FILE}@t{=}@i{file}] + [@t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}]@t{.} @t{MSAVE} @i{expression} - /@t{TYPE}=@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@} - [/@t{OUTFILE}=@i{file}] - [/@t{VARIABLES}=@i{variable}@dots{}] - [/@t{SNAMES}=@i{variable}@dots{}] - [/@t{SPLIT}=@i{expression}] - [/@t{FNAMES}=@i{variable}@dots{}] - [/@t{FACTOR}=@i{expression}]. + @t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@} + [@t{/OUTFILE}@t{=}@i{file}] + [@t{/VARIABLES}@t{=}@i{variable}@dots{}] + [@t{/SNAMES}@t{=}@i{variable}@dots{}] + [@t{/SPLIT}@t{=}@i{expression}] + [@t{/FNAMES}@t{=}@i{variable}@dots{}] + [@t{/FACTOR}@t{=}@i{expression}]@t{.} @end display @noindent The following matrix commands provide additional support: @display -@t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}]. -@t{RELEASE} @i{variable}@dots{}. +@t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}]@t{.} +@t{RELEASE} @i{variable}@dots{}@t{.} @end display -@node Matrix Introduction -@subsection Introduction - @code{MATRIX} and @code{END MATRIX} enclose a special @pspp{} sub-language, called the matrix language. The matrix language does not require an active dataset to be defined and only a few of the @@ -734,8 +728,21 @@ matrix language represents a single matrix. The matrix language does not support missing values. -@node Matrix Operators -@subsection Matrix Operators +@code{MATRIX} is a procedure, so it cannot be enclosed inside @code{DO +IF}, @code{LOOP}, etc. + +Macros may be used within a matrix program, and macros may expand to +include entire matrix programs. The @code{DEFINE} command may not +appear within a matrix program. @xref{DEFINE}, for more information +about macros. + +The following sections describe the details of the matrix language: +first, the syntax of matrix expressions, then each of the supported +commands. The @code{COMMENT} command (@pxref{COMMENT}) is also +supported. + +@node Matrix Expressions +@subsection Matrix Expressions Many matrix commands use expressions. A matrix expression may use the following operators, listed in descending order of operator @@ -780,6 +787,13 @@ Logical @t{OR} and @t{XOR} @xref{Matrix Functions}, for the available matrix functions. The remaining operators are described in more detail below. +@cindex restricted expressions +Expressions appear in the matrix language in some contexts where there +would be ambiguity whether @samp{/} is an operator or a separator +between subcommands. In these contexts, only the operators with +higher precedence than @samp{/} are allowed outside parentheses. +Later sections call these @dfn{restricted expressions}. + @node Matrix Construction Operator @subsubsection Matrix Construction Operator @t{@{@}} @@ -1238,8 +1252,12 @@ all @var{s}. @end deffn @deffn {Matrix Function} MDIAG (@var{V}) -Returns a @math{|@var{V}|@times{}|@var{V}|} matrix whose main diagonal -comes from @var{V} and whose other elements are zero. +@anchor{MDIAG} Given @var{n}-element vector @var{V}, returns a +@math{@var{n}@times{}@var{n}} matrix whose main diagonal is copied +from @var{V}. The other elements in the returned vector are zero. + +Use @code{CALL SETDIAG} (@pxref{CALL SETDIAG}) to replace the main +diagonal of a matrix in-place. @end deffn @deffn {Matrix Function} RESHAPE (@var{M}, @var{nr}, @var{nc}) @@ -1380,6 +1398,7 @@ Returns the determinant of square matrix @var{M}. @end deffn @deffn {Matrix Function} EVAL (@var{M}) +@anchor{EVAL} Returns a column vector containing the eigenvalues of symmetric matrix @var{M}, sorted in ascending order. @@ -1397,15 +1416,18 @@ Returns the @math{@var{k}@times{}@var{n}} matrix @var{A} that is the @deffn {Matrix Function} GSCH (@var{M}) +@var{M} must be a @math{@var{n}@times{}@var{m}} matrix, @math{@var{m} +@geq{} @var{n}}, with rank @var{n}. Returns an +@math{@var{n}@times{}@var{n}} orthonormal basis for @var{M}, obtained +using the Gram-Schmidt process. @end deffn - @deffn {Matrix Function} INV (@var{M}) Returns the @math{@var{n}@times{}@var{n}} matrix @var{A} that is the inverse of @math{@var{n}@times{}@var{n}} matrix @var{M}, defined such that @math{@var{M}@times{}@var{A} = @var{A}@times{}@var{M} = I}, where @var{I} is the identity matrix. @var{M} must not be singular, that -is, @math{\det(@var{M}) \ne 0}. +is, @math{\det(@var{M}) @ne{} 0}. @end deffn @deffn {Matrix Function} KRONEKER (@var{Ma}, @var{Mb}) @@ -1420,30 +1442,708 @@ equivalent to @code{@{A(1,1)*B, A(1,2)*B; A(2,1)*B, A(2,2)*B@}}. @end deffn @deffn {Matrix Function} RANK (@var{M}) +Returns the rank of matrix @var{M}, a integer scalar whose value is +the dimension of the vector space spanned by its columns or, +equivalently, by its rows. @end deffn +@deffn {Matrix Function} SOLVE (@var{Ma}, @var{Mb}) +@var{Ma} must be an @math{@var{n}@times{}@var{n}} matrix, with +@math{\det(@var{Ma}) @ne{} 0}, and @var{Mb} an +@math{@var{n}@times{}@var{k}} matrix. Returns an +@math{@var{n}@times{}@var{k}} matrix @var{X} such that @math{@var{Ma} +@times{} @var{X} = @var{Mb}}. +@end deffn +@deffn {Matrix Function} SVAL (@var{M}) +@anchor{SVAL} +Given @math{@var{n}@times{}@var{k}} matrix @var{M}, returns a +@math{\min(@var{n},@var{k})}-element column vector containing the +singular values of @var{M} in descending order. -@deffn {Matrix Function} SOLVE (@var{Ma}, @var{Mb}) +Use @code{CALL SVD} (@pxref{CALL SVD}) to compute the full singular +value decomposition of a matrix. @end deffn +@deffn {Matrix Function} SWEEP (@var{M}, @var{nk}) +Given @math{@var{r}@times{}@var{c}} matrix @var{M} and integer scalar +@math{k = @var{nk}} such that @math{1 @leq{} k @leq{} +\min(@var{r},@var{c})}, returns the @math{@var{r}@times{}@var{c}} +sweep matrix @var{A}. -@deffn {Matrix Function} SVAL (@var{M}) -@end deffn +If @math{@var{M}_{kk} @ne{} 0}, then: +@display +@math{@var{A}_{kk} = 1/@var{M}_{kk}}, +@math{@var{A}_{ik} = -@var{M}_{ik}/@var{M}_{kk} @r{for} i @ne{} k}, +@math{@var{A}_{kj} = @var{M}_{kj}/@var{M}_{kk} @r{for} j @ne{} k, @r{and}} +@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}. +@end display -@deffn {Matrix Function} SWEEP (@var{M}, @var{n}) -@end deffn +If @math{@var{M}_{kk} = 0}, then: +@display +@math{@var{A}_{ik} = @var{A}_{ki} = 0 @r{and}} +@math{@var{A}_{ij} = @var{M}_{ij}, @r{for} i @ne{} k @r{and} j @ne{} k}. +@end display +@end deffn @node Matrix IO @subsubsection I/O @deffn {Matrix Function} EOF (@var{file}) +@anchor{EOF Matrix Function} + +Given a file handle or file name @var{file}, returns an integer scalar +that indicates whether the last record in the file has been read. +Determining this requires attempting reading past the current record, +which means that @code{REREAD} on the next @code{READ} command +following @code{EOF} on the same file will be ineffective. @end deffn +@node Matrix COMPUTE Command +@subsection The @code{COMPUTE} Command + +@display +@t{COMPUTE} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}]@t{=}@i{expression}@t{.} +@end display + +The @code{COMPUTE} command evaluates an expression and assigns the +result to a variable or a submatrix of a variable. Assigning to a +submatrix uses the same syntax as the index operator (@pxref{Matrix +Index Operator}). + @node Matrix CALL command @subsection The @code{CALL} Command +A matrix function returns a single result. The @code{CALL} command +implements procedures, which take a similar syntactic form to +functions but yield results by modifying their arguments rather than +returning a value. + +Output arguments to a @code{CALL} procedure must be a single variable +name. + +The following procedures are implemented via @code{CALL} to allow them +to return multiple results. For these procedures, the output +arguments need not name existing variables; if they do, then their +previous values are replaced: + +@table @asis +@item @t{CALL EIGEN(@var{M}, @var{evec}, @var{eval})} @anchor{CALL EIGEN} + +Computes the eigenvalues and eigenvector of symmetric +@math{@var{n}@times{}@var{n}} matrix @var{M}. Assigns the +eigenvectors of @var{M} to the columns of +@math{@var{n}@times{}@var{n}} matrix @var{evec} and the eigenvalues in +descending order to @var{n}-element column vector @var{eval}. + +Use the @code{EVAL} function (@pxref{EVAL}) to compute just the +eigenvalues of a symmetric matrix. + +@item @t{CALL SVD(@var{M}, @var{U}, @var{S}, @var{V})} +@anchor{CALL SVD} + +Computes the singular value decomposition of +@math{@var{n}@times{}@var{k}} matrix @var{M}, assigning @var{S} a +@math{@var{n}@times{}@var{k}} diagonal matrix and to @var{U} and +@var{V} unitary @math{@var{k}@times{}@var{k}} matrices such that +@math{@var{M} = @var{U}@times{}@var{S}@times{}@var{V}^T}. The main +diagonal of @var{Q} contains the singular values of @var{M}. + +Use the @code{SVAL} function (@pxref{SVAL}) to compute just the +singular values of a matrix. +@end table + +The final procedure is implemented via @code{CALL} to allow it to +modify a matrix instead of returning a modified version. For this +procedure, the output argument must name an existing variable. + +@table @asis +@item @t{CALL SETDIAG(@var{M}, @var{V})} +@anchor{CALL SETDIAG} + +Replaces the main diagonal of @math{@var{n}@times{}@var{p}} matrix +@var{M} by the contents of @var{k}-element vector @var{V}. If +@math{@var{k} = 1}, so that @var{V} is a scalar, replaces all of the +diagonal elements of @var{M} by @var{V}. If @math{@var{k} < +\min(@var{n},@var{p})}, only the upper @var{k} diagonal elements are +replaced; if @math{@var{k} > \min(@var{n},@var{p})}, then the +extra elements of @var{V} are ignored. + +Use the @code{MDIAG} function (@pxref{MDIAG}) to construct a new +matrix with a specified main diagonal. +@end table + +@node Matrix PRINT Command +@subsection The @code{PRINT} Command + +@display +@t{PRINT} [@i{expression}] + [@t{/FORMAT}@t{=}@i{format}] + [@t{/TITLE}@t{=}@i{title}] + [@t{/SPACE}@t{=}@{@t{NEWPAGE} @math{|} @i{n}@}] + [@{@t{/RLABELS}@t{=}@i{string}@dots{} @math{|} @t{/RNAMES}@t{=}@i{expression}@}] + [@{@t{/CLABELS}@t{=}@i{string}@dots{} @math{|} @t{/CNAMES}@t{=}@i{expression}@}]@t{.} +@end display + +The @code{PRINT} command is commonly used to display a matrix. It +evaluates the restricted @var{expression}, if present, and outputs it +either as text or a pivot table, depending on the setting of +@code{MDISPLAY} (@pxref{SET MDISPLAY}). + +Use the @code{FORMAT} subcommand to specify a format, such as +@code{F8.2}, for displaying the matrix elements. @code{FORMAT} is +optional for numerical matrices. When it is omitted, @pspp{} chooses +how to format entries automatically using @var{m}, the magnitude of +the largest-magnitude element in the matrix to be displayed: + +@enumerate +@item +If the matrix's elements are all integers, then, if possible, @pspp{} +chooses the narrowest @code{F} format with width 12 or less that fits +@var{m} plus a sign. + +@item +Otherwise, if @math{@var{m} @geq{} 10^9} or @math{@var{m} @leq{} +10^{-4}}, @pspp{} scales all of the numbers in the matrix by +@math{10^x}, where @var{x} is the exponent used when @var{m} is +displayed in scientific notation, and displays the scaled value in +format @code{F13.10}. @pspp{} adds a note to the output to indicate +the scale factor. + +@item +Otherwise, @pspp{} displays the value, without scaling, in format +@code{F13.10}. +@end enumerate + +The optional @code{TITLE} subcommand specifies a title for the output +text or table, as a quoted string. When it is omitted, the syntax of +the matrix expression is used as the title. + +Use the @code{SPACE} subcommand to request extra space above the +matrix output. With a numerical argument, it adds the specified +number of lines of blank space above the matrix. With @code{NEWPAGE} +as an argument, it prints the matrix at the top of a new page. The +@code{SPACE} subcommand has no effect when a matrix is output as a +pivot table. + +The @code{RLABELS} and @code{RNAMES} subcommands, which are mutually +exclusive, can supply a label to accompany each row in the output. +With @code{RLABELS}, specify the labels as comma-separated strings or +other tokens. With @code{RNAMES}, specify a single expression that +evaluates to a vector of strings. Either way, if there are more +labels than rows, the extra labels are ignored, and if there are more +rows than labels, the extra rows are unlabeled. For output to a pivot +table with @code{RLABELS}, the labels can be any length; otherwise, +the labels are truncated to 8 bytes. + +The @code{CLABELS} and @code{CNAMES} subcommands work for labeling +columns as @code{RLABELS} and @code{RNAMES} do for labeling rows. + +@subsubheading Text Output + +When the @var{expression} is omitted, @code{PRINT} does not output a +matrix. Instead, it outputs only the text specified on @code{TITLE}, +if any, preceded by any space specified on the @code{SPACE} +subcommand, if any. Any other subcommands are ignored, and the +command acts as if @code{MDISPLAY} is set to @code{TEXT} regardless of +its actual setting. + +@node Matrix DO IF Command +@subsection The @code{DO IF} Command + +@display +@t{DO IF} @i{expression}@t{.} + @dots{}@i{matrix commands}@dots{} +[@t{ELSE IF} @i{expression}@t{.} + @dots{}@i{matrix commands}@dots{}]@dots{} +[@t{ELSE} + @dots{}@i{matrix commands}@dots{}] +@t{END IF}@t{.} +@end display + +A @code{DO IF} command evaluates its expression argument. If the +@code{DO IF} expression evaluates to true, then @pspp{} executes the +associated commands. Otherwise, @pspp{} evaluates the expression on +each @code{ELSE IF} clause (if any) in order, and executes the +commands associated with the first one that yields a true value. +Finally, if the @code{DO IF} and all the @code{ELSE IF} expressions +all evaluate to false, @pspp{} executes the commands following the +@code{ELSE} clause (if any). + +Each expression on @code{DO IF} and @code{ELSE IF} must evaluate to a +scalar. Positive scalars are considered to be true, and scalars that +are zero or negative are considered to be false. + +@node Matrix LOOP and BREAK Commands +@subsection The @code{LOOP} and @code{BREAK} Commands + +@display +@t{LOOP} [@i{var}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{step}]] [@t{IF} @i{expression}]@t{.} + @dots{}@i{matrix commands}@dots{} +@t{END LOOP} [@t{IF} @i{expression}]@t{.} + +@t{BREAK}@t{.} +@end display + +The @code{LOOP} command executes a nested group of matrix commands, +called the loop's @dfn{body}, repeatedly. It has three optional +clauses that control how many times the loop body executes. +Regardless of these clauses, the global @code{MXLOOPS} setting, which +defaults to 40, also limits the number of iterations of a loop. To +iterate more times, raise the maximum with @code{SET MXLOOPS} outside +of the @code{MATRIX} command (@pxref{SET MXLOOPS}). + +The optional index clause causes @var{var} to be assigned successive +values on each trip through the loop: first @var{first}, then +@math{@var{first} + @var{step}}, then @math{@var{first} + 2 @times{} +@var{step}}, and so on. The loop ends when @math{@var{var} > +@var{last}}, for positive @var{step}, or @math{@var{var} < +@var{last}}, for negative @var{step}. If @var{step} is not specified, +it defaults to 1. All the index clause expressions must evaluate to +scalars, and non-integers are rounded toward zero. If @var{step} +evaluates as zero (or rounds to zero), then the loop body never +executes. + +The optional @code{IF} on @code{LOOP} is evaluated before each +iteration through the loop body. If its expression, which must +evaluate to a scalar, is zero or negative, then the loop terminates +without executing the loop body. + +The optional @code{IF} on @code{END LOOP} is evaluated after each +iteration through the loop body. If its expression, which must +evaluate to a scalar, is zero or negative, then the loop terminates. + +The @code{BREAK} command may be used inside a loop body, ordinarily +within a @code{DO IF} command. If it is executed, then the loop +terminates immediately, jumping to the command just following +@code{END LOOP}. When multiple @code{LOOP} commands nest, +@code{BREAK} terminates the innermost loop. + +@node Matrix READ and WRITE Commands +@subsection The @code{READ} and @code{WRITE} Commands + +The @code{READ} and @code{WRITE} commands perform matrix input and +output with text files. They share the following syntax for +specifying how data is divided among input lines: + +@display +@t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}] +[@t{/FORMAT}@t{=}@i{format}] +@end display + +Both commands require the @code{FIELD} subcommand. It specifies the +range of columns, from @var{first} to @var{last}, inclusive, that the +data occupies on each line of the file. The leftmost column is column +1. The columns must be literal numbers, not expressions. To use +entire lines, even if they might be very long, specify a column range +such as @code{1 TO 100000}. + +The @code{FORMAT} subcommand is optional for numerical matrices. For +string matrix input and output, specify an @code{A} format. In +addition to @code{FORMAT}, the optional @code{BY} specification on +@code{FIELD} determine the meaning of each text line: + +@itemize @bullet +@item +Without @code{BY} and @code{FORMAT}, the numbers in the text file are +in @code{F} format separated by spaces or commas. For @code{WRITE}, +@pspp{} uses as many digits of precision needed to represent the +numbers in the matrix + +@item +With @code{BY @i{width}}, the input area is divided into fixed-width +fields with the given @i{width}. The input area must be a multiple of +@i{width} columns wide. Numbers are read or written as +@code{F@i{width}.0} format. + +@item +With @code{FORMAT=@i{count}F}, the input area is divided into +@i{count} equal-width fields per line. The input area must be a +multiple of @i{count} columns wide. Another format type may be +substituted for @code{F}. + +@item +@code{FORMAT=F@i{w}.@i{d}} divides the input area into fixed-width +fields with width @i{w}. The input area must be a multiple of @i{w} +columns wide. Another format type may be substituted for @code{F}. + +@item +If @code{BY} and @code{FORMAT} are both used, then they must agree on +the field width. +@end itemize + +@node Matrix READ Command +@subsubsection The @code{READ} Command + +@display +@t{READ} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}] + [@t{/FILE}@t{=}@i{file}] + @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}] + [@t{/FORMAT}@t{=}@i{format}] + [@t{/SIZE}@t{=}@i{expression}] + [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{SYMMETRIC}@}] + [@t{/REREAD}]@t{.} +@end display + +The @code{READ} command reads from a text file into a matrix variable. +Specify the target variable just after the command name, either just a +variable name to create or replace an entire variable, or a variable +name followed by an indexing expression to replace a submatrix of an +existing variable. + +The @code{FILE} subcommand is required in the first @code{READ} +command that appears within @code{MATRIX}. It specifies the text file +to be read, either as a file name in quotes or a file handle +previously declared on @code{FILE HANDLE} (@pxref{FILE HANDLE}). +Later @code{READ} commands (in syntax order) use the previous +referenced file if @code{FILE} is omitted. + +The @code{FIELD} and @code{FORMAT} subcommands specify how input lines +are interpreted. @xref{Matrix READ and WRITE Commands}, for details. + +The @code{SIZE} subcommand is required for reading into an entire +variable. Its restricted expression argument should evaluate to a +2-element vector @code{@{@var{n},@w{ }@var{m}@}} or +@code{@{@var{n};@w{ }@var{m}@}}, which indicates a +@math{@var{n}@times{}@var{m}} matrix destination. A scalar @var{n} is +also allowed and indicates a @math{@var{n}@times{}1} column vector +destination. When the destination is a submatrix, @code{SIZE} is +optional, and if it is present then it must match the size of the +submatrix. + +By default, or with @code{MODE=RECTANGULAR}, the command reads an +entry for every row and column. With @code{MODE=SYMMETRIC}, the +command reads only the entries on and below the matrix's main +diagonal, and copies the entries above the main diagonal from the +corresponding symmetric entries below it. Only square matrices +may use @code{MODE=SYMMETRIC}. + +Ordinarily, each @code{READ} command starts from a new line in the +text file. Specify the @code{REREAD} subcommand to instead start from +the last line read by the previous @code{READ} command. This has no +effect for the first @code{READ} command to read from a particular +file. It is also ineffective just after a command that uses the +@code{EOF} matrix function (@pxref{EOF Matrix Function}) on a +particular file, because @code{EOF} has to try to read the next line +from the file to determine whether the file contains more input. + +@node Matrix WRITE Command +@subsubsection The @code{WRITE} Command + +@display +@t{WRITE} @i{expression} + [@t{/OUTFILE}@t{=}@i{file}] + @t{/FIELD}@t{=}@i{first} @t{TO} @i{last} [@t{BY} @i{width}] + [@t{/FORMAT}@t{=}@i{format}] + [@t{/MODE}@t{=}@{@t{RECTANGULAR} @math{|} @t{TRIANGULAR}@}] + [@t{/HOLD}]@t{.} +@end display + +The @code{WRITE} command evaluates @i{expression} and writes it to a +text file in a specified format. Write the expression to evaluate +just after the command name. + +The @code{OUTFILE} subcommand is required in the first @code{WRITE} +command that appears within @code{MATRIX}. It specifies the text file +to be written, either as a file name in quotes or a file handle +previously declared on @code{FILE HANDLE} (@pxref{FILE HANDLE}). +Later @code{WRITE} commands (in syntax order) use the previous +referenced file if @code{FILE} is omitted. + +The @code{FIELD} and @code{FORMAT} subcommands specify how output +lines are formed. @xref{Matrix READ and WRITE Commands}, for details. + +By default, or with @code{MODE=RECTANGULAR}, the command writes an +entry for every row and column. With @code{MODE=TRIANGULAR}, the +command writes only the entries on and below the matrix's main +diagonal. Entries above the diagonal are not written. Only square +matrices may be written with @code{MODE=TRIANGULAR}. + +Ordinarily, each @code{WRITE} command starts a new line in the output +file. With @code{HOLD}, the next @code{WRITE} command will write to +the same line as the current one. This can be useful to write more +than one matrix on a single output line. + +@node Matrix GET Command +@subsection The @code{GET} Command + +@display +@t{GET} @i{variable}[@t{(}@i{index}[@t{,}@i{index}]@t{)}] + [@t{/FILE}@t{=}@{@i{file} @math{|} @t{*}@}] + [@t{/VARIABLES}@t{=}@i{variable}@dots{}] + [@t{/NAMES}@t{=}@i{variable}] + [@t{/MISSING}@t{=}@{@t{ACCEPT} @math{|} @t{OMIT} @math{|} @i{number}@}] + [@t{/SYSMIS}@t{=}@{@t{OMIT} @math{|} @i{number}@}]@t{.} +@end display + +The @code{READ} command reads numeric data from an SPSS system file, +SPSS/PC+ system file, or SPSS portable file into a matrix variable or +submatrix: + +@itemize @bullet +@item +To read data into a variable, specify just its name following +@code{GET}. The variable need not already exist; if it does, it is +replaced. The variable will have as many columns as there are +variables specified on the @code{VARIABLES} subcommand and as many +rows as there are cases in the input file. + +@item +To read data into a submatrix, specify the name of an existing +variable, followed by an indexing expression, just after @code{GET}. +The submatrix must have as many columns as variables specified on +@code{VARIABLES} and as many rows as cases in the input file. +@end itemize + +Specify the name or handle of the file to be read on @code{FILE}. Use +@samp{*}, or simply omit the @code{FILE} subcommand, to read from the +active file. Reading from the active file is only permitted if it was +already defined outside @code{MATRIX}. + +List the variables to be read as columns in the matrix on the +@code{VARIABLES} subcommand. The list can use @code{TO} for +collections of variables or @code{ALL} for all variables. If +@code{VARIABLES} is omitted, all variables are read. Only numeric +variables may be read. + +If a variable is named on @code{NAMES}, then the names of the +variables read as data columns are stored in a string vector within +the given name, replacing any existing matrix variable with that name. +Variable names are truncated to 8 bytes. + +The @code{MISSING} and @code{SYSMIS} subcommands control the treatment +of missing values in the input file. By default, any user- or +system-missing data in the variables being read from the input causes +an error that prevents @code{GET} from executing. To accept missing +values, specify one of the following settings on @code{MISSING}: + +@table @asis +@item @code{ACCEPT} +Accept user-missing values with no change. By default, system-missing +values still yield an error. Use the @code{SYSMIS} subcommand to +change this treatment: + +@table @asis +@item @code{OMIT} +Skip any case that contains a system-missing value. + +@item @i{number} +Recode the system-missing value to @i{number}. +@end table + +@item @code{OMIT} +Skip any case that contains any user- or system-missing value. + +@item @i{number} +Recode all user- and system-missing values to @i{number}. +@end table + +The @code{SYSMIS} subcommand has an effect only with +@code{MISSING=ACCEPT}. + +@node Matrix SAVE Command +@subsection The @code{SAVE} Command + +@display +@t{SAVE} @i{expression} + [@t{/OUTFILE}@t{=}@{@i{file} @math{|} @t{*}@}] + [@t{/VARIABLES}@t{=}@i{variable}@dots{}] + [@t{/NAMES}@t{=}@i{expression}] + [@t{/STRINGS}@t{=}@i{variable}@dots{}]@t{.} +@end display + +The @code{SAVE} matrix command evaluates @i{expression} and writes the +resulting matrix to an SPSS system file. In the system file, each +matrix row becomes a case and each column becomes a variable. + +Specify the name or handle of the SPSS system file on the +@code{OUTFILE} subcommand, or @samp{*} to write the output as the new +active file. The @code{OUTFILE} subcommand is required on the first +@code{SAVE} command, in syntax order, within @code{MATRIX}. For +@code{SAVE} commands after the first, the default output file is the +same as the previous. + +When multiple @code{SAVE} commands write to one destination within a +single @code{MATRIX}, the later commands append to the same output +file. All the matrices written to the file must have the same number +of columns. The @code{VARIABLES}, @code{NAMES}, and @code{STRINGS} +subcommands are honored only for the first @code{SAVE} command that +writes to a given file. + +By default, @code{SAVE} names the variables in the output file +@code{COL1} through @code{COL@i{n}}. Use @code{VARIABLES} or +@code{NAMES} to give the variables meaningful names. The +@code{VARIABLES} subcommand accepts a comma-separated list of variable +names. Its alternative, @code{NAMES}, instead accepts an expression +that must evaluate to a row or column string vector of names. The +number of names need not exactly match the number of columns in the +matrix to be written: extra names are ignored; extra columns use +default names. + +By default, @code{SAVE} assumes that the matrix to be written is all +numeric. To write string columns, specify a comma-separated list of +the string columns' variable names on @code{STRINGS}. + +@node Matrix MGET Command +@subsection The @code{MGET} Command + +@display +@t{MGET} [@t{/FILE}@t{=}@i{file}] + [@t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}]@t{.} +@end display + +The @code{MGET} command reads the data from a matrix file +(@pxref{Matrix Files}) into matrix variables. Specify the name or +handle of the matrix file to be read on the @code{FILE} subcommand; if +it is omitted, then the command reads the active file. + +By default, @code{MGET} reads all of the data from the matrix file. +Specify a space-delimited list of matrix types @code{TYPE} to limit the +kinds of data to the one specified: + +@table @code +@item COV +Covariance matrix. + +@item CORR +Correlation coefficient matrix. + +@item MEAN +Vector of means. + +@item STDDEV +Vector of standard deviations. + +@item N +Vector of case counts. + +@item COUNT +Vector of counts. +@end table + +@code{MGET} reads the entire matrix file and automatically names, +creates, and populates matrix variables using its contents. It +constructs the name of each variable by concatenating the following: + +@itemize @bullet +@item +A 2-character prefix that identifies the type of the matrix: + +@table @code +@item CV +Covariance matrix. + +@item CR +Correlation coefficient matrix. + +@item MN +Vector of means. + +@item SD +Vector of standard deviations. + +@item NC +Vector of case counts. + +@item CN +Vector of counts. +@end table + +@item +If the matrix file has factor variables, @code{F@i{n}}, where @i{n} +is a number identifying a group of factors: @code{F1} for the first +group, @code{F2} for the second, and so on. + +@item +If the matrix file has split file variables, @code{S@i{n}}, where +@i{n} is a number identifying a split group: @code{S1} for the first +group, @code{S2} for the second, and so on. +@end itemize + +If @code{MGET} chooses the name of an existing variable, it issues a +warning and does not change the variable. + +@node Matrix MSAVE Command +@subsection The @code{MSAVE} Command + +@display +@t{MSAVE} @i{expression} + @t{/TYPE}@t{=}@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@} + [@t{/FACTOR}@t{=}@i{expression}] + [@t{/SPLIT}@t{=}@i{expression}] + [@t{/OUTFILE}@t{=}@i{file}] + [@t{/VARIABLES}@t{=}@i{variable}@dots{}] + [@t{/SNAMES}@t{=}@i{variable}@dots{}] + [@t{/FNAMES}@t{=}@i{variable}@dots{}]@t{.} +@end display + +The @code{MSAVE} command evaluates the @i{expression} specifies just +after the command name, and writes the resulting matrix to a matrix +file (@pxref{Matrix Files}). + +The @code{TYPE} subcommand is required. It specifies the +@code{ROWTYPE_} to write along with this matrix. + +The @code{FACTOR} and @code{SPLIT} subcommands are required if and +only if the matrix file has factor or split variables, respectively. +Each one takes an expression that must evaluate to a vector with the +same number of entries as the matrix has factor or split variables, +respectively. Each @code{MSAVE} only writes data for a single +combination of factor and split variables, so many @code{MSAVE} +commands (or one inside a loop) may be needed to write a complete set. + +The remaining @code{MSAVE} subcommands define the format of the matrix +file. All of the @code{MSAVE} commands within a given matrix program +write to the same matrix file, so these subcommands are only +meaningful on the first @code{MSAVE} command within a matrix program. +(If they are given again on later @code{MSAVE} commands, then they +must have the same values as on the first.) + +The @code{OUTFILE} subcommand specifies the name or handle of the +matrix file to be written. Output must go to an external file, not a +data set or the active file. + +The @code{VARIABLES} subcommand specifies a comma-separated list of +the names of the continuous variables to be written to the matrix +file. The @code{TO} keyword can be used to define variables named +with consecutive integer suffixes. These names become column names +and names that appear in @code{VARNAME_} in the matrix file. +@code{ROWTYPE_} and @code{VARNAME_} are not allowed on +@code{VARIABLES}. If @code{VARIABLES} is omitted, then @pspp{} uses +the names @code{COL1}, @code{COL2}, and so on. + +The @code{FNAMES} subcommand may be used to supply a comma-separated +list of factor variable names. The default names are @code{FAC1}, +@code{FAC2}, and so on. + +The @code{SNAMES} subcommand can supply a comma-separated list of +split variable names. The default names are @code{SPL1}, @code{SPL2}, +and so on. + +@node Matrix DISPLAY Command +@subsection The @code{DISPLAY} Command + +@display +@t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}]@t{.} +@end display + +The @code{DISPLAY} command makes @pspp{} display a table with the name +and dimensions of each matrix variable. The @code{DICTIONARY} and +@code{STATUS} keywords are accepted but have no effect. + +@node Matrix RELEASE Command +@subsection The @code{RELEASE} Command + +@display +@t{RELEASE} @i{variable}@dots{}@t{.} +@end display + +The @code{RELEASE} command accepts a comma-separated list of matrix +variable names. It deletes each variable and releases the memory +associated with it. + +The @code{END MATRIX} command releases all matrix variables.