Work on matrix documentation.

[pspp] / doc / matrices.texi

@c PSPP - a program for statistical analysis.
@c Copyright (C) 2017, 2020, 2021 Free Software Foundation, Inc.
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3
@c or any later version published by the Free Software Foundation;
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c A copy of the license is included in the section entitled "GNU
@c Free Documentation License".
@c
@node Matrices
@chapter Matrices

Some @pspp{} procedures work with matrices by producing numeric
matrices that report results of data analysis, or by consuming
matrices as a basis for further analysis.  This chapter documents the
format of data files that store these matrices and commands for
working with them, as well as @pspp{}'s general-purpose facility for
matrix operations.

@node Matrix Files
@section Matrix Files
@vindex Matrix file

A matrix file is an SPSS system file that conforms to the dictionary
and case structure described in this section.  Procedures that read
matrices from files expect them to be in the matrix file format.
Procedures that write matrices also use this format.

Text files that contain matrices can be converted to matrix file
format.  @xref{MATRIX DATA}, for a command to read a text file as a
matrix file.

A matrix file's dictionary must have the following variables in the
specified order:

@enumerate
@item
Zero or more numeric split variables.  These are included by
procedures when @cmd{SPLIT FILE} is active.  @cmd{MATRIX DATA} assigns
split variables format F4.0.

@item
@code{ROWTYPE_}, a string variable with width 8.  This variable
indicates the kind of matrix or vector that a given case represents.
The supported row types are listed below.

@item
Zero or more numeric factor variables.  These are included by
procedures that divide data into cells.  For within-cell data, factor
variables are filled with non-missing values; for pooled data, they
are missing.  @cmd{MATRIX DATA} assigns factor variables format F4.0.

@item
@code{VARNAME_}, a string variable.  Matrix data includes one row per
continuous variable (see below), naming each continuous variable in
order.  This column is blank for vector data.  @cmd{MATRIX DATA} makes
@code{VARNAME_} wide enough for the name of any of the continuous
variables, but at least 8 bytes.

@item
One or more numeric continuous variables.  These are the variables
whose data was analyzed to produce the matrices.  @cmd{MATRIX DATA}
assigns continuous variables format F10.4.
@end enumerate

Case weights are ignored in matrix files. 

@subheading Row Types
@anchor{Matrix File Row Types}

Matrix files support a fixed set of types of matrix and vector data.
The @code{ROWTYPE_} variable in each case of a matrix file indicates
its row type.  

The supported matrix row types are listed below.  Each type is listed
with the keyword that identifies it in @code{ROWTYPE_}.  All supported
types of matrices are square, meaning that each matrix must include
one row per continuous variable, with the @code{VARNAME_} variable
indicating each continuous variable in turn in the same order as the
dictionary.

@table @code
@item CORR
Correlation coefficients.

@item COV
Covariance coefficients.

@item MAT
General-purpose matrix.

@item N_MATRIX
Counts.

@item PROX
Proximities matrix.
@end table

The supported vector row types are listed below, along with their
associated keyword.  Vector row types only require a single row, whose
@code{VARNAME_} is blank:

@table @code
@item COUNT
Unweighted counts.

@item DFE
Degrees of freedom.

@item MEAN
Means.

@item MSE
Mean squared errors.

@item N
Counts.

@item STDDEV
Standard deviations.
@end table

Only the row types listed above may appear in matrix files.  The
@cmd{MATRIX DATA} command, however, accepts the additional row types
listed below, which it changes into matrix file row types as part of
its conversion process:

@table @code
@item N_VECTOR
Synonym for @cmd{N}.

@item SD
Synonym for @code{STDDEV}.

@item N_SCALAR
Accepts a single number from the @code{MATRIX DATA} input and writes
it as an @code{N} row with the number replicated across all the
continuous variables.
@end table

@node MATRIX DATA
@section MATRIX DATA
@vindex MATRIX DATA

