tests
[pspp] / doc / variables.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020 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 Manipulating Variables
11 @chapter Manipulating Variables
12 @cindex Variables
13
14 Every value in a dataset is associated with a @dfn{variable}.
15 Variables describe what the values represent and properties of those values,
16 such as the format in which they should be displayed, whether they are numeric
17 or alphabetic and how missing values should be represented.
18 There are several utility commands for examining and adjusting variables.
19
20 @menu
21 * DISPLAY::                     Display information about the active dataset.
22 * NUMERIC::                     Create new numeric variables.
23 * STRING::                      Create new string variables.
24 * MODIFY VARS::                 Rename, reorder, and drop variables.
25 * RENAME VARIABLES::            Rename variables.
26 * SORT VARIABLES::              Reorder variables.
27 * DELETE VARIABLES::            Delete variables.
28 * VARIABLE LABELS::             Set variable labels for variables.
29 * PRINT FORMATS::               Set variable print formats.
30 * WRITE FORMATS::               Set variable write formats.
31 * FORMATS::                     Set print and write formats.
32 * VALUE LABELS::                Set value labels for variables.
33 * ADD VALUE LABELS::            Add value labels to variables.
34 * MISSING VALUES::              Set missing values for variables.
35 * VARIABLE ATTRIBUTE::          Set custom attributes on variables.
36 * VARIABLE ALIGNMENT::          Set the alignment for display.
37 * VARIABLE WIDTH::              Set the display width.
38 * VARIABLE LEVEL::              Set the measurement level.
39 * VARIABLE ROLE::               Set the role that a variable fills in analysis.
40 * VECTOR::                      Declare an array of variables.
41 * MRSETS::                      Add, modify, and list multiple response sets.
42 * LEAVE::                       Don't clear variables between cases.
43 @end menu
44
45 @node DISPLAY
46 @section DISPLAY
47 @vindex DISPLAY
48
49 The @cmd{DISPLAY} command displays information about the variables in the active dataset.
50 A variety of different forms of information can be requested.
51 By default, all variables in the active dataset are displayed.  However you can select
52 variables of interest using the @subcmd{/VARIABLES} subcommand.
53
54 @display
55 DISPLAY [SORTED] NAMES [[/VARIABLES=]@var{var_list}].
56 DISPLAY [SORTED] INDEX [[/VARIABLES=]@var{var_list}].
57 DISPLAY [SORTED] LABELS [[/VARIABLES=]@var{var_list}].
58 DISPLAY [SORTED] VARIABLES [[/VARIABLES=]@var{var_list}].
59 DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]@var{var_list}].
60 DISPLAY [SORTED] SCRATCH [[/VARIABLES=]@var{var_list}].
61 DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]@var{var_list}].
62 DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]@var{var_list}].
63 DISPLAY [SORTED] VECTORS.
64 @end display
65
66 The following keywords primarily cause information about variables to
67 be displayed.  With these keywords, by default information is
68 displayed about all variable in the active dataset, in the order that
69 variables occur in the active dataset dictionary.  The @subcmd{SORTED} keyword
70 causes output to be sorted alphabetically by variable name.
71
72 @table @asis
73 @item NAMES
74 The variables' names are displayed.
75
76 @item INDEX
77 The variables' names are displayed along with a value describing their
78 position within the active dataset dictionary.
79
80 @item LABELS
81 Variable names, positions, and variable labels are displayed.
82
83 @item VARIABLES
84 Variable names, positions, print and write formats, and missing values
85 are displayed.
86
87 @item DICTIONARY
88 Variable names, positions, print and write formats, missing values,
89 variable labels, and value labels are displayed.
90
91 @item SCRATCH
92 Variable names are displayed, for scratch variables only (@pxref{Scratch
93 Variables}).
94
95 @item ATTRIBUTES
96 @itemx @@ATTRIBUTES
97 Datafile and variable attributes are displayed.
98 The first form of the command omits those attributes
99 whose names begin with @code{@@} or @code{$@@}.
100 In the second for, all datafile and variable attributes are displayed.
101 @end table
102
103 With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
104 declared vectors.  If the @subcmd{SORTED} keyword is given, the vectors are
105 listed in alphabetical order; otherwise, they are listed in textual
106 order of definition within the @pspp{} syntax file.
107
108 For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
109 FILE LABEL}.
110
111 @node NUMERIC
112 @section NUMERIC
113 @vindex NUMERIC
114
115 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
116 setting their output formats.
117
118 @display
119 NUMERIC @var{var_list} [(@var{fmt_spec})] [/@var{var_list} [(@var{fmt_spec})]]@dots{}
120 @end display
121
122 Specify the names of the new numeric variables as @var{var_list}.  If
123 you wish to set the variables' output formats, follow their names by
124 an output format specification in parentheses (@pxref{Input and Output
125 Formats}); otherwise, the default is F8.2.
126
127 Variables created with @cmd{NUMERIC} are initialized to the
128 system-missing value.
129
130 @node STRING
131 @section STRING
132 @vindex STRING
133
134 @cmd{STRING} creates new string variables.
135
136 @display
137 STRING @var{var_list} (@var{fmt_spec}) [/@var{var_list} (@var{fmt_spec})] [@dots{}].
138 @end display
139
140 Specify a list of names for the variable you want to create,
141 followed by the desired output format specification in
142 parentheses (@pxref{Input and Output Formats}).
143 Variable widths are
144 implicitly derived from the specified output formats.
145 The created variables will be initialized to spaces.
146
147 If you want to create several variables with  distinct
148 output formats, you can either use two or more separate @cmd{STRING} commands,
149 or you can specify further variable list and format specification pairs, each separated
150 from the previous by a slash (@samp{/}).
151
152 The following example is one way to create three string variables; Two of the
153 variables have format A24 and the other A80:
154 @example
155 STRING firstname lastname (A24) / address (A80).
156 @end example
157
158 @noindent Here is another way to achieve the same result:
159 @example
160 STRING firstname lastname (A24).
161 STRING address (A80).
162 @end example
163
164 @noindent @dots{} and here is yet another way:
165
166 @example
167 STRING firstname (A24).
168 STRING lastname (A24).
169 STRING address (A80).
170 @end example
171
172 @node MODIFY VARS
173 @section MODIFY VARS
174 @vindex MODIFY VARS
175
176 You can use @cmd{MODIFY VARS} to reorder, rename, or delete variables.
177
178 @display
179 MODIFY VARS
180         /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (@var{var_list})@dots{}
181         /RENAME=(@var{old_names}=@var{new_names})@dots{}
182         /@{DROP,KEEP@}=@var{var_list}
183         /MAP
184 @end display
185
186 At least one subcommand must be specified, and no subcommand may be
187 specified more than once.  @subcmd{DROP} and @subcmd{KEEP} may not both
188 be specified.
189
190 The @subcmd{REORDER} subcommand changes the order of variables in the active
191 dataset.  Specify one or more lists of variable names in parentheses.  By
192 default, each list of variables is rearranged into the specified order.
193 To put the variables into the reverse of the specified order, put
194 keyword @subcmd{BACKWARD} before the parentheses.  To put them into alphabetical
195 order in the dictionary, specify keyword @subcmd{ALPHA} before the parentheses.
196 @subcmd{BACKWARD} and @subcmd{ALPHA} may also be combined.
197
198 To rename variables in the active dataset, specify @subcmd{RENAME}, an equals sign
199 (@samp{=}), and lists of the old variable names and new variable names
200 separated by another equals sign within parentheses.  There must be the
201 same number of old and new variable names.  Each old variable is renamed to
202 the corresponding new variable name.  Multiple parenthesized groups of
203 variables may be specified.
204
205 The @subcmd{DROP} subcommand deletes a specified list of variables
206 from the active dataset.  @cmd{MODIFY VARS} may not be used to delete
207 all variables from the dictionary; use @cmd{NEW FILE} to do that
208 (@pxref{NEW FILE}).
209
210 The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
211 dataset.  Any unlisted variables are deleted from the active dataset.
212
213 @subcmd{MAP} is currently ignored.
214
215 If either @subcmd{DROP} or @subcmd{KEEP} is specified, the data is read;
216 otherwise it is not.
217
218 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
219 (@pxref{TEMPORARY}).
220
221 @node RENAME VARIABLES
222 @section RENAME VARIABLES
223 @vindex RENAME VARIABLES
224
225 @cmd{RENAME VARIABLES} changes the names of variables in the active
226 dataset.
227
228 @display
229 RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
230 @end display
231
232 Specify lists of the old variable names and new
233 variable names, separated by an equals sign (@samp{=}), within
234 parentheses.  There must be the same number of old and new variable
235 names.  Each old variable is renamed to the corresponding new variable
236 name.  Multiple parenthesized groups of variables may be specified.
237 When the old and new variable names contain only a single variable name,
238 the parentheses are optional.
239
240 @cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
241 to be read.
242
243 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
244 (@pxref{TEMPORARY}).
245
246 @node SORT VARIABLES
247 @section SORT VARIABLES
248 @vindex SORT VARIABLES
249
250 @cmd{SORT VARIABLES} reorders the variables in the active dataset's dictionary
251 according to a chosen sort key.
252
253 @display
254 SORT VARIABLES [BY]
255     (NAME | TYPE | FORMAT | LABEL | VALUES | MISSING | MEASURE
256      | ROLE | COLUMNS | ALIGNMENT | ATTRIBUTE @var{name})
257     [(D)].
258 @end display
259
260 The main specification is one of the following identifiers, which
261 determines how the variables are sorted:
262
263 @table @asis
264 @item NAME
265 Sorts the variables according to their names, in a case-insensitive
266 fashion.  However, when variable names differ only in a number at the
267 end, they are sorted numerically.  For example, @code{VAR5} is sorted
268 before @code{VAR400} even though @samp{4} precedes @samp{5}.
269
270 @item TYPE
271 Sorts numeric variables before string variables, and shorter string
272 variables before longer ones.
273
274 @item FORMAT
275 Groups variables by print format; within a format, sorts narrower
276 formats before wider ones; with the same format and width, sorts fewer
277 decimal places before more decimal places.
278 @xref{FORMATS}.
279
280 @item LABEL
281 Sorts variables without a variable label before those with one.
282 @xref{VARIABLE LABELS}.
283
284 @item VALUES
285 Sorts variables without value labels before those with some.
286 @xref{VALUE LABELS}.
287
288 @item MISSING
289 Sorts variables without missing values before those with some.
290 @xref{MISSING VALUES}.
291
292 @item MEASURE
293 Sorts nominal variables first, followed by ordinal variables, followed
294 by scale variables.  @xref{VARIABLE LEVEL}.
295
296 @item ROLE
297 Groups variables according to their role.  @xref{VARIABLE ROLE}.
298
299 @item COLUMNS
300 Sorts variables in ascending display width.  @xref{VARIABLE WIDTH}.
301
302 @item ALIGNMENT
303 Sorts variables according to their alignment, first left-aligned, then
304 right-aligned, then centered.  @xref{VARIABLE ALIGNMENT}.
305
306 @item ATTRIBUTE @var{name}
307 Sorts variables according to the first value of their @var{name}
308 attribute.  Variables without attribute are sorted first.
309 @xref{VARIABLE ATTRIBUTE}.
310 @end table
311
312 Only one sort criterion can be specified.  The sort is ``stable,'' so
313 to sort on multiple criteria one may perform multiple sorts.  For
314 example, the following will sort primarily based on alignment, with
315 variables that have the same alignment ordered based on display width:
316
317 @example
318 SORT VARIABLES BY COLUMNS.
319 SORT VARIABLES BY ALIGNMENT.
320 @end example
321
322 Specify @code{(D)} to reverse the sort order.
323
324 @node DELETE VARIABLES
325 @section DELETE VARIABLES
326 @vindex DELETE VARIABLES
327
328 @cmd{DELETE VARIABLES} deletes the specified variables from the dictionary.
329
330 @display
331 DELETE VARIABLES @var{var_list}.
332 @end display
333
334 @cmd{DELETE VARIABLES} should not be used after defining transformations
335 but before executing a procedure.  If it is used in such a context, it
336 causes the data to be read.  If it is used while @cmd{TEMPORARY} is in
337 effect, it causes the temporary transformations to become permanent.
338
339 @cmd{DELETE VARIABLES} may not be used to delete all variables from the
340 dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
341
342 @node VARIABLE LABELS
343 @section VARIABLE LABELS
344 @vindex VARIABLE LABELS
345
346 In addition to a variable's name, each variable can have a @dfn{label}.
347 Whereas the name is limited to certain constraints (@pxref{Attributes}) a variable's
348 label has no such constraints.
349 Typically, the names are concise, easy to type mnemonics for the variable
350 and the labels are longer, more verbose descriptions.
351
352 @display
353 VARIABLE LABELS
354         @var{var_list} '@var{var_label}'
355         [ /@var{var_list} '@var{var_label}']
356         .
357         .
358         .
359         [ /@var{var_list} '@var{var_label}']
360 @end display
361
362 @cmd{VARIABLE LABELS} associates explanatory names
363 with variables.  This name, called a @dfn{variable label}, is displayed by
364 statistical procedures.
365
366 To assign a variable label to a group of variables, specify a
367 list of variable names and the variable label as a string.
368 To assign different labels to different variables in the same command,
369 precede the subsequent variable list with a slash (@samp{/}).
370
371 @node PRINT FORMATS
372 @section PRINT FORMATS
373 @vindex PRINT FORMATS
374
375 @display
376 PRINT FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
377 @end display
378
379 @cmd{PRINT FORMATS} sets the print formats for the specified
380 variables to the specified format specification.
381
382 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
383 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
384
385 @node WRITE FORMATS
386 @section WRITE FORMATS
387 @vindex WRITE FORMATS
388
389 @display
390 WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
391 @end display
392
393 @cmd{WRITE FORMATS} sets the write formats for the specified variables
394 to the specified format specification.  Its syntax is identical to
395 that of @cmd{FORMATS} (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
396 write formats, not print formats.
397
398 @node FORMATS
399 @section FORMATS
400 @vindex FORMATS
401
402 @display
403 FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
404 @end display
405
406 @cmd{FORMATS} set both print and write formats for the specified
407 variables to the specified format specification.
408 @xref{Input and Output Formats}.
409
410 Specify a list of variables followed by a format specification in
411 parentheses.  The print and write formats of the specified variables
412 will be changed.  All of the variables listed together must have
413 the same type and, for string variables, the same width.
414
415 Additional lists of variables and formats may be included following
416 the first one.
417
418 @cmd{FORMATS} takes effect immediately.  It is not affected by
419 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
420
421 @node VALUE LABELS
422 @section VALUE LABELS
423 @vindex VALUE LABELS
424
425 The values of a variable can be associated with an arbitrary text string.
426 In this way, a short value can stand for a longer, more descriptive label.
427
428 Both numeric and string variables can be given labels.  For string
429 variables, the values are case-sensitive, so that, for example, a
430 capitalized value and its lowercase variant would have to be labeled
431 separately if both are present in the data.
432
433 @display
434 VALUE LABELS
435         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
436 @end display
437
438 @cmd{VALUE LABELS} allows values of variables to be associated with labels.
439
440 To set up value labels for one or more variables, specify the
441 variable names after a slash (@samp{/}), followed by a list of values
442 and their associated labels, separated by spaces.
443
444 Value labels in output are normally broken into lines automatically.
445 Put @samp{\n} in a label string to force a line break at that point.
446 The label may still be broken into lines at additional points.
447
448 Before @cmd{VALUE LABELS} is executed, any existing value labels
449 are cleared from the variables specified.  Use @cmd{ADD VALUE LABELS}
450 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
451 already present.
452
453 @node ADD VALUE LABELS
454 @section ADD VALUE LABELS
455 @vindex ADD VALUE LABELS
456
457 @cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
458 LABELS} (@pxref{VALUE LABELS}), but it does not clear value
459 labels from the variables before adding the ones specified.
460
461 @display
462 ADD VALUE LABELS
463         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
464 @end display
465
466
467 @node MISSING VALUES
468 @section MISSING VALUES
469 @vindex MISSING VALUES
470
471 In many situations the data available for analysis is incomplete and a placeholder
472 must be used in place of a value to indicate that the value is unknown.  One way
473 that missing values are represented is through the $SYSMIS variable
474 (@pxref{System Variables}).  Another, more flexible way is through
475 @dfn{user-missing values} which are determined on a per variable basis.
476
477 The @cmd{MISSING VALUES} command sets user-missing values for variables.
478
479 @display
480 MISSING VALUES @var{var_list} (@var{missing_values}).
481
482 where @var{missing_values} takes one of the following forms:
483         @var{num1}
484         @var{num1}, @var{num2}
485         @var{num1}, @var{num2}, @var{num3}
486         @var{num1} THRU @var{num2}
487         @var{num1} THRU @var{num2}, @var{num3}
488         @var{string1}
489         @var{string1}, @var{string2}
490         @var{string1}, @var{string2}, @var{string3}
491 As part of a range, @subcmd{LO} or @subcmd{LOWEST} may take the place of @var{num1};
492 @subcmd{HI} or @subcmd{HIGHEST} may take the place of @var{num2}.
493 @end display
494
495 @cmd{MISSING VALUES} sets user-missing values for numeric and string
496 variables.  Long string variables may have missing values, but
497 characters after the first 8 bytes of the missing value must be
498 spaces.
499
500 Specify a list of variables, followed by a list of their user-missing
501 values in parentheses.  Up to three discrete values may be given, or,
502 for numeric variables only, a range of values optionally accompanied by
503 a single discrete value.  Ranges may be open-ended on one end, indicated
504 through the use of the
505 keyword @subcmd{LO} or @subcmd{LOWEST} or @subcmd{HI} or @subcmd{HIGHEST}.
506
507 The @cmd{MISSING VALUES} command takes effect immediately.  It is not
508 affected by conditional and looping constructs such as @cmd{DO IF} or
509 @cmd{LOOP}.
510
511 @node VARIABLE ATTRIBUTE
512 @section VARIABLE ATTRIBUTE
513 @vindex VARIABLE ATTRIBUTE
514
515 @cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
516 attributes associated with variables in the active dataset.  Custom
517 variable attributes are not interpreted by @pspp{}, but they are saved as
518 part of system files and may be used by other software that reads
519 them.
520
521 @display
522 VARIABLE ATTRIBUTE
523          VARIABLES=@var{var_list}
524          ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
525          ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
526          DELETE=@var{name} [@var{name}]@dots{}
527          DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
528 @end display
529
530 The required @subcmd{VARIABLES} subcommand must come first.  Specify the
531 variables to which the following @subcmd{ATTRIBUTE} or @subcmd{DELETE} subcommand
532 should apply.
533
534 Use the @subcmd{ATTRIBUTE} subcommand to add or modify custom variable
535 attributes.  Specify the name of the attribute as an identifier
536 (@pxref{Tokens}), followed by the desired value, in parentheses, as a
537 quoted string.  The specified attributes are then added or modified in
538 the variables specified on @subcmd{VARIABLES}.  Attribute names that begin with
539 @code{$} are reserved for @pspp{}'s internal use, and attribute names
540 that begin with @code{@@} or @code{$@@} are not displayed by most @pspp{}
541 commands that display other attributes.  Other attribute names are not
542 treated specially.
543
544 Attributes may also be organized into arrays.  To assign to an array
545 element, add an integer array index enclosed in square brackets
546 (@code{[} and @code{]}) between the attribute name and value.  Array
547 indexes start at 1, not 0.  An attribute array that has a single
548 element (number 1) is not distinguished from a non-array attribute.
549
550 Use the @subcmd{DELETE} subcommand to delete an attribute from the variable
551 specified on @subcmd{VARIABLES}.  Specify an attribute name by itself to delete
552 an entire attribute, including all array elements for attribute
553 arrays.  Specify an attribute name followed by an array index in
554 square brackets to delete a single element of an attribute array.  In
555 the latter case, all the array elements numbered higher than the
556 deleted element are shifted down, filling the vacated position.
557
558 To associate custom attributes with the entire active dataset, instead of
559 with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
560
561 @cmd{VARIABLE ATTRIBUTE} takes effect immediately.  It is not affected
562 by conditional and looping structures such as @cmd{DO IF} or
563 @cmd{LOOP}.
564
565 @node VARIABLE ALIGNMENT
566 @section VARIABLE ALIGNMENT
567 @vindex VARIABLE ALIGNMENT
568
569 @cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
570 purposes.   It  does not affect the display of variables in the @pspp{} output.
571
572 @display
573 VARIABLE ALIGNMENT
574         @var{var_list} ( LEFT | RIGHT | CENTER )
575         [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
576         .
577         .
578         .
579         [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
580 @end display
581
582 @node VARIABLE WIDTH
583 @section VARIABLE WIDTH
584 @vindex VARIABLE WIDTH
585 @display
586 VARIABLE WIDTH
587         @var{var_list} (width)
588         [ /@var{var_list} (width) ]
589         .
590         .
591         .
592         [ /@var{var_list} (width) ]
593 @end display
594
595 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
596 purposes.   It does not affect the display of variables in the @pspp{} output.
597
598
599 @node VARIABLE LEVEL
600 @section VARIABLE LEVEL
601 @vindex VARIABLE LEVEL
602 @display
603 @t{VARIABLE LEVEL} @i{variables} @t{(}@{@t{SCALE} @math{|} @t{NOMINAL} @math{|} @t{ORDINAL}@}@t{)}@dots{}
604 @end display
605
606 @cmd{VARIABLE LEVEL} sets the measurement level of @var{variables} as
607 specified.  @xref{Attributes}, for the definitions of the available
608 measurement levels.
609
610 @node VARIABLE ROLE
611 @section VARIABLE ROLE
612 @vindex VARIABLE ROLE
613 @display
614 VARIABLE ROLE
615         /@var{role} @var{var_list}
616         [/@var{role} @var{var_list}]@dots{}
617 @end display
618
619 @cmd{VARIABLE ROLE} sets the intended role of a variable for use in
620 dialog boxes in graphical user interfaces.  Each @var{role} specifies
621 one of the following roles for the variables that follow it:
622
623 @table @code
624 @item INPUT
625 An input variable, such as an independent variable.
626
627 @item TARGET
628 An output variable, such as an dependent variable.
629
630 @item BOTH
631 A variable used for input and output.
632
633 @item NONE
634 No role assigned.  (This is a variable's default role.)
635
636 @item PARTITION
637 Used to break the data into groups for testing.
638
639 @item SPLIT
640 No meaning except for certain third party software.  (This role's
641 meaning is unrelated to @cmd{SPLIT FILE}.)
642 @end table
643
644 The PSPPIRE GUI does not yet use variable roles as intended.
645
646 @node VECTOR
647 @section VECTOR
648 @vindex VECTOR
649
650 @display
651 Two possible syntaxes:
652         VECTOR @var{vec_name}=@var{var_list}.
653         VECTOR @var{vec_name_list}(@var{count} [@var{format}]).
654 @end display
655
656 @cmd{VECTOR} allows a group of variables to be accessed as if they
657 were consecutive members of an array with a vector(index) notation.
658
659 To make a vector out of a set of existing variables, specify a name
660 for the vector followed by an equals sign (@samp{=}) and the variables
661 to put in the vector.  The variables must be all numeric or all
662 string, and string variables must have the same width.
663
664 To make a vector and create variables at the same time, specify one or
665 more vector names followed by a count in parentheses.  This will
666 create variables named @code{@var{vec}1} through
667 @code{@var{vec}@var{count}}.  By default, the new variables are
668 numeric with format F8.2, but an alternate format may be specified
669 inside the parentheses before or after the count and separated from it
670 by white space or a comma.  With a string format such as A8, the
671 variables will be string variables; with a numeric format, they will
672 be numeric.  Variable names including the suffixes may not exceed 64
673 characters in length, and none of the variables may exist prior to
674 @cmd{VECTOR}.
675
676 Vectors created with @cmd{VECTOR} disappear after any procedure or
677 procedure-like command is executed.  The variables contained in the
678 vectors remain, unless they are scratch variables (@pxref{Scratch
679 Variables}).
680
681 Variables within a vector may be referenced in expressions using
682 @code{vector(index)} syntax.
683
684 @node MRSETS
685 @section MRSETS
686 @vindex MRSETS
687
688 @cmd{MRSETS} creates, modifies, deletes, and displays multiple
689 response sets.  A multiple response set is a set of variables that
690 represent multiple responses to a survey question.
691
692 Multiple responses are represented in one of the two following ways:
693
694 @itemize @bullet
695 @item
696 A @dfn{multiple dichotomy set} is analogous to a survey question with
697 a set of checkboxes.  Each variable in the set is treated in a Boolean
698 fashion: one value (the "counted value") means that the box was
699 checked, and any other value means that it was not.
700
701 @item
702 A @dfn{multiple category set} represents a survey question where the
703 respondent is instructed to list up to @var{n} choices.  Each variable
704 represents one of the responses.
705 @end itemize
706
707 @display
708 MRSETS
709     /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
710      [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
711      [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
712
713     /MCGROUP NAME=@var{name} VARIABLES=@var{var_list} [LABEL='@var{label}']
714
715     /DELETE NAME=@{[@var{names}],ALL@}
716
717     /DISPLAY NAME=@{[@var{names}],ALL@}
718 @end display
719
720
721 Any number of subcommands may be specified in any order.
722
723 The @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or
724 replaces an existing multiple response set.  The @subcmd{NAME},
725 @subcmd{VARIABLES}, and
726 @subcmd{VALUE} specifications are required.  The others are optional:
727
728 @itemize @bullet
729 @item
730 @var{NAME} specifies the name used in syntax for the new multiple dichotomy
731 set.  The name must begin with @samp{$}; it must otherwise follow the
732 rules for identifiers (@pxref{Tokens}).
733
734 @item
735 @subcmd{VARIABLES} specifies the variables that belong to the set.  At least
736 two variables must be specified.  The variables must be all string or
737 all numeric.
738
739 @item
740 @subcmd{VALUE} specifies the counted value.  If the variables are numeric, the
741 value must be an integer.  If the variables are strings, then the
742 value must be a string that is no longer than the shortest of the
743 variables in the set (ignoring trailing spaces).
744
745 @item
746 @subcmd{CATEGORYLABELS} optionally specifies the source of the labels for each
747 category in the set:
748
749 @itemize @minus
750 @item
751 @subcmd{VARLABELS}, the default, uses variable labels or, for variables without
752 variable labels, variable names.  @pspp{} warns if two variables have the
753 same variable label, since these categories cannot be distinguished in
754 output.
755
756 @item
757 @subcmd{COUNTEDVALUES} instead uses each variable's value label for the counted
758 value.  @pspp{} warns if two variables have the same value label for the
759 counted value or if one of the variables lacks a value label, since
760 such categories cannot be distinguished in output.
761 @end itemize
762
763 @item
764 @subcmd{LABEL} optionally specifies a label for the multiple response set.  If
765 neither @subcmd{LABEL} nor @subcmd{LABELSOURCE=VARLABEL} is specified, the set is
766 unlabeled.
767
768 @item
769 @subcmd{LABELSOURCE=VARLABEL} draws the multiple response set's label from the
770 first variable label among the variables in the set; if none of the
771 variables has a label, the name of the first variable is used.
772 @subcmd{LABELSOURCE=VARLABEL} must be used with @subcmd{CATEGORYLABELS=COUNTEDVALUES}.
773 It is mutually exclusive with @subcmd{LABEL}.
774 @end itemize
775
776 The @subcmd{MCGROUP} subcommand creates a new multiple category set or
777 replaces an existing multiple response set.  The @subcmd{NAME} and @subcmd{VARIABLES}
778 specifications are required, and @subcmd{LABEL} is optional.  Their meanings
779 are as described above in @subcmd{MDGROUP}.  @pspp{} warns if two variables in the
780 set have different value labels for a single value, since each of the
781 variables in the set should have the same possible categories.
782
783 The @subcmd{DELETE} subcommand deletes multiple response groups.  A list of
784 groups may be named within a set of required square brackets, or ALL
785 may be used to delete all groups.
786
787 The @subcmd{DISPLAY} subcommand displays information about defined multiple
788 response sets.  Its syntax is the same as the @subcmd{DELETE} subcommand.
789
790 Multiple response sets are saved to and read from system files by,
791 @i{e.g.}, the @cmd{SAVE} and @cmd{GET} command.  Otherwise, multiple
792 response sets are currently used only by third party software.
793
794 @node LEAVE
795 @section LEAVE
796 @vindex LEAVE
797
798 @cmd{LEAVE} prevents the specified variables from being
799 reinitialized whenever a new case is processed.
800
801 @display
802 LEAVE @var{var_list}.
803 @end display
804
805 Normally, when a data file is processed, every variable in the active
806 dataset is initialized to the system-missing value or spaces at the
807 beginning of processing for each case.  When a variable has been
808 specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
809 initialized to 0 (not system-missing) or spaces for the first case.
810 After that, it retains its value between cases.
811
812 This becomes useful for counters.  For instance, in the example below
813 the variable @code{SUM} maintains a running total of the values in the @code{ITEM}
814 variable.
815
816 @example
817 DATA LIST /ITEM 1-3.
818 COMPUTE SUM=SUM+ITEM.
819 PRINT /ITEM SUM.
820 LEAVE SUM
821 BEGIN DATA.
822 123
823 404
824 555
825 999
826 END DATA.
827 @end example
828
829 @noindent Partial output from this example:
830
831 @example
832 123   123.00
833 404   527.00
834 555  1082.00
835 999  2081.00
836 @end example
837
838 It is best to use @cmd{LEAVE} command immediately before invoking a
839 procedure command, because the left status of variables is reset by
840 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
841 Left status is also reset by all procedure invocations.
842