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.

Matrix Files
============

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.  See 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:

 1. Zero or more numeric split variables.  These are included by procedures when SPLIT FILE is active.  MATRIX DATA assigns split variables format F4.0.

 2. 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.

 3. 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.  MATRIX DATA assigns factor variables format F4.0.

 4. 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.  MATRIX DATA makes VARNAME_ wide enough for the name of any of the continuous variables, but at least 8 bytes.

 5. One or more numeric continuous variables.  These are the variables whose data was analyzed to produce the matrices.  MATRIX DATA assigns continuous variables format F10.4.

Case weights are ignored in matrix files.

Row Types
---------

Matrix files support a fixed set of types of matrix and vector data. The 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 ROWTYPE_.  All supported types of matrices are square, meaning that each matrix must include one row per continuous variable, with the VARNAME_ variable indicating each continuous variable in turn in the same order as the dictionary.

CORR
     Correlation coefficients.

COV
     Covariance coefficients.

MAT
     General-purpose matrix.

N_MATRIX
     Counts.

PROX
     Proximities matrix.

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

COUNT
     Unweighted counts.

DFE
     Degrees of freedom.

MEAN
     Means.

MSE
     Mean squared errors.

N
     Counts.

STDDEV
     Standard deviations.

Only the row types listed above may appear in matrix files.  The 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:

N_VECTOR
     Synonym for N.

SD
     Synonym for STDDEV.

N_SCALAR
     Accepts a single number from the MATRIX DATA input and writes it as an N row with the number replicated across all the continuous variables.

