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