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