Manipulating variables
**********************

The variables in the active file dictionary are important.  There are several utility functions for examining and adjusting them.

ADD VALUE LABELS
================

     ADD VALUE LABELS
             /var_list value 'label' [value 'label']...

ADD VALUE LABELS has the same syntax and purpose as VALUE LABELS (see VALUE LABELS), but it does not clear value labels from the variables before adding the ones specified.

DELETE VARIABLES
================

     DELETE VARIABLES var_list.

DELETE VARIABLES deletes the specified variables from the dictionary.  It may not be used to delete all variables from the dictionary; use NEW FILE to do that (see NEW FILE).

DELETE VARIABLES should not used after defining transformations and before executing a procedure.  If it is used in such a context, it causes the data to be read.  If it is used while TEMPORARY is in effect, it causes the temporary transformations to become permanent.

DISPLAY
=======

     DISPLAY {NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH}
             [SORTED] [var_list]

DISPLAY displays requested information on variables.  Variables can optionally be sorted alphabetically.  The entire dictionary or just specified variables can be described.

One of the following keywords can be present:

NAMES
     The variables' names are displayed.

INDEX
     The variables' names are displayed along with a value describing their position within the active file dictionary.

LABELS
     Variable names, positions, and variable labels are displayed.

VARIABLES
     Variable names, positions, print and write formats, and missing values are displayed.

DICTIONARY
     Variable names, positions, print and write formats, missing values, variable labels, and value labels are displayed.

SCRATCH
     Varible names are displayed, for scratch variables only (see Scratch Variables).

If SORTED is specified, then the variables are displayed in ascending order based on their names; otherwise, they are displayed in the order that they occur in the active file dictionary.

DISPLAY VECTORS
===============

     DISPLAY VECTORS.

DISPLAY VECTORS lists all the currently declared vectors.

FORMATS
=======

     FORMATS var_list (fmt_spec).

FORMATS set both print and write formats for the specified numeric variables to the specified format specification. See Input and Output Formats.

Specify a list of variables followed by a format specification in parentheses.  The print and write formats of the specified variables will be changed.

Additional lists of variables and formats may be included if they are delimited by a slash (/).

FORMATS takes effect immediately.  It is not affected by conditional and looping structures such as DO IF or LOOP.

LEAVE
=====

     LEAVE var_list.

LEAVE prevents the specified variables from being reinitialized whenever a new case is processed.

Normally, when a data file is processed, every variable in the active file is initialized to the system-missing value or spaces at the beginning of processing for each case.  When a variable has been specified on LEAVE, this is not the case.  Instead, that variable is initialized to 0 (not system-missing) or spaces for the first case. After that, it retains its value between cases.

This becomes useful for counters.  For instance, in the example below the variable SUM maintains a running total of the values in the ITEM variable.

     DATA LIST /ITEM 1-3.
     COMPUTE SUM=SUM+ITEM.
     PRINT /ITEM SUM.
     LEAVE SUM
     BEGIN DATA.
     123
     404
     555
     999
     END DATA.

Partial output from this example:

     123   123.00
     404   527.00
     555  1082.00
     999  2081.00

It is best to use LEAVE command immediately before invoking a procedure command, because the left status of variables is reset by certain transformations---for instance, COMPUTE and IF. Left status is also reset by all procedure invocations.

MISSING VALUES
==============

     MISSING VALUES var_list (missing_values).

     missing_values takes one of the following forms:
             num1
             num1, num2
             num1, num2, num3
             num1 THRU num2
             num1 THRU num2, num3
             string1
             string1, string2
             string1, string2, string3
     As part of a range, LO or LOWEST may take the place of num1;
     HI or HIGHEST may take the place of num2.

MISSING VALUES sets user-missing values for numeric and short string variables.  Long string variables may not have missing values.

Specify a list of variables, followed by a list of their user-missing values in parentheses.  Up to three discrete values may be given, or, for numeric variables only, a range of values optionally accompanied by a single discrete value.  Ranges may be open-ended on one end, indicated through the use of the keyword LO or LOWEST or HI or HIGHEST.

The MISSING VALUES command takes effect immediately.  It is not affected by conditional and looping constructs such as DO IF or LOOP.

MODIFY VARS
===========

     MODIFY VARS
             /REORDER={FORWARD,BACKWARD} {POSITIONAL,ALPHA} (var_list)...
             /RENAME=(old_names=new_names)...
             /{DROP,KEEP}=var_list
             /MAP

MODIFY VARS reorders, renames, and deletes variables in the active file.

At least one subcommand must be specified, and no subcommand may be specified more than once.  DROP and KEEP may not both be specified.

The REORDER subcommand changes the order of variables in the active file.  Specify one or more lists of variable names in parentheses.  By default, each list of variables is rearranged into the specified order. To put the variables into the reverse of the specified order, put keyword BACKWARD before the parentheses.  To put them into alphabetical order in the dictionary, specify keyword ALPHA before the parentheses. BACKWARD and ALPHA may also be combined.

To rename variables in the active file, specify RENAME, an equals sign (=), and lists of the old variable names and new variable names separated by another equals sign within parentheses.  There must be the same number of old and new variable names.  Each old variable is renamed to the corresponding new variable name.  Multiple parenthesized groups of variables may be specified.

