doc/variables.texi

   1 @node Variable Attributes
   2 @chapter Manipulating variables
   3
   4 The variables in the active file dictionary are important.  There are
   5 several utility functions for examining and adjusting them.
   6
   7 @menu
   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 * NUMERIC::                     Create new numeric variables.
  16 * PRINT FORMATS::               Set variable print formats.
  17 * RENAME VARIABLES::            Rename variables.
  18 * VALUE LABELS::                Set value labels for variables.
  19 * STRING::                      Create new string variables.
  20 * VARIABLE ATTRIBUTE::          Set custom attributes on variables.
  21 * VARIABLE LABELS::             Set variable labels for variables.
  22 * VARIABLE ALIGNMENT::          Set the alignment for display.
  23 * VARIABLE WIDTH::              Set the display width.
  24 * VARIABLE LEVEL::              Set the measurement level.
  25 * VECTOR::                      Declare an array of variables.
  26 * WRITE FORMATS::               Set variable write formats.
  27 @end menu
  28
  29 @node ADD VALUE LABELS
  30 @section ADD VALUE LABELS
  31 @vindex ADD VALUE LABELS
  32
  33 @display
  34 ADD VALUE LABELS
  35         /var_list value 'label' [value 'label']@dots{}
  36 @end display
  37
  38 @cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
  39 LABELS} (@pxref{VALUE LABELS}), but it does not clear value
  40 labels from the variables before adding the ones specified.
  41
  42 @node DELETE VARIABLES
  43 @section DELETE VARIABLES
  44 @vindex DELETE VARIABLES
  45
  46 @display
  47 DELETE VARIABLES var_list.
  48 @end display
  49
  50 @cmd{DELETE VARIABLES} deletes the specified variables from the
  51 dictionary.  It may not be used to delete all variables from the
  52 dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
  53
  54 @cmd{DELETE VARIABLES} should not used after defining transformations
  55 and before executing a procedure.  If it is used in such a context, it
  56 causes the data to be read.  If it is used while @cmd{TEMPORARY} is in
  57 effect, it causes the temporary transformations to become permanent.
  58
  59 @node DISPLAY
  60 @section DISPLAY
  61 @vindex DISPLAY
  62
  63 @display
  64 DISPLAY [SORTED] NAMES [[/VARIABLES=]var_list].
  65 DISPLAY [SORTED] INDEX [[/VARIABLES=]var_list].
  66 DISPLAY [SORTED] LABELS [[/VARIABLES=]var_list].
  67 DISPLAY [SORTED] VARIABLES [[/VARIABLES=]var_list].
  68 DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]var_list].
  69 DISPLAY [SORTED] SCRATCH [[/VARIABLES=]var_list].
  70 DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]var_list].
  71 DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]var_list].
  72 DISPLAY [SORTED] VECTORS.
  73 @end display
  74
  75 @cmd{DISPLAY} displays information about the active file.  A variety
  76 of different forms of information can be requested.
  77
  78 The following keywords primarily cause information about variables to
  79 be displayed.  With these keywords, by default information is
  80 displayed about all variable in the active file, in the order that
  81 variables occur in the active file dictionary.  The SORTED keyword
  82 causes output to be sorted alphabetically by variable name.  The
  83 VARIABLES subcommand limits output to the specified variables.
  84
  85 @table @asis
  86 @item NAMES
  87 The variables' names are displayed.
  88
  89 @item INDEX
  90 The variables' names are displayed along with a value describing their
  91 position within the active file dictionary.
  92
  93 @item LABELS
  94 Variable names, positions, and variable labels are displayed.
  95
  96 @item VARIABLES
  97 Variable names, positions, print and write formats, and missing values
  98 are displayed.
  99
 100 @item DICTIONARY
 101 Variable names, positions, print and write formats, missing values,
 102 variable labels, and value labels are displayed.
 103
 104 @item SCRATCH
 105 Variable names are displayed, for scratch variables only (@pxref{Scratch
 106 Variables}).
 107
 108 @item ATTRIBUTES
 109 Datafile and variable attributes are displayed, except that attributes
 110 whose names begin with @code{@@} or @code{$@@} are omitted.
 111
 112 @itemx @@ATTRIBUTES
 113 All datafile and variable attributes are displayed.
 114 @end table
 115
 116 With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
 117 declared vectors.  If the SORTED keyword is given, the vectors are
 118 listed in alphabetical order; otherwise, they are listed in textual
 119 order of definition within the PSPP syntax file.
 120
 121 For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
 122 FILE LABEL}.
 123
 124 @node FORMATS
 125 @section FORMATS
 126 @vindex FORMATS
 127
 128 @display
 129 FORMATS var_list (fmt_spec).
 130 @end display
 131
 132 @cmd{FORMATS} set both print and write formats for the specified
 133 numeric variables to the specified format specification.
 134 @xref{Input and Output Formats}.
 135
 136 Specify a list of variables followed by a format specification in
 137 parentheses.  The print and write formats of the specified variables
 138 will be changed.
 139
 140 Additional lists of variables and formats may be included if they are
 141 delimited by a slash (@samp{/}).
 142
 143 @cmd{FORMATS} takes effect immediately.  It is not affected by
 144 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
 145
 146 @node LEAVE
 147 @section LEAVE
 148 @vindex LEAVE
 149
 150 @display
 151 LEAVE var_list.
 152 @end display
 153
 154 @cmd{LEAVE} prevents the specified variables from being
 155 reinitialized whenever a new case is processed.
 156
 157 Normally, when a data file is processed, every variable in the active
 158 file is initialized to the system-missing value or spaces at the
 159 beginning of processing for each case.  When a variable has been
 160 specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
 161 initialized to 0 (not system-missing) or spaces for the first case.
 162 After that, it retains its value between cases.
 163
 164 This becomes useful for counters.  For instance, in the example below
 165 the variable SUM maintains a running total of the values in the ITEM
 166 variable.
 167
 168 @example
 169 DATA LIST /ITEM 1-3.
 170 COMPUTE SUM=SUM+ITEM.
 171 PRINT /ITEM SUM.
 172 LEAVE SUM
 173 BEGIN DATA.
 174 123
 175 404
 176 555
 177 999
 178 END DATA.
 179 @end example
 180
 181 @noindent Partial output from this example:
 182
 183 @example
 184 123   123.00
 185 404   527.00
 186 555  1082.00
 187 999  2081.00
 188 @end example
 189
 190 It is best to use @cmd{LEAVE} command immediately before invoking a
 191 procedure command, because the left status of variables is reset by
 192 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
 193 Left status is also reset by all procedure invocations.
 194
 195 @node MISSING VALUES
 196 @section MISSING VALUES
 197 @vindex MISSING VALUES
 198
 199 @display
 200 MISSING VALUES var_list (missing_values).
 201
 202 missing_values takes one of the following forms:
 203         num1
 204         num1, num2
 205         num1, num2, num3
 206         num1 THRU num2
 207         num1 THRU num2, num3
 208         string1
 209         string1, string2
 210         string1, string2, string3
 211 As part of a range, LO or LOWEST may take the place of num1;
 212 HI or HIGHEST may take the place of num2.
 213 @end display
 214
 215 @cmd{MISSING VALUES} sets user-missing values for numeric and
 216 short string variables.  Long string variables may not have missing
 217 values.
 218
 219 Specify a list of variables, followed by a list of their user-missing
 220 values in parentheses.  Up to three discrete values may be given, or,
 221 for numeric variables only, a range of values optionally accompanied by
 222 a single discrete value.  Ranges may be open-ended on one end, indicated
 223 through the use of the keyword LO or LOWEST or HI or HIGHEST.
 224
 225 The @cmd{MISSING VALUES} command takes effect immediately.  It is not
 226 affected by conditional and looping constructs such as @cmd{DO IF} or
 227 @cmd{LOOP}.
 228
 229 @node MODIFY VARS
 230 @section MODIFY VARS
 231 @vindex MODIFY VARS
 232
 233 @display
 234 MODIFY VARS
 235         /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
 236         /RENAME=(old_names=new_names)@dots{}
 237         /@{DROP,KEEP@}=var_list
 238         /MAP
 239 @end display
 240
 241 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
 242 active file.
 243
 244 At least one subcommand must be specified, and no subcommand may be
 245 specified more than once.  DROP and KEEP may not both be specified.
 246
 247 The REORDER subcommand changes the order of variables in the active
 248 file.  Specify one or more lists of variable names in parentheses.  By
 249 default, each list of variables is rearranged into the specified order.
 250 To put the variables into the reverse of the specified order, put
 251 keyword BACKWARD before the parentheses.  To put them into alphabetical
 252 order in the dictionary, specify keyword ALPHA before the parentheses.
 253 BACKWARD and ALPHA may also be combined.
 254
 255 To rename variables in the active file, specify RENAME, an equals sign
 256 (@samp{=}), and lists of the old variable names and new variable names
 257 separated by another equals sign within parentheses.  There must be the
 258 same number of old and new variable names.  Each old variable is renamed to
 259 the corresponding new variable name.  Multiple parenthesized groups of
 260 variables may be specified.
 261
 262 The DROP subcommand deletes a specified list of variables from the
 263 active file.
 264
 265 The KEEP subcommand keeps the specified list of variables in the active
 266 file.  Any unlisted variables are deleted from the active file.
 267
 268 MAP is currently ignored.
 269
 270 If either DROP or KEEP is specified, the data is read; otherwise it is
 271 not.
 272
 273 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
 274 (@pxref{TEMPORARY}).
 275
 276 @node NUMERIC
 277 @section NUMERIC
 278 @vindex NUMERIC
 279
 280 @display
 281 NUMERIC /var_list [(fmt_spec)].
 282 @end display
 283
 284 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
 285 setting their output formats.
 286
 287 Specify a slash (@samp{/}), followed by the names of the new numeric
 288 variables.  If you wish to set their output formats, follow their names
 289 by an output format specification in parentheses (@pxref{Input and Output
 290 Formats}); otherwise, the default is F8.2.
 291
 292 Variables created with @cmd{NUMERIC} are initialized to the
 293 system-missing value.
 294
 295 @node PRINT FORMATS
 296 @section PRINT FORMATS
 297 @vindex PRINT FORMATS
 298
 299 @display
 300 PRINT FORMATS var_list (fmt_spec).
 301 @end display
 302
 303 @cmd{PRINT FORMATS} sets the print formats for the specified
 304 numeric variables to the specified format specification.
 305
 306 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
 307 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
 308
 309 @node RENAME VARIABLES
 310 @section RENAME VARIABLES
 311 @vindex RENAME VARIABLES
 312
 313 @display
 314 RENAME VARIABLES (old_names=new_names)@dots{} .
 315 @end display
 316
 317 @cmd{RENAME VARIABLES} changes the names of variables in the active
 318 file.  Specify lists of the old variable names and new
 319 variable names, separated by an equals sign (@samp{=}), within
 320 parentheses.  There must be the same number of old and new variable
 321 names.  Each old variable is renamed to the corresponding new variable
 322 name.  Multiple parenthesized groups of variables may be specified.
 323
 324 @cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
 325 to be read.
 326
 327 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
 328 (@pxref{TEMPORARY}).
 329
 330 @node VALUE LABELS
 331 @section VALUE LABELS
 332 @vindex VALUE LABELS
 333
 334 @display
 335 VALUE LABELS
 336         /var_list value 'label' [value 'label']@dots{}
 337 @end display
 338
 339 @cmd{VALUE LABELS} allows values of numeric and short string
 340 variables to be associated with labels.  In this way, a short value can
 341 stand for a long value.
 342
 343 To set up value labels for a set of variables, specify the
 344 variable names after a slash (@samp{/}), followed by a list of values
 345 and their associated labels, separated by spaces.
 346
 347 Before @cmd{VALUE LABELS} is executed, any existing value labels
 348 are cleared from the variables specified.  Use @cmd{ADD VALUE LABELS}
 349 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
 350 already present.
 351
 352 @node STRING
 353 @section STRING
 354 @vindex STRING
 355
 356 @display
 357 STRING /var_list (fmt_spec).
 358 @end display
 359
 360 @cmd{STRING} creates new string variables for use in
 361 transformations.
 362
 363 Specify a slash (@samp{/}), followed by the names of the string
 364 variables to create and the desired output format specification in
 365 parentheses (@pxref{Input and Output Formats}).  Variable widths are
 366 implicitly derived from the specified output formats.
 367
 368 Created variables are initialized to spaces.
 369
 370
 371 @node VARIABLE ATTRIBUTE
 372 @section VARIABLE ATTRIBUTE
 373 @vindex VARIABLE ATTRIBUTE
 374
 375 @display
 376 VARIABLE ATTRIBUTE
 377          VARIABLES=var_list
 378          ATTRIBUTE=name('value') [name('value')]@dots{}
 379          ATTRIBUTE=name@b{[}index@b{]}('value') [name@b{[}index@b{]}('value')]@dots{}
 380          DELETE=name [name]@dots{}
 381          DELETE=name@b{[}index@b{]} [name@b{[}index@b{]}]@dots{}
 382 @end display
 383
 384 @cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
 385 attributes associated with variables in the active file.  Custom
 386 variable attributes are not interpreted by PSPP, but they are saved as
 387 part of system files and may be used by other software that reads
 388 them.
 389
 390 The required VARIABLES subcommand must come first.  Specify the
 391 variables to which the following ATTRIBUTE or DELETE subcommand
 392 should apply.
 393
 394 Use the ATTRIBUTE subcommand to add or modify custom variable
 395 attributes.  Specify the name of the attribute as an identifier
 396 (@pxref{Tokens}), followed by the desired value, in parentheses, as a
 397 quoted string.  The specified attributes are then added or modified in
 398 the variables specified on VARIABLES.  Attribute names that begin with
 399 @code{$} are reserved for PSPP's internal use, and attribute names
 400 that begin with @code{@@} or @code{$@@} are not displayed by most PSPP
 401 commands that display other attributes.  Other attribute names are not
 402 treated specially.
 403
 404 Attributes may also be organized into arrays.  To assign to an array
 405 element, add an integer array index enclosed in square brackets
 406 (@code{[} and @code{]}) between the attribute name and value.  Array
 407 indexes start at 1, not 0.  An attribute array that has a single
 408 element (number 1) is not distinguished from a non-array attribute.
 409
 410 Use the DELETE subcommand to delete an attribute from the variable
 411 specified on VARIABLES.  Specify an attribute name by itself to delete
 412 an entire attribute, including all array elements for attribute
 413 arrays.  Specify an attribute name followed by an array index in
 414 square brackets to delete a single element of an attribute array.  In
 415 the latter case, all the array elements numbered higher than the
 416 deleted element are shifted down, filling the vacated position.
 417
 418 To associate custom attributes with the entire active file, instead of
 419 with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
 420
 421 @cmd{VARIABLE ATTRIBUTE} takes effect immediately.  It is not affected
 422 by conditional and looping structures such as @cmd{DO IF} or
 423 @cmd{LOOP}.
 424
 425 @node VARIABLE LABELS
 426 @section VARIABLE LABELS
 427 @vindex VARIABLE LABELS
 428
 429 @display
 430 VARIABLE LABELS
 431         var_list 'var_label'
 432         [ /var_list 'var_label']
 433         .
 434         .
 435         .
 436         [ /var_list 'var_label']
 437 @end display
 438
 439 @cmd{VARIABLE LABELS} associates explanatory names
 440 with variables.  This name, called a @dfn{variable label}, is displayed by
 441 statistical procedures.
 442
 443 To assign a variable label to a group of variables, specify a
 444 list of variable names and the variable label as a string.
 445 To assign different labels to different variables in the same command,
 446 precede the subsequent variable list with a slash (@samp{/}).
 447
 448
 449 @node VARIABLE ALIGNMENT
 450 @comment  node-name,  next,  previous,  u
 451 @section VARIABLE ALIGNMENT
 452 @vindex VARIABLE ALIGNMENT
 453
 454 @display
 455 VARIABLE ALIGNMENT
 456         var_list ( LEFT | RIGHT | CENTER )
 457         [ /var_list ( LEFT | RIGHT | CENTER ) ]
 458         .
 459         .
 460         .
 461         [ /var_list ( LEFT | RIGHT | CENTER ) ]
 462 @end display
 463
 464 @cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
 465 purposes.   This only has effect for third party software.  It does not affect
 466 the display of variables in the PSPP output.
 467
 468
 469
 470
 471 @node VARIABLE WIDTH
 472 @comment  node-name,  next,  previous,  up
 473 @section VARIABLE WIDTH
 474 @vindex VARIABLE WIDTH
 475 @display
 476 VARIABLE WIDTH
 477         var_list (width)
 478         [ /var_list (width) ]
 479         .
 480         .
 481         .
 482         [ /var_list (width) ]
 483 @end display
 484
 485 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
 486 purposes.   This only affects third party software.  It does not affect
 487 the display of variables in the PSPP output.
 488
 489
 490 @node VARIABLE LEVEL
 491 @comment  node-name,  next,  previous,  up
 492 @section VARIABLE LEVEL
 493 @vindex VARIABLE LEVEL
 494 @display
 495 VARIABLE LEVEL
 496         var_list ( SCALE | NOMINAL | ORDINAL )
 497         [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
 498         .
 499         .
 500         .
 501         [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
 502 @end display
 503
 504 @cmd{VARIABLE LEVEL} sets the measurement level of  variables.
 505 Currently, this has no effect except for certain third party software.
 506
 507
 508 @node VECTOR
 509 @section VECTOR
 510 @vindex VECTOR
 511
 512 @display
 513 Two possible syntaxes:
 514         VECTOR vec_name=var_list.
 515         VECTOR vec_name_list(count [format]).
 516 @end display
 517
 518 @cmd{VECTOR} allows a group of variables to be accessed as if they
 519 were consecutive members of an array with a vector(index) notation.
 520
 521 To make a vector out of a set of existing variables, specify a name
 522 for the vector followed by an equals sign (@samp{=}) and the variables
 523 to put in the vector.  All the variables in the vector must be the same
 524 type.  String variables in a vector must all have the same width.
 525
 526 To make a vector and create variables at the same time, specify one or
 527 more vector names followed by a count in parentheses.  This will cause
 528 variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
 529 to be created as numeric variables.  By default, the new variables
 530 have print and write format F8.2, but an alternate format may be
 531 specified inside the parentheses before or after the count and
 532 separated from it by white space or a comma.  Variable names including
 533 numeric suffixes may not exceed 64 characters in length, and none of
 534 the variables may exist prior to @cmd{VECTOR}.
 535
 536 Vectors created with @cmd{VECTOR} disappear after any procedure or
 537 procedure-like command is executed.  The variables contained in the
 538 vectors remain, unless they are scratch variables (@pxref{Scratch
 539 Variables}).
 540
 541 Variables within a vector may be referenced in expressions using
 542 @code{vector(index)} syntax.
 543
 544 @node WRITE FORMATS
 545 @section WRITE FORMATS
 546 @vindex WRITE FORMATS
 547
 548 @display
 549 WRITE FORMATS var_list (fmt_spec).
 550 @end display
 551
 552 @cmd{WRITE FORMATS} sets the write formats for the specified numeric
 553 variables
 554 to the specified format specification.  Its syntax is identical to
 555 that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
 556 write formats, not print formats.