@display
MATRIX DATA
        VARIABLES=@var{variables}
        [FILE=@{'@var{file_name}' | INLINE@}
        [/FORMAT=[@{LIST | FREE@}]
                 [@{UPPER | LOWER | FULL@}]
                 [@{DIAGONAL | NODIAGONAL@}]]
        [/SPLIT=@var{split_vars}]
        [/FACTORS=@var{factor_vars}]
        [/N=@var{n}]

The following subcommands are only needed when ROWTYPE_ is not
specified on the VARIABLES subcommand:
        [/CONTENTS=@{CORR,COUNT,COV,DFE,MAT,MEAN,MSE,
                    N_MATRIX,N|N_VECTOR,N_SCALAR,PROX,SD|STDDEV@}]
        [/CELLS=@var{n_cells}]
@end display

The @cmd{MATRIX DATA} command convert matrices and vectors from text
format into the matrix file format (@xref{Matrix Files}) for use by
procedures that read matrices.  It reads a text file or inline data
and outputs to the active file, replacing any data already in the
active dataset.  The matrix file may then be used by other commands
directly from the active file, or it may be written to a @file{.sav}
file using the @cmd{SAVE} command.

The text data read by @cmd{MATRIX DATA} can be delimited by spaces or
commas.  A plus or minus sign, except immediately following a @samp{d}
or @samp{e}, also begins a new value.  Optionally, values may be
enclosed in single or double quotes.

@cmd{MATRIX DATA} can read the types of matrix and vector data
supported in matrix files (@pxref{Matrix File Row Types}).

The @subcmd{FILE} subcommand specifies the source of the command's
input.  To read input from a text file, specify its name in quotes.
To supply input inline, omit @subcmd{FILE} or specify @code{INLINE}.
Inline data must directly follow @code{MATRIX DATA}, inside @cmd{BEGIN
DATA} (@pxref{BEGIN DATA}).

@subcmd{VARIABLES} is the only required subcommand.  It names the
variables present in each input record in the order that they appear.
(@cmd{MATRIX DATA} reorders the variables in the matrix file it
produces, if needed to fit the matrix file format.)  The variable list
must include split variables and factor variables, if they are present
in the data, in addition to the continuous variables that form matrix
rows and columns.  It may also include a special variable named
@code{ROWTYPE_}.

Matrix data may include split variables or factor variables or both.
List split variables, if any, on the @subcmd{SPLIT} subcommand and
factor variables, if any, on the @subcmd{FACTORS} subcommand.  Split
and factor variables must be numeric.  Split and factor variables must
also be listed on @subcmd{VARIABLES}, with one exception: if
@subcmd{VARIABLES} does not include @code{ROWTYPE_}, then
@subcmd{SPLIT} may name a single variable that is not in
@subcmd{VARIABLES} (@pxref{MATRIX DATA Example 8}).

The @subcmd{FORMAT} subcommand accepts settings to describe the format
of the input data:

@table @asis
@item @code{LIST} (default)
@itemx @code{FREE}
LIST requires each row to begin at the start of a new input line.
FREE allows rows to begin in the middle of a line.  Either setting
allows a single row to continue across multiple input lines.

@item @code{LOWER} (default)
@itemx @code{UPPER}
@itemx @code{FULL}
With LOWER, only the lower triangle is read from the input data and
the upper triangle is mirrored across the main diagonal.  UPPER
behaves similarly for the upper triangle.  FULL reads the entire
matrix.

@item @code{DIAGONAL} (default)
@itemx @code{NODIAGONAL}
With DIAGONAL, the main diagonal is read from the input data.  With
NODIAGONAL, which is incompatible with FULL, the main diagonal is not
read from the input data but instead set to 1 for correlation matrices
and system-missing for others.
@end table

The @subcmd{N} subcommand is a way to specify the size of the
population.  It is equivalent to specifying an @code{N} vector with
the specified value for each split file.

@cmd{MATRIX DATA} supports two different ways to indicate the kinds of
matrices and vectors present in the data, depending on whether a
variable with the special name @code{ROWTYPE_} is present in
@code{VARIABLES}.  The following subsections explain @cmd{MATRIX DATA}
syntax and behavior in each case.

@node MATRIX DATA with ROWTYPE_
@subsection With @code{ROWTYPE_}

If @code{VARIABLES} includes @code{ROWTYPE_}, each case's
@code{ROWTYPE_} indicates the type of data contained in the row.
@xref{Matrix File Row Types}, for a list of supported row types.

@subsubheading Example 1: Defaults with @code{ROWTYPE_}
@anchor{MATRIX DATA Example 1}

This example shows a simple use of @cmd{MATRIX DATA} with
@code{ROWTYPE_} plus 8 variables named @code{var01} through
@code{var08}.

Because @code{ROWTYPE_} is the first variable in @subcmd{VARIABLES},
it appears first on each line. The first three lines in the example
data have @code{ROWTYPE_} values of @samp{MEAN}, @samp{SD}, and
@samp{N}.  These indicate that these lines contain vectors of means,
standard deviations, and counts, respectively, for @code{var01}
through @code{var08} in order.

The remaining 8 lines have a ROWTYPE_ of @samp{CORR} which indicates
that the values are correlation coefficients.  Each of the lines
corresponds to a row in the correlation matrix: the first line is for
@code{var01}, the next line for @code{var02}, and so on.  The input
only contains values for the lower triangle, including the diagonal,
since @code{FORMAT=LOWER DIAGONAL} is the default.

With @code{ROWTYPE_}, the @code{CONTENTS} subcommand is optional and
the @code{CELLS} subcommand may not be used.

@example
MATRIX DATA
    VARIABLES=ROWTYPE_ var01 TO var08.
BEGIN DATA.
MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
N       92    92    92    92    92    92    92    92
CORR  1.00
CORR   .18  1.00
CORR  -.22  -.17  1.00
CORR   .36   .31  -.14  1.00
CORR   .27   .16  -.12   .22  1.00
CORR   .33   .15  -.17   .24   .21  1.00
CORR   .50   .29  -.20   .32   .12   .38  1.00
CORR   .17   .29  -.05   .20   .27   .20   .04  1.00
END DATA.
@end example

@subsubheading Example 2: @code{FORMAT=UPPER NODIAGONAL}

This syntax produces the same matrix file as example 1, but it uses
@code{FORMAT=UPPER NODIAGONAL} to specify the upper triangle and omit
the diagonal.  Because the matrix's @code{ROWTYPE_} is @code{CORR},
@pspp{} automatically fills in the diagonal with 1.

@example
MATRIX DATA
    VARIABLES=ROWTYPE_ var01 TO var08
    /FORMAT=UPPER NODIAGONAL.
BEGIN DATA.
MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
N       92    92    92    92    92    92    92    92
CORR         .17   .50  -.33   .27   .36  -.22   .18
CORR               .29   .29  -.20   .32   .12   .38
CORR                     .05   .20  -.15   .16   .21
CORR                           .20   .32  -.17   .12
CORR                                 .27   .12  -.24
CORR                                      -.20  -.38
CORR                                             .04
END DATA.
@end example

@subsubheading Example 3: @subcmd{N} subcommand

This syntax uses the @subcmd{N} subcommand in place of an @code{N}
vector.  It produces the same matrix file as examples 1 and 2.

@example
MATRIX DATA
    VARIABLES=ROWTYPE_ var01 TO var08
    /FORMAT=UPPER NODIAGONAL
    /N 92.
BEGIN DATA.
MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
CORR         .17   .50  -.33   .27   .36  -.22   .18
CORR               .29   .29  -.20   .32   .12   .38
CORR                     .05   .20  -.15   .16   .21
CORR                           .20   .32  -.17   .12
CORR                                 .27   .12  -.24
CORR                                      -.20  -.38
CORR                                             .04
END DATA.
@end example

@subsubheading Example 4: Split variables
@anchor{MATRIX DATA Example 4}

This syntax defines two matrices, using the variable @samp{s1} to
distinguish between them.  Notice how the order of variables in the
input matches their order on @subcmd{VARIABLES}.  This example also
uses @code{FORMAT=FULL}.

@example
MATRIX DATA
    VARIABLES=s1 ROWTYPE_  var01 TO var04
    /SPLIT=s1
    /FORMAT=FULL.
BEGIN DATA.
0 MEAN 34 35 36 37
0 SD   22 11 55 66
0 N    99 98 99 92
0 CORR  1 .9 .8 .7
0 CORR .9  1 .6 .5
0 CORR .8 .6  1 .4
0 CORR .7 .5 .4  1
1 MEAN 44 45 34 39
1 SD   23 15 51 46
1 N    98 34 87 23
1 CORR  1 .2 .3 .4
1 CORR .2  1 .5 .6
1 CORR .3 .5  1 .7
1 CORR .4 .6 .7  1
END DATA.
@end example

@subsubheading Example 5: Factor variables
@anchor{MATRIX DATA Example 5}

This syntax defines a matrix file that includes a factor variable
@samp{f1}.  The data includes mean, standard deviation, and count
vectors for two values of the factor variable, plus a correlation
matrix for pooled data.

@example
MATRIX DATA
    VARIABLES=ROWTYPE_ f1 var01 TO var04
    /FACTOR=f1.
BEGIN DATA.
MEAN 0 34 35 36 37
SD   0 22 11 55 66
N    0 99 98 99 92
MEAN 1 44 45 34 39
SD   1 23 15 51 46
N    1 98 34 87 23
CORR .  1
CORR . .9  1
CORR . .8 .6  1
CORR . .7 .5 .4  1
END DATA.
@end example

@node MATRIX DATA without ROWTYPE_
@subsection Without @code{ROWTYPE_}

If @code{VARIABLES} does not contain @code{ROWTYPE_}, the
@subcmd{CONTENTS} subcommand defines the row types that appear in the
file and their order.  If @subcmd{CONTENTS} is omitted,
@code{CONTENTS=CORR} is assumed.

Factor variables without @code{ROWTYPE_} introduce special
requirements, illustrated below in Examples 8 and 9.

@subsubheading Example 6: Defaults without @code{ROWTYPE_}

This example shows a simple use of @cmd{MATRIX DATA} with 8 variables
named @code{var01} through @code{var08}, without @code{ROWTYPE_}.
This yields the same matrix file as Example 1 (@pxref{MATRIX DATA
Example 1}).

@example
MATRIX DATA
    VARIABLES=var01 TO var08
   /CONTENTS=MEAN SD N CORR.
BEGIN DATA.
24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
 5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
  92    92    92    92    92    92    92    92
1.00
 .18  1.00
-.22  -.17  1.00
 .36   .31  -.14  1.00
 .27   .16  -.12   .22  1.00
 .33   .15  -.17   .24   .21  1.00
 .50   .29  -.20   .32   .12   .38  1.00
 .17   .29  -.05   .20   .27   .20   .04  1.00
END DATA.
@end example

@subsubheading Example 7: Split variables with explicit values

This syntax defines two matrices, using the variable @code{s1} to
distinguish between them.  Each line of data begins with @code{s1}.
This yields the same matrix file as Example 4 (@pxref{MATRIX DATA
Example 4}).

@example
MATRIX DATA
    VARIABLES=s1 var01 TO var04
    /SPLIT=s1
    /FORMAT=FULL
    /CONTENTS=MEAN SD N CORR.
BEGIN DATA.
0 34 35 36 37
0 22 11 55 66
0 99 98 99 92
0  1 .9 .8 .7
0 .9  1 .6 .5
0 .8 .6  1 .4
0 .7 .5 .4  1
1 44 45 34 39
1 23 15 51 46
1 98 34 87 23
1  1 .2 .3 .4
1 .2  1 .5 .6
1 .3 .5  1 .7
1 .4 .6 .7  1
END DATA.
@end example

@subsubheading Example 8: Split variable with sequential values
@anchor{MATRIX DATA Example 8}

Like this previous example, this syntax defines two matrices with
split variable @code{s1}.  In this case, though, @code{s1} is not
listed in @subcmd{VARIABLES}, which means that its value does not
appear in the data.  Instead, @cmd{MATRIX DATA} reads matrix data
until the input is exhausted, supplying 1 for the first split, 2 for
the second, and so on.

@example
MATRIX DATA
    VARIABLES=var01 TO var04
    /SPLIT=s1
    /FORMAT=FULL
    /CONTENTS=MEAN SD N CORR.
BEGIN DATA.
34 35 36 37
22 11 55 66
99 98 99 92
 1 .9 .8 .7
.9  1 .6 .5
.8 .6  1 .4
.7 .5 .4  1
44 45 34 39
23 15 51 46
98 34 87 23
 1 .2 .3 .4
.2  1 .5 .6
.3 .5  1 .7
.4 .6 .7  1
END DATA.
@end example

@subsubsection Factor variables without @code{ROWTYPE_}

Without @subcmd{ROWTYPE_}, factor variables introduce two new wrinkles
to @cmd{MATRIX DATA} syntax.  First, the @subcmd{CELLS} subcommand
must declare the number of combinations of factor variables present in
the data.  If there is, for example, one factor variable for which the
data contains three values, one would write @code{CELLS=3}; if there
are two (or more) factor variables for which the data contains five
combinations, one would use @code{CELLS=5}; and so on.

Second, the @subcmd{CONTENTS} subcommand must distinguish within-cell
data from pooled data by enclosing within-cell row types in
parentheses.  When different within-cell row types for a single factor
appear in subsequent lines, enclose the row types in a single set of
parentheses; when different factors' values for a given within-cell
row type appear in subsequent lines, enclose each row type in
individual parentheses.

Without @subcmd{ROWTYPE_}, input lines for pooled data do not include
factor values, not even as missing values, but input lines for
within-cell data do.

The following examples aim to clarify this syntax.

@subsubheading Example 9: Factor variables, grouping within-cell records by factor

This syntax defines the same matrix file as Example 5 (@pxref{MATRIX
DATA Example 5}), without using @code{ROWTYPE_}.  It declares
@code{CELLS=2} because the data contains two values (0 and 1) for
factor variable @code{f1}.  Within-cell vector row types @code{MEAN},
@code{SD}, and @code{N} are in a single set of parentheses on
@subcmd{CONTENTS} because they are grouped together in subsequent
lines for a single factor value.  The data lines with the pooled
correlation matrix do not have any factor values.

@example
MATRIX DATA
    VARIABLES=f1 var01 TO var04
    /FACTOR=f1
    /CELLS=2
    /CONTENTS=(MEAN SD N) CORR.
BEGIN DATA.
0 34 35 36 37
0 22 11 55 66
0 99 98 99 92
1 44 45 34 39
1 23 15 51 46
1 98 34 87 23
   1
  .9  1
  .8 .6  1
  .7 .5 .4  1
END DATA.
@end example

@subsubheading Example 10: Factor variables, grouping within-cell records by row type

This syntax defines the same matrix file as the previous example.  The
only difference is that the within-cell vector rows are grouped
differently: two rows of means (one for each factor), followed by two
rows of standard deviations, followed by two rows of counts.

@example
MATRIX DATA
    VARIABLES=f1 var01 TO var04
    /FACTOR=f1
    /CELLS=2
    /CONTENTS=(MEAN) (SD) (N) CORR.
BEGIN DATA.
0 34 35 36 37
1 44 45 34 39
0 22 11 55 66
1 23 15 51 46
0 99 98 99 92
1 98 34 87 23
   1
  .9  1
  .8 .6  1
  .7 .5 .4  1
END DATA.
@end example

@node MCONVERT
@section MCONVERT
@vindex MCONVERT

@display
MCONVERT
    [[MATRIX=]
     [IN(@{@samp{*}|'@var{file}'@})]
     [OUT(@{@samp{*}|'@var{file}'@})]]
    [/@{REPLACE,APPEND@}].
@end display

The @cmd{MCONVERT} command converts matrix data from a correlation
matrix and a vector of standard deviations into a covariance matrix,
or vice versa.

By default, @cmd{MCONVERT} both reads and writes the active file.  Use
the @cmd{MATRIX} subcommand to specify other files.  To read a matrix
file, specify its name inside parentheses following @code{IN}.  To
write a matrix file, specify its name inside parentheses following
@code{OUT}.  Use @samp{*} to explicitly specify the active file for
input or output.

When @cmd{MCONVERT} reads the input, by default it substitutes a
correlation matrix and a vector of standard deviations each time it
encounters a covariance matrix, and vice versa.  Specify
@code{/APPEND} to instead have @cmd{MCONVERT} add the other form of
data without removing the existing data.  Use @code{/REPLACE} to
explicitly request removing the existing data.

The @cmd{MCONVERT} command requires its input to be a matrix file.
Use @cmd{MATRIX DATA} to convert text input into matrix file format.
@xref{MATRIX DATA}, for details.

@node MATRIX
@section MATRIX
@vindex MATRIX
@vindex END MATRIX

@subsection Overview

@display
@t{MATRIX.}
@dots{}@i{matrix commands}@dots{}
@t{END MATRIX.}
@end display

@noindent
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{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}@}].
@end display

