-@node Variable Attributes
-@chapter Manipulating variables
-
-The variables in the active dataset dictionary are important. There are
-several utility functions for examining and adjusting them.
+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+@c A copy of the license is included in the section entitled "GNU
+@c Free Documentation License".
+@c
+@node Manipulating Variables
+@chapter Manipulating Variables
+@cindex Variables
+
+Every value in a dataset is associated with a @dfn{variable}.
+Variables describe what the values represent and properties of those values,
+such as the format in which they should be displayed, whether they are numeric
+or alphabetic and how missing values should be represented.
+There are several utility commands for examining and adjusting variables.
@menu
-* ADD VALUE LABELS:: Add value labels to variables.
-* DELETE VARIABLES:: Delete variables.
* DISPLAY:: Display information about the active dataset.
-* FORMATS:: Set print and write formats.
-* LEAVE:: Don't clear variables between cases.
-* MISSING VALUES:: Set missing values for variables.
-* MODIFY VARS:: Rename, reorder, and drop variables.
-* MRSETS:: Add, modify, and list multiple response sets.
* NUMERIC:: Create new numeric variables.
-* PRINT FORMATS:: Set variable print formats.
+* STRING:: Create new string variables.
* RENAME VARIABLES:: Rename variables.
+* SORT VARIABLES:: Reorder variables.
+* DELETE VARIABLES:: Delete variables.
+* VARIABLE LABELS:: Set variable labels for variables.
+* PRINT FORMATS:: Set variable print formats.
+* WRITE FORMATS:: Set variable write formats.
+* FORMATS:: Set print and write formats.
* VALUE LABELS:: Set value labels for variables.
-* STRING:: Create new string variables.
+* ADD VALUE LABELS:: Add value labels to variables.
+* MISSING VALUES:: Set missing values for variables.
* VARIABLE ATTRIBUTE:: Set custom attributes on variables.
-* VARIABLE LABELS:: Set variable labels for variables.
* VARIABLE ALIGNMENT:: Set the alignment for display.
* VARIABLE WIDTH:: Set the display width.
* VARIABLE LEVEL:: Set the measurement level.
+* VARIABLE ROLE:: Set the role that a variable fills in analysis.
* VECTOR:: Declare an array of variables.
-* WRITE FORMATS:: Set variable write formats.
+* MRSETS:: Add, modify, and list multiple response sets.
+* LEAVE:: Don't clear variables between cases.
@end menu
-@node ADD VALUE LABELS
-@section ADD VALUE LABELS
-@vindex ADD VALUE LABELS
-
-@display
-ADD VALUE LABELS
- /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
-@end display
-
-@cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
-LABELS} (@pxref{VALUE LABELS}), but it does not clear value
-labels from the variables before adding the ones specified.
-
-@node DELETE VARIABLES
-@section DELETE VARIABLES
-@vindex DELETE VARIABLES
-
-@display
-DELETE VARIABLES @var{var_list}.
-@end display
-
-@cmd{DELETE VARIABLES} deletes the specified variables from the
-dictionary. It may not be used to delete all variables from the
-dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
-
-@cmd{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 @cmd{TEMPORARY} is in
-effect, it causes the temporary transformations to become permanent.
-
@node DISPLAY
@section DISPLAY
@vindex DISPLAY
+The @cmd{DISPLAY} command displays information about the variables in the active dataset.
+A variety of different forms of information can be requested.
+By default, all variables in the active dataset are displayed. However you can select
+variables of interest using the @subcmd{/VARIABLES} subcommand.
+
@display
DISPLAY [SORTED] NAMES [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] INDEX [[/VARIABLES=]@var{var_list}].
DISPLAY [SORTED] VECTORS.
@end display
-@cmd{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 @subcmd{SORTED} keyword
-causes output to be sorted alphabetically by variable name. The
-@subcmd{VARIABLES} subcommand limits output to the specified variables.
+causes output to be sorted alphabetically by variable name.
@table @asis
@item NAMES
@item ATTRIBUTES
@itemx @@ATTRIBUTES
Datafile and variable attributes are displayed.
-The first form of the command omits those attributes
+The first form of the command omits those attributes
whose names begin with @code{@@} or @code{$@@}.
In the second for, all datafile and variable attributes are displayed.
@end table
For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
FILE LABEL}.
+@node NUMERIC
+@section NUMERIC
+@vindex NUMERIC
+
+@cmd{NUMERIC} explicitly declares new numeric variables, optionally
+setting their output formats.
+
+@display
+NUMERIC @var{var_list} [(@var{fmt_spec})] [/@var{var_list} [(@var{fmt_spec})]]@dots{}
+@end display
+
+Specify the names of the new numeric variables as @var{var_list}. If
+you wish to set the variables' output formats, follow their names by
+an output format specification in parentheses (@pxref{Input and Output
+Formats}); otherwise, the default is F8.2.
+
+Variables created with @cmd{NUMERIC} are initialized to the
+system-missing value.
+
+@node STRING
+@section STRING
+@vindex STRING
+
+@cmd{STRING} creates new string variables.
+
+@display
+STRING @var{var_list} (@var{fmt_spec}) [/@var{var_list} (@var{fmt_spec})] [@dots{}].
+@end display
+
+Specify a list of names for the variable you want to create,
+followed by the desired output format specification in
+parentheses (@pxref{Input and Output Formats}).
+Variable widths are
+implicitly derived from the specified output formats.
+The created variables will be initialized to spaces.
+
+If you want to create several variables with distinct
+output formats, you can either use two or more separate @cmd{STRING} commands,
+or you can specify further variable list and format specification pairs, each separated
+from the previous by a slash (@samp{/}).
+
+The following example is one way to create three string variables; Two of the
+variables have format A24 and the other A80:
+@example
+STRING firstname lastname (A24) / address (A80).
+@end example
+
+@noindent Here is another way to achieve the same result:
+@example
+STRING firstname lastname (A24).
+STRING address (A80).
+@end example
+
+@noindent @dots{} and here is yet another way:
+
+@example
+STRING firstname (A24).
+STRING lastname (A24).
+STRING address (A80).
+@end example
+
+@node RENAME VARIABLES
+@section RENAME VARIABLES
+@vindex RENAME VARIABLES
+
+@cmd{RENAME VARIABLES} changes the names of variables in the active
+dataset.
+
+@display
+RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
+@end display
+
+Specify lists of the old variable names and new
+variable names, separated by an equals sign (@samp{=}), 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.
+When the old and new variable names contain only a single variable name,
+the parentheses are optional.
+
+@cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
+to be read.
+
+@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}).
+
+@node SORT VARIABLES
+@section SORT VARIABLES
+@vindex SORT VARIABLES
+
+@cmd{SORT VARIABLES} reorders the variables in the active dataset's dictionary
+according to a chosen sort key.
+
+@display
+SORT VARIABLES [BY]
+ (NAME | TYPE | FORMAT | LABEL | VALUES | MISSING | MEASURE
+ | ROLE | COLUMNS | ALIGNMENT | ATTRIBUTE @var{name})
+ [(D)].
+@end display
+
+The main specification is one of the following identifiers, which
+determines how the variables are sorted:
+
+@table @asis
+@item NAME
+Sorts the variables according to their names, in a case-insensitive
+fashion. However, when variable names differ only in a number at the
+end, they are sorted numerically. For example, @code{VAR5} is sorted
+before @code{VAR400} even though @samp{4} precedes @samp{5}.
+
+@item TYPE
+Sorts numeric variables before string variables, and shorter string
+variables before longer ones.
+
+@item FORMAT
+Groups variables by print format; within a format, sorts narrower
+formats before wider ones; with the same format and width, sorts fewer
+decimal places before more decimal places.
+@xref{FORMATS}.
+
+@item LABEL
+Sorts variables without a variable label before those with one.
+@xref{VARIABLE LABELS}.
+
+@item VALUES
+Sorts variables without value labels before those with some.
+@xref{VALUE LABELS}.
+
+@item MISSING
+Sorts variables without missing values before those with some.
+@xref{MISSING VALUES}.
+
+@item MEASURE
+Sorts nominal variables first, followed by ordinal variables, followed
+by scale variables. @xref{VARIABLE LEVEL}.
+
+@item ROLE
+Groups variables according to their role. @xref{VARIABLE ROLE}.
+
+@item COLUMNS
+Sorts variables in ascending display width. @xref{VARIABLE WIDTH}.
+
+@item ALIGNMENT
+Sorts variables according to their alignment, first left-aligned, then
+right-aligned, then centered. @xref{VARIABLE ALIGNMENT}.
+
+@item ATTRIBUTE @var{name}
+Sorts variables according to the first value of their @var{name}
+attribute. Variables without attribute are sorted first.
+@xref{VARIABLE ATTRIBUTE}.
+@end table
+
+Only one sort criterion can be specified. The sort is ``stable,'' so
+to sort on multiple criteria one may perform multiple sorts. For
+example, the following will sort primarily based on alignment, with
+variables that have the same alignment ordered based on display width:
+
+@example
+SORT VARIABLES BY COLUMNS.
+SORT VARIABLES BY ALIGNMENT.
+@end example
+
+Specify @code{(D)} to reverse the sort order.
+
+@node DELETE VARIABLES
+@section DELETE VARIABLES
+@vindex DELETE VARIABLES
+
+@cmd{DELETE VARIABLES} deletes the specified variables from the dictionary.
+
+@display
+DELETE VARIABLES @var{var_list}.
+@end display
+
+@cmd{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 @cmd{TEMPORARY} is in
+effect, it causes the temporary transformations to become permanent.
+
+@cmd{DELETE VARIABLES} may not be used to delete all variables from the
+dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
+
+@node VARIABLE LABELS
+@section VARIABLE LABELS
+@vindex VARIABLE LABELS
+
+In addition to a variable's name, each variable can have a
+@dfn{label}. Whereas a variable name is a concise, easy-to-type
+mnemonic for the variable, a label may be longer and more descriptive.
+
+@display
+VARIABLE LABELS
+ @var{variable} '@var{label}'
+ [@var{variable} '@var{label}']@dots{}
+@end display
+
+@cmd{VARIABLE LABELS} associates explanatory names
+with variables. This name, called a @dfn{variable label}, is displayed by
+statistical procedures.
+
+Specify each variable followed by its label as a quoted string.
+Variable-label pairs may be separated by an optional slash @samp{/}.
+
+If a listed variable already has a label, the new one replaces it.
+Specifying an empty string as the label, e.g.@:@samp{''}, removes a
+label.
+
+@node PRINT FORMATS
+@section PRINT FORMATS
+@vindex PRINT FORMATS
+
+@display
+PRINT FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
+@end display
+
+@cmd{PRINT FORMATS} sets the print formats for the specified
+variables to the specified format specification.
+
+Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
+but @cmd{PRINT FORMATS} sets only print formats, not write formats.
+
+@node WRITE FORMATS
+@section WRITE FORMATS
+@vindex WRITE FORMATS
+
+@display
+WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
+@end display
+
+@cmd{WRITE FORMATS} sets the write formats for the specified variables
+to the specified format specification. Its syntax is identical to
+that of @cmd{FORMATS} (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
+write formats, not print formats.
+
@node FORMATS
@section FORMATS
@vindex FORMATS
@cmd{FORMATS} takes effect immediately. It is not affected by
conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
-@node LEAVE
-@section LEAVE
-@vindex LEAVE
+@node VALUE LABELS
+@section VALUE LABELS
+@vindex VALUE LABELS
+
+The values of a variable can be associated with an arbitrary text string.
+In this way, a short value can stand for a longer, more descriptive label.
+
+Both numeric and string variables can be given labels. For string
+variables, the values are case-sensitive, so that, for example, a
+capitalized value and its lowercase variant would have to be labeled
+separately if both are present in the data.
@display
-LEAVE @var{var_list}.
+VALUE LABELS
+ /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
@end display
-@cmd{LEAVE} prevents the specified variables from being
-reinitialized whenever a new case is processed.
+@cmd{VALUE LABELS} allows values of variables to be associated with labels.
-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 @cmd{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.
+To set up value labels for one or more variables, specify the
+variable names after a slash (@samp{/}), followed by a list of values
+and their associated labels, separated by spaces.
-This becomes useful for counters. For instance, in the example below
-the variable @code{SUM} maintains a running total of the values in the @code{ITEM}
-variable.
+Value labels in output are normally broken into lines automatically.
+Put @samp{\n} in a label string to force a line break at that point.
+The label may still be broken into lines at additional points.
-@example
-DATA LIST /ITEM 1-3.
-COMPUTE SUM=SUM+ITEM.
-PRINT /ITEM SUM.
-LEAVE SUM
-BEGIN DATA.
-123
-404
-555
-999
-END DATA.
-@end example
+Before @cmd{VALUE LABELS} is executed, any existing value labels
+are cleared from the variables specified. Use @cmd{ADD VALUE LABELS}
+(@pxref{ADD VALUE LABELS}) to add value labels without clearing those
+already present.
-@noindent Partial output from this example:
+@node ADD VALUE LABELS
+@section ADD VALUE LABELS
+@vindex ADD VALUE LABELS
-@example
-123 123.00
-404 527.00
-555 1082.00
-999 2081.00
-@end example
+@cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
+LABELS} (@pxref{VALUE LABELS}), but it does not clear value
+labels from the variables before adding the ones specified.
+
+@display
+ADD VALUE LABELS
+ /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
+@end display
-It is best to use @cmd{LEAVE} command immediately before invoking a
-procedure command, because the left status of variables is reset by
-certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
-Left status is also reset by all procedure invocations.
@node MISSING VALUES
@section MISSING VALUES
@vindex MISSING VALUES
+In many situations the data available for analysis is incomplete and a placeholder
+must be used in place of a value to indicate that the value is unknown. One way
+that missing values are represented is through the $SYSMIS variable
+(@pxref{System Variables}). Another, more flexible way is through
+@dfn{user-missing values} which are determined on a per variable basis.
+
+The @cmd{MISSING VALUES} command sets user-missing values for variables.
+
@display
MISSING VALUES @var{var_list} (@var{missing_values}).
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
+through the use of the
keyword @subcmd{LO} or @subcmd{LOWEST} or @subcmd{HI} or @subcmd{HIGHEST}.
The @cmd{MISSING VALUES} command takes effect immediately. It is not
affected by conditional and looping constructs such as @cmd{DO IF} or
@cmd{LOOP}.
-@node MODIFY VARS
-@section MODIFY VARS
-@vindex MODIFY VARS
-
-@display
-MODIFY VARS
- /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (@var{var_list})@dots{}
- /RENAME=(@var{old_names}=@var{new_names})@dots{}
- /@{DROP,KEEP@}=@var{var_list}
- /MAP
-@end display
+@node VARIABLE ATTRIBUTE
+@section VARIABLE ATTRIBUTE
+@vindex VARIABLE ATTRIBUTE
-@cmd{MODIFY VARS} reorders, renames, and deletes variables in the
-active dataset.
+@cmd{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.
-At least one subcommand must be specified, and no subcommand may be
-specified more than once. @subcmd{DROP} and @subcmd{KEEP} may not both
-be specified.
+@display
+VARIABLE ATTRIBUTE
+ VARIABLES=@var{var_list}
+ ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
+ ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
+ DELETE=@var{name} [@var{name}]@dots{}
+ DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
+@end display
-The @subcmd{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 @subcmd{BACKWARD} before the parentheses. To put them into alphabetical
-order in the dictionary, specify keyword @subcmd{ALPHA} before the parentheses.
-@subcmd{BACKWARD} and @subcmd{ALPHA} may also be combined.
+The required @subcmd{VARIABLES} subcommand must come first. Specify the
+variables to which the following @subcmd{ATTRIBUTE} or @subcmd{DELETE} subcommand
+should apply.
-To rename variables in the active dataset, specify @subcmd{RENAME}, an equals sign
-(@samp{=}), 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.
+Use the @subcmd{ATTRIBUTE} subcommand to add or modify custom variable
+attributes. Specify the name of the attribute as an identifier
+(@pxref{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 @subcmd{VARIABLES}. Attribute names that begin with
+@code{$} are reserved for @pspp{}'s internal use, and attribute names
+that begin with @code{@@} or @code{$@@} are not displayed by most @pspp{}
+commands that display other attributes. Other attribute names are not
+treated specially.
-The @subcmd{DROP} subcommand deletes a specified list of variables from the
-active dataset.
+Attributes may also be organized into arrays. To assign to an array
+element, add an integer array index enclosed in square brackets
+(@code{[} and @code{]}) 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.
-The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
-dataset. Any unlisted variables are deleted from the active dataset.
+Use the @subcmd{DELETE} subcommand to delete an attribute from the variable
+specified on @subcmd{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.
-@subcmd{MAP} is currently ignored.
+To associate custom attributes with the entire active dataset, instead of
+with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
-If either @subcmd{DROP} or @subcmd{KEEP} is specified, the data is read;
-otherwise it is not.
+@cmd{VARIABLE ATTRIBUTE} takes effect immediately. It is not affected
+by conditional and looping structures such as @cmd{DO IF} or
+@cmd{LOOP}.
-@cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
-(@pxref{TEMPORARY}).
+@node VARIABLE ALIGNMENT
+@section VARIABLE ALIGNMENT
+@vindex VARIABLE ALIGNMENT
-@node MRSETS
-@section MRSETS
-@vindex MRSETS
+@cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
+purposes. It does not affect the display of variables in the @pspp{} output.
@display
-MRSETS
- /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
- [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
- [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
+VARIABLE ALIGNMENT
+ @var{var_list} ( LEFT | RIGHT | CENTER )
+ [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
+ .
+ .
+ .
+ [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
+@end display
- /MCGROUP NAME=@var{name} VARIABLES=@var{var_list} [LABEL='@var{label}']
+@node VARIABLE WIDTH
+@section VARIABLE WIDTH
+@vindex VARIABLE WIDTH
+@display
+VARIABLE WIDTH
+ @var{var_list} (width)
+ [ /@var{var_list} (width) ]
+ .
+ .
+ .
+ [ /@var{var_list} (width) ]
+@end display
- /DELETE NAME=@{[@var{names}],ALL@}
+@cmd{VARIABLE WIDTH} sets the column width of variables for display editing
+purposes. It does not affect the display of variables in the @pspp{} output.
- /DISPLAY NAME=@{[@var{names}],ALL@}
+
+@node VARIABLE LEVEL
+@section VARIABLE LEVEL
+@vindex VARIABLE LEVEL
+@display
+@t{VARIABLE LEVEL} @i{variables} @t{(}@{@t{SCALE} @math{|} @t{NOMINAL} @math{|} @t{ORDINAL}@}@t{)}@dots{}
@end display
+@cmd{VARIABLE LEVEL} sets the measurement level of @var{variables} as
+specified. @xref{Attributes}, for the definitions of the available
+measurement levels.
+
+@node VARIABLE ROLE
+@section VARIABLE ROLE
+@vindex VARIABLE ROLE
+@display
+VARIABLE ROLE
+ /@var{role} @var{var_list}
+ [/@var{role} @var{var_list}]@dots{}
+@end display
+
+@cmd{VARIABLE ROLE} sets the intended role of a variable for use in
+dialog boxes in graphical user interfaces. Each @var{role} specifies
+one of the following roles for the variables that follow it:
+
+@table @code
+@item INPUT
+An input variable, such as an independent variable.
+
+@item TARGET
+An output variable, such as an dependent variable.
+
+@item BOTH
+A variable used for input and output.
+
+@item NONE
+No role assigned. (This is a variable's default role.)
+
+@item PARTITION
+Used to break the data into groups for testing.
+
+@item SPLIT
+No meaning except for certain third party software. (This role's
+meaning is unrelated to @cmd{SPLIT FILE}.)
+@end table
+
+The PSPPIRE GUI does not yet use variable roles as intended.
+
+@node VECTOR
+@section VECTOR
+@vindex VECTOR
+
+@display
+Two possible syntaxes:
+ VECTOR @var{vec_name}=@var{var_list}.
+ VECTOR @var{vec_name_list}(@var{count} [@var{format}]).
+@end display
+
+@cmd{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 (@samp{=}) and the variables
+to put in the vector. The variables must be all numeric or all
+string, and string variables must 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
+create variables named @code{@var{vec}1} through
+@code{@var{vec}@var{count}}. By default, the new variables are
+numeric with 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. With a string format such as A8, the
+variables will be string variables; with a numeric format, they will
+be numeric. Variable names including the suffixes may not exceed 64
+characters in length, and none of the variables may exist prior to
+@cmd{VECTOR}.
+
+Vectors created with @cmd{VECTOR} disappear after any procedure or
+procedure-like command is executed. The variables contained in the
+vectors remain, unless they are scratch variables (@pxref{Scratch
+Variables}).
+
+Variables within a vector may be referenced in expressions using
+@code{vector(index)} syntax.
+
+@node MRSETS
+@section MRSETS
+@vindex MRSETS
+
@cmd{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:
+represent multiple responses to a survey question.
+
+Multiple responses are represented in one of the two following ways:
@itemize @bullet
@item
represents one of the responses.
@end itemize
+@display
+MRSETS
+ /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
+ [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
+ [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
+
+ /MCGROUP NAME=@var{name} VARIABLES=@var{var_list} [LABEL='@var{label}']
+
+ /DELETE NAME=@{[@var{names}],ALL@}
+
+ /DISPLAY NAME=@{[@var{names}],ALL@}
+@end display
+
+
Any number of subcommands may be specified in any order.
The @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or
same variable label, since these categories cannot be distinguished in
output.
-@item
+@item
@subcmd{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
response sets. Its syntax is the same as the @subcmd{DELETE} subcommand.
Multiple response sets are saved to and read from system files by,
-e.g., the @cmd{SAVE} and @cmd{GET} command. Otherwise, multiple
+@i{e.g.}, the @cmd{SAVE} and @cmd{GET} command. Otherwise, multiple
response sets are currently used only by third party software.
-@node NUMERIC
-@section NUMERIC
-@vindex NUMERIC
-
-@display
-NUMERIC /@var{var_list} [(@var{fmt_spec})].
-@end display
-
-@cmd{NUMERIC} explicitly declares new numeric variables, optionally
-setting their output formats.
-
-Specify a slash (@samp{/}), 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 (@pxref{Input and Output
-Formats}); otherwise, the default is F8.2.
-
-Variables created with @cmd{NUMERIC} are initialized to the
-system-missing value.
-
-@node PRINT FORMATS
-@section PRINT FORMATS
-@vindex PRINT FORMATS
-
-@display
-PRINT FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
-@end display
-
-@cmd{PRINT FORMATS} sets the print formats for the specified
-variables to the specified format specification.
-
-Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
-but @cmd{PRINT FORMATS} sets only print formats, not write formats.
-
-@node RENAME VARIABLES
-@section RENAME VARIABLES
-@vindex RENAME VARIABLES
-
-@display
-RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
-@end display
-
-@cmd{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 (@samp{=}), 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.
-
-@cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
-to be read.
-
-@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
-(@pxref{TEMPORARY}).
-
-@node VALUE LABELS
-@section VALUE LABELS
-@vindex VALUE LABELS
-
-@display
-VALUE LABELS
- /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
-@end display
-
-@cmd{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 (@samp{/}), followed by a list of values
-and their associated labels, separated by spaces.
-
-Value labels in output are normally broken into lines automatically.
-Put @samp{\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 @cmd{VALUE LABELS} is executed, any existing value labels
-are cleared from the variables specified. Use @cmd{ADD VALUE LABELS}
-(@pxref{ADD VALUE LABELS}) to add value labels without clearing those
-already present.
-
-@node STRING
-@section STRING
-@vindex STRING
-
-@display
-STRING /@var{var_list} (@var{fmt_spec}).
-@end display
-
-@cmd{STRING} creates new string variables for use in
-transformations.
-
-Specify a slash (@samp{/}), followed by the names of the string
-variables to create and the desired output format specification in
-parentheses (@pxref{Input and Output Formats}). Variable widths are
-implicitly derived from the specified output formats.
-
-Created variables are initialized to spaces.
-
-
-@node VARIABLE ATTRIBUTE
-@section VARIABLE ATTRIBUTE
-@vindex VARIABLE ATTRIBUTE
-
-@display
-VARIABLE ATTRIBUTE
- VARIABLES=@var{var_list}
- ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
- ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
- DELETE=@var{name} [@var{name}]@dots{}
- DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
-@end display
-
-@cmd{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 @subcmd{VARIABLES} subcommand must come first. Specify the
-variables to which the following @subcmd{ATTRIBUTE} or @subcmd{DELETE} subcommand
-should apply.
-
-Use the @subcmd{ATTRIBUTE} subcommand to add or modify custom variable
-attributes. Specify the name of the attribute as an identifier
-(@pxref{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 @subcmd{VARIABLES}. Attribute names that begin with
-@code{$} are reserved for @pspp{}'s internal use, and attribute names
-that begin with @code{@@} or @code{$@@} 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
-(@code{[} and @code{]}) 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 @subcmd{DELETE} subcommand to delete an attribute from the variable
-specified on @subcmd{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 @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
-
-@cmd{VARIABLE ATTRIBUTE} takes effect immediately. It is not affected
-by conditional and looping structures such as @cmd{DO IF} or
-@cmd{LOOP}.
-
-@node VARIABLE LABELS
-@section VARIABLE LABELS
-@vindex VARIABLE LABELS
-
-@display
-VARIABLE LABELS
- @var{var_list} '@var{var_label}'
- [ /@var{var_list} '@var{var_label}']
- .
- .
- .
- [ /@var{var_list} '@var{var_label}']
-@end display
-
-@cmd{VARIABLE LABELS} associates explanatory names
-with variables. This name, called a @dfn{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 (@samp{/}).
-
-
-@node VARIABLE ALIGNMENT
-@section VARIABLE ALIGNMENT
-@vindex VARIABLE ALIGNMENT
-
-@display
-VARIABLE ALIGNMENT
- @var{var_list} ( LEFT | RIGHT | CENTER )
- [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
- .
- .
- .
- [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
-@end display
-
-@cmd{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.
-
-
-
-
-@node VARIABLE WIDTH
-@section VARIABLE WIDTH
-@vindex VARIABLE WIDTH
-@display
-VARIABLE WIDTH
- @var{var_list} (width)
- [ /@var{var_list} (width) ]
- .
- .
- .
- [ /@var{var_list} (width) ]
-@end display
-
-@cmd{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.
-
-
-@node VARIABLE LEVEL
-@section VARIABLE LEVEL
-@vindex VARIABLE LEVEL
-@display
-VARIABLE LEVEL
- @var{var_list} ( SCALE | NOMINAL | ORDINAL )
- [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
- .
- .
- .
- [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
-@end display
-
-@cmd{VARIABLE LEVEL} sets the measurement level of variables.
-Currently, this has no effect except for certain third party software.
-
+@node LEAVE
+@section LEAVE
+@vindex LEAVE
-@node VECTOR
-@section VECTOR
-@vindex VECTOR
+@cmd{LEAVE} prevents the specified variables from being
+reinitialized whenever a new case is processed.
@display
-Two possible syntaxes:
- VECTOR @var{vec_name}=@var{var_list}.
- VECTOR @var{vec_name_list}(@var{count} [@var{format}]).
+LEAVE @var{var_list}.
@end display
-@cmd{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 (@samp{=}) 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.
+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 @cmd{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.
-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 @code{@var{vec}1} through @code{@var{vec}@var{count}}
-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 @cmd{VECTOR}.
+This becomes useful for counters. For instance, in the example below
+the variable @code{SUM} maintains a running total of the values in the @code{ITEM}
+variable.
-Vectors created with @cmd{VECTOR} disappear after any procedure or
-procedure-like command is executed. The variables contained in the
-vectors remain, unless they are scratch variables (@pxref{Scratch
-Variables}).
+@example
+DATA LIST /ITEM 1-3.
+COMPUTE SUM=SUM+ITEM.
+PRINT /ITEM SUM.
+LEAVE SUM
+BEGIN DATA.
+123
+404
+555
+999
+END DATA.
+@end example
-Variables within a vector may be referenced in expressions using
-@code{vector(index)} syntax.
+@noindent Partial output from this example:
-@node WRITE FORMATS
-@section WRITE FORMATS
-@vindex WRITE FORMATS
+@example
+123 123.00
+404 527.00
+555 1082.00
+999 2081.00
+@end example
-@display
-WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
-@end display
+It is best to use @cmd{LEAVE} command immediately before invoking a
+procedure command, because the left status of variables is reset by
+certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
+Left status is also reset by all procedure invocations.
-@cmd{WRITE FORMATS} sets the write formats for the specified variables
-to the specified format specification. Its syntax is identical to
-that of @cmd{FORMATS} (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
-write formats, not print formats.
projects / pspp / blobdiff