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 * 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.
30 @node ADD VALUE LABELS
31 @section ADD VALUE LABELS
32 @vindex ADD VALUE LABELS
36 /var_list value 'label' [value 'label']@dots{}
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.
43 @node DELETE VARIABLES
44 @section DELETE VARIABLES
45 @vindex DELETE VARIABLES
48 DELETE VARIABLES var_list.
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}).
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.
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.
76 @cmd{DISPLAY} displays information about the active file. A variety
77 of different forms of information can be requested.
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.
88 The variables' names are displayed.
91 The variables' names are displayed along with a value describing their
92 position within the active file dictionary.
95 Variable names, positions, and variable labels are displayed.
98 Variable names, positions, print and write formats, and missing values
102 Variable names, positions, print and write formats, missing values,
103 variable labels, and value labels are displayed.
106 Variable names are displayed, for scratch variables only (@pxref{Scratch
110 Datafile and variable attributes are displayed, except that attributes
111 whose names begin with @code{@@} or @code{$@@} are omitted.
114 All datafile and variable attributes are displayed.
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.
122 For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
130 FORMATS var_list (fmt_spec).
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}.
137 Specify a list of variables followed by a format specification in
138 parentheses. The print and write formats of the specified variables
141 Additional lists of variables and formats may be included if they are
142 delimited by a slash (@samp{/}).
144 @cmd{FORMATS} takes effect immediately. It is not affected by
145 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
155 @cmd{LEAVE} prevents the specified variables from being
156 reinitialized whenever a new case is processed.
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.
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
171 COMPUTE SUM=SUM+ITEM.
182 @noindent Partial output from this example:
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.
197 @section MISSING VALUES
198 @vindex MISSING VALUES
201 MISSING VALUES var_list (missing_values).
203 missing_values takes one of the following forms:
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.
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
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.
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
237 /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
238 /RENAME=(old_names=new_names)@dots{}
239 /@{DROP,KEEP@}=var_list
243 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
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.
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.
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.
264 The DROP subcommand deletes a specified list of variables from the
267 The KEEP subcommand keeps the specified list of variables in the active
268 file. Any unlisted variables are deleted from the active file.
270 MAP is currently ignored.
272 If either DROP or KEEP is specified, the data is read; otherwise it is
275 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
283 NUMERIC /var_list [(fmt_spec)].
286 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
287 setting their output formats.
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.
294 Variables created with @cmd{NUMERIC} are initialized to the
295 system-missing value.
303 /MDGROUP NAME=name VARIABLES=var_list VALUE=value
304 [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
305 [@{LABEL='label',LABELSOURCE=VARLABEL@}]
307 /MCGROUP NAME=name VARIABLES=var_list [LABEL='label']
309 /DELETE NAME=@{[names],ALL@}
311 /DISPLAY NAME=@{[names],ALL@}
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
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.
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.
332 Any number of subcommands may be specified in any order.
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:
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}).
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
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).
356 CATEGORYLABELS optionally specifies the source of the labels for each
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
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.
374 LABEL optionally specifies a label for the multiple response set. If
375 neither LABEL nor LABELSOURCE=VARLABEL is specified, the set is
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.
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.
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.
397 The DISPLAY subcommand displays information about defined multiple
398 response sets. Its syntax is the same as the DELETE subcommand.
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.
405 @section PRINT FORMATS
406 @vindex PRINT FORMATS
409 PRINT FORMATS var_list (fmt_spec).
412 @cmd{PRINT FORMATS} sets the print formats for the specified
413 numeric variables to the specified format specification.
415 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
416 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
418 @node RENAME VARIABLES
419 @section RENAME VARIABLES
420 @vindex RENAME VARIABLES
423 RENAME VARIABLES (old_names=new_names)@dots{} .
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.
433 @cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
436 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
440 @section VALUE LABELS
445 /var_list value 'label' [value 'label']@dots{}
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.
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.
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
466 STRING /var_list (fmt_spec).
469 @cmd{STRING} creates new string variables for use in
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.
477 Created variables are initialized to spaces.
480 @node VARIABLE ATTRIBUTE
481 @section VARIABLE ATTRIBUTE
482 @vindex VARIABLE ATTRIBUTE
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{}
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
499 The required VARIABLES subcommand must come first. Specify the
500 variables to which the following ATTRIBUTE or DELETE subcommand
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
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.
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.
527 To associate custom attributes with the entire active file, instead of
528 with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
530 @cmd{VARIABLE ATTRIBUTE} takes effect immediately. It is not affected
531 by conditional and looping structures such as @cmd{DO IF} or
534 @node VARIABLE LABELS
535 @section VARIABLE LABELS
536 @vindex VARIABLE LABELS
541 [ /var_list 'var_label']
545 [ /var_list 'var_label']
548 @cmd{VARIABLE LABELS} associates explanatory names
549 with variables. This name, called a @dfn{variable label}, is displayed by
550 statistical procedures.
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{/}).
558 @node VARIABLE ALIGNMENT
559 @comment node-name, next, previous, u
560 @section VARIABLE ALIGNMENT
561 @vindex VARIABLE ALIGNMENT
565 var_list ( LEFT | RIGHT | CENTER )
566 [ /var_list ( LEFT | RIGHT | CENTER ) ]
570 [ /var_list ( LEFT | RIGHT | CENTER ) ]
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.
581 @comment node-name, next, previous, up
582 @section VARIABLE WIDTH
583 @vindex VARIABLE WIDTH
587 [ /var_list (width) ]
591 [ /var_list (width) ]
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.
600 @comment node-name, next, previous, up
601 @section VARIABLE LEVEL
602 @vindex VARIABLE LEVEL
605 var_list ( SCALE | NOMINAL | ORDINAL )
606 [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
610 [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
613 @cmd{VARIABLE LEVEL} sets the measurement level of variables.
614 Currently, this has no effect except for certain third party software.
622 Two possible syntaxes:
623 VECTOR vec_name=var_list.
624 VECTOR vec_name_list(count [format]).
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.
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.
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}.
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
650 Variables within a vector may be referenced in expressions using
651 @code{vector(index)} syntax.
654 @section WRITE FORMATS
655 @vindex WRITE FORMATS
658 WRITE FORMATS var_list (fmt_spec).
661 @cmd{WRITE FORMATS} sets the write formats for the specified numeric
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.