doc/variables.texi

   1 @c PSPP - a program for statistical analysis.
   2 @c Copyright (C) 2017 Free Software Foundation, Inc.
   3 @c Permission is granted to copy, distribute and/or modify this document
   4 @c under the terms of the GNU Free Documentation License, Version 1.3
   5 @c or any later version published by the Free Software Foundation;
   6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
   7 @c A copy of the license is included in the section entitled "GNU
   8 @c Free Documentation License".
   9 @c
  10 @node Variable Attributes
  11 @chapter Manipulating variables
  12
  13 The variables in the active dataset dictionary are important.  There are
  14 several utility functions for examining and adjusting them.
  15
  16 @menu
  17 * ADD VALUE LABELS::            Add value labels to variables.
  18 * DELETE VARIABLES::            Delete variables.
  19 * DISPLAY::                     Display information about the active dataset.
  20 * FORMATS::                     Set print and write formats.
  21 * LEAVE::                       Don't clear variables between cases.
  22 * MISSING VALUES::              Set missing values for variables.
  23 * MODIFY VARS::                 Rename, reorder, and drop variables.
  24 * MRSETS::                      Add, modify, and list multiple response sets.
  25 * NUMERIC::                     Create new numeric variables.
  26 * PRINT FORMATS::               Set variable print formats.
  27 * RENAME VARIABLES::            Rename variables.
  28 * SORT VARIABLES::              Reorder variables.
  29 * VALUE LABELS::                Set value labels for variables.
  30 * STRING::                      Create new string variables.
  31 * VARIABLE ATTRIBUTE::          Set custom attributes on variables.
  32 * VARIABLE LABELS::             Set variable labels for variables.
  33 * VARIABLE ALIGNMENT::          Set the alignment for display.
  34 * VARIABLE WIDTH::              Set the display width.
  35 * VARIABLE LEVEL::              Set the measurement level.
  36 * VARIABLE ROLE::               Set the role that a variable fills in analysis.
  37 * VECTOR::                      Declare an array of variables.
  38 * WRITE FORMATS::               Set variable write formats.
  39 @end menu
  40
  41 @node ADD VALUE LABELS
  42 @section ADD VALUE LABELS
  43 @vindex ADD VALUE LABELS
  44
  45 @display
  46 ADD VALUE LABELS
  47         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
  48 @end display
  49
  50 @cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
  51 LABELS} (@pxref{VALUE LABELS}), but it does not clear value
  52 labels from the variables before adding the ones specified.
  53
  54 @node DELETE VARIABLES
  55 @section DELETE VARIABLES
  56 @vindex DELETE VARIABLES
  57
  58 @display
  59 DELETE VARIABLES @var{var_list}.
  60 @end display
  61
  62 @cmd{DELETE VARIABLES} deletes the specified variables from the
  63 dictionary.  It may not be used to delete all variables from the
  64 dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
  65
  66 @cmd{DELETE VARIABLES} should not be used after defining transformations
  67 but before executing a procedure.  If it is used in such a context, it
  68 causes the data to be read.  If it is used while @cmd{TEMPORARY} is in
  69 effect, it causes the temporary transformations to become permanent.
  70
  71 @node DISPLAY
  72 @section DISPLAY
  73 @vindex DISPLAY
  74
  75 @display
  76 DISPLAY [SORTED] NAMES [[/VARIABLES=]@var{var_list}].
  77 DISPLAY [SORTED] INDEX [[/VARIABLES=]@var{var_list}].
  78 DISPLAY [SORTED] LABELS [[/VARIABLES=]@var{var_list}].
  79 DISPLAY [SORTED] VARIABLES [[/VARIABLES=]@var{var_list}].
  80 DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]@var{var_list}].
  81 DISPLAY [SORTED] SCRATCH [[/VARIABLES=]@var{var_list}].
  82 DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]@var{var_list}].
  83 DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]@var{var_list}].
  84 DISPLAY [SORTED] VECTORS.
  85 @end display
  86
  87 @cmd{DISPLAY} displays information about the active dataset.  A variety
  88 of different forms of information can be requested.
  89
  90 The following keywords primarily cause information about variables to
  91 be displayed.  With these keywords, by default information is
  92 displayed about all variable in the active dataset, in the order that
  93 variables occur in the active dataset dictionary.  The @subcmd{SORTED} keyword
  94 causes output to be sorted alphabetically by variable name.  The
  95 @subcmd{VARIABLES} subcommand limits output to the specified variables.
  96
  97 @table @asis
  98 @item NAMES
  99 The variables' names are displayed.
 100
 101 @item INDEX
 102 The variables' names are displayed along with a value describing their
 103 position within the active dataset dictionary.
 104
 105 @item LABELS
 106 Variable names, positions, and variable labels are displayed.
 107
 108 @item VARIABLES
 109 Variable names, positions, print and write formats, and missing values
 110 are displayed.
 111
 112 @item DICTIONARY
 113 Variable names, positions, print and write formats, missing values,
 114 variable labels, and value labels are displayed.
 115
 116 @item SCRATCH
 117 Variable names are displayed, for scratch variables only (@pxref{Scratch
 118 Variables}).
 119
 120 @item ATTRIBUTES
 121 @itemx @@ATTRIBUTES
 122 Datafile and variable attributes are displayed.
 123 The first form of the command omits those attributes
 124 whose names begin with @code{@@} or @code{$@@}.
 125 In the second for, all datafile and variable attributes are displayed.
 126 @end table
 127
 128 With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
 129 declared vectors.  If the @subcmd{SORTED} keyword is given, the vectors are
 130 listed in alphabetical order; otherwise, they are listed in textual
 131 order of definition within the @pspp{} syntax file.
 132
 133 For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
 134 FILE LABEL}.
 135
 136 @node FORMATS
 137 @section FORMATS
 138 @vindex FORMATS
 139
 140 @display
 141 FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
 142 @end display
 143
 144 @cmd{FORMATS} set both print and write formats for the specified
 145 variables to the specified format specification.
 146 @xref{Input and Output Formats}.
 147
 148 Specify a list of variables followed by a format specification in
 149 parentheses.  The print and write formats of the specified variables
 150 will be changed.  All of the variables listed together must have
 151 the same type and, for string variables, the same width.
 152
 153 Additional lists of variables and formats may be included following
 154 the first one.
 155
 156 @cmd{FORMATS} takes effect immediately.  It is not affected by
 157 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
 158
 159 @node LEAVE
 160 @section LEAVE
 161 @vindex LEAVE
 162
 163 @display
 164 LEAVE @var{var_list}.
 165 @end display
 166
 167 @cmd{LEAVE} prevents the specified variables from being
 168 reinitialized whenever a new case is processed.
 169
 170 Normally, when a data file is processed, every variable in the active
 171 dataset is initialized to the system-missing value or spaces at the
 172 beginning of processing for each case.  When a variable has been
 173 specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
 174 initialized to 0 (not system-missing) or spaces for the first case.
 175 After that, it retains its value between cases.
 176
 177 This becomes useful for counters.  For instance, in the example below
 178 the variable @code{SUM} maintains a running total of the values in the @code{ITEM}
 179 variable.
 180
 181 @example
 182 DATA LIST /ITEM 1-3.
 183 COMPUTE SUM=SUM+ITEM.
 184 PRINT /ITEM SUM.
 185 LEAVE SUM
 186 BEGIN DATA.
 187 123
 188 404
 189 555
 190 999
 191 END DATA.
 192 @end example
 193
 194 @noindent Partial output from this example:
 195
 196 @example
 197 123   123.00
 198 404   527.00
 199 555  1082.00
 200 999  2081.00
 201 @end example
 202
 203 It is best to use @cmd{LEAVE} command immediately before invoking a
 204 procedure command, because the left status of variables is reset by
 205 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
 206 Left status is also reset by all procedure invocations.
 207
 208 @node MISSING VALUES
 209 @section MISSING VALUES
 210 @vindex MISSING VALUES
 211
 212 @display
 213 MISSING VALUES @var{var_list} (@var{missing_values}).
 214
 215 where @var{missing_values} takes one of the following forms:
 216         @var{num1}
 217         @var{num1}, @var{num2}
 218         @var{num1}, @var{num2}, @var{num3}
 219         @var{num1} THRU @var{num2}
 220         @var{num1} THRU @var{num2}, @var{num3}
 221         @var{string1}
 222         @var{string1}, @var{string2}
 223         @var{string1}, @var{string2}, @var{string3}
 224 As part of a range, @subcmd{LO} or @subcmd{LOWEST} may take the place of @var{num1};
 225 @subcmd{HI} or @subcmd{HIGHEST} may take the place of @var{num2}.
 226 @end display
 227
 228 @cmd{MISSING VALUES} sets user-missing values for numeric and string
 229 variables.  Long string variables may have missing values, but
 230 characters after the first 8 bytes of the missing value must be
 231 spaces.
 232
 233 Specify a list of variables, followed by a list of their user-missing
 234 values in parentheses.  Up to three discrete values may be given, or,
 235 for numeric variables only, a range of values optionally accompanied by
 236 a single discrete value.  Ranges may be open-ended on one end, indicated
 237 through the use of the
 238 keyword @subcmd{LO} or @subcmd{LOWEST} or @subcmd{HI} or @subcmd{HIGHEST}.
 239
 240 The @cmd{MISSING VALUES} command takes effect immediately.  It is not
 241 affected by conditional and looping constructs such as @cmd{DO IF} or
 242 @cmd{LOOP}.
 243
 244 @node MODIFY VARS
 245 @section MODIFY VARS
 246 @vindex MODIFY VARS
 247
 248 @display
 249 MODIFY VARS
 250         /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (@var{var_list})@dots{}
 251         /RENAME=(@var{old_names}=@var{new_names})@dots{}
 252         /@{DROP,KEEP@}=@var{var_list}
 253         /MAP
 254 @end display
 255
 256 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
 257 active dataset.
 258
 259 At least one subcommand must be specified, and no subcommand may be
 260 specified more than once.  @subcmd{DROP} and @subcmd{KEEP} may not both
 261 be specified.
 262
 263 The @subcmd{REORDER} subcommand changes the order of variables in the active
 264 dataset.  Specify one or more lists of variable names in parentheses.  By
 265 default, each list of variables is rearranged into the specified order.
 266 To put the variables into the reverse of the specified order, put
 267 keyword @subcmd{BACKWARD} before the parentheses.  To put them into alphabetical
 268 order in the dictionary, specify keyword @subcmd{ALPHA} before the parentheses.
 269 @subcmd{BACKWARD} and @subcmd{ALPHA} may also be combined.
 270
 271 To rename variables in the active dataset, specify @subcmd{RENAME}, an equals sign
 272 (@samp{=}), and lists of the old variable names and new variable names
 273 separated by another equals sign within parentheses.  There must be the
 274 same number of old and new variable names.  Each old variable is renamed to
 275 the corresponding new variable name.  Multiple parenthesized groups of
 276 variables may be specified.
 277
 278 The @subcmd{DROP} subcommand deletes a specified list of variables from the
 279 active dataset.
 280
 281 The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
 282 dataset.  Any unlisted variables are deleted from the active dataset.
 283
 284 @subcmd{MAP} is currently ignored.
 285
 286 If either @subcmd{DROP} or @subcmd{KEEP} is specified, the data is read;
 287 otherwise it is not.
 288
 289 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
 290 (@pxref{TEMPORARY}).
 291
 292 @node MRSETS
 293 @section MRSETS
 294 @vindex MRSETS
 295
 296 @display
 297 MRSETS
 298     /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
 299      [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
 300      [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
 301
 302     /MCGROUP NAME=@var{name} VARIABLES=@var{var_list} [LABEL='@var{label}']
 303
 304     /DELETE NAME=@{[@var{names}],ALL@}
 305
 306     /DISPLAY NAME=@{[@var{names}],ALL@}
 307 @end display
 308
 309 @cmd{MRSETS} creates, modifies, deletes, and displays multiple
 310 response sets.  A multiple response set is a set of variables that
 311 represent multiple responses to a single survey question in one of the
 312 two following ways:
 313
 314 @itemize @bullet
 315 @item
 316 A @dfn{multiple dichotomy set} is analogous to a survey question with
 317 a set of checkboxes.  Each variable in the set is treated in a Boolean
 318 fashion: one value (the "counted value") means that the box was
 319 checked, and any other value means that it was not.
 320
 321 @item
 322 A @dfn{multiple category set} represents a survey question where the
 323 respondent is instructed to list up to @var{n} choices.  Each variable
 324 represents one of the responses.
 325 @end itemize
 326
 327 Any number of subcommands may be specified in any order.
 328
 329 The @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or
 330 replaces an existing multiple response set.  The @subcmd{NAME},
 331 @subcmd{VARIABLES}, and
 332 @subcmd{VALUE} specifications are required.  The others are optional:
 333
 334 @itemize @bullet
 335 @item
 336 @var{NAME} specifies the name used in syntax for the new multiple dichotomy
 337 set.  The name must begin with @samp{$}; it must otherwise follow the
 338 rules for identifiers (@pxref{Tokens}).
 339
 340 @item
 341 @subcmd{VARIABLES} specifies the variables that belong to the set.  At least
 342 two variables must be specified.  The variables must be all string or
 343 all numeric.
 344
 345 @item
 346 @subcmd{VALUE} specifies the counted value.  If the variables are numeric, the
 347 value must be an integer.  If the variables are strings, then the
 348 value must be a string that is no longer than the shortest of the
 349 variables in the set (ignoring trailing spaces).
 350
 351 @item
 352 @subcmd{CATEGORYLABELS} optionally specifies the source of the labels for each
 353 category in the set:
 354
 355 @itemize @minus
 356 @item
 357 @subcmd{VARLABELS}, the default, uses variable labels or, for variables without
 358 variable labels, variable names.  @pspp{} warns if two variables have the
 359 same variable label, since these categories cannot be distinguished in
 360 output.
 361
 362 @item
 363 @subcmd{COUNTEDVALUES} instead uses each variable's value label for the counted
 364 value.  @pspp{} warns if two variables have the same value label for the
 365 counted value or if one of the variables lacks a value label, since
 366 such categories cannot be distinguished in output.
 367 @end itemize
 368
 369 @item
 370 @subcmd{LABEL} optionally specifies a label for the multiple response set.  If
 371 neither @subcmd{LABEL} nor @subcmd{LABELSOURCE=VARLABEL} is specified, the set is
 372 unlabeled.
 373
 374 @item
 375 @subcmd{LABELSOURCE=VARLABEL} draws the multiple response set's label from the
 376 first variable label among the variables in the set; if none of the
 377 variables has a label, the name of the first variable is used.
 378 @subcmd{LABELSOURCE=VARLABEL} must be used with @subcmd{CATEGORYLABELS=COUNTEDVALUES}.
 379 It is mutually exclusive with @subcmd{LABEL}.
 380 @end itemize
 381
 382 The @subcmd{MCGROUP} subcommand creates a new multiple category set or
 383 replaces an existing multiple response set.  The @subcmd{NAME} and @subcmd{VARIABLES}
 384 specifications are required, and @subcmd{LABEL} is optional.  Their meanings
 385 are as described above in @subcmd{MDGROUP}.  @pspp{} warns if two variables in the
 386 set have different value labels for a single value, since each of the
 387 variables in the set should have the same possible categories.
 388
 389 The @subcmd{DELETE} subcommand deletes multiple response groups.  A list of
 390 groups may be named within a set of required square brackets, or ALL
 391 may be used to delete all groups.
 392
 393 The @subcmd{DISPLAY} subcommand displays information about defined multiple
 394 response sets.  Its syntax is the same as the @subcmd{DELETE} subcommand.
 395
 396 Multiple response sets are saved to and read from system files by,
 397 e.g., the @cmd{SAVE} and @cmd{GET} command.  Otherwise, multiple
 398 response sets are currently used only by third party software.
 399
 400 @node NUMERIC
 401 @section NUMERIC
 402 @vindex NUMERIC
 403
 404 @display
 405 NUMERIC /@var{var_list} [(@var{fmt_spec})].
 406 @end display
 407
 408 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
 409 setting their output formats.
 410
 411 Specify a slash (@samp{/}), followed by the names of the new numeric
 412 variables.  If you wish to set their output formats, follow their names
 413 by an output format specification in parentheses (@pxref{Input and Output
 414 Formats}); otherwise, the default is F8.2.
 415
 416 Variables created with @cmd{NUMERIC} are initialized to the
 417 system-missing value.
 418
 419 @node PRINT FORMATS
 420 @section PRINT FORMATS
 421 @vindex PRINT FORMATS
 422
 423 @display
 424 PRINT FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
 425 @end display
 426
 427 @cmd{PRINT FORMATS} sets the print formats for the specified
 428 variables to the specified format specification.
 429
 430 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
 431 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
 432
 433 @node RENAME VARIABLES
 434 @section RENAME VARIABLES
 435 @vindex RENAME VARIABLES
 436
 437 @display
 438 RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
 439 @end display
 440
 441 @cmd{RENAME VARIABLES} changes the names of variables in the active
 442 dataset.  Specify lists of the old variable names and new
 443 variable names, separated by an equals sign (@samp{=}), within
 444 parentheses.  There must be the same number of old and new variable
 445 names.  Each old variable is renamed to the corresponding new variable
 446 name.  Multiple parenthesized groups of variables may be specified.
 447 When the old and new variable names contain only a single variable name,
 448 the parentheses are optional.
 449
 450 @cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
 451 to be read.
 452
 453 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
 454 (@pxref{TEMPORARY}).
 455
 456 @node SORT VARIABLES
 457 @section SORT VARIABLES
 458 @vindex SORT VARIABLES
 459
 460 @display
 461 SORT VARIABLES [BY]
 462     (NAME | TYPE | FORMAT | LABEL | VALUES | MISSING | MEASURE
 463      | ROLE | COLUMNS | ALIGNMENT | ATTRIBUTE @var{name})
 464     [(D)].
 465 @end display
 466
 467 @cmd{SORT VARIABLES} reorders the variables in the active dataset.
 468 The main specification is one of the following identifiers, which
 469 determines how the variables are sorted:
 470
 471 @table @asis
 472 @item NAME
 473 Sorts the variables according to their names, in a case-insensitive
 474 fashion.  However, when variable names differ only in a number at the
 475 end, they are sorted numerically.  For example, @code{VAR5} is sorted
 476 before @code{VAR400} even though @samp{4} precedes @samp{5}.
 477
 478 @item TYPE
 479 Sorts numeric variables before string variables, and shorter string
 480 variables before longer ones.
 481
 482 @item FORMAT
 483 Groups variables by print format; within a format, sorts narrower
 484 formats before wider ones; with the same format and width, sorts fewer
 485 decimal places before more decimal places.
 486 @xref{FORMATS}.
 487
 488 @item LABEL
 489 Sorts variables without a variable label before those with one.
 490 @xref{VARIABLE LABELS}.
 491
 492 @item VALUES
 493 Sorts variables without value labels before those with some.
 494 @xref{VALUE LABELS}.
 495
 496 @item MISSING
 497 Sorts variables without missing values before those with some.
 498 @xref{MISSING VALUES}.
 499
 500 @item MEASURE
 501 Sorts nominal variables first, followed by ordinal variables, followed
 502 by scale variables.  @xref{VARIABLE LEVEL}.
 503
 504 @item ROLE
 505 Groups variables according to their role.  @xref{VARIABLE ROLE}.
 506
 507 @item COLUMNS
 508 Sorts variables in ascending display width.  @xref{VARIABLE WIDTH}.
 509
 510 @item ALIGNMENT
 511 Sorts variables according to their alignment, first left-aligned, then
 512 right-aligned, then centered.  @xref{VARIABLE ALIGNMENT}.
 513
 514 @item ATTRIBUTE @var{name}
 515 Sorts variables according to the first value of their @var{name}
 516 attribute.  Variables without attribute are sorted first.
 517 @xref{VARIABLE ATTRIBUTE}.
 518 @end table
 519
 520 Only one sort criterion can be specified.  The sort is ``stable,'' so
 521 to sort on multiple criteria one may perform multiple sorts.  For
 522 example, the following will sort primarily based on alignment, with
 523 variables that have the same alignment ordered based on display width:
 524
 525 @example
 526 SORT VARIABLES BY COLUMNS.
 527 SORT VARIABLES BY ALIGNMENT.
 528 @end example
 529
 530 Specify @code{(D)} to reverse the sort order.
 531
 532 @node VALUE LABELS
 533 @section VALUE LABELS
 534 @vindex VALUE LABELS
 535
 536 @display
 537 VALUE LABELS
 538         /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
 539 @end display
 540
 541 @cmd{VALUE LABELS} allows values of
 542 variables to be associated with labels.  In this way, a short value can
 543 stand for a longer, more descriptive label.
 544
 545 Both numeric and string variables can be given labels.  For string
 546 variables, the values are case-sensitive, so that, for example, a
 547 capitalized value and its lowercase variant would have to be labeled
 548 separately if both are present in the data.
 549
 550 To set up value labels for one or more variables, specify the
 551 variable names after a slash (@samp{/}), followed by a list of values
 552 and their associated labels, separated by spaces.
 553
 554 Value labels in output are normally broken into lines automatically.
 555 Put @samp{\n} in a label string to force a line break at that point.
 556 The label may still be broken into lines at additional points.
 557
 558 Before @cmd{VALUE LABELS} is executed, any existing value labels
 559 are cleared from the variables specified.  Use @cmd{ADD VALUE LABELS}
 560 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
 561 already present.
 562
 563 @node STRING
 564 @section STRING
 565 @vindex STRING
 566
 567 @display
 568 STRING @var{var_list} (@var{fmt_spec}) [/@var{var_list} (@var{fmt_spec})] [@dots{}].
 569 @end display
 570
 571 @cmd{STRING} creates new string variables for use in
 572 transformations.
 573
 574 Specify a list of names for the variable you want to create,
 575 followed by the desired output format specification in
 576 parentheses (@pxref{Input and Output Formats}).
 577 Variable widths are
 578 implicitly derived from the specified output formats.
 579 The created variables will be initialized to spaces.
 580
 581 If you want to create several variables with  distinct
 582 output formats, you can either use two or more separate @cmd{STRING} commands,
 583 or you can specify further variable list and format specification pairs, each separated
 584 from the previous by a slash (@samp{/}).
 585
 586 The following example is one way to create three string variables; Two of the
 587 variables have format A24 and the other A80:
 588 @example
 589 STRING firstname lastname (A24) / address (A80).
 590 @end example
 591
 592 @noindent Here is another way to achieve the same result:
 593 @example
 594 STRING firstname lastname (A24).
 595 STRING address (A80).
 596 @end example
 597
 598 @noindent @dots{} and here is yet another way:
 599
 600 @example
 601 STRING firstname (A24).
 602 STRING lastname (A24).
 603 STRING address (A80).
 604 @end example
 605
 606
 607
 608
 609 @node VARIABLE ATTRIBUTE
 610 @section VARIABLE ATTRIBUTE
 611 @vindex VARIABLE ATTRIBUTE
 612
 613 @display
 614 VARIABLE ATTRIBUTE
 615          VARIABLES=@var{var_list}
 616          ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
 617          ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
 618          DELETE=@var{name} [@var{name}]@dots{}
 619          DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
 620 @end display
 621
 622 @cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
 623 attributes associated with variables in the active dataset.  Custom
 624 variable attributes are not interpreted by @pspp{}, but they are saved as
 625 part of system files and may be used by other software that reads
 626 them.
 627
 628 The required @subcmd{VARIABLES} subcommand must come first.  Specify the
 629 variables to which the following @subcmd{ATTRIBUTE} or @subcmd{DELETE} subcommand
 630 should apply.
 631
 632 Use the @subcmd{ATTRIBUTE} subcommand to add or modify custom variable
 633 attributes.  Specify the name of the attribute as an identifier
 634 (@pxref{Tokens}), followed by the desired value, in parentheses, as a
 635 quoted string.  The specified attributes are then added or modified in
 636 the variables specified on @subcmd{VARIABLES}.  Attribute names that begin with
 637 @code{$} are reserved for @pspp{}'s internal use, and attribute names
 638 that begin with @code{@@} or @code{$@@} are not displayed by most @pspp{}
 639 commands that display other attributes.  Other attribute names are not
 640 treated specially.
 641
 642 Attributes may also be organized into arrays.  To assign to an array
 643 element, add an integer array index enclosed in square brackets
 644 (@code{[} and @code{]}) between the attribute name and value.  Array
 645 indexes start at 1, not 0.  An attribute array that has a single
 646 element (number 1) is not distinguished from a non-array attribute.
 647
 648 Use the @subcmd{DELETE} subcommand to delete an attribute from the variable
 649 specified on @subcmd{VARIABLES}.  Specify an attribute name by itself to delete
 650 an entire attribute, including all array elements for attribute
 651 arrays.  Specify an attribute name followed by an array index in
 652 square brackets to delete a single element of an attribute array.  In
 653 the latter case, all the array elements numbered higher than the
 654 deleted element are shifted down, filling the vacated position.
 655
 656 To associate custom attributes with the entire active dataset, instead of
 657 with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
 658
 659 @cmd{VARIABLE ATTRIBUTE} takes effect immediately.  It is not affected
 660 by conditional and looping structures such as @cmd{DO IF} or
 661 @cmd{LOOP}.
 662
 663 @node VARIABLE LABELS
 664 @section VARIABLE LABELS
 665 @vindex VARIABLE LABELS
 666
 667 @display
 668 VARIABLE LABELS
 669         @var{var_list} '@var{var_label}'
 670         [ /@var{var_list} '@var{var_label}']
 671         .
 672         .
 673         .
 674         [ /@var{var_list} '@var{var_label}']
 675 @end display
 676
 677 @cmd{VARIABLE LABELS} associates explanatory names
 678 with variables.  This name, called a @dfn{variable label}, is displayed by
 679 statistical procedures.
 680
 681 To assign a variable label to a group of variables, specify a
 682 list of variable names and the variable label as a string.
 683 To assign different labels to different variables in the same command,
 684 precede the subsequent variable list with a slash (@samp{/}).
 685
 686
 687 @node VARIABLE ALIGNMENT
 688 @section VARIABLE ALIGNMENT
 689 @vindex VARIABLE ALIGNMENT
 690
 691 @display
 692 VARIABLE ALIGNMENT
 693         @var{var_list} ( LEFT | RIGHT | CENTER )
 694         [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
 695         .
 696         .
 697         .
 698         [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
 699 @end display
 700
 701 @cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
 702 purposes.   This only has effect for third party software.  It does not affect
 703 the display of variables in the @pspp{} output.
 704
 705
 706
 707
 708 @node VARIABLE WIDTH
 709 @section VARIABLE WIDTH
 710 @vindex VARIABLE WIDTH
 711 @display
 712 VARIABLE WIDTH
 713         @var{var_list} (width)
 714         [ /@var{var_list} (width) ]
 715         .
 716         .
 717         .
 718         [ /@var{var_list} (width) ]
 719 @end display
 720
 721 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
 722 purposes.   This only affects third party software.  It does not affect
 723 the display of variables in the @pspp{} output.
 724
 725
 726 @node VARIABLE LEVEL
 727 @section VARIABLE LEVEL
 728 @vindex VARIABLE LEVEL
 729 @display
 730 VARIABLE LEVEL
 731         @var{var_list} ( SCALE | NOMINAL | ORDINAL )
 732         [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
 733         .
 734         .
 735         .
 736         [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
 737 @end display
 738
 739 @cmd{VARIABLE LEVEL} sets the measurement level of  variables.
 740 Currently, this has no effect except for certain third party software.
 741
 742
 743 @node VARIABLE ROLE
 744 @section VARIABLE ROLE
 745 @vindex VARIABLE ROLE
 746 @display
 747 VARIABLE ROLE
 748         /@var{role} @var{var_list}
 749         [/@var{role} @var{var_list}]@dots{}
 750 @end display
 751
 752 @cmd{VARIABLE ROLE} sets the intended role of a variable for use in
 753 dialog boxes in graphical user interfaces.  Each @var{role} specifies
 754 one of the following roles for the variables that follow it:
 755
 756 @table @code
 757 @item INPUT
 758 An input variable, such as an independent variable.
 759
 760 @item TARGET
 761 An output variable, such as an dependent variable.
 762
 763 @item BOTH
 764 A variable used for input and output.
 765
 766 @item NONE
 767 No role assigned.  (This is a variable's default role.)
 768
 769 @item PARTITION
 770 Used to break the data into groups for testing.
 771
 772 @item SPLIT
 773 No meaning except for certain third party software.  (This role's
 774 meaning is unrelated to @cmd{SPLIT FILE}.)
 775 @end table
 776
 777 The PSPPIRE GUI does not yet use variable roles as intended.
 778
 779 @node VECTOR
 780 @section VECTOR
 781 @vindex VECTOR
 782
 783 @display
 784 Two possible syntaxes:
 785         VECTOR @var{vec_name}=@var{var_list}.
 786         VECTOR @var{vec_name_list}(@var{count} [@var{format}]).
 787 @end display
 788
 789 @cmd{VECTOR} allows a group of variables to be accessed as if they
 790 were consecutive members of an array with a vector(index) notation.
 791
 792 To make a vector out of a set of existing variables, specify a name
 793 for the vector followed by an equals sign (@samp{=}) and the variables
 794 to put in the vector.  The variables must be all numeric or all
 795 string, and string variables must have the same width.
 796
 797 To make a vector and create variables at the same time, specify one or
 798 more vector names followed by a count in parentheses.  This will
 799 create variables named @code{@var{vec}1} through
 800 @code{@var{vec}@var{count}}.  By default, the new variables are
 801 numeric with format F8.2, but an alternate format may be specified
 802 inside the parentheses before or after the count and separated from it
 803 by white space or a comma.  With a string format such as A8, the
 804 variables will be string variables; with a numeric format, they will
 805 be numeric.  Variable names including the suffixes may not exceed 64
 806 characters in length, and none of the variables may exist prior to
 807 @cmd{VECTOR}.
 808
 809 Vectors created with @cmd{VECTOR} disappear after any procedure or
 810 procedure-like command is executed.  The variables contained in the
 811 vectors remain, unless they are scratch variables (@pxref{Scratch
 812 Variables}).
 813
 814 Variables within a vector may be referenced in expressions using
 815 @code{vector(index)} syntax.
 816
 817 @node WRITE FORMATS
 818 @section WRITE FORMATS
 819 @vindex WRITE FORMATS
 820
 821 @display
 822 WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
 823 @end display
 824
 825 @cmd{WRITE FORMATS} sets the write formats for the specified variables
 826 to the specified format specification.  Its syntax is identical to
 827 that of @cmd{FORMATS} (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
 828 write formats, not print formats.