@noindent
The following matrix commands offer support for flow control:

@display
@t{DO IF} @i{expression}.
  @dots{}@i{matrix commands}@dots{}
[@t{ELSE IF} @i{expression}.
  @dots{}@i{matrix commands}@dots{}]@dots{}
[@t{ELSE}
  @dots{}@i{matrix commands}@dots{}]
@t{END IF}.

@t{LOOP} [@i{var}=@i{first} @t{TO} @i{last} [@t{BY} @i{step}]] [@t{IF} @i{expression}].
  @dots{}@i{matrix commands}@dots{}
@t{END LOOP} [@t{IF} @i{expression}].

@t{BREAK}.
@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{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{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{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}].
@end display

@noindent
The following matrix commands provide additional support:

@display
@t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}].
@t{RELEASE} @i{variable}@dots{}.
@end display

@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
matrix language commands work with any datasets that are defined.
Each instance of @code{MATRIX}@dots{}@code{END MATRIX} is a separate
program whose state is independent of any instance, so that variables
declared within a matrix program are forgotten at its end.

The matrix language works with matrices, where a @dfn{matrix} is a
rectangular array of real numbers.  An @math{@var{n}@times{}@var{m}}
matrix has @var{n} rows and @var{m} columns.  Some special cases are
important: a @math{@var{n}@times{}1} matrix is a @dfn{column vector},
a @math{1@times{}@var{n}} is a @dfn{row vector}, and a
@math{1@times{}1} matrix is a @dfn{scalar}.

