doc/variables.texi

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