1 @node Variable Attributes
2 @chapter Manipulating variables
4 The variables in the active dataset 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 dataset.
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{var_list} @var{value} '@var{label}' [@var{value} '@var{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{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 be used after defining transformations
56 but 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{var_list}].
66 DISPLAY [SORTED] INDEX [[/VARIABLES=]@var{var_list}].
67 DISPLAY [SORTED] LABELS [[/VARIABLES=]@var{var_list}].
68 DISPLAY [SORTED] VARIABLES [[/VARIABLES=]@var{var_list}].
69 DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]@var{var_list}].
70 DISPLAY [SORTED] SCRATCH [[/VARIABLES=]@var{var_list}].
71 DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]@var{var_list}].
72 DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]@var{var_list}].
73 DISPLAY [SORTED] VECTORS.
76 @cmd{DISPLAY} displays information about the active dataset. 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 dataset, in the order that
82 variables occur in the active dataset dictionary. The @subcmd{SORTED} keyword
83 causes output to be sorted alphabetically by variable name. The
84 @subcmd{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 dataset 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
111 Datafile and variable attributes are displayed.
112 The first form of the command omits those attributes
113 whose names begin with @code{@@} or @code{$@@}.
114 In the second for, all datafile and variable attributes are displayed.
117 With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
118 declared vectors. If the @subcmd{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{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
133 @cmd{FORMATS} set both print and write formats for the specified
134 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
139 will be changed. All of the variables listed together must have
140 the same type and, for string variables, the same width.
142 Additional lists of variables and formats may be included following
145 @cmd{FORMATS} takes effect immediately. It is not affected by
146 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
153 LEAVE @var{var_list}.
156 @cmd{LEAVE} prevents the specified variables from being
157 reinitialized whenever a new case is processed.
159 Normally, when a data file is processed, every variable in the active
160 dataset is initialized to the system-missing value or spaces at the
161 beginning of processing for each case. When a variable has been
162 specified on @cmd{LEAVE}, this is not the case. Instead, that variable is
163 initialized to 0 (not system-missing) or spaces for the first case.
164 After that, it retains its value between cases.
166 This becomes useful for counters. For instance, in the example below
167 the variable @code{SUM} maintains a running total of the values in the @code{ITEM}
172 COMPUTE SUM=SUM+ITEM.
183 @noindent Partial output from this example:
192 It is best to use @cmd{LEAVE} command immediately before invoking a
193 procedure command, because the left status of variables is reset by
194 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
195 Left status is also reset by all procedure invocations.
198 @section MISSING VALUES
199 @vindex MISSING VALUES
202 MISSING VALUES @var{var_list} (@var{missing_values}).
204 where @var{missing_values} takes one of the following forms:
206 @var{num1}, @var{num2}
207 @var{num1}, @var{num2}, @var{num3}
208 @var{num1} THRU @var{num2}
209 @var{num1} THRU @var{num2}, @var{num3}
211 @var{string1}, @var{string2}
212 @var{string1}, @var{string2}, @var{string3}
213 As part of a range, LO or LOWEST may take the place of @var{num1};
214 HI or HIGHEST may take the place of @var{num2}.
217 @cmd{MISSING VALUES} sets user-missing values for numeric and string
218 variables. Long string variables may have missing values, but
219 characters after the first 8 bytes of the missing value must be
222 Specify a list of variables, followed by a list of their user-missing
223 values in parentheses. Up to three discrete values may be given, or,
224 for numeric variables only, a range of values optionally accompanied by
225 a single discrete value. Ranges may be open-ended on one end, indicated
226 through the use of the keyword LO or LOWEST or HI or HIGHEST.
228 The @cmd{MISSING VALUES} command takes effect immediately. It is not
229 affected by conditional and looping constructs such as @cmd{DO IF} or
238 /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (@var{var_list})@dots{}
239 /RENAME=(@var{old_names}=@var{new_names})@dots{}
240 /@{DROP,KEEP@}=@var{var_list}
244 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
247 At least one subcommand must be specified, and no subcommand may be
248 specified more than once. @subcmd{DROP} and @subcmd{KEEP} may not both
251 The @subcmd{REORDER} subcommand changes the order of variables in the active
252 dataset. Specify one or more lists of variable names in parentheses. By
253 default, each list of variables is rearranged into the specified order.
254 To put the variables into the reverse of the specified order, put
255 keyword @subcmd{BACKWARD} before the parentheses. To put them into alphabetical
256 order in the dictionary, specify keyword @subcmd{ALPHA} before the parentheses.
257 @subcmd{BACKWARD} and @subcmd{ALPHA} may also be combined.
259 To rename variables in the active dataset, specify @subcmd{RENAME}, an equals sign
260 (@samp{=}), and lists of the old variable names and new variable names
261 separated by another equals sign within parentheses. There must be the
262 same number of old and new variable names. Each old variable is renamed to
263 the corresponding new variable name. Multiple parenthesized groups of
264 variables may be specified.
266 The @subcmd{DROP} subcommand deletes a specified list of variables from the
269 The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
270 dataset. Any unlisted variables are deleted from the active dataset.
272 @subcmd{MAP} is currently ignored.
274 If either @subcmd{DROP} or @subcmd{KEEP} is specified, the data is read;
277 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
286 /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
287 [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
288 [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
290 /MCGROUP NAME=@var{name} VARIABLES=@var{var_list} [LABEL='@var{label}']
292 /DELETE NAME=@{[@var{names}],ALL@}
294 /DISPLAY NAME=@{[@var{names}],ALL@}
297 @cmd{MRSETS} creates, modifies, deletes, and displays multiple
298 response sets. A multiple response set is a set of variables that
299 represent multiple responses to a single survey question in one of the
304 A @dfn{multiple dichotomy set} is analogous to a survey question with
305 a set of checkboxes. Each variable in the set is treated in a Boolean
306 fashion: one value (the "counted value") means that the box was
307 checked, and any other value means that it was not.
310 A @dfn{multiple category set} represents a survey question where the
311 respondent is instructed to list up to @var{n} choices. Each variable
312 represents one of the responses.
315 Any number of subcommands may be specified in any order.
317 The @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or
318 replaces an existing multiple response set. The @subcmd{NAME},
319 @subcmd{VARIABLES}, and
320 @subcmd{VALUE} specifications are required. The others are optional:
324 @var{NAME} specifies the name used in syntax for the new multiple dichotomy
325 set. The name must begin with @samp{$}; it must otherwise follow the
326 rules for identifiers (@pxref{Tokens}).
329 @subcmd{VARIABLES} specifies the variables that belong to the set. At least
330 two variables must be specified. The variables must be all string or
334 @subcmd{VALUE} specifies the counted value. If the variables are numeric, the
335 value must be an integer. If the variables are strings, then the
336 value must be a string that is no longer than the shortest of the
337 variables in the set (ignoring trailing spaces).
340 @subcmd{CATEGORYLABELS} optionally specifies the source of the labels for each
345 @subcmd{VARLABELS}, the default, uses variable labels or, for variables without
346 variable labels, variable names. @pspp{} warns if two variables have the
347 same variable label, since these categories cannot be distinguished in
351 @subcmd{COUNTEDVALUES} instead uses each variable's value label for the counted
352 value. @pspp{} warns if two variables have the same value label for the
353 counted value or if one of the variables lacks a value label, since
354 such categories cannot be distinguished in output.
358 @subcmd{LABEL} optionally specifies a label for the multiple response set. If
359 neither @subcmd{LABEL} nor @subcmd{LABELSOURCE=VARLABEL} is specified, the set is
363 @subcmd{LABELSOURCE=VARLABEL} draws the multiple response set's label from the
364 first variable label among the variables in the set; if none of the
365 variables has a label, the name of the first variable is used.
366 @subcmd{LABELSOURCE=VARLABEL} must be used with @subcmd{CATEGORYLABELS=COUNTEDVALUES}.
367 It is mutually exclusive with @subcmd{LABEL}.
370 The @subcmd{MCGROUP} subcommand creates a new multiple category set or
371 replaces an existing multiple response set. The @subcmd{NAME} and @subcmd{VARIABLES}
372 specifications are required, and @subcmd{LABEL} is optional. Their meanings
373 are as described above in @subcmd{MDGROUP}. @pspp{} warns if two variables in the
374 set have different value labels for a single value, since each of the
375 variables in the set should have the same possible categories.
377 The @subcmd{DELETE} subcommand deletes multiple response groups. A list of
378 groups may be named within a set of required square brackets, or ALL
379 may be used to delete all groups.
381 The @subcmd{DISPLAY} subcommand displays information about defined multiple
382 response sets. Its syntax is the same as the @subcmd{DELETE} subcommand.
384 Multiple response sets are saved to and read from system files by,
385 e.g., the @cmd{SAVE} and @cmd{GET} command. Otherwise, multiple
386 response sets are currently used only by third party software.
393 NUMERIC /@var{var_list} [(@var{fmt_spec})].
396 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
397 setting their output formats.
399 Specify a slash (@samp{/}), followed by the names of the new numeric
400 variables. If you wish to set their output formats, follow their names
401 by an output format specification in parentheses (@pxref{Input and Output
402 Formats}); otherwise, the default is F8.2.
404 Variables created with @cmd{NUMERIC} are initialized to the
405 system-missing value.
408 @section PRINT FORMATS
409 @vindex PRINT FORMATS
412 PRINT FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
415 @cmd{PRINT FORMATS} sets the print formats for the specified
416 variables to the specified format specification.
418 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
419 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
421 @node RENAME VARIABLES
422 @section RENAME VARIABLES
423 @vindex RENAME VARIABLES
426 RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
429 @cmd{RENAME VARIABLES} changes the names of variables in the active
430 dataset. Specify lists of the old variable names and new
431 variable names, separated by an equals sign (@samp{=}), within
432 parentheses. There must be the same number of old and new variable
433 names. Each old variable is renamed to the corresponding new variable
434 name. Multiple parenthesized groups of variables may be specified.
436 @cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
439 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
443 @section VALUE LABELS
448 /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
451 @cmd{VALUE LABELS} allows values of numeric and short string
452 variables to be associated with labels. In this way, a short value can
453 stand for a long value.
455 To set up value labels for a set of variables, specify the
456 variable names after a slash (@samp{/}), followed by a list of values
457 and their associated labels, separated by spaces.
459 Value labels in output are normally broken into lines automatically.
460 Put @samp{\n} in a label string to force a line break at that point.
461 The label may still be broken into lines at additional points.
463 Before @cmd{VALUE LABELS} is executed, any existing value labels
464 are cleared from the variables specified. Use @cmd{ADD VALUE LABELS}
465 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
473 STRING /@var{var_list} (@var{fmt_spec}).
476 @cmd{STRING} creates new string variables for use in
479 Specify a slash (@samp{/}), followed by the names of the string
480 variables to create and the desired output format specification in
481 parentheses (@pxref{Input and Output Formats}). Variable widths are
482 implicitly derived from the specified output formats.
484 Created variables are initialized to spaces.
487 @node VARIABLE ATTRIBUTE
488 @section VARIABLE ATTRIBUTE
489 @vindex VARIABLE ATTRIBUTE
493 VARIABLES=@var{var_list}
494 ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
495 ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
496 DELETE=@var{name} [@var{name}]@dots{}
497 DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
500 @cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
501 attributes associated with variables in the active dataset. Custom
502 variable attributes are not interpreted by @pspp{}, but they are saved as
503 part of system files and may be used by other software that reads
506 The required @subcmd{VARIABLES} subcommand must come first. Specify the
507 variables to which the following @subcmd{ATTRIBUTE} or @subcmd{DELETE} subcommand
510 Use the @subcmd{ATTRIBUTE} subcommand to add or modify custom variable
511 attributes. Specify the name of the attribute as an identifier
512 (@pxref{Tokens}), followed by the desired value, in parentheses, as a
513 quoted string. The specified attributes are then added or modified in
514 the variables specified on @subcmd{VARIABLES}. Attribute names that begin with
515 @code{$} are reserved for @pspp{}'s internal use, and attribute names
516 that begin with @code{@@} or @code{$@@} are not displayed by most @pspp{}
517 commands that display other attributes. Other attribute names are not
520 Attributes may also be organized into arrays. To assign to an array
521 element, add an integer array index enclosed in square brackets
522 (@code{[} and @code{]}) between the attribute name and value. Array
523 indexes start at 1, not 0. An attribute array that has a single
524 element (number 1) is not distinguished from a non-array attribute.
526 Use the @subcmd{DELETE} subcommand to delete an attribute from the variable
527 specified on @subcmd{VARIABLES}. Specify an attribute name by itself to delete
528 an entire attribute, including all array elements for attribute
529 arrays. Specify an attribute name followed by an array index in
530 square brackets to delete a single element of an attribute array. In
531 the latter case, all the array elements numbered higher than the
532 deleted element are shifted down, filling the vacated position.
534 To associate custom attributes with the entire active dataset, instead of
535 with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
537 @cmd{VARIABLE ATTRIBUTE} takes effect immediately. It is not affected
538 by conditional and looping structures such as @cmd{DO IF} or
541 @node VARIABLE LABELS
542 @section VARIABLE LABELS
543 @vindex VARIABLE LABELS
547 @var{var_list} '@var{var_label}'
548 [ /@var{var_list} '@var{var_label}']
552 [ /@var{var_list} '@var{var_label}']
555 @cmd{VARIABLE LABELS} associates explanatory names
556 with variables. This name, called a @dfn{variable label}, is displayed by
557 statistical procedures.
559 To assign a variable label to a group of variables, specify a
560 list of variable names and the variable label as a string.
561 To assign different labels to different variables in the same command,
562 precede the subsequent variable list with a slash (@samp{/}).
565 @node VARIABLE ALIGNMENT
566 @section VARIABLE ALIGNMENT
567 @vindex VARIABLE ALIGNMENT
571 @var{var_list} ( LEFT | RIGHT | CENTER )
572 [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
576 [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
579 @cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
580 purposes. This only has effect for third party software. It does not affect
581 the display of variables in the @pspp{} output.
587 @section VARIABLE WIDTH
588 @vindex VARIABLE WIDTH
591 @var{var_list} (width)
592 [ /@var{var_list} (width) ]
596 [ /@var{var_list} (width) ]
599 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
600 purposes. This only affects third party software. It does not affect
601 the display of variables in the @pspp{} output.
605 @section VARIABLE LEVEL
606 @vindex VARIABLE LEVEL
609 @var{var_list} ( SCALE | NOMINAL | ORDINAL )
610 [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
614 [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
617 @cmd{VARIABLE LEVEL} sets the measurement level of variables.
618 Currently, this has no effect except for certain third party software.
626 Two possible syntaxes:
627 VECTOR @var{vec_name}=@var{var_list}.
628 VECTOR @var{vec_name_list}(@var{count} [@var{format}]).
631 @cmd{VECTOR} allows a group of variables to be accessed as if they
632 were consecutive members of an array with a vector(index) notation.
634 To make a vector out of a set of existing variables, specify a name
635 for the vector followed by an equals sign (@samp{=}) and the variables
636 to put in the vector. All the variables in the vector must be the same
637 type. String variables in a vector must all have the same width.
639 To make a vector and create variables at the same time, specify one or
640 more vector names followed by a count in parentheses. This will cause
641 variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
642 to be created as numeric variables. By default, the new variables
643 have print and write format F8.2, but an alternate format may be
644 specified inside the parentheses before or after the count and
645 separated from it by white space or a comma. Variable names including
646 numeric suffixes may not exceed 64 characters in length, and none of
647 the variables may exist prior to @cmd{VECTOR}.
649 Vectors created with @cmd{VECTOR} disappear after any procedure or
650 procedure-like command is executed. The variables contained in the
651 vectors remain, unless they are scratch variables (@pxref{Scratch
654 Variables within a vector may be referenced in expressions using
655 @code{vector(index)} syntax.
658 @section WRITE FORMATS
659 @vindex WRITE FORMATS
662 WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
665 @cmd{WRITE FORMATS} sets the write formats for the specified variables
666 to the specified format specification. Its syntax is identical to
667 that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
668 write formats, not print formats.