The matrix language also has limited support for matrices that contain
8-byte strings instead of numbers.  Strings longer than 8 bytes are
truncated, and shorter strings are padded with spaces.  String
matrices are mainly useful for labeling rows and columns when printing
numerical matrices with the @code{MATRIX PRINT} command.  Arithmetic
operations on string matrices will not produce useful results.  The
user should not mix strings and numbers within a matrix.

The matrix language does not work with cases.  A variable in the
matrix language represents a single matrix.

The matrix language does not support missing values.

@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
precedence:

@itemize @bullet
@item @t{(@dots{})}  @t{@{@dots{}@}}

@item @t{(}@i{index}[@t{,} @i{index}]@t{)}

@item @t{+  -}

@item @t{:}

@item @t{**  &**}

@item @t{*  /  &*  &/}

@item @t{+  -}

@item @t{< <= = >= > <>}

@item @t{NOT}

@item @t{AND}

@item @t{OR  XOR}
@end itemize

Each of these operators is described in more detail below.

@node Matrix Construction Operator
@subsubsection The Matrix Construction Operator @t{@{@}}

Use the @t{@{}@t{@}} operator to construct matrices.  Within
the curly braces, commas separate elements within a row and semicolons
separate rows.  The following examples show a @math{2@times{}3}
matrix, a @math{1@times{}4} row vector, a @math{3@times{}1} column
vector, and a scalar.

