1 @node Variable Attributes
2 @chapter Manipulating variables
4 The variables in the active file dictionary are important. There are
5 several utility functions for examining and adjusting them.
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.
29 @node ADD VALUE LABELS
30 @section ADD VALUE LABELS
31 @vindex ADD VALUE LABELS
35 /var_list value 'label' [value 'label']@dots{}
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.
42 @node DELETE VARIABLES
43 @section DELETE VARIABLES
44 @vindex DELETE VARIABLES
47 DELETE VARIABLES var_list.
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}).
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.
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.
75 @cmd{DISPLAY} displays information about the active file. A variety
76 of different forms of information can be requested.
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.
87 The variables' names are displayed.
90 The variables' names are displayed along with a value describing their
91 position within the active file dictionary.
94 Variable names, positions, and variable labels are displayed.
97 Variable names, positions, print and write formats, and missing values
101 Variable names, positions, print and write formats, missing values,
102 variable labels, and value labels are displayed.
105 Variable names are displayed, for scratch variables only (@pxref{Scratch
109 Datafile and variable attributes are displayed, except that attributes
110 whose names begin with @code{@@} or @code{$@@} are omitted.
113 All datafile and variable attributes are displayed.
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.
121 For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
129 FORMATS var_list (fmt_spec).
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}.
136 Specify a list of variables followed by a format specification in
137 parentheses. The print and write formats of the specified variables
140 Additional lists of variables and formats may be included if they are
141 delimited by a slash (@samp{/}).
143 @cmd{FORMATS} takes effect immediately. It is not affected by
144 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
154 @cmd{LEAVE} prevents the specified variables from being
155 reinitialized whenever a new case is processed.
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.
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
170 COMPUTE SUM=SUM+ITEM.
181 @noindent Partial output from this example:
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.
196 @section MISSING VALUES
197 @vindex MISSING VALUES
200 MISSING VALUES var_list (missing_values).
202 missing_values takes one of the following forms:
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.
215 @cmd{MISSING VALUES} sets user-missing values for numeric and
216 short string variables. Long string variables may not have missing
219 Specify a list of variables, followed by a list of their user-missing
220 values in parentheses. Up to three discrete values may be given, or,
221 for numeric variables only, a range of values optionally accompanied by
222 a single discrete value. Ranges may be open-ended on one end, indicated
223 through the use of the keyword LO or LOWEST or HI or HIGHEST.
225 The @cmd{MISSING VALUES} command takes effect immediately. It is not
226 affected by conditional and looping constructs such as @cmd{DO IF} or
235 /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
236 /RENAME=(old_names=new_names)@dots{}
237 /@{DROP,KEEP@}=var_list
241 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
244 At least one subcommand must be specified, and no subcommand may be
245 specified more than once. DROP and KEEP may not both be specified.
247 The REORDER subcommand changes the order of variables in the active
248 file. Specify one or more lists of variable names in parentheses. By
249 default, each list of variables is rearranged into the specified order.
250 To put the variables into the reverse of the specified order, put
251 keyword BACKWARD before the parentheses. To put them into alphabetical
252 order in the dictionary, specify keyword ALPHA before the parentheses.
253 BACKWARD and ALPHA may also be combined.
255 To rename variables in the active file, specify RENAME, an equals sign
256 (@samp{=}), and lists of the old variable names and new variable names
257 separated by another equals sign within parentheses. There must be the
258 same number of old and new variable names. Each old variable is renamed to
259 the corresponding new variable name. Multiple parenthesized groups of
260 variables may be specified.
262 The DROP subcommand deletes a specified list of variables from the
265 The KEEP subcommand keeps the specified list of variables in the active
266 file. Any unlisted variables are deleted from the active file.
268 MAP is currently ignored.
270 If either DROP or KEEP is specified, the data is read; otherwise it is
273 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
281 NUMERIC /var_list [(fmt_spec)].
284 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
285 setting their output formats.
287 Specify a slash (@samp{/}), followed by the names of the new numeric
288 variables. If you wish to set their output formats, follow their names
289 by an output format specification in parentheses (@pxref{Input and Output
290 Formats}); otherwise, the default is F8.2.
292 Variables created with @cmd{NUMERIC} are initialized to the
293 system-missing value.
296 @section PRINT FORMATS
297 @vindex PRINT FORMATS
300 PRINT FORMATS var_list (fmt_spec).
303 @cmd{PRINT FORMATS} sets the print formats for the specified
304 numeric variables to the specified format specification.
306 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
307 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
309 @node RENAME VARIABLES
310 @section RENAME VARIABLES
311 @vindex RENAME VARIABLES
314 RENAME VARIABLES (old_names=new_names)@dots{} .
317 @cmd{RENAME VARIABLES} changes the names of variables in the active
318 file. Specify lists of the old variable names and new
319 variable names, separated by an equals sign (@samp{=}), within
320 parentheses. There must be the same number of old and new variable
321 names. Each old variable is renamed to the corresponding new variable
322 name. Multiple parenthesized groups of variables may be specified.
324 @cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
327 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
331 @section VALUE LABELS
336 /var_list value 'label' [value 'label']@dots{}
339 @cmd{VALUE LABELS} allows values of numeric and short string
340 variables to be associated with labels. In this way, a short value can
341 stand for a long value.
343 To set up value labels for a set of variables, specify the
344 variable names after a slash (@samp{/}), followed by a list of values
345 and their associated labels, separated by spaces.
347 Before @cmd{VALUE LABELS} is executed, any existing value labels
348 are cleared from the variables specified. Use @cmd{ADD VALUE LABELS}
349 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
357 STRING /var_list (fmt_spec).
360 @cmd{STRING} creates new string variables for use in
363 Specify a slash (@samp{/}), followed by the names of the string
364 variables to create and the desired output format specification in
365 parentheses (@pxref{Input and Output Formats}). Variable widths are
366 implicitly derived from the specified output formats.
368 Created variables are initialized to spaces.
371 @node VARIABLE ATTRIBUTE
372 @section VARIABLE ATTRIBUTE
373 @vindex VARIABLE ATTRIBUTE
378 ATTRIBUTE=name('value') [name('value')]@dots{}
379 ATTRIBUTE=name@b{[}index@b{]}('value') [name@b{[}index@b{]}('value')]@dots{}
380 DELETE=name [name]@dots{}
381 DELETE=name@b{[}index@b{]} [name@b{[}index@b{]}]@dots{}
384 @cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
385 attributes associated with variables in the active file. Custom
386 variable attributes are not interpreted by PSPP, but they are saved as
387 part of system files and may be used by other software that reads
390 The required VARIABLES subcommand must come first. Specify the
391 variables to which the following ATTRIBUTE or DELETE subcommand
394 Use the ATTRIBUTE subcommand to add or modify custom variable
395 attributes. Specify the name of the attribute as an identifier
396 (@pxref{Tokens}), followed by the desired value, in parentheses, as a
397 quoted string. The specified attributes are then added or modified in
398 the variables specified on VARIABLES. Attribute names that begin with
399 @code{$} are reserved for PSPP's internal use, and attribute names
400 that begin with @code{@@} or @code{$@@} are not displayed by most PSPP
401 commands that display other attributes. Other attribute names are not
404 Attributes may also be organized into arrays. To assign to an array
405 element, add an integer array index enclosed in square brackets
406 (@code{[} and @code{]}) between the attribute name and value. Array
407 indexes start at 1, not 0. An attribute array that has a single
408 element (number 1) is not distinguished from a non-array attribute.
410 Use the DELETE subcommand to delete an attribute from the variable
411 specified on VARIABLES. Specify an attribute name by itself to delete
412 an entire attribute, including all array elements for attribute
413 arrays. Specify an attribute name followed by an array index in
414 square brackets to delete a single element of an attribute array. In
415 the latter case, all the array elements numbered higher than the
416 deleted element are shifted down, filling the vacated position.
418 To associate custom attributes with the entire active file, instead of
419 with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
421 @cmd{VARIABLE ATTRIBUTE} takes effect immediately. It is not affected
422 by conditional and looping structures such as @cmd{DO IF} or
425 @node VARIABLE LABELS
426 @section VARIABLE LABELS
427 @vindex VARIABLE LABELS
432 [ /var_list 'var_label']
436 [ /var_list 'var_label']
439 @cmd{VARIABLE LABELS} associates explanatory names
440 with variables. This name, called a @dfn{variable label}, is displayed by
441 statistical procedures.
443 To assign a variable label to a group of variables, specify a
444 list of variable names and the variable label as a string.
445 To assign different labels to different variables in the same command,
446 precede the subsequent variable list with a slash (@samp{/}).
449 @node VARIABLE ALIGNMENT
450 @comment node-name, next, previous, u
451 @section VARIABLE ALIGNMENT
452 @vindex VARIABLE ALIGNMENT
456 var_list ( LEFT | RIGHT | CENTER )
457 [ /var_list ( LEFT | RIGHT | CENTER ) ]
461 [ /var_list ( LEFT | RIGHT | CENTER ) ]
464 @cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
465 purposes. This only has effect for third party software. It does not affect
466 the display of variables in the PSPP output.
472 @comment node-name, next, previous, up
473 @section VARIABLE WIDTH
474 @vindex VARIABLE WIDTH
478 [ /var_list (width) ]
482 [ /var_list (width) ]
485 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
486 purposes. This only affects third party software. It does not affect
487 the display of variables in the PSPP output.
491 @comment node-name, next, previous, up
492 @section VARIABLE LEVEL
493 @vindex VARIABLE LEVEL
496 var_list ( SCALE | NOMINAL | ORDINAL )
497 [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
501 [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
504 @cmd{VARIABLE LEVEL} sets the measurement level of variables.
505 Currently, this has no effect except for certain third party software.
513 Two possible syntaxes:
514 VECTOR vec_name=var_list.
515 VECTOR vec_name_list(count [format]).
518 @cmd{VECTOR} allows a group of variables to be accessed as if they
519 were consecutive members of an array with a vector(index) notation.
521 To make a vector out of a set of existing variables, specify a name
522 for the vector followed by an equals sign (@samp{=}) and the variables
523 to put in the vector. All the variables in the vector must be the same
524 type. String variables in a vector must all have the same width.
526 To make a vector and create variables at the same time, specify one or
527 more vector names followed by a count in parentheses. This will cause
528 variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
529 to be created as numeric variables. By default, the new variables
530 have print and write format F8.2, but an alternate format may be
531 specified inside the parentheses before or after the count and
532 separated from it by white space or a comma. Variable names including
533 numeric suffixes may not exceed 64 characters in length, and none of
534 the variables may exist prior to @cmd{VECTOR}.
536 Vectors created with @cmd{VECTOR} disappear after any procedure or
537 procedure-like command is executed. The variables contained in the
538 vectors remain, unless they are scratch variables (@pxref{Scratch
541 Variables within a vector may be referenced in expressions using
542 @code{vector(index)} syntax.
545 @section WRITE FORMATS
546 @vindex WRITE FORMATS
549 WRITE FORMATS var_list (fmt_spec).
552 @cmd{WRITE FORMATS} sets the write formats for the specified numeric
554 to the specified format specification. Its syntax is identical to
555 that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
556 write formats, not print formats.