1 @node Variable Attributes, Data Manipulation, System and Portable Files, Top
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 * DISPLAY:: Display variable names & descriptions.
10 * DISPLAY VECTORS:: Display a list of vectors.
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 LABELS:: Set variable labels for variables.
21 * VARIABLE ALIGNMENT:: Set the alignment for display.
22 * VARIABLE WIDTH:: Set the display width.
23 * VARIABLE LEVEL:: Set the measurement level.
24 * VECTOR:: Declare an array of variables.
25 * WRITE FORMATS:: Set variable write formats.
28 @node ADD VALUE LABELS, DISPLAY, Variable Attributes, Variable Attributes
29 @section ADD VALUE LABELS
30 @vindex ADD VALUE LABELS
34 /var_list value 'label' [value 'label']@dots{}
37 @cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
38 LABELS} (@pxref{VALUE LABELS}), but it does not clear value
39 labels from the variables before adding the ones specified.
41 @node DISPLAY, DISPLAY VECTORS, ADD VALUE LABELS, Variable Attributes
46 DISPLAY @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH@}
50 @cmd{DISPLAY} displays requested information on variables. Variables can
51 optionally be sorted alphabetically. The entire dictionary or just
52 specified variables can be described.
54 One of the following keywords can be present:
58 The variables' names are displayed.
61 The variables' names are displayed along with a value describing their
62 position within the active file dictionary.
65 Variable names, positions, and variable labels are displayed.
68 Variable names, positions, print and write formats, and missing values
72 Variable names, positions, print and write formats, missing values,
73 variable labels, and value labels are displayed.
76 Varible names are displayed, for scratch variables only (@pxref{Scratch
80 If SORTED is specified, then the variables are displayed in ascending
81 order based on their names; otherwise, they are displayed in the order
82 that they occur in the active file dictionary.
84 @node DISPLAY VECTORS, FORMATS, DISPLAY, Variable Attributes
85 @section DISPLAY VECTORS
86 @vindex DISPLAY VECTORS
92 @cmd{DISPLAY VECTORS} lists all the currently declared vectors.
94 @node FORMATS, LEAVE, DISPLAY VECTORS, Variable Attributes
99 FORMATS var_list (fmt_spec).
102 @cmd{FORMATS} set both print and write formats for the specified
103 numeric variables to the specified format specification.
104 @xref{Input and Output Formats}.
106 Specify a list of variables followed by a format specification in
107 parentheses. The print and write formats of the specified variables
110 Additional lists of variables and formats may be included if they are
111 delimited by a slash (@samp{/}).
113 @cmd{FORMATS} takes effect immediately. It is not affected by
114 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
116 @node LEAVE, MISSING VALUES, FORMATS, Variable Attributes
124 @cmd{LEAVE} prevents the specified variables from being
125 reinitialized whenever a new case is processed.
127 Normally, when a data file is processed, every variable in the active
128 file is initialized to the system-missing value or spaces at the
129 beginning of processing for each case. When a variable has been
130 specified on @cmd{LEAVE}, this is not the case. Instead, that variable is
131 initialized to 0 (not system-missing) or spaces for the first case.
132 After that, it retains its value between cases.
134 This becomes useful for counters. For instance, in the example below
135 the variable SUM maintains a running total of the values in the ITEM
140 COMPUTE SUM=SUM+ITEM.
151 @noindent Partial output from this example:
160 It is best to use @cmd{LEAVE} command immediately before invoking a
161 procedure command, because the left status of variables is reset by
162 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
163 Left status is also reset by all procedure invocations.
165 @node MISSING VALUES, MODIFY VARS, LEAVE, Variable Attributes
166 @section MISSING VALUES
167 @vindex MISSING VALUES
170 MISSING VALUES var_list (missing_values).
172 missing_values takes one of the following forms:
180 string1, string2, string3
181 As part of a range, LO or LOWEST may take the place of num1;
182 HI or HIGHEST may take the place of num2.
185 @cmd{MISSING VALUES} sets user-missing values for numeric and
186 short string variables. Long string variables may not have missing
189 Specify a list of variables, followed by a list of their user-missing
190 values in parentheses. Up to three discrete values may be given, or,
191 for numeric variables only, a range of values optionally accompanied by
192 a single discrete value. Ranges may be open-ended on one end, indicated
193 through the use of the keyword LO or LOWEST or HI or HIGHEST.
195 The @cmd{MISSING VALUES} command takes effect immediately. It is not
196 affected by conditional and looping constructs such as @cmd{DO IF} or
199 @node MODIFY VARS, NUMERIC, MISSING VALUES, Variable Attributes
205 /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
206 /RENAME=(old_names=new_names)@dots{}
207 /@{DROP,KEEP@}=var_list
211 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
214 At least one subcommand must be specified, and no subcommand may be
215 specified more than once. DROP and KEEP may not both be specified.
217 The REORDER subcommand changes the order of variables in the active
218 file. Specify one or more lists of variable names in parentheses. By
219 default, each list of variables is rearranged into the specified order.
220 To put the variables into the reverse of the specified order, put
221 keyword BACKWARD before the parentheses. To put them into alphabetical
222 order in the dictionary, specify keyword ALPHA before the parentheses.
223 BACKWARD and ALPHA may also be combined.
225 To rename variables in the active file, specify RENAME, an equals sign
226 (@samp{=}), and lists of the old variable names and new variable names
227 separated by another equals sign within parentheses. There must be the
228 same number of old and new variable names. Each old variable is renamed to
229 the corresponding new variable name. Multiple parenthesized groups of
230 variables may be specified.
232 The DROP subcommand deletes a specified list of variables from the
235 The KEEP subcommand keeps the specified list of variables in the active
236 file. Any unlisted variables are deleted from the active file.
238 MAP is currently ignored.
240 If either DROP or KEEP is specified, the data is read; otherwise it is
243 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
246 @node NUMERIC, PRINT FORMATS, MODIFY VARS, Variable Attributes
251 NUMERIC /var_list [(fmt_spec)].
254 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
255 setting their output formats.
257 Specify a slash (@samp{/}), followed by the names of the new numeric
258 variables. If you wish to set their output formats, follow their names
259 by an output format specification in parentheses (@pxref{Input and Output
260 Formats}); otherwise, the default is F8.2.
262 Variables created with @cmd{NUMERIC} are initialized to the
263 system-missing value.
265 @node PRINT FORMATS, RENAME VARIABLES, NUMERIC, Variable Attributes
266 @section PRINT FORMATS
267 @vindex PRINT FORMATS
270 PRINT FORMATS var_list (fmt_spec).
273 @cmd{PRINT FORMATS} sets the print formats for the specified
274 numeric variables to the specified format specification.
276 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
277 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
279 @node RENAME VARIABLES, VALUE LABELS, PRINT FORMATS, Variable Attributes
280 @section RENAME VARIABLES
281 @vindex RENAME VARIABLES
284 RENAME VARIABLES (old_names=new_names)@dots{} .
287 @cmd{RENAME VARIABLES} changes the names of variables in the active
288 file. Specify lists of the old variable names and new
289 variable names, separated by an equals sign (@samp{=}), within
290 parentheses. There must be the same number of old and new variable
291 names. Each old variable is renamed to the corresponding new variable
292 name. Multiple parenthesized groups of variables may be specified.
294 @cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
297 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
300 @node VALUE LABELS, STRING, RENAME VARIABLES, Variable Attributes
301 @section VALUE LABELS
306 /var_list value 'label' [value 'label']@dots{}
309 @cmd{VALUE LABELS} allows values of numeric and short string
310 variables to be associated with labels. In this way, a short value can
311 stand for a long value.
313 To set up value labels for a set of variables, specify the
314 variable names after a slash (@samp{/}), followed by a list of values
315 and their associated labels, separated by spaces. Long string
316 variables may not be specified.
318 Before @cmd{VALUE LABELS} is executed, any existing value labels
319 are cleared from the variables specified. Use @cmd{ADD VALUE LABELS}
320 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
323 @node STRING, VARIABLE LABELS, VALUE LABELS, Variable Attributes
328 STRING /var_list (fmt_spec).
331 @cmd{STRING} creates new string variables for use in
334 Specify a slash (@samp{/}), followed by the names of the string
335 variables to create and the desired output format specification in
336 parentheses (@pxref{Input and Output Formats}). Variable widths are
337 implicitly derived from the specified output formats.
339 Created variables are initialized to spaces.
342 @node VARIABLE LABELS, VARIABLE ALIGNMENT, STRING, Variable Attributes
343 @section VARIABLE LABELS
344 @vindex VARIABLE LABELS
349 [ /var_list 'var_label']
353 [ /var_list 'var_label']
356 @cmd{VARIABLE LABELS} associates explanatory names
357 with variables. This name, called a @dfn{variable label}, is displayed by
358 statistical procedures.
360 To assign a variable label to a group of variables, specify a
361 list of variable names and the variable label as a string.
362 To assign different labels to different variables in the same command,
363 preceed the subsequent variable list with a slash (@samp{/}).
366 @node VARIABLE ALIGNMENT, VARIABLE WIDTH, VARIABLE LABELS, Variable Attributes
367 @comment node-name, next, previous, u
368 @section VARIABLE ALIGNMENT
369 @vindex VARIABLE ALIGNMENT
373 var_list ( LEFT | RIGHT | CENTER )
374 [ /var_list ( LEFT | RIGHT | CENTER ) ]
378 [ /var_list ( LEFT | RIGHT | CENTER ) ]
381 @cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
382 purposes. This only has effect for third party software. It does not affect
383 the display of variables in the PSPP output.
388 @node VARIABLE WIDTH, VARIABLE LEVEL, VARIABLE ALIGNMENT, Variable Attributes
389 @comment node-name, next, previous, up
390 @section VARIABLE WIDTH
391 @vindex VARIABLE WIDTH
395 [ /var_list (width) ]
399 [ /var_list (width) ]
402 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
403 purposes. This only affects third party software. It does not affect
404 the display of variables in the PSPP output.
407 @node VARIABLE LEVEL, VECTOR, VARIABLE WIDTH, Variable Attributes
408 @comment node-name, next, previous, up
409 @section VARIABLE LEVEL
410 @vindex VARIABLE LEVEL
413 var_list ( SCALE | NOMINAL | ORDINAL )
414 [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
418 [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
421 @cmd{VARIABLE LEVEL} sets the measurement level of variables.
422 Currently, this has no effect except for certain third party software.
425 @node VECTOR, WRITE FORMATS, VARIABLE LEVEL, Variable Attributes
430 Two possible syntaxes:
431 VECTOR vec_name=var_list.
432 VECTOR vec_name_list(count).
435 @cmd{VECTOR} allows a group of variables to be accessed as if they
436 were consecutive members of an array with a vector(index) notation.
438 To make a vector out of a set of existing variables, specify a name for
439 the vector followed by an equals sign (@samp{=}) and the variables that
440 belong in the vector.
442 To make a vector and create variables at the same time, specify one or
443 more vector names followed by a count in parentheses. This will cause
444 variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
445 to be created as numeric variables with print and write format F8.2.
446 Variable names including numeric suffixes may not exceed 64 characters
447 in length, and none of the variables may exist prior to @cmd{VECTOR}.
449 All the variables in a vector must be the same type.
451 Vectors created with @cmd{VECTOR} disappear after any procedure or
452 procedure-like command is executed. The variables contained in the
453 vectors remain, unless they are scratch variables (@pxref{Scratch
456 Variables within a vector may be referenced in expressions using
457 @code{vector(index)} syntax.
462 @node WRITE FORMATS, , VECTOR, Variable Attributes
463 @section WRITE FORMATS
464 @vindex WRITE FORMATS
467 WRITE FORMATS var_list (fmt_spec).
470 @cmd{WRITE FORMATS} sets the write formats for the specified numeric
472 to the specified format specification. Its syntax is identical to
473 that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
474 write formats, not print formats.