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