@multitable @columnfractions .4 .05 .4
@item @t{@{1, 2, 3; 4, 5, 6@}}
@tab @result{}
@tab
@ifnottex
@t{[1  2  3] @* [4  5  6]}
@end ifnottex
@iftex
@math{\left(\matrix{1 & 2 & 3 \cr 4 & 5 & 6}\right)}
@end iftex
@
@item @t{@{3.14, 6.28, 9.24, 12.57@}}
@tab @result{}
@tab
@ifnottex
[3.14  6.28  9.42  12.57]
@end ifnottex
@iftex
@math{(\matrix{3.14 & 6.28 & 9.42 & 12.57})}
@end iftex
@
@item @t{@{1.41; 1.73; 2@}}
@tab @result{}
@tab
@ifnottex
@t{[1.41] @* [1.73] @* [2.00]}
@end ifnottex
@iftex
@math{(\matrix{1.41 & 1.73 & 2.00})}
@end iftex
@
@item @t{@{5@}}
@tab @result{}
@tab 5
@end multitable

Curly braces are not limited to holding numeric literals.  They can
contain calculations, and they can paste together matrices and vectors
in any way as long as the result is rectangular.  For example, if
@samp{m} is matrix @code{@{1, 2; 3, 4@}}, @samp{r} is row vector
@code{@{5, 6@}}, and @samp{c} is column vector @code{@{7, 8@}}, then
curly braces can be used as follows:

