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