doc/variables.texi

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