@multitable @columnfractions .4 .05 .4
@item @t{@{m, c; r, 10@}}
@tab @result{}
@tab
@ifnottex
@t{[1 2  7] @* [3 4  8] @* [5 6 10]}
@end ifnottex
@iftex
@math{\left(\matrix{1 & 2 & 7 \cr 3 & 4 & 8 \cr 5 & 6 & 10}\right)}
@end iftex
@
@item @t{@{c, 2 * c, T(r)@}}
@tab @result{}
@tab
@ifnottex
@t{[7 14 5] @* [8 16 6]}
@end ifnottex
@iftex
@math{\left(\matrix{7 & 14 & 5 \cr 8 & 16 & 6}\right)}
@end iftex
@end multitable

The final example above uses the transposition function @code{T}.

@node Matrix Sequence Operator
@subsubsection The Integer Sequence Operator @samp{:}

The syntax @code{@var{first}:@var{last}:@var{step}} yields a row
vector of consecutive integers from @var{first} to @var{last} counting
by @var{step}.  The final @code{:@var{step}} is optional and
defaults to 1 when omitted.

Each of @var{first}, @var{last}, and @var{step} must be a scalar and
should be an integer (any fractional part is discarded).  Because
@samp{:} has a high precedence, operands other than numeric literals
must usually be parenthesized.

