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

The variables in the active dataset 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 be used after defining transformations but 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 [SORTED] NAMES [[/VARIABLES=]var_list].
     DISPLAY [SORTED] INDEX [[/VARIABLES=]var_list].
     DISPLAY [SORTED] LABELS [[/VARIABLES=]var_list].
     DISPLAY [SORTED] VARIABLES [[/VARIABLES=]var_list].
     DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]var_list].
     DISPLAY [SORTED] SCRATCH [[/VARIABLES=]var_list].
     DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]var_list].
     DISPLAY [SORTED] @ATTRIBUTES [[/VARIABLES=]var_list].
     DISPLAY [SORTED] VECTORS.

DISPLAY displays information about the active dataset.  A variety of different forms of information can be requested.

The following keywords primarily cause information about variables to be displayed.  With these keywords, by default information is displayed about all variable in the active dataset, in the order that variables occur in the active dataset dictionary.  The SORTED keyword causes output to be sorted alphabetically by variable name.  The VARIABLES subcommand limits output to the specified variables.

NAMES
     The variables' names are displayed.

INDEX
     The variables' names are displayed along with a value describing their position within the active dataset 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
     Variable names are displayed, for scratch variables only (see Scratch Variables).

ATTRIBUTES
@ATTRIBUTES
     Datafile and variable attributes are displayed. The first form of the command omits those attributes whose names begin with @ or $@. In the second for, all datafile and variable attributes are displayed.

With the VECTOR keyword, DISPLAY lists all the currently declared vectors.  If the SORTED keyword is given, the vectors are listed in alphabetical order; otherwise, they are listed in textual order of definition within the pspp syntax file.

For related commands, see DISPLAY DOCUMENTS and DISPLAY FILE LABEL.

FORMATS
=======

     FORMATS var_list (fmt_spec) [var_list (fmt_spec)]....

FORMATS set both print and write formats for the specified 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.  All of the variables listed together must have the same type and, for string variables, the same width.

Additional lists of variables and formats may be included following the first one.

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 dataset 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 string variables.  Long string variables may have missing values, but characters after the first 8 bytes of the missing value must be spaces.

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 dataset.

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 dataset.  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 dataset, 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 dataset.

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

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).

MRSETS
======

     MRSETS
         /MDGROUP NAME=name VARIABLES=var_list VALUE=value
          [CATEGORYLABELS={VARLABELS,COUNTEDVALUES}]
          [{LABEL='label',LABELSOURCE=VARLABEL}]

         /MCGROUP NAME=name VARIABLES=var_list [LABEL='label']

         /DELETE NAME={[names],ALL}

         /DISPLAY NAME={[names],ALL}

MRSETS creates, modifies, deletes, and displays multiple response sets.  A multiple response set is a set of variables that represent multiple responses to a single survey question in one of the two following ways:

  * A multiple dichotomy set is analogous to a survey question with a set of checkboxes.  Each variable in the set is treated in a Boolean fashion: one value (the "counted value") means that the box was checked, and any other value means that it was not.

  * A multiple category set represents a survey question where the respondent is instructed to list up to N choices.  Each variable represents one of the responses.

Any number of subcommands may be specified in any order.

The MDGROUP subcommand creates a new multiple dichotomy set or replaces an existing multiple response set.  The NAME, VARIABLES, and VALUE specifications are required.  The others are optional:

  * NAME specifies the name used in syntax for the new multiple dichotomy set.  The name must begin with $; it must otherwise follow the rules for identifiers (see Tokens).

  * VARIABLES specifies the variables that belong to the set.  At least two variables must be specified.  The variables must be all string or all numeric.

  * VALUE specifies the counted value.  If the variables are numeric, the value must be an integer.  If the variables are strings, then the value must be a string that is no longer than the shortest of the variables in the set (ignoring trailing spaces).

  * CATEGORYLABELS optionally specifies the source of the labels for each category in the set:

       - VARLABELS, the default, uses variable labels or, for variables without variable labels, variable names.  pspp warns if two variables have the same variable label, since these categories cannot be distinguished in output.

       - COUNTEDVALUES instead uses each variable's value label for the counted value.  pspp warns if two variables have the same value label for the counted value or if one of the variables lacks a value label, since such categories cannot be distinguished in output.

  * LABEL optionally specifies a label for the multiple response set.  If neither LABEL nor LABELSOURCE=VARLABEL is specified, the set is unlabeled.

  * LABELSOURCE=VARLABEL draws the multiple response set's label from the first variable label among the variables in the set; if none of the variables has a label, the name of the first variable is used. LABELSOURCE=VARLABEL must be used with CATEGORYLABELS=COUNTEDVALUES. It is mutually exclusive with LABEL.