The DROP subcommand deletes a specified list of variables from the active file.

The KEEP subcommand keeps the specified list of variables in the active file.  Any unlisted variables are deleted from the active file.

MAP is currently ignored.

If either DROP or KEEP is specified, the data is read; otherwise it is not.

MODIFY VARS may not be specified following TEMPORARY (see TEMPORARY).

NUMERIC
=======

     NUMERIC /var_list [(fmt_spec)].

NUMERIC explicitly declares new numeric variables, optionally setting their output formats.

Specify a slash (/), followed by the names of the new numeric variables.  If you wish to set their output formats, follow their names by an output format specification in parentheses (see Input and Output Formats); otherwise, the default is F8.2.

Variables created with NUMERIC are initialized to the system-missing value.

PRINT FORMATS
=============

     PRINT FORMATS var_list (fmt_spec).

PRINT FORMATS sets the print formats for the specified numeric variables to the specified format specification.

Its syntax is identical to that of FORMATS (see FORMATS), but PRINT FORMATS sets only print formats, not write formats.

RENAME VARIABLES
================

     RENAME VARIABLES (old_names=new_names)... .

RENAME VARIABLES changes the names of variables in the active file.  Specify lists of the old variable names and new variable names, separated by an equals sign (=), within parentheses.  There must be the same number of old and new variable names.  Each old variable is renamed to the corresponding new variable name.  Multiple parenthesized groups of variables may be specified.

RENAME VARIABLES takes effect immediately.  It does not cause the data to be read.

RENAME VARIABLES may not be specified following TEMPORARY (see TEMPORARY).

VALUE LABELS
============

     VALUE LABELS
             /var_list value 'label' [value 'label']...

VALUE LABELS allows values of numeric and short string variables to be associated with labels.  In this way, a short value can stand for a long value.

To set up value labels for a set of variables, specify the variable names after a slash (/), followed by a list of values and their associated labels, separated by spaces.  Long string variables may not be specified.

Before VALUE LABELS is executed, any existing value labels are cleared from the variables specified.  Use ADD VALUE LABELS (see ADD VALUE LABELS) to add value labels without clearing those already present.

STRING
======

     STRING /var_list (fmt_spec).

STRING creates new string variables for use in transformations.

Specify a slash (/), followed by the names of the string variables to create and the desired output format specification in parentheses (see Input and Output Formats).  Variable widths are implicitly derived from the specified output formats.

Created variables are initialized to spaces.

VARIABLE LABELS
===============

     VARIABLE LABELS
             var_list 'var_label'
             [ /var_list 'var_label']
             .
             .
             .
             [ /var_list 'var_label']

VARIABLE LABELS associates explanatory names with variables.  This name, called a variable label, is displayed by statistical procedures.

To assign a variable label to a group of variables, specify a list of variable names and the variable label as a string. To assign different labels to different variables in the same command, preceed the subsequent variable list with a slash (/).

VARIABLE ALIGNMENT
==================

     VARIABLE ALIGNMENT
             var_list ( LEFT | RIGHT | CENTER )
             [ /var_list ( LEFT | RIGHT | CENTER ) ]
             .
             .
             .
             [ /var_list ( LEFT | RIGHT | CENTER ) ]

VARIABLE ALIGNMENT sets the alignment of variables for display editing purposes.   This only has effect for third party software.  It does not affect the display of variables in the PSPP output.

VARIABLE WIDTH
==============

     VARIABLE WIDTH
             var_list (width)
             [ /var_list (width) ]
             .
             .
             .
             [ /var_list (width) ]

VARIABLE WIDTH sets the column width of variables for display editing purposes.   This only affects third party software.  It does not affect the display of variables in the PSPP output.

VARIABLE LEVEL
==============

     VARIABLE LEVEL
             var_list ( SCALE | NOMINAL | ORDINAL )
             [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
             .
             .
             .
             [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]

VARIABLE LEVEL sets the measurement level of  variables. Currently, this has no effect except for certain third party software.

VECTOR
======

     Two possible syntaxes:
             VECTOR vec_name=var_list.
             VECTOR vec_name_list(count).

VECTOR allows a group of variables to be accessed as if they were consecutive members of an array with a vector(index) notation.

To make a vector out of a set of existing variables, specify a name for the vector followed by an equals sign (=) and the variables that belong in the vector.

To make a vector and create variables at the same time, specify one or more vector names followed by a count in parentheses.  This will cause variables named VEC1 through VECCOUNT to be created as numeric variables with print and write format F8.2. Variable names including numeric suffixes may not exceed 64 characters in length, and none of the variables may exist prior to VECTOR.

All the variables in a vector must be the same type.  String variables in a vector must all have the same width.

Vectors created with VECTOR disappear after any procedure or procedure-like command is executed.  The variables contained in the vectors remain, unless they are scratch variables (see Scratch Variables).

Variables within a vector may be referenced in expressions using vector(index) syntax.

WRITE FORMATS
=============

     WRITE FORMATS var_list (fmt_spec).

WRITE FORMATS sets the write formats for the specified numeric variables to the specified format specification.  Its syntax is identical to that of FORMATS (see FORMATS), but WRITE FORMATS sets only write formats, not print formats.