When @var{step} is positive (or omitted) and @math{@var{end} <
@var{start}}, or if @var{step} is negative and @math{@var{end} >
@var{start}}, then the result is an empty matrix.  If @var{step} is 0,
then @pspp{} reports an error.

Here are some examples:

@multitable @columnfractions .4 .05 .4
@item @t{1:6}      @tab @result{} @tab @t{@{1, 2, 3, 4, 5, 6@}}
@item @t{1:6:2}    @tab @result{} @tab @t{@{1, 3, 5@}}
@item @t{-1:-5:-1} @tab @result{} @tab @t{@{-1, -2, -3, -4, -5@}}
@item @t{-1:-5}    @tab @result{} @tab @t{@{@}}
@item @t{2:1:0}    @tab @result{} @tab (error)
@end multitable

@node Matrix Index Operator
@subsubsection The Index Operator @code{()}

The result of the submatrix or indexing operator, written
@code{@var{m}(@var{rindex}, @var{cindex})}, contains the rows of
@var{m} whose indexes are given in vector @var{rindex} and the columns
whose indexes are given in vector @var{cindex}.

In the simplest case, if @var{rindex} and @var{cindex} are both
scalars, the result is also a scalar:

@multitable @columnfractions .4 .05 .4
@item @t{@{10, 20; 30, 40@}(1, 1)} @tab @result{} @tab @t{10}
@item @t{@{10, 20; 30, 40@}(1, 2)} @tab @result{} @tab @t{20}
@item @t{@{10, 20; 30, 40@}(2, 1)} @tab @result{} @tab @t{30}
@item @t{@{10, 20; 30, 40@}(2, 2)} @tab @result{} @tab @t{40}
@end multitable

If the index arguments have multiple elements, then the result
includes multiple rows or columns:

@multitable @columnfractions .4 .05 .4
@item @t{@{10, 20; 30, 40@}(1:2, 1)} @tab @result{} @tab @t{@{10; 30@}}
@item @t{@{10, 20; 30, 40@}(2, 1:2)} @tab @result{} @tab @t{@{30, 40@}}
@item @t{@{10, 20; 30, 40@}(1:2, 1:2)} @tab @result{} @tab @t{@{10, 20; 30, 40@}}
@end multitable

The special argument @samp{:} may stand in for all the rows or columns
in the matrix being indexed, like this:

@multitable @columnfractions .4 .05 .4
@item @t{@{10, 20; 30, 40@}(:, 1)} @tab @result{} @tab @t{@{10; 30@}}
@item @t{@{10, 20; 30, 40@}(2, :)} @tab @result{} @tab @t{@{30, 40@}}
@item @t{@{10, 20; 30, 40@}(:, :)} @tab @result{} @tab @t{@{10, 20; 30, 40@}}
@end multitable

The index arguments do not have to be in order, and they may contain
repeated values, like this:

@multitable @columnfractions .4 .05 .4
@item @t{@{10, 20; 30, 40@}(@{2, 1@}, 1)} @tab @result{} @tab @t{@{30; 10@}}
@item @t{@{10, 20; 30, 40@}(2, @{2; 2; 1@})} @tab @result{} @tab @t{@{40, 40, 30@}}
@item @t{@{10, 20; 30, 40@}(2:1:-1, :)} @tab @result{} @tab @t{@{30, 40; 10, 20@}}
@end multitable

When the matrix being indexed is a row or column vector, only a single
index argument is needed, like this:

@multitable @columnfractions .4 .05 .4
@item @t{@{11, 12, 13, 14, 15@}(2:4)} @tab @result{} @tab @t{@{12, 13, 14@}}
@item @t{@{11; 12; 13; 14; 15@}(2:4)} @tab @result{} @tab @t{@{12; 13; 14@}}
@end multitable

