doc/matrices.texi

   1 @c PSPP - a program for statistical analysis.
   2 @c Copyright (C) 2017, 2020, 2021 Free Software Foundation, Inc.
   3 @c Permission is granted to copy, distribute and/or modify this document
   4 @c under the terms of the GNU Free Documentation License, Version 1.3
   5 @c or any later version published by the Free Software Foundation;
   6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
   7 @c A copy of the license is included in the section entitled "GNU
   8 @c Free Documentation License".
   9 @c
  10 @node Matrices
  11 @chapter Matrices
  12
  13 Some @pspp{} procedures work with matrices by producing numeric
  14 matrices that report results of data analysis, or by consuming
  15 matrices as a basis for further analysis.  This chapter documents the
  16 format of data files that store these matrices and commands for
  17 working with them, as well as @pspp{}'s general-purpose facility for
  18 matrix operations.
  19
  20 @node Matrix Files
  21 @section Matrix Files
  22 @vindex Matrix file
  23
  24 A matrix file is an SPSS system file that conforms to the dictionary
  25 and case structure described in this section.  Procedures that read
  26 matrices from files expect them to be in the matrix file format.
  27 Procedures that write matrices also use this format.
  28
  29 Text files that contain matrices can be converted to matrix file
  30 format.  @xref{MATRIX DATA}, for a command to read a text file as a
  31 matrix file.
  32
  33 A matrix file's dictionary must have the following variables in the
  34 specified order:
  35
  36 @enumerate
  37 @item
  38 Zero or more numeric split variables.  These are included by
  39 procedures when @cmd{SPLIT FILE} is active.  @cmd{MATRIX DATA} assigns
  40 split variables format F4.0.
  41
  42 @item
  43 @code{ROWTYPE_}, a string variable with width 8.  This variable
  44 indicates the kind of matrix or vector that a given case represents.
  45 The supported row types are listed below.
  46
  47 @item
  48 Zero or more numeric factor variables.  These are included by
  49 procedures that divide data into cells.  For within-cell data, factor
  50 variables are filled with non-missing values; for pooled data, they
  51 are missing.  @cmd{MATRIX DATA} assigns factor variables format F4.0.
  52
  53 @item
  54 @code{VARNAME_}, a string variable.  Matrix data includes one row per
  55 continuous variable (see below), naming each continuous variable in
  56 order.  This column is blank for vector data.  @cmd{MATRIX DATA} makes
  57 @code{VARNAME_} wide enough for the name of any of the continuous
  58 variables, but at least 8 bytes.
  59
  60 @item
  61 One or more numeric continuous variables.  These are the variables
  62 whose data was analyzed to produce the matrices.  @cmd{MATRIX DATA}
  63 assigns continuous variables format F10.4.
  64 @end enumerate
  65
  66 Case weights are ignored in matrix files.
  67
  68 @subheading Row Types
  69 @anchor{Matrix File Row Types}
  70
  71 Matrix files support a fixed set of types of matrix and vector data.
  72 The @code{ROWTYPE_} variable in each case of a matrix file indicates
  73 its row type.
  74
  75 The supported matrix row types are listed below.  Each type is listed
  76 with the keyword that identifies it in @code{ROWTYPE_}.  All supported
  77 types of matrices are square, meaning that each matrix must include
  78 one row per continuous variable, with the @code{VARNAME_} variable
  79 indicating each continuous variable in turn in the same order as the
  80 dictionary.
  81
  82 @table @code
  83 @item CORR
  84 Correlation coefficients.
  85
  86 @item COV
  87 Covariance coefficients.
  88
  89 @item MAT
  90 General-purpose matrix.
  91
  92 @item N_MATRIX
  93 Counts.
  94
  95 @item PROX
  96 Proximities matrix.
  97 @end table
  98
  99 The supported vector row types are listed below, along with their
 100 associated keyword.  Vector row types only require a single row, whose
 101 @code{VARNAME_} is blank:
 102
 103 @table @code
 104 @item COUNT
 105 Unweighted counts.
 106
 107 @item DFE
 108 Degrees of freedom.
 109
 110 @item MEAN
 111 Means.
 112
 113 @item MSE
 114 Mean squared errors.
 115
 116 @item N
 117 Counts.
 118
 119 @item STDDEV
 120 Standard deviations.
 121 @end table
 122
 123 Only the row types listed above may appear in matrix files.  The
 124 @cmd{MATRIX DATA} command, however, accepts the additional row types
 125 listed below, which it changes into matrix file row types as part of
 126 its conversion process:
 127
 128 @table @code
 129 @item N_VECTOR
 130 Synonym for @cmd{N}.
 131
 132 @item SD
 133 Synonym for @code{STDDEV}.
 134
 135 @item N_SCALAR
 136 Accepts a single number from the @code{MATRIX DATA} input and writes
 137 it as an @code{N} row with the number replicated across all the
 138 continuous variables.
 139 @end table
 140
 141 @node MATRIX DATA
 142 @section MATRIX DATA
 143 @vindex MATRIX DATA
 144
 145 @display
 146 MATRIX DATA
 147         VARIABLES=@var{variables}
 148         [FILE=@{'@var{file_name}' | INLINE@}
 149         [/FORMAT=[@{LIST | FREE@}]
 150                  [@{UPPER | LOWER | FULL@}]
 151                  [@{DIAGONAL | NODIAGONAL@}]]
 152         [/SPLIT=@var{split_vars}]
 153         [/FACTORS=@var{factor_vars}]
 154         [/N=@var{n}]
 155
 156 The following subcommands are only needed when ROWTYPE_ is not
 157 specified on the VARIABLES subcommand:
 158         [/CONTENTS=@{CORR,COUNT,COV,DFE,MAT,MEAN,MSE,
 159                     N_MATRIX,N|N_VECTOR,N_SCALAR,PROX,SD|STDDEV@}]
 160         [/CELLS=@var{n_cells}]
 161 @end display
 162
 163 The @cmd{MATRIX DATA} command convert matrices and vectors from text
 164 format into the matrix file format (@xref{Matrix Files}) for use by
 165 procedures that read matrices.  It reads a text file or inline data
 166 and outputs to the active file, replacing any data already in the
 167 active dataset.  The matrix file may then be used by other commands
 168 directly from the active file, or it may be written to a @file{.sav}
 169 file using the @cmd{SAVE} command.
 170
 171 The text data read by @cmd{MATRIX DATA} can be delimited by spaces or
 172 commas.  A plus or minus sign, except immediately following a @samp{d}
 173 or @samp{e}, also begins a new value.  Optionally, values may be
 174 enclosed in single or double quotes.
 175
 176 @cmd{MATRIX DATA} can read the types of matrix and vector data
 177 supported in matrix files (@pxref{Matrix File Row Types}).
 178
 179 The @subcmd{FILE} subcommand specifies the source of the command's
 180 input.  To read input from a text file, specify its name in quotes.
 181 To supply input inline, omit @subcmd{FILE} or specify @code{INLINE}.
 182 Inline data must directly follow @code{MATRIX DATA}, inside @cmd{BEGIN
 183 DATA} (@pxref{BEGIN DATA}).
 184
 185 @subcmd{VARIABLES} is the only required subcommand.  It names the
 186 variables present in each input record in the order that they appear.
 187 (@cmd{MATRIX DATA} reorders the variables in the matrix file it
 188 produces, if needed to fit the matrix file format.)  The variable list
 189 must include split variables and factor variables, if they are present
 190 in the data, in addition to the continuous variables that form matrix
 191 rows and columns.  It may also include a special variable named
 192 @code{ROWTYPE_}.
 193
 194 Matrix data may include split variables or factor variables or both.
 195 List split variables, if any, on the @subcmd{SPLIT} subcommand and
 196 factor variables, if any, on the @subcmd{FACTORS} subcommand.  Split
 197 and factor variables must be numeric.  Split and factor variables must
 198 also be listed on @subcmd{VARIABLES}, with one exception: if
 199 @subcmd{VARIABLES} does not include @code{ROWTYPE_}, then
 200 @subcmd{SPLIT} may name a single variable that is not in
 201 @subcmd{VARIABLES} (@pxref{MATRIX DATA Example 8}).
 202
 203 The @subcmd{FORMAT} subcommand accepts settings to describe the format
 204 of the input data:
 205
 206 @table @asis
 207 @item @code{LIST} (default)
 208 @itemx @code{FREE}
 209 LIST requires each row to begin at the start of a new input line.
 210 FREE allows rows to begin in the middle of a line.  Either setting
 211 allows a single row to continue across multiple input lines.
 212
 213 @item @code{LOWER} (default)
 214 @itemx @code{UPPER}
 215 @itemx @code{FULL}
 216 With LOWER, only the lower triangle is read from the input data and
 217 the upper triangle is mirrored across the main diagonal.  UPPER
 218 behaves similarly for the upper triangle.  FULL reads the entire
 219 matrix.
 220
 221 @item @code{DIAGONAL} (default)
 222 @itemx @code{NODIAGONAL}
 223 With DIAGONAL, the main diagonal is read from the input data.  With
 224 NODIAGONAL, which is incompatible with FULL, the main diagonal is not
 225 read from the input data but instead set to 1 for correlation matrices
 226 and system-missing for others.
 227 @end table
 228
 229 The @subcmd{N} subcommand is a way to specify the size of the
 230 population.  It is equivalent to specifying an @code{N} vector with
 231 the specified value for each split file.
 232
 233 @cmd{MATRIX DATA} supports two different ways to indicate the kinds of
 234 matrices and vectors present in the data, depending on whether a
 235 variable with the special name @code{ROWTYPE_} is present in
 236 @code{VARIABLES}.  The following subsections explain @cmd{MATRIX DATA}
 237 syntax and behavior in each case.
 238
 239 @node MATRIX DATA with ROWTYPE_
 240 @subsection With @code{ROWTYPE_}
 241
 242 If @code{VARIABLES} includes @code{ROWTYPE_}, each case's
 243 @code{ROWTYPE_} indicates the type of data contained in the row.
 244 @xref{Matrix File Row Types}, for a list of supported row types.
 245
 246 @subsubheading Example 1: Defaults with @code{ROWTYPE_}
 247 @anchor{MATRIX DATA Example 1}
 248
 249 This example shows a simple use of @cmd{MATRIX DATA} with
 250 @code{ROWTYPE_} plus 8 variables named @code{var01} through
 251 @code{var08}.
 252
 253 Because @code{ROWTYPE_} is the first variable in @subcmd{VARIABLES},
 254 it appears first on each line. The first three lines in the example
 255 data have @code{ROWTYPE_} values of @samp{MEAN}, @samp{SD}, and
 256 @samp{N}.  These indicate that these lines contain vectors of means,
 257 standard deviations, and counts, respectively, for @code{var01}
 258 through @code{var08} in order.
 259
 260 The remaining 8 lines have a ROWTYPE_ of @samp{CORR} which indicates
 261 that the values are correlation coefficients.  Each of the lines
 262 corresponds to a row in the correlation matrix: the first line is for
 263 @code{var01}, the next line for @code{var02}, and so on.  The input
 264 only contains values for the lower triangle, including the diagonal,
 265 since @code{FORMAT=LOWER DIAGONAL} is the default.
 266
 267 With @code{ROWTYPE_}, the @code{CONTENTS} subcommand is optional and
 268 the @code{CELLS} subcommand may not be used.
 269
 270 @example
 271 MATRIX DATA
 272     VARIABLES=ROWTYPE_ var01 TO var08.
 273 BEGIN DATA.
 274 MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
 275 SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
 276 N       92    92    92    92    92    92    92    92
 277 CORR  1.00
 278 CORR   .18  1.00
 279 CORR  -.22  -.17  1.00
 280 CORR   .36   .31  -.14  1.00
 281 CORR   .27   .16  -.12   .22  1.00
 282 CORR   .33   .15  -.17   .24   .21  1.00
 283 CORR   .50   .29  -.20   .32   .12   .38  1.00
 284 CORR   .17   .29  -.05   .20   .27   .20   .04  1.00
 285 END DATA.
 286 @end example
 287
 288 @subsubheading Example 2: @code{FORMAT=UPPER NODIAGONAL}
 289
 290 This syntax produces the same matrix file as example 1, but it uses
 291 @code{FORMAT=UPPER NODIAGONAL} to specify the upper triangle and omit
 292 the diagonal.  Because the matrix's @code{ROWTYPE_} is @code{CORR},
 293 @pspp{} automatically fills in the diagonal with 1.
 294
 295 @example
 296 MATRIX DATA
 297     VARIABLES=ROWTYPE_ var01 TO var08
 298     /FORMAT=UPPER NODIAGONAL.
 299 BEGIN DATA.
 300 MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
 301 SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
 302 N       92    92    92    92    92    92    92    92
 303 CORR         .17   .50  -.33   .27   .36  -.22   .18
 304 CORR               .29   .29  -.20   .32   .12   .38
 305 CORR                     .05   .20  -.15   .16   .21
 306 CORR                           .20   .32  -.17   .12
 307 CORR                                 .27   .12  -.24
 308 CORR                                      -.20  -.38
 309 CORR                                             .04
 310 END DATA.
 311 @end example
 312
 313 @subsubheading Example 3: @subcmd{N} subcommand
 314
 315 This syntax uses the @subcmd{N} subcommand in place of an @code{N}
 316 vector.  It produces the same matrix file as examples 1 and 2.
 317
 318 @example
 319 MATRIX DATA
 320     VARIABLES=ROWTYPE_ var01 TO var08
 321     /FORMAT=UPPER NODIAGONAL
 322     /N 92.
 323 BEGIN DATA.
 324 MEAN  24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
 325 SD     5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
 326 CORR         .17   .50  -.33   .27   .36  -.22   .18
 327 CORR               .29   .29  -.20   .32   .12   .38
 328 CORR                     .05   .20  -.15   .16   .21
 329 CORR                           .20   .32  -.17   .12
 330 CORR                                 .27   .12  -.24
 331 CORR                                      -.20  -.38
 332 CORR                                             .04
 333 END DATA.
 334 @end example
 335
 336 @subsubheading Example 4: Split variables
 337 @anchor{MATRIX DATA Example 4}
 338
 339 This syntax defines two matrices, using the variable @samp{s1} to
 340 distinguish between them.  Notice how the order of variables in the
 341 input matches their order on @subcmd{VARIABLES}.  This example also
 342 uses @code{FORMAT=FULL}.
 343
 344 @example
 345 MATRIX DATA
 346     VARIABLES=s1 ROWTYPE_  var01 TO var04
 347     /SPLIT=s1
 348     /FORMAT=FULL.
 349 BEGIN DATA.
 350 0 MEAN 34 35 36 37
 351 0 SD   22 11 55 66
 352 0 N    99 98 99 92
 353 0 CORR  1 .9 .8 .7
 354 0 CORR .9  1 .6 .5
 355 0 CORR .8 .6  1 .4
 356 0 CORR .7 .5 .4  1
 357 1 MEAN 44 45 34 39
 358 1 SD   23 15 51 46
 359 1 N    98 34 87 23
 360 1 CORR  1 .2 .3 .4
 361 1 CORR .2  1 .5 .6
 362 1 CORR .3 .5  1 .7
 363 1 CORR .4 .6 .7  1
 364 END DATA.
 365 @end example
 366
 367 @subsubheading Example 5: Factor variables
 368 @anchor{MATRIX DATA Example 5}
 369
 370 This syntax defines a matrix file that includes a factor variable
 371 @samp{f1}.  The data includes mean, standard deviation, and count
 372 vectors for two values of the factor variable, plus a correlation
 373 matrix for pooled data.
 374
 375 @example
 376 MATRIX DATA
 377     VARIABLES=ROWTYPE_ f1 var01 TO var04
 378     /FACTOR=f1.
 379 BEGIN DATA.
 380 MEAN 0 34 35 36 37
 381 SD   0 22 11 55 66
 382 N    0 99 98 99 92
 383 MEAN 1 44 45 34 39
 384 SD   1 23 15 51 46
 385 N    1 98 34 87 23
 386 CORR .  1
 387 CORR . .9  1
 388 CORR . .8 .6  1
 389 CORR . .7 .5 .4  1
 390 END DATA.
 391 @end example
 392
 393 @node MATRIX DATA without ROWTYPE_
 394 @subsection Without @code{ROWTYPE_}
 395
 396 If @code{VARIABLES} does not contain @code{ROWTYPE_}, the
 397 @subcmd{CONTENTS} subcommand defines the row types that appear in the
 398 file and their order.  If @subcmd{CONTENTS} is omitted,
 399 @code{CONTENTS=CORR} is assumed.
 400
 401 Factor variables without @code{ROWTYPE_} introduce special
 402 requirements, illustrated below in Examples 8 and 9.
 403
 404 @subsubheading Example 6: Defaults without @code{ROWTYPE_}
 405
 406 This example shows a simple use of @cmd{MATRIX DATA} with 8 variables
 407 named @code{var01} through @code{var08}, without @code{ROWTYPE_}.
 408 This yields the same matrix file as Example 1 (@pxref{MATRIX DATA
 409 Example 1}).
 410
 411 @example
 412 MATRIX DATA
 413     VARIABLES=var01 TO var08
 414    /CONTENTS=MEAN SD N CORR.
 415 BEGIN DATA.
 416 24.3   5.4  69.7  20.1  13.4   2.7  27.9   3.7
 417  5.7   1.5  23.5   5.8   2.8   4.5   5.4   1.5
 418   92    92    92    92    92    92    92    92
 419 1.00
 420  .18  1.00
 421 -.22  -.17  1.00
 422  .36   .31  -.14  1.00
 423  .27   .16  -.12   .22  1.00
 424  .33   .15  -.17   .24   .21  1.00
 425  .50   .29  -.20   .32   .12   .38  1.00
 426  .17   .29  -.05   .20   .27   .20   .04  1.00
 427 END DATA.
 428 @end example
 429
 430 @subsubheading Example 7: Split variables with explicit values
 431
 432 This syntax defines two matrices, using the variable @code{s1} to
 433 distinguish between them.  Each line of data begins with @code{s1}.
 434 This yields the same matrix file as Example 4 (@pxref{MATRIX DATA
 435 Example 4}).
 436
 437 @example
 438 MATRIX DATA
 439     VARIABLES=s1 var01 TO var04
 440     /SPLIT=s1
 441     /FORMAT=FULL
 442     /CONTENTS=MEAN SD N CORR.
 443 BEGIN DATA.
 444 0 34 35 36 37
 445 0 22 11 55 66
 446 0 99 98 99 92
 447 0  1 .9 .8 .7
 448 0 .9  1 .6 .5
 449 0 .8 .6  1 .4
 450 0 .7 .5 .4  1
 451 1 44 45 34 39
 452 1 23 15 51 46
 453 1 98 34 87 23
 454 1  1 .2 .3 .4
 455 1 .2  1 .5 .6
 456 1 .3 .5  1 .7
 457 1 .4 .6 .7  1
 458 END DATA.
 459 @end example
 460
 461 @subsubheading Example 8: Split variable with sequential values
 462 @anchor{MATRIX DATA Example 8}
 463
 464 Like this previous example, this syntax defines two matrices with
 465 split variable @code{s1}.  In this case, though, @code{s1} is not
 466 listed in @subcmd{VARIABLES}, which means that its value does not
 467 appear in the data.  Instead, @cmd{MATRIX DATA} reads matrix data
 468 until the input is exhausted, supplying 1 for the first split, 2 for
 469 the second, and so on.
 470
 471 @example
 472 MATRIX DATA
 473     VARIABLES=var01 TO var04
 474     /SPLIT=s1
 475     /FORMAT=FULL
 476     /CONTENTS=MEAN SD N CORR.
 477 BEGIN DATA.
 478 34 35 36 37
 479 22 11 55 66
 480 99 98 99 92
 481  1 .9 .8 .7
 482 .9  1 .6 .5
 483 .8 .6  1 .4
 484 .7 .5 .4  1
 485 44 45 34 39
 486 23 15 51 46
 487 98 34 87 23
 488  1 .2 .3 .4
 489 .2  1 .5 .6
 490 .3 .5  1 .7
 491 .4 .6 .7  1
 492 END DATA.
 493 @end example
 494
 495 @subsubsection Factor variables without @code{ROWTYPE_}
 496
 497 Without @subcmd{ROWTYPE_}, factor variables introduce two new wrinkles
 498 to @cmd{MATRIX DATA} syntax.  First, the @subcmd{CELLS} subcommand
 499 must declare the number of combinations of factor variables present in
 500 the data.  If there is, for example, one factor variable for which the
 501 data contains three values, one would write @code{CELLS=3}; if there
 502 are two (or more) factor variables for which the data contains five
 503 combinations, one would use @code{CELLS=5}; and so on.
 504
 505 Second, the @subcmd{CONTENTS} subcommand must distinguish within-cell
 506 data from pooled data by enclosing within-cell row types in
 507 parentheses.  When different within-cell row types for a single factor
 508 appear in subsequent lines, enclose the row types in a single set of
 509 parentheses; when different factors' values for a given within-cell
 510 row type appear in subsequent lines, enclose each row type in
 511 individual parentheses.
 512
 513 Without @subcmd{ROWTYPE_}, input lines for pooled data do not include
 514 factor values, not even as missing values, but input lines for
 515 within-cell data do.
 516
 517 The following examples aim to clarify this syntax.
 518
 519 @subsubheading Example 9: Factor variables, grouping within-cell records by factor
 520
 521 This syntax defines the same matrix file as Example 5 (@pxref{MATRIX
 522 DATA Example 5}), without using @code{ROWTYPE_}.  It declares
 523 @code{CELLS=2} because the data contains two values (0 and 1) for
 524 factor variable @code{f1}.  Within-cell vector row types @code{MEAN},
 525 @code{SD}, and @code{N} are in a single set of parentheses on
 526 @subcmd{CONTENTS} because they are grouped together in subsequent
 527 lines for a single factor value.  The data lines with the pooled
 528 correlation matrix do not have any factor values.
 529
 530 @example
 531 MATRIX DATA
 532     VARIABLES=f1 var01 TO var04
 533     /FACTOR=f1
 534     /CELLS=2
 535     /CONTENTS=(MEAN SD N) CORR.
 536 BEGIN DATA.
 537 0 34 35 36 37
 538 0 22 11 55 66
 539 0 99 98 99 92
 540 1 44 45 34 39
 541 1 23 15 51 46
 542 1 98 34 87 23
 543    1
 544   .9  1
 545   .8 .6  1
 546   .7 .5 .4  1
 547 END DATA.
 548 @end example
 549
 550 @subsubheading Example 10: Factor variables, grouping within-cell records by row type
 551
 552 This syntax defines the same matrix file as the previous example.  The
 553 only difference is that the within-cell vector rows are grouped
 554 differently: two rows of means (one for each factor), followed by two
 555 rows of standard deviations, followed by two rows of counts.
 556
 557 @example
 558 MATRIX DATA
 559     VARIABLES=f1 var01 TO var04
 560     /FACTOR=f1
 561     /CELLS=2
 562     /CONTENTS=(MEAN) (SD) (N) CORR.
 563 BEGIN DATA.
 564 0 34 35 36 37
 565 1 44 45 34 39
 566 0 22 11 55 66
 567 1 23 15 51 46
 568 0 99 98 99 92
 569 1 98 34 87 23
 570    1
 571   .9  1
 572   .8 .6  1
 573   .7 .5 .4  1
 574 END DATA.
 575 @end example
 576
 577 @node MCONVERT
 578 @section MCONVERT
 579 @vindex MCONVERT
 580
 581 @display
 582 MCONVERT
 583     [[MATRIX=]
 584      [IN(@{@samp{*}|'@var{file}'@})]
 585      [OUT(@{@samp{*}|'@var{file}'@})]]
 586     [/@{REPLACE,APPEND@}].
 587 @end display
 588
 589 The @cmd{MCONVERT} command converts matrix data from a correlation
 590 matrix and a vector of standard deviations into a covariance matrix,
 591 or vice versa.
 592
 593 By default, @cmd{MCONVERT} both reads and writes the active file.  Use
 594 the @cmd{MATRIX} subcommand to specify other files.  To read a matrix
 595 file, specify its name inside parentheses following @code{IN}.  To
 596 write a matrix file, specify its name inside parentheses following
 597 @code{OUT}.  Use @samp{*} to explicitly specify the active file for
 598 input or output.
 599
 600 When @cmd{MCONVERT} reads the input, by default it substitutes a
 601 correlation matrix and a vector of standard deviations each time it
 602 encounters a covariance matrix, and vice versa.  Specify
 603 @code{/APPEND} to instead have @cmd{MCONVERT} add the other form of
 604 data without removing the existing data.  Use @code{/REPLACE} to
 605 explicitly request removing the existing data.
 606
 607 The @cmd{MCONVERT} command requires its input to be a matrix file.
 608 Use @cmd{MATRIX DATA} to convert text input into matrix file format.
 609 @xref{MATRIX DATA}, for details.