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".
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
23 A matrix file is an SPSS system file that conforms to the dictionary
24 and case structure described in this section. Procedures that read
25 matrices from files expect them to be in the matrix file format.
26 Procedures that write matrices also use this format.
28 Text files that contain matrices can be converted to matrix file
29 format. @xref{MATRIX DATA}, for a command to read a text file as a
32 A matrix file's dictionary must have the following variables in the
37 Zero or more numeric split variables. These are included by
38 procedures when @cmd{SPLIT FILE} is active. @cmd{MATRIX DATA} assigns
39 split variables format F4.0.
42 @code{ROWTYPE_}, a string variable with width 8. This variable
43 indicates the kind of matrix or vector that a given case represents.
44 The supported row types are listed below.
47 Zero or more numeric factor variables. These are included by
48 procedures that divide data into cells. For within-cell data, factor
49 variables are filled with non-missing values; for pooled data, they
50 are missing. @cmd{MATRIX DATA} assigns factor variables format F4.0.
53 @code{VARNAME_}, a string variable. Matrix data includes one row per
54 continuous variable (see below), naming each continuous variable in
55 order. This column is blank for vector data. @cmd{MATRIX DATA} makes
56 @code{VARNAME_} wide enough for the name of any of the continuous
57 variables, but at least 8 bytes.
60 One or more continuous variables. These are the variables whose data
61 was analyzed to produce the matrices. @cmd{MATRIX DATA} assigns
62 continuous variables format F10.4.
65 Case weights are ignored in matrix files.
68 @anchor{Matrix File Row Types}
70 Matrix files support a fixed set of types of matrix and vector data.
71 The @code{ROWTYPE_} variable in each case of a matrix file indicates
74 The supported matrix row types are listed below. Each type is listed
75 with the keyword that identifies it in @code{ROWTYPE_}. All supported
76 types of matrices are square, meaning that each matrix must include
77 one row per continuous variable, with the @code{VARNAME_} variable
78 indicating each continuous variable in turn in the same order as the
83 Correlation coefficients.
86 Covariance coefficients.
89 General-purpose matrix.
98 The supported vector row types are listed below, along with their
99 associated keyword. Vector row types only require a single row, whose
100 @code{VARNAME_} is blank:
122 Only the row types listed above may appear in matrix files. The
123 @cmd{MATRIX DATA} command, however, accepts the additional row types
124 listed below, which it changes into matrix file row types as part of
125 its conversion process:
132 Synonym for @code{STDDEV}.
135 Accepts a single number from the @code{MATRIX DATA} input and writes
136 it as an @code{N} row with the number replicated across all the
137 continuous variables.
146 VARIABLES=@var{variables}
147 [FILE=@{'@var{file_name}' | INLINE@}
148 [/FORMAT=[@{LIST | FREE@}]
149 [@{UPPER | LOWER | FULL@}]
150 [@{DIAGONAL | NODIAGONAL@}]]
151 [/SPLIT=@var{split_vars}]
152 [/FACTORS=@var{factor_vars}]
155 The following subcommands are only needed when ROWTYPE_ is not
156 specified on the VARIABLES subcommand:
157 [/CONTENTS=@{CORR,COUNT,COV,DFE,MAT,MEAN,MSE,
158 N_MATRIX,N|N_VECTOR,N_SCALAR,PROX,SD|STDDEV@}]
159 [/CELLS=@var{n_cells}]
162 The @cmd{MATRIX DATA} command convert matrices and vectors from text
163 format into the matrix file format (@xref{Matrix Files}) for use by
164 procedures that read matrices. It reads a text file or inline data
165 and outputs to the active file, replacing any data already in the
166 active dataset. The matrix file may then be used by other commands
167 directly from the active file, or it may be written to a @file{.sav}
168 file using the @cmd{SAVE} command.
170 The text data read by @cmd{MATRIX DATA} can be delimited by spaces or
171 commas. A plus or minus sign, except immediately following a @samp{d}
172 or @samp{e}, also begins a new value. Optionally, values may be
173 enclosed in single or double quotes.
175 @cmd{MATRIX DATA} can read the types of matrix and vector data
176 supported in matrix files (@pxref{Matrix File Row Types}).
178 The @subcmd{FILE} subcommand specifies the source of the command's
179 input. To read input from a text file, specify its name in quotes.
180 To supply input inline, omit @subcmd{FILE} or specify @code{INLINE}.
181 Inline data must directly follow @code{MATRIX DATA}, inside @cmd{BEGIN
182 DATA} (@pxref{BEGIN DATA}).
184 @subcmd{VARIABLES} is the only required subcommand. It names the
185 variables present in each input record in the order that they appear.
186 (@cmd{MATRIX DATA} reorders the variables in the matrix file it
187 produces, if needed to fit the matrix file format.) The variable list
188 must include split variables and factor variables, if they are present
189 in the data, in addition to the continuous variables that form matrix
190 rows and columns. It may also include a special variable named
193 Matrix data may include split variables or factor variables or both.
194 List split variables, if any, on the @subcmd{SPLIT} subcommand and
195 factor variables, if any, on the @subcmd{FACTORS} subcommand. Split
196 and factor variables must be numeric. Split and factor variables must
197 also be listed on @subcmd{VARIABLES}, with one exception: if
198 @subcmd{VARIABLES} does not include @code{ROWTYPE_}, then
199 @subcmd{SPLIT} may name a single variable that is not in
200 @subcmd{VARIABLES} (@pxref{MATRIX DATA Example 8}).
202 The @subcmd{FORMAT} subcommand accepts settings to describe the format
206 @item @code{LIST} (default)
208 LIST requires each row to begin at the start of a new input line.
209 FREE allows rows to begin in the middle of a line. Either setting
210 allows a single row to continue across multiple input lines.
212 @item @code{LOWER} (default)
215 With LOWER, only the lower triangle is read from the input data and
216 the upper triangle is mirrored across the main diagonal. UPPER
217 behaves similarly for the upper triangle. FULL reads the entire
220 @item @code{DIAGONAL} (default)
221 @itemx @code{NODIAGONAL}
222 With DIAGONAL, the main diagonal is read from the input data. With
223 NODIAGONAL, which is incompatible with FULL, the main diagonal is not
224 read from the input data but instead set to 1 for correlation matrices
225 and system-missing for others.
228 The @subcmd{N} subcommand is a way to specify the size of the
229 population. It is equivalent to specifying an @code{N} vector with
230 the specified value for each split file.
232 @cmd{MATRIX DATA} supports two different ways to indicate the kinds of
233 matrices and vectors present in the data, depending on whether a
234 variable with the special name @code{ROWTYPE_} is present in
235 @code{VARIABLES}. The following subsections explain @cmd{MATRIX DATA}
236 syntax and behavior in each case.
238 @node MATRIX DATA with ROWTYPE_
239 @subsection With @code{ROWTYPE_}
241 If @code{VARIABLES} includes @code{ROWTYPE_}, each case's
242 @code{ROWTYPE_} indicates the type of data contained in the row.
243 @xref{Matrix File Row Types}, for a list of supported row types.
245 @subsubheading Example 1: Defaults with @code{ROWTYPE_}
246 @anchor{MATRIX DATA Example 1}
248 This example shows a simple use of @cmd{MATRIX DATA} with
249 @code{ROWTYPE_} plus 8 variables named @code{var01} through
252 Because @code{ROWTYPE_} is the first variable in @subcmd{VARIABLES},
253 it appears first on each line. The first three lines in the example
254 data have @code{ROWTYPE_} values of @samp{MEAN}, @samp{SD}, and
255 @samp{N}. These indicate that these lines contain vectors of means,
256 standard deviations, and counts, respectively, for @code{var01}
257 through @code{var08} in order.
259 The remaining 8 lines have a ROWTYPE_ of @samp{CORR} which indicates
260 that the values are correlation coefficients. Each of the lines
261 corresponds to a row in the correlation matrix: the first line is for
262 @code{var01}, the next line for @code{var02}, and so on. The input
263 only contains values for the lower triangle, including the diagonal,
264 since @code{FORMAT=LOWER DIAGONAL} is the default.
266 With @code{ROWTYPE_}, the @code{CONTENTS} subcommand is optional and
267 the @code{CELLS} subcommand may not be used.
271 VARIABLES=ROWTYPE_ var01 TO var08.
273 MEAN 24.3 5.4 69.7 20.1 13.4 2.7 27.9 3.7
274 SD 5.7 1.5 23.5 5.8 2.8 4.5 5.4 1.5
275 N 92 92 92 92 92 92 92 92
279 CORR .36 .31 -.14 1.00
280 CORR .27 .16 -.12 .22 1.00
281 CORR .33 .15 -.17 .24 .21 1.00
282 CORR .50 .29 -.20 .32 .12 .38 1.00
283 CORR .17 .29 -.05 .20 .27 .20 .04 1.00
287 @subsubheading Example 2: @code{FORMAT=UPPER NODIAGONAL}
289 This syntax produces the same matrix file as example 1, but it uses
290 @code{FORMAT=UPPER NODIAGONAL} to specify the upper triangle and omit
291 the diagonal. Because the matrix's @code{ROWTYPE_} is @code{CORR},
292 @pspp{} automatically fills in the diagonal with 1.
296 VARIABLES=ROWTYPE_ var01 TO var08
297 /FORMAT=UPPER NODIAGONAL.
299 MEAN 24.3 5.4 69.7 20.1 13.4 2.7 27.9 3.7
300 SD 5.7 1.5 23.5 5.8 2.8 4.5 5.4 1.5
301 N 92 92 92 92 92 92 92 92
302 CORR .17 .50 -.33 .27 .36 -.22 .18
303 CORR .29 .29 -.20 .32 .12 .38
304 CORR .05 .20 -.15 .16 .21
305 CORR .20 .32 -.17 .12
312 @subsubheading Example 3: @subcmd{N} subcommand
314 This syntax uses the @subcmd{N} subcommand in place of an @code{N}
315 vector. It produces the same matrix file as examples 1 and 2.
319 VARIABLES=ROWTYPE_ var01 TO var08
320 /FORMAT=UPPER NODIAGONAL
323 MEAN 24.3 5.4 69.7 20.1 13.4 2.7 27.9 3.7
324 SD 5.7 1.5 23.5 5.8 2.8 4.5 5.4 1.5
325 CORR .17 .50 -.33 .27 .36 -.22 .18
326 CORR .29 .29 -.20 .32 .12 .38
327 CORR .05 .20 -.15 .16 .21
328 CORR .20 .32 -.17 .12
335 @subsubheading Example 4: Split variables
336 @anchor{MATRIX DATA Example 4}
338 This syntax defines two matrices, using the variable @samp{s1} to
339 distinguish between them. Notice how the order of variables in the
340 input matches their order on @subcmd{VARIABLES}. This example also
341 uses @code{FORMAT=FULL}.
345 VARIABLES=s1 ROWTYPE_ var01 TO var04
366 @subsubheading Example 5: Factor variables
367 @anchor{MATRIX DATA Example 5}
369 This syntax defines a matrix file that includes a factor variable
370 @samp{f1}. The data includes mean, standard deviation, and count
371 vectors for two values of the factor variable, plus a correlation
372 matrix for pooled data.
376 VARIABLES=ROWTYPE_ f1 var01 TO var04
392 @node MATRIX DATA without ROWTYPE_
393 @subsection Without @code{ROWTYPE_}
395 If @code{VARIABLES} does not contain @code{ROWTYPE_}, the
396 @subcmd{CONTENTS} subcommand defines the row types that appear in the
397 file and their order. If @subcmd{CONTENTS} is omitted,
398 @code{CONTENTS=CORR} is assumed.
400 Factor variables without @code{ROWTYPE_} introduce special
401 requirements, illustrated below in Examples 8 and 9.
403 @subsubheading Example 6: Defaults without @code{ROWTYPE_}
405 This example shows a simple use of @cmd{MATRIX DATA} with 8 variables
406 named @code{var01} through @code{var08}, without @code{ROWTYPE_}.
407 This yields the same matrix file as Example 1 (@pxref{MATRIX DATA
412 VARIABLES=var01 TO var08
413 /CONTENTS=MEAN SD N CORR.
415 24.3 5.4 69.7 20.1 13.4 2.7 27.9 3.7
416 5.7 1.5 23.5 5.8 2.8 4.5 5.4 1.5
417 92 92 92 92 92 92 92 92
422 .27 .16 -.12 .22 1.00
423 .33 .15 -.17 .24 .21 1.00
424 .50 .29 -.20 .32 .12 .38 1.00
425 .17 .29 -.05 .20 .27 .20 .04 1.00
429 @subsubheading Example 7: Split variables with explicit values
431 This syntax defines two matrices, using the variable @code{s1} to
432 distinguish between them. Each line of data begins with @code{s1}.
433 This yields the same matrix file as Example 4 (@pxref{MATRIX DATA
438 VARIABLES=s1 var01 TO var04
441 /CONTENTS=MEAN SD N CORR.
460 @subsubheading Example 8: Split variable with sequential values
461 @anchor{MATRIX DATA Example 8}
463 Like this previous example, this syntax defines two matrices with
464 split variable @code{s1}. In this case, though, @code{s1} is not
465 listed in @subcmd{VARIABLES}, which means that its value does not
466 appear in the data. Instead, @cmd{MATRIX DATA} reads matrix data
467 until the input is exhausted, supplying 1 for the first split, 2 for
468 the second, and so on.
472 VARIABLES=var01 TO var04
475 /CONTENTS=MEAN SD N CORR.
494 @subsubsection Factor variables without @code{ROWTYPE_}
496 Without @subcmd{ROWTYPE_}, factor variables introduce two new wrinkles
497 to @cmd{MATRIX DATA} syntax. First, the @subcmd{CELLS} subcommand
498 must declare the number of combinations of factor variables present in
499 the data. If there is, for example, one factor variable for which the
500 data contains three values, one would write @code{CELLS=3}; if there
501 are two (or more) factor variables for which the data contains five
502 combinations, one would use @code{CELLS=5}; and so on.
504 Second, the @subcmd{CONTENTS} subcommand must distinguish within-cell
505 data from pooled data by enclosing within-cell row types in
506 parentheses. When different within-cell row types for a single factor
507 appear in subsequent lines, enclose the row types in a single set of
508 parentheses; when different factors' values for a given within-cell
509 row type appear in subsequent lines, enclose each row type in
510 individual parentheses.
512 Without @subcmd{ROWTYPE_}, input lines for pooled data do not include
513 factor values, not even as missing values, but input lines for
516 The following examples aim to clarify this syntax.
518 @subsubheading Example 9: Factor variables, grouping within-cell records by factor
520 This syntax defines the same matrix file as Example 5 (@pxref{MATRIX
521 DATA Example 5}), without using @code{ROWTYPE_}. It declares
522 @code{CELLS=2} because the data contains two values (0 and 1) for
523 factor variable @code{f1}. Within-cell vector row types @code{MEAN},
524 @code{SD}, and @code{N} are in a single set of parentheses on
525 @subcmd{CONTENTS} because they are grouped together in subsequent
526 lines for a single factor value. The data lines with the pooled
527 correlation matrix do not have any factor values.
531 VARIABLES=f1 var01 TO var04
534 /CONTENTS=(MEAN SD N) CORR.
549 @subsubheading Example 10: Factor variables, grouping within-cell records by row type
551 This syntax defines the same matrix file as the previous example. The
552 only difference is that the within-cell vector rows are grouped
553 differently: two rows of means (one for each factor), followed by two
554 rows of standard deviations, followed by two rows of counts.
558 VARIABLES=f1 var01 TO var04
561 /CONTENTS=(MEAN) (SD) (N) CORR.