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 variable names & descriptions.
  11 * DISPLAY VECTORS::             Display a list of vectors.
  12 * FORMATS::                     Set print and write formats.
  13 * LEAVE::                       Don't clear variables between cases.
  14 * MISSING VALUES::              Set missing values for variables.
  15 * MODIFY VARS::                 Rename, reorder, and drop variables.
  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 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 @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH@}
  65         [SORTED] [var_list]
  66 @end display
  67
  68 @cmd{DISPLAY} displays requested information on variables.  Variables can
  69 optionally be sorted alphabetically.  The entire dictionary or just
  70 specified variables can be described.
  71
  72 One of the following keywords can be present:
  73
  74 @table @asis
  75 @item NAMES
  76 The variables' names are displayed.
  77
  78 @item INDEX
  79 The variables' names are displayed along with a value describing their
  80 position within the active file dictionary.
  81
  82 @item LABELS
  83 Variable names, positions, and variable labels are displayed.
  84
  85 @item VARIABLES
  86 Variable names, positions, print and write formats, and missing values
  87 are displayed.
  88
  89 @item DICTIONARY
  90 Variable names, positions, print and write formats, missing values,
  91 variable labels, and value labels are displayed.
  92
  93 @item SCRATCH
  94 Varible names are displayed, for scratch variables only (@pxref{Scratch
  95 Variables}).
  96 @end table
  97
  98 If SORTED is specified, then the variables are displayed in ascending
  99 order based on their names; otherwise, they are displayed in the order
 100 that they occur in the active file dictionary.
 101
 102 @node DISPLAY VECTORS
 103 @section DISPLAY VECTORS
 104 @vindex DISPLAY VECTORS
 105
 106 @display
 107 DISPLAY VECTORS.
 108 @end display
 109
 110 @cmd{DISPLAY VECTORS} lists all the currently declared vectors.
 111
 112 @node FORMATS
 113 @section FORMATS
 114 @vindex FORMATS
 115
 116 @display
 117 FORMATS var_list (fmt_spec).
 118 @end display
 119
 120 @cmd{FORMATS} set both print and write formats for the specified
 121 numeric variables to the specified format specification.
 122 @xref{Input and Output Formats}.
 123
 124 Specify a list of variables followed by a format specification in
 125 parentheses.  The print and write formats of the specified variables
 126 will be changed.
 127
 128 Additional lists of variables and formats may be included if they are
 129 delimited by a slash (@samp{/}).
 130
 131 @cmd{FORMATS} takes effect immediately.  It is not affected by
 132 conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
 133
 134 @node LEAVE
 135 @section LEAVE
 136 @vindex LEAVE
 137
 138 @display
 139 LEAVE var_list.
 140 @end display
 141
 142 @cmd{LEAVE} prevents the specified variables from being
 143 reinitialized whenever a new case is processed.
 144
 145 Normally, when a data file is processed, every variable in the active
 146 file is initialized to the system-missing value or spaces at the
 147 beginning of processing for each case.  When a variable has been
 148 specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
 149 initialized to 0 (not system-missing) or spaces for the first case.
 150 After that, it retains its value between cases.
 151
 152 This becomes useful for counters.  For instance, in the example below
 153 the variable SUM maintains a running total of the values in the ITEM
 154 variable.
 155
 156 @example
 157 DATA LIST /ITEM 1-3.
 158 COMPUTE SUM=SUM+ITEM.
 159 PRINT /ITEM SUM.
 160 LEAVE SUM
 161 BEGIN DATA.
 162 123
 163 404
 164 555
 165 999
 166 END DATA.
 167 @end example
 168
 169 @noindent Partial output from this example:
 170
 171 @example
 172 123   123.00
 173 404   527.00
 174 555  1082.00
 175 999  2081.00
 176 @end example
 177
 178 It is best to use @cmd{LEAVE} command immediately before invoking a
 179 procedure command, because the left status of variables is reset by
 180 certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
 181 Left status is also reset by all procedure invocations.
 182
 183 @node MISSING VALUES
 184 @section MISSING VALUES
 185 @vindex MISSING VALUES
 186
 187 @display
 188 MISSING VALUES var_list (missing_values).
 189
 190 missing_values takes one of the following forms:
 191         num1
 192         num1, num2
 193         num1, num2, num3
 194         num1 THRU num2
 195         num1 THRU num2, num3
 196         string1
 197         string1, string2
 198         string1, string2, string3
 199 As part of a range, LO or LOWEST may take the place of num1;
 200 HI or HIGHEST may take the place of num2.
 201 @end display
 202
 203 @cmd{MISSING VALUES} sets user-missing values for numeric and
 204 short string variables.  Long string variables may not have missing
 205 values.
 206
 207 Specify a list of variables, followed by a list of their user-missing
 208 values in parentheses.  Up to three discrete values may be given, or,
 209 for numeric variables only, a range of values optionally accompanied by
 210 a single discrete value.  Ranges may be open-ended on one end, indicated
 211 through the use of the keyword LO or LOWEST or HI or HIGHEST.
 212
 213 The @cmd{MISSING VALUES} command takes effect immediately.  It is not
 214 affected by conditional and looping constructs such as @cmd{DO IF} or
 215 @cmd{LOOP}.
 216
 217 @node MODIFY VARS
 218 @section MODIFY VARS
 219 @vindex MODIFY VARS
 220
 221 @display
 222 MODIFY VARS
 223         /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
 224         /RENAME=(old_names=new_names)@dots{}
 225         /@{DROP,KEEP@}=var_list
 226         /MAP
 227 @end display
 228
 229 @cmd{MODIFY VARS} reorders, renames, and deletes variables in the
 230 active file.
 231
 232 At least one subcommand must be specified, and no subcommand may be
 233 specified more than once.  DROP and KEEP may not both be specified.
 234
 235 The REORDER subcommand changes the order of variables in the active
 236 file.  Specify one or more lists of variable names in parentheses.  By
 237 default, each list of variables is rearranged into the specified order.
 238 To put the variables into the reverse of the specified order, put
 239 keyword BACKWARD before the parentheses.  To put them into alphabetical
 240 order in the dictionary, specify keyword ALPHA before the parentheses.
 241 BACKWARD and ALPHA may also be combined.
 242
 243 To rename variables in the active file, specify RENAME, an equals sign
 244 (@samp{=}), and lists of the old variable names and new variable names
 245 separated by another equals sign within parentheses.  There must be the
 246 same number of old and new variable names.  Each old variable is renamed to
 247 the corresponding new variable name.  Multiple parenthesized groups of
 248 variables may be specified.
 249
 250 The DROP subcommand deletes a specified list of variables from the
 251 active file.
 252
 253 The KEEP subcommand keeps the specified list of variables in the active
 254 file.  Any unlisted variables are deleted from the active file.
 255
 256 MAP is currently ignored.
 257
 258 If either DROP or KEEP is specified, the data is read; otherwise it is
 259 not.
 260
 261 @cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
 262 (@pxref{TEMPORARY}).
 263
 264 @node NUMERIC
 265 @section NUMERIC
 266 @vindex NUMERIC
 267
 268 @display
 269 NUMERIC /var_list [(fmt_spec)].
 270 @end display
 271
 272 @cmd{NUMERIC} explicitly declares new numeric variables, optionally
 273 setting their output formats.
 274
 275 Specify a slash (@samp{/}), followed by the names of the new numeric
 276 variables.  If you wish to set their output formats, follow their names
 277 by an output format specification in parentheses (@pxref{Input and Output
 278 Formats}); otherwise, the default is F8.2.
 279
 280 Variables created with @cmd{NUMERIC} are initialized to the
 281 system-missing value.
 282
 283 @node PRINT FORMATS
 284 @section PRINT FORMATS
 285 @vindex PRINT FORMATS
 286
 287 @display
 288 PRINT FORMATS var_list (fmt_spec).
 289 @end display
 290
 291 @cmd{PRINT FORMATS} sets the print formats for the specified
 292 numeric variables to the specified format specification.
 293
 294 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
 295 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
 296
 297 @node RENAME VARIABLES
 298 @section RENAME VARIABLES
 299 @vindex RENAME VARIABLES
 300
 301 @display
 302 RENAME VARIABLES (old_names=new_names)@dots{} .
 303 @end display
 304
 305 @cmd{RENAME VARIABLES} changes the names of variables in the active
 306 file.  Specify lists of the old variable names and new
 307 variable names, separated by an equals sign (@samp{=}), within
 308 parentheses.  There must be the same number of old and new variable
 309 names.  Each old variable is renamed to the corresponding new variable
 310 name.  Multiple parenthesized groups of variables may be specified.
 311
 312 @cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
 313 to be read.
 314
 315 @cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
 316 (@pxref{TEMPORARY}).
 317
 318 @node VALUE LABELS
 319 @section VALUE LABELS
 320 @vindex VALUE LABELS
 321
 322 @display
 323 VALUE LABELS
 324         /var_list value 'label' [value 'label']@dots{}
 325 @end display
 326
 327 @cmd{VALUE LABELS} allows values of numeric and short string
 328 variables to be associated with labels.  In this way, a short value can
 329 stand for a long value.
 330
 331 To set up value labels for a set of variables, specify the
 332 variable names after a slash (@samp{/}), followed by a list of values
 333 and their associated labels, separated by spaces.  Long string
 334 variables may not be specified.
 335
 336 Before @cmd{VALUE LABELS} is executed, any existing value labels
 337 are cleared from the variables specified.  Use @cmd{ADD VALUE LABELS}
 338 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
 339 already present.
 340
 341 @node STRING
 342 @section STRING
 343 @vindex STRING
 344
 345 @display
 346 STRING /var_list (fmt_spec).
 347 @end display
 348
 349 @cmd{STRING} creates new string variables for use in
 350 transformations.
 351
 352 Specify a slash (@samp{/}), followed by the names of the string
 353 variables to create and the desired output format specification in
 354 parentheses (@pxref{Input and Output Formats}).  Variable widths are
 355 implicitly derived from the specified output formats.
 356
 357 Created variables are initialized to spaces.
 358
 359
 360 @node VARIABLE LABELS
 361 @section VARIABLE LABELS
 362 @vindex VARIABLE LABELS
 363
 364 @display
 365 VARIABLE LABELS
 366         var_list 'var_label'
 367         [ /var_list 'var_label']
 368         .
 369         .
 370         .
 371         [ /var_list 'var_label']
 372 @end display
 373
 374 @cmd{VARIABLE LABELS} associates explanatory names
 375 with variables.  This name, called a @dfn{variable label}, is displayed by
 376 statistical procedures.
 377
 378 To assign a variable label to a group of variables, specify a
 379 list of variable names and the variable label as a string.
 380 To assign different labels to different variables in the same command,
 381 precede the subsequent variable list with a slash (@samp{/}).
 382
 383
 384 @node VARIABLE ALIGNMENT
 385 @comment  node-name,  next,  previous,  u
 386 @section VARIABLE ALIGNMENT
 387 @vindex VARIABLE ALIGNMENT
 388
 389 @display
 390 VARIABLE ALIGNMENT
 391         var_list ( LEFT | RIGHT | CENTER )
 392         [ /var_list ( LEFT | RIGHT | CENTER ) ]
 393         .
 394         .
 395         .
 396         [ /var_list ( LEFT | RIGHT | CENTER ) ]
 397 @end display
 398
 399 @cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
 400 purposes.   This only has effect for third party software.  It does not affect
 401 the display of variables in the PSPP output.
 402
 403
 404
 405
 406 @node VARIABLE WIDTH
 407 @comment  node-name,  next,  previous,  up
 408 @section VARIABLE WIDTH
 409 @vindex VARIABLE WIDTH
 410 @display
 411 VARIABLE WIDTH
 412         var_list (width)
 413         [ /var_list (width) ]
 414         .
 415         .
 416         .
 417         [ /var_list (width) ]
 418 @end display
 419
 420 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
 421 purposes.   This only affects third party software.  It does not affect
 422 the display of variables in the PSPP output.
 423
 424
 425 @node VARIABLE LEVEL
 426 @comment  node-name,  next,  previous,  up
 427 @section VARIABLE LEVEL
 428 @vindex VARIABLE LEVEL
 429 @display
 430 VARIABLE LEVEL
 431         var_list ( SCALE | NOMINAL | ORDINAL )
 432         [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
 433         .
 434         .
 435         .
 436         [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
 437 @end display
 438
 439 @cmd{VARIABLE LEVEL} sets the measurement level of  variables.
 440 Currently, this has no effect except for certain third party software.
 441
 442
 443 @node VECTOR
 444 @section VECTOR
 445 @vindex VECTOR
 446
 447 @display
 448 Two possible syntaxes:
 449         VECTOR vec_name=var_list.
 450         VECTOR vec_name_list(count [format]).
 451 @end display
 452
 453 @cmd{VECTOR} allows a group of variables to be accessed as if they
 454 were consecutive members of an array with a vector(index) notation.
 455
 456 To make a vector out of a set of existing variables, specify a name
 457 for the vector followed by an equals sign (@samp{=}) and the variables
 458 to put in the vector.  All the variables in the vector must be the same
 459 type.  String variables in a vector must all have the same width.
 460
 461 To make a vector and create variables at the same time, specify one or
 462 more vector names followed by a count in parentheses.  This will cause
 463 variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
 464 to be created as numeric variables.  By default, the new variables
 465 have print and write format F8.2, but an alternate format may be
 466 specified inside the parentheses before or after the count and
 467 separated from it by white space or a comma.  Variable names including
 468 numeric suffixes may not exceed 64 characters in length, and none of
 469 the variables may exist prior to @cmd{VECTOR}.
 470
 471 Vectors created with @cmd{VECTOR} disappear after any procedure or
 472 procedure-like command is executed.  The variables contained in the
 473 vectors remain, unless they are scratch variables (@pxref{Scratch
 474 Variables}).
 475
 476 Variables within a vector may be referenced in expressions using
 477 @code{vector(index)} syntax.
 478
 479 @node WRITE FORMATS
 480 @section WRITE FORMATS
 481 @vindex WRITE FORMATS
 482
 483 @display
 484 WRITE FORMATS var_list (fmt_spec).
 485 @end display
 486
 487 @cmd{WRITE FORMATS} sets the write formats for the specified numeric
 488 variables
 489 to the specified format specification.  Its syntax is identical to
 490 that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
 491 write formats, not print formats.
 492 @setfilename ignored