variable-parser: Rewrite parse_DATA_LIST_vars().
[pspp] / doc / variables.texi
1 @node Variable Attributes
2 @chapter Manipulating variables
3
4 The variables in the active file 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 file.
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 * VALUE LABELS::                Set value labels for variables.
20 * STRING::                      Create new string variables.
21 * VARIABLE ATTRIBUTE::          Set custom attributes on variables.
22 * VARIABLE LABELS::             Set variable labels for variables.
23 * VARIABLE ALIGNMENT::          Set the alignment for display.
24 * VARIABLE WIDTH::              Set the display width.
25 * VARIABLE LEVEL::              Set the measurement level.
26 * VECTOR::                      Declare an array of variables.
27 * WRITE FORMATS::               Set variable write formats.
28 @end menu
29
30 @node ADD VALUE LABELS
31 @section ADD VALUE LABELS
32 @vindex ADD VALUE LABELS
33
34 @display 
35 ADD VALUE LABELS
36         /var_list value 'label' [value 'label']@dots{}
37 @end display
38
39 @cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
40 LABELS} (@pxref{VALUE LABELS}), but it does not clear value
41 labels from the variables before adding the ones specified.
42
43 @node DELETE VARIABLES
44 @section DELETE VARIABLES
45 @vindex DELETE VARIABLES
46
47 @display
48 DELETE VARIABLES var_list.
49 @end display
50
51 @cmd{DELETE VARIABLES} deletes the specified variables from the
52 dictionary.  It may not be used to delete all variables from the
53 dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
54
55 @cmd{DELETE VARIABLES} should not used after defining transformations
56 and before executing a procedure.  If it is used in such a context, it
57 causes the data to be read.  If it is used while @cmd{TEMPORARY} is in
58 effect, it causes the temporary transformations to become permanent.
59
60 @node DISPLAY
61 @section DISPLAY
62 @vindex DISPLAY
63
64 @display
65 DISPLAY [SORTED] NAMES [[/VARIABLES=]var_list].
66 DISPLAY [SORTED] INDEX [[/VARIABLES=]var_list].
67 DISPLAY [SORTED] LABELS [[/VARIABLES=]var_list].
68 DISPLAY [SORTED] VARIABLES [[/VARIABLES=]var_list].
69 DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]var_list].
70 DISPLAY [SORTED] SCRATCH [[/VARIABLES=]var_list].
71 DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]var_list].
72 DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]var_list].
73 DISPLAY [SORTED] VECTORS.
74 @end display
75
76 @cmd{DISPLAY} displays information about the active file.  A variety
77 of different forms of information can be requested.
78
79 The following keywords primarily cause information about variables to
80 be displayed.  With these keywords, by default information is
81 displayed about all variable in the active file, in the order that
82 variables occur in the active file dictionary.  The SORTED keyword
83 causes output to be sorted alphabetically by variable name.  The
84 VARIABLES subcommand limits output to the specified variables.
85
86 @table @asis
87 @item NAMES
88 The variables' names are displayed.
89
90 @item INDEX
91 The variables' names are displayed along with a value describing their
92 position within the active file dictionary.
93
94 @item LABELS
95 Variable names, positions, and variable labels are displayed.
96
97 @item VARIABLES
98 Variable names, positions, print and write formats, and missing values
99 are displayed.
100
101 @item DICTIONARY
102 Variable names, positions, print and write formats, missing values,
103 variable labels, and value labels are displayed.
104
105 @item SCRATCH
106 Variable names are displayed, for scratch variables only (@pxref{Scratch
107 Variables}).
108
109 @item ATTRIBUTES
110 Datafile and variable attributes are displayed, except that attributes
111 whose names begin with @code{@@} or @code{$@@} are omitted.
112
113 @itemx @@ATTRIBUTES
114 All datafile and variable attributes are displayed.
115 @end table
116
117 With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
118 declared vectors.  If the SORTED keyword is given, the vectors are
119 listed in alphabetical order; otherwise, they are listed in textual
120 order of definition within the PSPP syntax file.
121
122 For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
123 FILE LABEL}.
124
125 @node FORMATS
126 @section FORMATS
127 @vindex FORMATS
128
129 @display
130 FORMATS var_list (fmt_spec).
131 @end display
132
133 @cmd{FORMATS} set both print and write formats for the specified
134 numeric variables to the specified format specification.
135 @xref{Input and Output Formats}.
136
137 Specify a list of variables followed by a format specification in
138 parentheses.  The print and write formats of the specified variables
139 will be changed.
140
141 Additional lists of variables and formats may be included if they are
142 delimited by a slash (@samp{/}).
143
144 @cmd{FORMATS} takes effect immediately.  It is not affected by
145 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
146
147 @node LEAVE
148 @section LEAVE
149 @vindex LEAVE
150
151 @display
152 LEAVE var_list.
153 @end display
154
155 @cmd{LEAVE} prevents the specified variables from being
156 reinitialized whenever a new case is processed.
157
158 Normally, when a data file is processed, every variable in the active
159 file is initialized to the system-missing value or spaces at the
160 beginning of processing for each case.  When a variable has been
161 specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
162 initialized to 0 (not system-missing) or spaces for the first case.
163 After that, it retains its value between cases.
164
165 This becomes useful for counters.  For instance, in the example below
166 the variable SUM maintains a running total of the values in the ITEM
167 variable.
168
169 @example
170 DATA LIST /ITEM 1-3.
171 COMPUTE SUM=SUM+ITEM.
172 PRINT /ITEM SUM.
173 LEAVE SUM
174 BEGIN DATA.
175 123
176 404
177 555
178 999
179 END DATA.
180 @end example
181
182 @noindent Partial output from this example:
183
184 @example
185 123   123.00
186 404   527.00
187 555  1082.00
188 999  2081.00
189 @end example
190
191 It is best to use @cmd{LEAVE} command immediately before invoking a
192 procedure command, because the left status of variables is reset by
193 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
194 Left status is also reset by all procedure invocations.
195
196 @node MISSING VALUES
197 @section MISSING VALUES
198 @vindex MISSING VALUES
199
200 @display
201 MISSING VALUES var_list (missing_values).
202
203 missing_values takes one of the following forms:
204         num1
205         num1, num2
206         num1, num2, num3
207         num1 THRU num2
208         num1 THRU num2, num3
209         string1
210         string1, string2
211         string1, string2, string3
212 As part of a range, LO or LOWEST may take the place of num1;
213 HI or HIGHEST may take the place of num2.
214 @end display
215
216 @cmd{MISSING VALUES} sets user-missing values for numeric and string
217 variables.  Long string variables may have missing values, but
218 characters after the first 8 bytes of the missing value must be
219 spaces.
220
221 Specify a list of variables, followed by a list of their user-missing
222 values in parentheses.  Up to three discrete values may be given, or,
223 for numeric variables only, a range of values optionally accompanied by
224 a single discrete value.  Ranges may be open-ended on one end, indicated
225 through the use of the keyword LO or LOWEST or HI or HIGHEST.
226
227 The @cmd{MISSING VALUES} command takes effect immediately.  It is not
228 affected by conditional and looping constructs such as @cmd{DO IF} or
229 @cmd{LOOP}.
230
231 @node MODIFY VARS
232 @section MODIFY VARS
233 @vindex MODIFY VARS
234
235 @display 
236 MODIFY VARS
237         /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
238         /RENAME=(old_names=new_names)@dots{}
239         /@{DROP,KEEP@}=var_list
240         /MAP    
241 @end display
242
243 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
244 active file.
245
246 At least one subcommand must be specified, and no subcommand may be
247 specified more than once.  DROP and KEEP may not both be specified.
248
249 The REORDER subcommand changes the order of variables in the active
250 file.  Specify one or more lists of variable names in parentheses.  By
251 default, each list of variables is rearranged into the specified order.
252 To put the variables into the reverse of the specified order, put
253 keyword BACKWARD before the parentheses.  To put them into alphabetical
254 order in the dictionary, specify keyword ALPHA before the parentheses.
255 BACKWARD and ALPHA may also be combined.
256
257 To rename variables in the active file, specify RENAME, an equals sign
258 (@samp{=}), and lists of the old variable names and new variable names
259 separated by another equals sign within parentheses.  There must be the
260 same number of old and new variable names.  Each old variable is renamed to
261 the corresponding new variable name.  Multiple parenthesized groups of
262 variables may be specified.
263
264 The DROP subcommand deletes a specified list of variables from the
265 active file.
266
267 The KEEP subcommand keeps the specified list of variables in the active
268 file.  Any unlisted variables are deleted from the active file.
269
270 MAP is currently ignored.
271
272 If either DROP or KEEP is specified, the data is read; otherwise it is
273 not.
274
275 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
276 (@pxref{TEMPORARY}).
277
278 @node NUMERIC
279 @section NUMERIC
280 @vindex NUMERIC
281
282 @display
283 NUMERIC /var_list [(fmt_spec)].
284 @end display
285
286 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
287 setting their output formats.
288
289 Specify a slash (@samp{/}), followed by the names of the new numeric
290 variables.  If you wish to set their output formats, follow their names
291 by an output format specification in parentheses (@pxref{Input and Output
292 Formats}); otherwise, the default is F8.2.
293
294 Variables created with @cmd{NUMERIC} are initialized to the
295 system-missing value.
296
297 @node MRSETS
298 @section MRSETS
299 @vindex MRSETS
300
301 @display
302 MRSETS 
303     /MDGROUP NAME=name VARIABLES=var_list VALUE=value
304      [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
305      [@{LABEL='label',LABELSOURCE=VARLABEL@}]
306
307     /MCGROUP NAME=name VARIABLES=var_list [LABEL='label']
308
309     /DELETE NAME=@{[names],ALL@}
310
311     /DISPLAY NAME=@{[names],ALL@}
312 @end display
313
314 @cmd{MRSETS} creates, modifies, deletes, and displays multiple
315 response sets.  A multiple response set is a set of variables that
316 represent multiple responses to a single survey question in one of the
317 two following ways:
318
319 @itemize @bullet
320 @item
321 A @dfn{multiple dichotomy set} is analogous to a survey question with
322 a set of checkboxes.  Each variable in the set is treated in a Boolean
323 fashion: one value (the "counted value") means that the box was
324 checked, and any other value means that it was not.
325
326 @item
327 A @dfn{multiple category set} represents a survey question where the
328 respondent is instructed to list up to @var{n} choices.  Each variable
329 represents one of the responses.
330 @end itemize
331
332 Any number of subcommands may be specified in any order.
333
334 The MDGROUP subcommand creates a new multiple dichotomy set or
335 replaces an existing multiple response set.  The NAME, VARIABLES, and
336 VALUE specifications are required.  The others are optional:
337
338 @itemize @bullet
339 @item
340 NAME specifies the name used in syntax for the new multiple dichotomy
341 set.  The name must begin with @samp{$}; it must otherwise follow the
342 rules for identifiers (@pxref{Tokens}).
343
344 @item
345 VARIABLES specifies the variables that belong to the set.  At least
346 two variables must be specified.  The variables must be all string or
347 all numeric.
348
349 @item
350 VALUE specifies the counted value.  If the variables are numeric, the
351 value must be an integer.  If the variables are strings, then the
352 value must be a string that is no longer than the shortest of the
353 variables in the set (ignoring trailing spaces).
354
355 @item
356 CATEGORYLABELS optionally specifies the source of the labels for each
357 category in the set:
358
359 @itemize @minus
360 @item
361 VARLABELS, the default, uses variable labels or, for variables without
362 variable labels, variable names.  PSPP warns if two variables have the
363 same variable label, since these categories cannot be distinguished in
364 output.
365
366 @item 
367 COUNTEDVALUES instead uses each variable's value label for the counted
368 value.  PSPP warns if two variables have the same value label for the
369 counted value or if one of the variables lacks a value label, since
370 such categories cannot be distinguished in output.
371 @end itemize
372
373 @item
374 LABEL optionally specifies a label for the multiple response set.  If
375 neither LABEL nor LABELSOURCE=VARLABEL is specified, the set is
376 unlabeled.
377
378 @item
379 LABELSOURCE=VARLABEL draws the multiple response set's label from the
380 first variable label among the variables in the set; if none of the
381 variables has a label, the name of the first variable is used.
382 LABELSOURCE=VARLABEL must be used with CATEGORYLABELS=COUNTEDVALUES.
383 It is mutually exclusive with LABEL.
384 @end itemize
385
386 The MCGROUP subcommand creates a new multiple category set or
387 replaces an existing multiple response set.  The NAME and VARIABLES
388 specifications are required, and LABEL is optional.  Their meanings
389 are as described above to MDGROUP.  PSPP warns if two variables in the
390 set have different value labels for a single value, since each of the
391 variables in the set should have the same possible categories.
392
393 The DELETE subcommand deletes multiple response groups.  A list of
394 groups may be named within a set of required square brackets, or ALL
395 may be used to delete all groups.
396
397 The DISPLAY subcommand displays information about defined multiple
398 response sets.  Its syntax is the same as the DELETE subcommand.
399
400 Multiple response sets are saved to and read from system files by,
401 e.g., the @cmd{SAVE} and @cmd{GET} command.  Otherwise, multiple
402 response sets are currently used only by third party software.
403
404 @node PRINT FORMATS
405 @section PRINT FORMATS
406 @vindex PRINT FORMATS
407
408 @display
409 PRINT FORMATS var_list (fmt_spec).
410 @end display
411
412 @cmd{PRINT FORMATS} sets the print formats for the specified
413 numeric variables to the specified format specification.
414
415 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
416 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
417
418 @node RENAME VARIABLES
419 @section RENAME VARIABLES
420 @vindex RENAME VARIABLES
421
422 @display
423 RENAME VARIABLES (old_names=new_names)@dots{} .
424 @end display
425
426 @cmd{RENAME VARIABLES} changes the names of variables in the active
427 file.  Specify lists of the old variable names and new
428 variable names, separated by an equals sign (@samp{=}), within
429 parentheses.  There must be the same number of old and new variable
430 names.  Each old variable is renamed to the corresponding new variable
431 name.  Multiple parenthesized groups of variables may be specified.
432
433 @cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
434 to be read.
435
436 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
437 (@pxref{TEMPORARY}).
438
439 @node VALUE LABELS
440 @section VALUE LABELS
441 @vindex VALUE LABELS
442
443 @display 
444 VALUE LABELS
445         /var_list value 'label' [value 'label']@dots{}
446 @end display
447
448 @cmd{VALUE LABELS} allows values of numeric and short string
449 variables to be associated with labels.  In this way, a short value can
450 stand for a long value.
451
452 To set up value labels for a set of variables, specify the
453 variable names after a slash (@samp{/}), followed by a list of values
454 and their associated labels, separated by spaces.
455
456 Before @cmd{VALUE LABELS} is executed, any existing value labels
457 are cleared from the variables specified.  Use @cmd{ADD VALUE LABELS}
458 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
459 already present.
460
461 @node STRING
462 @section STRING
463 @vindex STRING
464
465 @display
466 STRING /var_list (fmt_spec).
467 @end display
468
469 @cmd{STRING} creates new string variables for use in
470 transformations.
471
472 Specify a slash (@samp{/}), followed by the names of the string
473 variables to create and the desired output format specification in
474 parentheses (@pxref{Input and Output Formats}).  Variable widths are
475 implicitly derived from the specified output formats.
476
477 Created variables are initialized to spaces.
478
479
480 @node VARIABLE ATTRIBUTE
481 @section VARIABLE ATTRIBUTE
482 @vindex VARIABLE ATTRIBUTE
483
484 @display
485 VARIABLE ATTRIBUTE
486          VARIABLES=var_list
487          ATTRIBUTE=name('value') [name('value')]@dots{}
488          ATTRIBUTE=name@b{[}index@b{]}('value') [name@b{[}index@b{]}('value')]@dots{}
489          DELETE=name [name]@dots{}
490          DELETE=name@b{[}index@b{]} [name@b{[}index@b{]}]@dots{}
491 @end display
492
493 @cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
494 attributes associated with variables in the active file.  Custom
495 variable attributes are not interpreted by PSPP, but they are saved as
496 part of system files and may be used by other software that reads
497 them.
498
499 The required VARIABLES subcommand must come first.  Specify the
500 variables to which the following ATTRIBUTE or DELETE subcommand
501 should apply.
502
503 Use the ATTRIBUTE subcommand to add or modify custom variable
504 attributes.  Specify the name of the attribute as an identifier
505 (@pxref{Tokens}), followed by the desired value, in parentheses, as a
506 quoted string.  The specified attributes are then added or modified in
507 the variables specified on VARIABLES.  Attribute names that begin with
508 @code{$} are reserved for PSPP's internal use, and attribute names
509 that begin with @code{@@} or @code{$@@} are not displayed by most PSPP
510 commands that display other attributes.  Other attribute names are not
511 treated specially.
512
513 Attributes may also be organized into arrays.  To assign to an array
514 element, add an integer array index enclosed in square brackets
515 (@code{[} and @code{]}) between the attribute name and value.  Array
516 indexes start at 1, not 0.  An attribute array that has a single
517 element (number 1) is not distinguished from a non-array attribute.
518
519 Use the DELETE subcommand to delete an attribute from the variable
520 specified on VARIABLES.  Specify an attribute name by itself to delete
521 an entire attribute, including all array elements for attribute
522 arrays.  Specify an attribute name followed by an array index in
523 square brackets to delete a single element of an attribute array.  In
524 the latter case, all the array elements numbered higher than the
525 deleted element are shifted down, filling the vacated position.
526
527 To associate custom attributes with the entire active file, instead of
528 with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
529
530 @cmd{VARIABLE ATTRIBUTE} takes effect immediately.  It is not affected
531 by conditional and looping structures such as @cmd{DO IF} or
532 @cmd{LOOP}.
533
534 @node VARIABLE LABELS
535 @section VARIABLE LABELS
536 @vindex VARIABLE LABELS
537
538 @display
539 VARIABLE LABELS
540         var_list 'var_label' 
541         [ /var_list 'var_label']
542         .
543         .
544         .
545         [ /var_list 'var_label']
546 @end display
547
548 @cmd{VARIABLE LABELS} associates explanatory names
549 with variables.  This name, called a @dfn{variable label}, is displayed by
550 statistical procedures.
551
552 To assign a variable label to a group of variables, specify a 
553 list of variable names and the variable label as a string.
554 To assign different labels to different variables in the same command, 
555 precede the subsequent variable list with a slash (@samp{/}).
556
557
558 @node VARIABLE ALIGNMENT
559 @comment  node-name,  next,  previous,  u
560 @section VARIABLE ALIGNMENT
561 @vindex VARIABLE ALIGNMENT
562
563 @display
564 VARIABLE ALIGNMENT
565         var_list ( LEFT | RIGHT | CENTER )
566         [ /var_list ( LEFT | RIGHT | CENTER ) ]
567         .
568         .
569         .
570         [ /var_list ( LEFT | RIGHT | CENTER ) ]
571 @end display
572
573 @cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing 
574 purposes.   This only has effect for third party software.  It does not affect 
575 the display of variables in the PSPP output.
576
577
578
579
580 @node VARIABLE WIDTH
581 @comment  node-name,  next,  previous,  up
582 @section VARIABLE WIDTH
583 @vindex VARIABLE WIDTH
584 @display
585 VARIABLE WIDTH
586         var_list (width)
587         [ /var_list (width) ] 
588         .
589         .
590         .
591         [ /var_list (width) ] 
592 @end display
593
594 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
595 purposes.   This only affects third party software.  It does not affect 
596 the display of variables in the PSPP output.
597
598
599 @node VARIABLE LEVEL
600 @comment  node-name,  next,  previous,  up
601 @section VARIABLE LEVEL
602 @vindex VARIABLE LEVEL
603 @display
604 VARIABLE LEVEL
605         var_list ( SCALE | NOMINAL | ORDINAL )
606         [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
607         .
608         .
609         .
610         [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
611 @end display
612
613 @cmd{VARIABLE LEVEL} sets the measurement level of  variables.
614 Currently, this has no effect except for certain third party software.
615
616
617 @node VECTOR
618 @section VECTOR
619 @vindex VECTOR
620
621 @display
622 Two possible syntaxes:
623         VECTOR vec_name=var_list.
624         VECTOR vec_name_list(count [format]).
625 @end display
626
627 @cmd{VECTOR} allows a group of variables to be accessed as if they
628 were consecutive members of an array with a vector(index) notation.
629
630 To make a vector out of a set of existing variables, specify a name
631 for the vector followed by an equals sign (@samp{=}) and the variables
632 to put in the vector.  All the variables in the vector must be the same
633 type.  String variables in a vector must all have the same width.
634
635 To make a vector and create variables at the same time, specify one or
636 more vector names followed by a count in parentheses.  This will cause
637 variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
638 to be created as numeric variables.  By default, the new variables
639 have print and write format F8.2, but an alternate format may be
640 specified inside the parentheses before or after the count and
641 separated from it by white space or a comma.  Variable names including
642 numeric suffixes may not exceed 64 characters in length, and none of
643 the variables may exist prior to @cmd{VECTOR}.
644
645 Vectors created with @cmd{VECTOR} disappear after any procedure or
646 procedure-like command is executed.  The variables contained in the
647 vectors remain, unless they are scratch variables (@pxref{Scratch
648 Variables}).
649
650 Variables within a vector may be referenced in expressions using
651 @code{vector(index)} syntax.
652
653 @node WRITE FORMATS
654 @section WRITE FORMATS
655 @vindex WRITE FORMATS
656
657 @display
658 WRITE FORMATS var_list (fmt_spec).
659 @end display
660
661 @cmd{WRITE FORMATS} sets the write formats for the specified numeric
662 variables
663 to the specified format specification.  Its syntax is identical to
664 that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
665 write formats, not print formats.