MATRIX DATA
===========

     MATRIX DATA
             VARIABLES=VARIABLES
             [FILE={'FILE_NAME' | INLINE}
             [/FORMAT=[{LIST | FREE}]
                      [{UPPER | LOWER | FULL}]
                      [{DIAGONAL | NODIAGONAL}]]
             [/SPLIT=SPLIT_VARS]
             [/FACTORS=FACTOR_VARS]
             [/N=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=N_CELLS]

The MATRIX DATA command convert matrices and vectors from text format into the matrix file format (see 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 .sav file using the SAVE command.

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

MATRIX DATA can read the types of matrix and vector data supported in matrix files (see Matrix File Row Types).

The 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 FILE or specify INLINE. Inline data must directly follow MATRIX DATA, inside BEGIN DATA (see BEGIN DATA).

VARIABLES is the only required subcommand.  It names the variables present in each input record in the order that they appear. (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 ROWTYPE_.

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

The FORMAT subcommand accepts settings to describe the format of the input data:

LIST (default)
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.

LOWER (default)
UPPER
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.

DIAGONAL (default)
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.

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

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 ROWTYPE_ is present in VARIABLES.  The following subsections explain MATRIX DATA syntax and behavior in each case.

With ROWTYPE_
-------------

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

Example 1: Defaults with ROWTYPE_
.................................

This example shows a simple use of MATRIX DATA with ROWTYPE_ plus 8 variables named var01 through var08.

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

The remaining 8 lines have a ROWTYPE_ of 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 var01, the next line for var02, and so on.  The input only contains values for the lower triangle, including the diagonal, since FORMAT=LOWER DIAGONAL is the default.

With ROWTYPE_, the CONTENTS subcommand is optional and the CELLS subcommand may not be used.

     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.

Example 2: FORMAT=UPPER NODIAGONAL
..................................

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

     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.

Example 3: N subcommand
.......................

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

     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.

Example 4: Split variables
..........................

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

     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.

Example 5: Factor variables
...........................

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

     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.

Without ROWTYPE_
----------------

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

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

Example 6: Defaults without ROWTYPE_
....................................

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

     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.

Example 7: Split variables with explicit values
...............................................

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

     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.

Example 8: Split variable with sequential values
................................................

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

     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.

Factor variables without ROWTYPE_
.................................

Without ROWTYPE_, factor variables introduce two new wrinkles to MATRIX DATA syntax.  First, the 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 CELLS=3; if there are two (or more) factor variables for which the data contains five combinations, one would use CELLS=5; and so on.

Second, the 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 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.

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

This syntax defines the same matrix file as Example 5 (see MATRIX DATA Example 5), without using ROWTYPE_.  It declares CELLS=2 because the data contains two values (0 and 1) for factor variable f1.  Within-cell vector row types MEAN, SD, and N are in a single set of parentheses on 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.

     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.

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.

     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.

MCONVERT
========

     MCONVERT
         [[MATRIX=]
          [IN({*|'FILE'})]
          [OUT({*|'FILE'})]]
         [/{REPLACE,APPEND}].

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

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

When 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 /APPEND to instead have MCONVERT add the other form of data without removing the existing data.  Use /REPLACE to explicitly request removing the existing data.

The MCONVERT command requires its input to be a matrix file. Use MATRIX DATA to convert text input into matrix file format. See MATRIX DATA, for details.

MATRIX
======

Overview
--------

     MATRIX.
     ...matrix commands...
     END MATRIX.

The following basic matrix commands are supported:

     COMPUTE variable[(index[,index])]=expression.
     CALL procedure(argument, ...).
     PRINT [expression]
           [/FORMAT=format]
           [/TITLE=title]
           [/SPACE={NEWPAGE | n}]
           [{/RLABELS=string... | /RNAMES=expression}]
           [{/CLABELS=string... | /CNAMES=expression}].

The following matrix commands offer support for flow control:

     DO IF expression.
       ...matrix commands...
     [ELSE IF expression.
       ...matrix commands...]...
     [ELSE
       ...matrix commands...]
     END IF.

     LOOP [var=first TO last [BY step]] [IF expression].
       ...matrix commands...
     END LOOP [IF expression].

     BREAK.

The following matrix commands support matrix input and output:

     READ variable[(index[,index])]
          [/FILE=file]
          /FIELD=first TO last [BY width]
          [/SIZE=expression]
          [/MODE={RECTANGULAR | SYMMETRIC}]
          [/REREAD]
          [/FORMAT=format].
     WRITE expression
           [/OUTFILE=file]
           /FIELD=first TO last [BY width]
           [/MODE={RECTANGULAR | TRIANGULAR}]
           [/HOLD]
           [/FORMAT=format].
     GET variable[(index[,index])]
         [/FILE={file | *}]
         [/VARIABLES=variable...]
         [/NAMES=expression]
         [/MISSING={ACCEPT | OMIT | number}]
         [/SYSMIS={OMIT | number}].
     SAVE expression
          [/OUTFILE={file | *}]
          [/VARIABLES=variable...]
          [/NAMES=expression]
          [/STRINGS=variable...].
     MGET [/FILE=file]
          [/TYPE={COV | CORR | MEAN | STDDEV | N | COUNT}].
     MSAVE expression
           /TYPE={COV | CORR | MEAN | STDDEV | N | COUNT}
           [/OUTFILE=file]
           [/VARIABLES=variable...]
           [/SNAMES=variable...]
           [/SPLIT=expression]
           [/FNAMES=variable...]
           [/FACTOR=expression].

The following matrix commands provide additional support:

     DISPLAY [{DICTIONARY | STATUS}].
     RELEASE variable....

Introduction
------------

MATRIX and 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 MATRIX...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 matrix is a rectangular array of real numbers.  An N times M matrix has N rows and M columns.  Some special cases are important: a N times1 matrix is a column vector, a 1 times N is a row vector, and a 1 times1 matrix is a 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 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.

Matrix Operators
----------------

Many matrix commands use expressions.  A matrix expression may use the following operators, listed in descending order of operator precedence.  Within a single level, operators associate from left to right.

  * Function call () and matrix construction {}

  * Indexing ()

  * Unary + and -

  * Integer sequence :

  * Exponentiation ** and &**

  * Multiplication * and &*, and division / and &/

  * Addition + and subtraction -

  * Relational < <= = >= > <>

  * Logical NOT

  * Logical AND

  * Logical OR and XOR

See Matrix Functions, for the available matrix functions.  The remaining operators are described in more detail below.

Matrix Construction Operator {}
...............................

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

{1, 2, 3; 4, 5, 6}
=>

[1  2  3]
 [4  5  6]
{3.14, 6.28, 9.24, 12.57}
=>

[3.14  6.28  9.42  12.57]
{1.41; 1.73; 2}
=>

[1.41]
 [1.73]
 [2.00]
{5}
=>
5

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 m is matrix {1, 2; 3, 4}, r is row vector {5, 6}, and c is column vector {7, 8}, then curly braces can be used as follows:

{m, c; r, 10}
=>

[1 2  7]
 [3 4  8]
 [5 6 10]
{c, 2 * c, T(r)}
=>

[7 14 5]
 [8 16 6]

The final example above uses the transposition function T.

Integer Sequence Operator :
...........................

The syntax FIRST:LAST:STEP yields a row vector of consecutive integers from FIRST to LAST counting by STEP.  The final :STEP is optional and defaults to 1 when omitted.

Each of FIRST, LAST, and STEP must be a scalar and should be an integer (any fractional part is discarded).  Because : has a high precedence, operands other than numeric literals must usually be parenthesized.

When STEP is positive (or omitted) and END < START, or if STEP is negative and END > START, then the result is an empty matrix.  If STEP is 0, then pspp reports an error.

Here are some examples:

1:6        =>   {1, 2, 3, 4, 5, 6}
1:6:2      =>   {1, 3, 5}
-1:-5:-1   =>   {-1, -2, -3, -4, -5}
-1:-5      =>   {}
2:1:0      =>   (error)

Index Operator ()
.................

The result of the submatrix or indexing operator, written M(RINDEX, CINDEX), contains the rows of M whose indexes are given in vector RINDEX and the columns whose indexes are given in vector CINDEX.

In the simplest case, if RINDEX and CINDEX are both scalars, the result is also a scalar:

{10, 20; 30, 40}(1, 1)   =>   10
{10, 20; 30, 40}(1, 2)   =>   20
{10, 20; 30, 40}(2, 1)   =>   30
{10, 20; 30, 40}(2, 2)   =>   40

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

{10, 20; 30, 40}(1:2, 1)   =>   {10; 30}
{10, 20; 30, 40}(2, 1:2)   =>   {30, 40}
{10, 20; 30, 40}(1:2, 1:2)   =>   {10, 20; 30, 40}

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

{10, 20; 30, 40}(:, 1)   =>   {10; 30}
{10, 20; 30, 40}(2, :)   =>   {30, 40}
{10, 20; 30, 40}(:, :)   =>   {10, 20; 30, 40}

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

{10, 20; 30, 40}({2, 1}, 1)   =>   {30; 10}
{10, 20; 30, 40}(2, {2; 2; 1})   =>   {40, 40, 30}
{10, 20; 30, 40}(2:1:-1, :)   =>   {30, 40; 10, 20}

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

{11, 12, 13, 14, 15}(2:4)   =>   {12, 13, 14}
{11; 12; 13; 14; 15}(2:4)   =>   {12; 13; 14}

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:

{11, 12, 13, 14}({2.5, 4.6})   =>   {12, 14}
{11; 12; 13; 14}(0)   =>   (error)

Unary Operators
...............

The unary operators take a single operand of any dimensions and operate on each of its elements independently.  The unary operators are:

-
     Inverts the sign of each element.

+
     No change.

NOT
     Logical inversion: each positive value becomes 0 and each zero or negative value becomes 1.

Examples:

-{1, -2; 3, -4}   =>   {-1, 2; -3, 4}
+{1, -2; 3, -4}   =>   {1, -2; 3, -4}
NOT {1, 0; -1, 1}   =>   {0, 1; 1, 0}

Elementwise Binary Operators
............................

The elementwise binary 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 binary operators are listed below.

  * The arithmetic operators, for familiar arithmetic operations:

     +
          Addition.

     -
          Subtraction.

     *
          Multiplication, if one operand is a scalar.  (Otherwise this is matrix multiplication, described below.)

     / or &/
          Division.

     &*
          Multiplication.

     &**
          Exponentiation.

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

     < or LT
          Less than.

     <= or LE
          Less than or equal.

     = or EQ
          Equal.

     > or GT
          Greater than.

     >= or GE
          Greater than or equal.

     <> or ~= or NE
          Not equal.

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

     AND
          True if both operands are true.

     OR
          True if at least one operand is true.

     XOR
          True if exactly one operand is true.

Examples:

1 + 2   =>   3
1 + {3; 4}   =>   {4; 5}
{66, 77; 88, 99} + 5   =>   {71, 82; 93, 104}
{4, 8; 3, 7} + {1, 0; 5, 2}   =>   {5, 8; 8, 9}
{1, 2; 3, 4} < {4, 3; 2, 1}   =>   {1, 1; 0, 0}
{1, 3; 2, 4} >= 3   =>   {0, 1; 0, 1}
{0, 0; 1, 1} AND {0, 1; 0, 1}   =>   {0, 0; 0, 1}

Matrix Multiplication Operator *
................................

If A is an M times N matrix and B is an N times P matrix, then A*B is the M times P matrix multiplication product C. pspp reports an error if the number of columns in A differs from the number of rows in B.

The * 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 INV or GINV.

Some examples:

{1, 2, 3} * {4; 5; 6}   =>   32
{4; 5; 6} * {1, 2, 3}   =>   {4,  8, 12;
 5, 10, 15;
 6, 12, 18}

Matrix Exponentiation Operator **
.................................

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

  * For B > 0, A**B is A*...*A, where there are B As.  (pspp implements this efficiently for large B, using exponentiation by squaring.)

  * For B < 0, A**B is INV(A**(-B)).

  * For B = 0, A**B is the identity matrix.

pspp reports an error if A is not square or B is not an integer.

Examples:

{2, 5; 1, 4}**3   =>   {48, 165; 33, 114}
{2, 5; 1, 4}**0   =>   {1, 0; 0, 1}
10*{4, 7; 2, 6}**-1   =>   {6, -7; -2, 4}

Matrix Functions
----------------

The matrix language support numerous functions in multiple categories. The following subsections document each of the currently supported functions.  The first letter of each parameter's name indicate the required argument type:

s
     Any scalar.

n
     A scalar with a nonnegative integer value.  (Non-integers are rounded down to the nearest integer.)

v
     A row or column vector.

m
     A matrix.

Elementwise Functions
.....................

These functions act on each element of their argument independently, like the elementwise operators (see Matrix Elementwise Binary Operators).

 -- Matrix Function: ABS (M)
     Takes the absolute value of each element of M.

     ABS({-1, 2; -3, 0}) => {1, 2; 3, 0}

 -- Matrix Function: ARSIN (M)
 -- Matrix Function: ARTAN (M)
     Computes the inverse sine or tangent, respectively, of each element in M.  The results are in radians, between -\pi/2 and +\pi/2, inclusive.

 -- Matrix Function: COS (M)
 -- Matrix Function: SIN (M)
     Computes the cosine or sine, respectively, of each element in M, which must be in radians.

 -- Matrix Function: EXP (M)
     Computes e^x for each element X in M.

 -- Matrix Function: LG10 (M)
 -- Matrix Function: LN (M)
     Takes the logarithm with base 10 or base e, respectively, of each element in M.

 -- Matrix Function: MOD (M, S)
     Takes each element in M modulo nonzero scalar value S, that is, the remainder of division by S.  The sign of the result is the same as the sign of the dividend.

 -- Matrix Function: RND (M)
 -- Matrix Function: TRUNC (M)
     Rounds each element of M to an integer.  RND rounds to the nearest integer, with halves rounded to even integers, and TRUNC rounds toward zero.

 -- Matrix Function: SQRT (M)
     Takes the square root of each element of M, which must not be negative.

Logical Functions
.................

 -- Matrix Function: ALL (M)
     Returns a scalar with value 1 if all of the elements in M are nonzero, or 0 if at least one element is zero.

 -- Matrix Function: ANY (M)
     Returns a scalar with value 1 if any of the elements in M is nonzero, or 0 if all of them are zero.

Matrix Construction Functions
.............................

 -- Matrix Function: BLOCK (M1, ..., MN)
     Returns a block diagonal matrix with as many rows as the sum of its arguments' row counts and as many columns as the sum of their columns. Each argument matrix is placed along the main diagonal of the result, and all other elements are zero.

 -- Matrix Function: IDENT (N)
 -- Matrix Function: IDENT (NR, NC)
     Returns an identity matrix, whose main diagonal elements are one and whose other elements are zero.  The returned matrix has N rows and columns or NR rows and NC columns, respectively.

 -- Matrix Function: MAGIC (N)
     Returns an N times N matrix that contains each of the integers 1...N once, in which each column, each row, and each diagonal sums to n(n^2+1)/2.  There are many magic squares with given dimensions, but this function always returns the same one for a given value of N.

 -- Matrix Function: MAKE (NR, NC, S)
     Returns an NR times NC matrix whose elements are all S.

 -- Matrix Function: MDIAG (V)
     Returns a |V|times|V| matrix whose main diagonal comes from V and whose other elements are zero.

 -- Matrix Function: RESHAPE (M, NR, NC)
     Returns an NR times NC matrix whose elements come from M, which must have the same number of elements as the new matrix, copying elements from M to the new matrix row by row.

 -- Matrix Function: T (M)
 -- Matrix Function: TRANSPOS (M)
     Returns M with rows exchanged for columns.

 -- Matrix Function: UNIFORM (NR, NC)
     Returns a NR times NC matrix in which each element is randomly chosen from a uniform distribution of real numbers between 0 and 1.

Minimum, Maximum, and Sum Functions
...................................

 -- Matrix Function: CMIN (M)
 -- Matrix Function: CMAX (M)
 -- Matrix Function: CSUM (M)
 -- Matrix Function: CSSQ (M)
     Returns a row vector with the same number of columns as M, in which each element is the minimum, maximum, sum, or sum of squares, respectively, of the elements in the same column of M.

 -- Matrix Function: MMIN (M)
 -- Matrix Function: MMAX (M)
 -- Matrix Function: MSUM (M)
 -- Matrix Function: MSSQ (M)
     Returns the minimum, maximum, sum, or sum of squares, respectively, of the elements of M.

 -- Matrix Function: RMIN (M)
 -- Matrix Function: RMAX (M)
 -- Matrix Function: RSUM (M)
 -- Matrix Function: RSSQ (M)
     Returns a column vector with the same number of rows as M, in which each element is the minimum, maximum, sum, or sum of squares, respectively, of the elements in the same row of M.

 -- Matrix Function: SSCP (M)
     Returns T(M) * M.

 -- Matrix Function: TRACE (M)
     Returns the sum of the elements along M's main diagonal, equivalent to MSUM(DIAG(M)).

Matrix Property Functions
.........................

 -- Matrix Function: NROW (M)
 -- Matrix Function: NCOL (M)
     Returns the number of row or columns, respectively, in M.

 -- Matrix Function: DIAG (M)
     Returns a column vector containing a copy of M's main diagonal. The vector's length is the lesser of NCOL(M) and NROW(M).

Matrix Rank Ordering Functions
..............................

 -- Matrix Function: GRADE (M)
     Returns a matrix with the same dimensions as M in which each elements is a unique integer, from 1 to the number of elements in M, that corresponds to its rank within M.  The smallest element in M corresponds to value 1 in the returned matrix, the next smallest to value 2, and so on.  When multiple elements in M have the same value, they are assigned consecutive unique ranks in the return matrix.

The GRADE function can be used to sort a vector.  For example, the following syntax:

     MATRIX.
     COMPUTE v={2, 5, 1, 4, 9, 7, 8, 10, 6, 3}.
     COMPUTE v(GRADE(v))=v.
     PRINT v.
     END MATRIX.

yields the following sorted output:

     v
        1   2   3   4   5   6   7   8   9  10

 -- Matrix Function: RNKORDER (M)

Matrix Algebra Functions
........................

 -- Matrix Function: CHOL (M)

 -- Matrix Function: DESIGN (M)

 -- Matrix Function: DET (M)

 -- Matrix Function: EVAL (M)

 -- Matrix Function: GINV (M)

 -- Matrix Function: GSCH (M)

 -- Matrix Function: INV (M)

 -- Matrix Function: KRONEKER (M1, M2)

 -- Matrix Function: RANK (M)

 -- Matrix Function: SOLVE (MA, MB)

 -- Matrix Function: SVAL (M)

 -- Matrix Function: SWEEP (M, N)

I/O
...

 -- Matrix Function: EOF (FILE)