When an index is not an integer, @pspp{} discards the fractional part.
It is an error for an index to be less than 1 or greater than the
number of rows or columns:

@multitable @columnfractions .4 .05 .4
@item @t{@{11, 12, 13, 14@}(@{2.5, 4.6@})} @tab @result{} @tab @t{@{12, 14@}}
@item @t{@{11; 12; 13; 14@}(0)} @tab @result{} @tab (error)
@end multitable

@node Matrix Unary Arithmetic Operators
@subsubsection Unary Arithmetic Operators

The unary @samp{-} operator inverts the sign of each element in its
argument.  The unary @samp{+} operator has no effect:

@multitable @columnfractions .4 .05 .4
@item @t{-@{1, -2; 3, -4@}} @tab @result{} @tab @t{@{-1, 2; -3, 4@}}
@item @t{+@{1, -2; 3, -4@}} @tab @result{} @tab @t{@{1, -2; 3, -4@}}
@end multitable

@node Matrix Elementwise Operators
@subsubsection Elementwise Operators

The elementwise operators require their operands to be matrices with
the same dimensions.  Alternatively, if one operand is a scalar, then
its value is treated as if it were duplicated to the dimensions of the
other operand.  The result is a matrix of the same size as the
operands, in which each element is the result of the applying the
operator to the corresponding elements of the operands.

The elementwise operators are listed below.

@itemize @bullet
@item
The arithmetic operators, for familiar arithmetic operations:

@table @asis
@item @code{+}
Addition.

@item @code{-}
Subtraction.

@item @code{*}
Multiplication, if one operand is a scalar.  (Otherwise this is matrix
multiplication, described below.)

@item @code{/} or @code{&/}
Division.

@item @code{&*}
Multiplication.

@item @code{&**}
Exponentiation.
@end table

@item
The relational operators, whose results are 1 when a comparison is
true and 0 when it is false:

@table @asis
@item @code{<} or @code{LT}
Less than.

@item @code{<=} or @code{LE}
Less than or equal.

@item @code{=} or @code{EQ}
Equal.

@item @code{>} or @code{GT}
Greater than.

@item @code{>=} or @code{GE}
Greater than or equal.

@item @code{<>} or @code{~=} or @code{NE}
Not equal.
@end table

@item
The logical operators, which treat positive operands as true and
nonpositive operands as false.  They yield 0 for false and 1 for true:

@table @code
@item NOT
True if its single operand is false.

@item AND
True if both operands are true.

@item OR
True if at least one operand is true.

@item XOR
True if exactly one operand is true.
@end table
@end itemize

@node Matrix Multiplication Operator
@subsubsection The Matrix Multiplication Operator @samp{*}

If @code{A} is an @math{@var{m}@times{}@var{n}} matrix and @code{B} is
an @math{@var{n}@times{}@var{p}} matrix, then @code{A*B} is the
@math{@var{m}@times{}@var{p}} matrix multiplication product @code{C}.
@pspp{} reports an error if the number of columns in @code{A} differs
from the number of rows in @code{B}.

The @code{*} operator performs elementwise multiplication (see above)
if one of its operands is a scalar.

No built-in operator yields the inverse of matrix multiplication.
Instead, multiply by the result of @code{INV} or @code{GINV}.

Some examples:

@multitable @columnfractions .4 .05 .4
@item @t{@{1, 2, 3@} * @{4; 5; 6@}} @tab @result{} @tab @t{32}
@item @t{@{4; 5; 6@} * @{1, 2, 3@}} @tab @result{} @tab @t{@{4,@w{ } 8, 12; @*@w{ }5, 10, 15; @*@w{ }6, 12, 18@}}
@end multitable

@node Matrix Exponentiation Operator
@subsubsection The Matrix Exponentiation Operator @code{**}

The result of @code{A**B} is defined as follows when @code{A} is a
square matrix and @code{B} is an integer scalar:

@itemize @bullet
@item
For @code{B > 0}, @code{A**B} is @code{A*@dots{}*A}, where there are
@code{B} @samp{A}s.  (@pspp{} implements this efficiently for large
@code{B}, using exponentiation by squaring.)

@item
For @code{B < 0}, @code{A**B} is @code{INV(A**(-B))}.

@item
For @code{B = 0}, @code{A**B} is the identity matrix.
@end itemize

@noindent
@pspp{} reports an error if @code{A} is not square or @code{B} is not
an integer.