X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fdata-io.texi;h=a5ba26f0186eace4fed20f708ae4f9b802916c71;hb=cc0b5800fcdde6126c4fc65b656f39c1459bf17c;hp=cd0fc6386bae2ea99fecfbd8a40c2c5c1451435a;hpb=181b4767c0bfd3db0f8792caa55f276afbf23dda;p=pspp

diff --git a/doc/data-io.texi b/doc/data-io.texi
index cd0fc6386b..a5ba26f018 100644
--- a/doc/data-io.texi
+++ b/doc/data-io.texi
@@ -39,6 +39,7 @@ actually be read until a procedure is executed.
 * INPUT PROGRAM::               Support for complex input programs.
 * LIST::                        List cases in the active dataset.
 * NEW FILE::                    Clear the active dataset.
+* MATRIX DATA::                 Defining matrix material for procedures.
 * PRINT::                       Display values in print formats.
 * PRINT EJECT::                 Eject the current page then print.
 * PRINT SPACE::                 Print blank lines.
@@ -958,6 +959,125 @@ NEW FILE.
 @cmd{NEW FILE} command clears the dictionary and data from the current
 active dataset.
 
+@node MATRIX DATA
+@section MATRIX DATA
+@vindex MATRIX DATA
+
+@display
+MATRIX DATA
+        VARIABLES = @var{columns}
+        [eFILE='@var{file_name}'| INLINE @}
+        [/FORMAT= [@{LIST | FREE@}]
+                  [@{UPPER | LOWER | FULL@}]
+                  [@{DIAGONAL | NODIAGONAL@}]]
+        [/SPLIT= @var{split_variables}].
+@end display
+
+The @cmd{MATRIX DATA} command is used to input data in the form of matrices
+which can subsequently be used by other commands.  If the
+@subcmd{FILE} is omitted or takes the value @samp{INLINE} then the command
+should immediately followed by @cmd{BEGIN DATA}, @xref{BEGIN DATA}.
+
+There is one mandatory subcommand, @i{viz:} @subcmd{VARIABLES}, which defines
+the @var{columns} of the matrix.
+Normally, the @var{columns} should include an item called @samp{ROWTYPE_}.
+The @samp{ROWTYPE_} column is used to specify the purpose of a row in the
+matrix.
+
+@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
+
+In the above example, the first three rows have ROWTYPE_ values of
+@samp{mean}, @samp{sd}, and @samp{n}.  These indicate that the rows
+contain mean values, standard deviations and counts, respectively.
+All subsequent rows have a ROWTYPE_ of @samp{corr} which indicates
+that the values are correlation coefficients.
+
+Note that in this example, the upper right values of the @samp{corr}
+values are blank, and in each case, the rightmost value is unity.
+This is because, the
+@subcmd{FORMAT} subcommand defaults to @samp{LOWER DIAGONAL},
+which indicates that only the lower triangle is provided in the data.
+The opposite triangle is automatically inferred.  One could instead
+specify the upper triangle as follows:
+
+
+@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
+
+In this example the @samp{NODIAGONAL} keyword is used.  Accordingly
+the diagonal values of the matrix are omitted.  This implies that
+there is one less @samp{corr} line than there are variables.
+If the @samp{FULL} option is passed to the @subcmd{FORMAT} subcommand,
+then all the matrix elements must be provided, including the diagonal
+elements.
+
+In the preceding examples, each matrix row has been specified on a
+single line.  If you pass the keyword @var{FREE} to @subcmd{FORMAT}
+then the data may be data for several matrix rows may be specified on
+the same line, or a single row may be split across lines.
+
+The @subcmd{SPLIT} is used to indicate that variables are to be
+considered as split variables.  For example, the following
+defines two matrices using the variable @samp{S1} to distinguish
+between them.
+
+@example
+matrix data
+    variables = s1 rowtype_  var01 TO var04
+    /split = s1
+    /format = full diagonal.
+
+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
+
 @node PRINT
 @section PRINT
 @vindex PRINT