The MCGROUP subcommand creates a new multiple category set or replaces an existing multiple response set.  The NAME and VARIABLES specifications are required, and LABEL is optional.  Their meanings are as described above to MDGROUP.  pspp warns if two variables in the set have different value labels for a single value, since each of the variables in the set should have the same possible categories.

The DELETE subcommand deletes multiple response groups.  A list of groups may be named within a set of required square brackets, or ALL may be used to delete all groups.

The DISPLAY subcommand displays information about defined multiple response sets.  Its syntax is the same as the DELETE subcommand.

Multiple response sets are saved to and read from system files by, e.g., the SAVE and GET command.  Otherwise, multiple response sets are currently used only by third party software.

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) [var_list (fmt_spec)]....

PRINT FORMATS sets the print formats for the specified 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 dataset.  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.

Value labels in output are normally broken into lines automatically. Put \n in a label string to force a line break at that point. The label may still be broken into lines at additional points.

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 ATTRIBUTE
==================

     VARIABLE ATTRIBUTE
              VARIABLES=var_list
              ATTRIBUTE=name('value') [name('value')]...
              ATTRIBUTE=name[index]('value') [name[index]('value')]...
              DELETE=name [name]...
              DELETE=name[index] [name[index]]...

VARIABLE ATTRIBUTE adds, modifies, or removes user-defined attributes associated with variables in the active dataset.  Custom variable attributes are not interpreted by pspp, but they are saved as part of system files and may be used by other software that reads them.

The required VARIABLES subcommand must come first.  Specify the variables to which the following ATTRIBUTE or DELETE subcommand should apply.

Use the ATTRIBUTE subcommand to add or modify custom variable attributes.  Specify the name of the attribute as an identifier (see Tokens), followed by the desired value, in parentheses, as a quoted string.  The specified attributes are then added or modified in the variables specified on VARIABLES.  Attribute names that begin with $ are reserved for pspp's internal use, and attribute names that begin with @ or $@ are not displayed by most pspp commands that display other attributes.  Other attribute names are not treated specially.

Attributes may also be organized into arrays.  To assign to an array element, add an integer array index enclosed in square brackets ([ and ]) between the attribute name and value.  Array indexes start at 1, not 0.  An attribute array that has a single element (number 1) is not distinguished from a non-array attribute.

Use the DELETE subcommand to delete an attribute from the variable specified on VARIABLES.  Specify an attribute name by itself to delete an entire attribute, including all array elements for attribute arrays.  Specify an attribute name followed by an array index in square brackets to delete a single element of an attribute array.  In the latter case, all the array elements numbered higher than the deleted element are shifted down, filling the vacated position.

To associate custom attributes with the entire active dataset, instead of with particular variables, use DATAFILE ATTRIBUTE (see DATAFILE ATTRIBUTE) instead.

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

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, precede 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 [format]).

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 to put in the vector.  All the variables in the vector must be the same type.  String variables in a vector must all have the same width.

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.  By default, the new variables have print and write format F8.2, but an alternate format may be specified inside the parentheses before or after the count and separated from it by white space or a comma.  Variable names including numeric suffixes may not exceed 64 characters in length, and none of the variables may exist prior to VECTOR.

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) [var_list (fmt_spec)]....

WRITE FORMATS sets the write formats for the specified 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.