-@node Variable Attributes
-@chapter Manipulating variables
-
-The variables in the active file 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 variable names & descriptions.
-* DISPLAY VECTORS:: Display a list of vectors.
-* 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.
+* DISPLAY:: Display information about the active dataset.
* NUMERIC:: Create new numeric variables.
-* PRINT FORMATS:: Set variable print formats.
-* RENAME VARIABLES:: Rename variables.
-* VALUE LABELS:: Set value labels for variables.
* 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.
+* ADD VALUE LABELS:: Add value labels to variables.
+* MISSING VALUES:: Set missing values for variables.
+* VARIABLE ATTRIBUTE:: Set custom attributes on 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_list value 'label' [value '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_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 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 @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 @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH@}
- [SORTED] [var_list]
+DISPLAY [SORTED] NAMES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] INDEX [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] LABELS [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] VARIABLES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] SCRATCH [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] VECTORS.
@end display
-@cmd{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:
+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.
@table @asis
@item NAMES
@item INDEX
The variables' names are displayed along with a value describing their
-position within the active file dictionary.
+position within the active dataset dictionary.
@item LABELS
Variable names, positions, and variable labels are displayed.
variable labels, and value labels are displayed.
@item SCRATCH
-Varible names are displayed, for scratch variables only (@pxref{Scratch
+Variable names are displayed, for scratch variables only (@pxref{Scratch
Variables}).
-@end table
-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.
+@item ATTRIBUTES
+@itemx @@ATTRIBUTES
+Datafile and variable attributes are displayed.
+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
-@node DISPLAY VECTORS
-@section DISPLAY VECTORS
-@vindex DISPLAY VECTORS
+With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
+declared vectors. If the @subcmd{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.
-@display
-DISPLAY VECTORS.
-@end display
+For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
+FILE LABEL}.
-@cmd{DISPLAY VECTORS} lists all the currently declared vectors.
+@node NUMERIC
+@section NUMERIC
+@vindex NUMERIC
-@node FORMATS
-@section FORMATS
-@vindex FORMATS
+@cmd{NUMERIC} explicitly declares new numeric variables, optionally
+setting their output formats.
@display
-FORMATS var_list (fmt_spec).
+NUMERIC @var{var_list} [(@var{fmt_spec})] [/@var{var_list} [(@var{fmt_spec})]]@dots{}
@end display
-@cmd{FORMATS} set both print and write formats for the specified
-numeric variables to the specified format specification.
-@xref{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.
+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.
-Additional lists of variables and formats may be included if they are
-delimited by a slash (@samp{/}).
+Variables created with @cmd{NUMERIC} are initialized to the
+system-missing value.
-@cmd{FORMATS} takes effect immediately. It is not affected by
-conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
+@node STRING
+@section STRING
+@vindex STRING
-@node LEAVE
-@section LEAVE
-@vindex LEAVE
+@cmd{STRING} creates new string variables.
@display
-LEAVE var_list.
+STRING @var{var_list} (@var{fmt_spec}) [/@var{var_list} (@var{fmt_spec})] [@dots{}].
@end display
-@cmd{LEAVE} prevents the specified variables from being
-reinitialized whenever a new case is processed.
+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.
-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 @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.
+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{/}).
-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.
+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
-DATA LIST /ITEM 1-3.
-COMPUTE SUM=SUM+ITEM.
-PRINT /ITEM SUM.
-LEAVE SUM
-BEGIN DATA.
-123
-404
-555
-999
-END DATA.
+STRING firstname lastname (A24).
+STRING address (A80).
@end example
-@noindent Partial output from this example:
+@noindent @dots{} and here is yet another way:
@example
-123 123.00
-404 527.00
-555 1082.00
-999 2081.00
+STRING firstname (A24).
+STRING lastname (A24).
+STRING address (A80).
@end example
-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 RENAME VARIABLES
+@section RENAME VARIABLES
+@vindex RENAME VARIABLES
-@node MISSING VALUES
-@section MISSING VALUES
-@vindex MISSING VALUES
+@cmd{RENAME VARIABLES} changes the names of variables in the active
+dataset.
@display
-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.
+RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
@end display
-@cmd{MISSING VALUES} sets user-missing values for numeric and
-short string variables. Long string variables may not have missing
-values.
+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.
-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.
+@cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
+to be read.
-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}.
+@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}).
-@node MODIFY VARS
-@section MODIFY VARS
-@vindex MODIFY VARS
+@node SORT VARIABLES
+@section SORT VARIABLES
+@vindex SORT VARIABLES
-@display
-MODIFY VARS
- /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
- /RENAME=(old_names=new_names)@dots{}
- /@{DROP,KEEP@}=var_list
- /MAP
+@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
-@cmd{MODIFY VARS} reorders, renames, and deletes variables in the
-active file.
+The main specification is one of the following identifiers, which
+determines how the variables are sorted:
-At least one subcommand must be specified, and no subcommand may be
-specified more than once. DROP and KEEP may not both be specified.
+@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
-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.
+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:
-To rename variables in the active file, specify 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.
+@example
+SORT VARIABLES BY COLUMNS.
+SORT VARIABLES BY ALIGNMENT.
+@end example
-The DROP subcommand deletes a specified list of variables from the
-active file.
+Specify @code{(D)} to reverse the sort order.
-The KEEP subcommand keeps the specified list of variables in the active
-file. Any unlisted variables are deleted from the active file.
+@node DELETE VARIABLES
+@section DELETE VARIABLES
+@vindex DELETE VARIABLES
-MAP is currently ignored.
+@cmd{DELETE VARIABLES} deletes the specified variables from the dictionary.
-If either DROP or KEEP is specified, the data is read; otherwise it is
-not.
+@display
+DELETE VARIABLES @var{var_list}.
+@end display
-@cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
-(@pxref{TEMPORARY}).
+@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 NUMERIC
-@section NUMERIC
-@vindex NUMERIC
+@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 the name is limited to certain constraints (@pxref{Attributes}) a variable's
+label has no such constraints.
+Typically, the names are concise, easy to type mnemonics for the variable
+and the labels are longer, more verbose descriptions.
@display
-NUMERIC /var_list [(fmt_spec)].
+VARIABLE LABELS
+ @var{var_list} '@var{var_label}'
+ [ /@var{var_list} '@var{var_label}']
+ .
+ .
+ .
+ [ /@var{var_list} '@var{var_label}']
@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.
+@cmd{VARIABLE LABELS} associates explanatory names
+with variables. This name, called a @dfn{variable label}, is displayed by
+statistical procedures.
-Variables created with @cmd{NUMERIC} are initialized to the
-system-missing value.
+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 PRINT FORMATS
@section PRINT FORMATS
@vindex PRINT FORMATS
@display
-PRINT FORMATS var_list (fmt_spec).
+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
-numeric variables to the specified format specification.
+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
+@node WRITE FORMATS
+@section WRITE FORMATS
+@vindex WRITE FORMATS
@display
-RENAME VARIABLES (old_names=new_names)@dots{} .
+WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
@end display
-@cmd{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 (@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{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.
-@cmd{RENAME VARIABLES} takes effect immediately. It does not cause the data
-to be read.
+@node FORMATS
+@section FORMATS
+@vindex FORMATS
-@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
-(@pxref{TEMPORARY}).
+@display
+FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
+@end display
+
+@cmd{FORMATS} set both print and write formats for the specified
+variables to the specified format specification.
+@xref{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.
+
+@cmd{FORMATS} takes effect immediately. It is not affected by
+conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
@node VALUE LABELS
@section VALUE LABELS
@vindex VALUE LABELS
-@display
+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
VALUE LABELS
- /var_list value 'label' [value 'label']@dots{}
+ /@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.
+@cmd{VALUE LABELS} allows values of variables to be associated with labels.
-To set up value labels for a set of variables, specify the
+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. Long string
-variables may not be specified.
+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
+@node ADD VALUE LABELS
+@section ADD VALUE LABELS
+@vindex ADD VALUE LABELS
+
+@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
-STRING /var_list (fmt_spec).
+ADD VALUE LABELS
+ /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
@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 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.
-@node VARIABLE LABELS
-@section VARIABLE LABELS
-@vindex VARIABLE LABELS
+The @cmd{MISSING VALUES} command sets user-missing values for variables.
@display
-VARIABLE LABELS
- var_list 'var_label'
- [ /var_list 'var_label']
- .
- .
- .
- [ /var_list 'var_label']
+MISSING VALUES @var{var_list} (@var{missing_values}).
+
+where @var{missing_values} takes one of the following forms:
+ @var{num1}
+ @var{num1}, @var{num2}
+ @var{num1}, @var{num2}, @var{num3}
+ @var{num1} THRU @var{num2}
+ @var{num1} THRU @var{num2}, @var{num3}
+ @var{string1}
+ @var{string1}, @var{string2}
+ @var{string1}, @var{string2}, @var{string3}
+As part of a range, @subcmd{LO} or @subcmd{LOWEST} may take the place of @var{num1};
+@subcmd{HI} or @subcmd{HIGHEST} may take the place of @var{num2}.
@end display
-@cmd{VARIABLE LABELS} associates explanatory names
-with variables. This name, called a @dfn{variable label}, is displayed by
-statistical procedures.
+@cmd{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.
-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{/}).
+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 @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 VARIABLE ATTRIBUTE
+@section VARIABLE ATTRIBUTE
+@vindex VARIABLE ATTRIBUTE
+
+@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.
+
+@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 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 ALIGNMENT
-@comment node-name, next, previous, u
@section VARIABLE ALIGNMENT
@vindex VARIABLE ALIGNMENT
+@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
VARIABLE ALIGNMENT
- var_list ( LEFT | RIGHT | CENTER )
- [ /var_list ( LEFT | RIGHT | CENTER ) ]
+ @var{var_list} ( LEFT | RIGHT | CENTER )
+ [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
.
.
.
- [ /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
-@comment node-name, next, previous, up
@section VARIABLE WIDTH
@vindex VARIABLE WIDTH
@display
VARIABLE WIDTH
- var_list (width)
- [ /var_list (width) ]
+ @var{var_list} (width)
+ [ /@var{var_list} (width) ]
.
.
.
- [ /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.
+purposes. It does not affect the display of variables in the @pspp{} output.
@node VARIABLE LEVEL
-@comment node-name, next, previous, up
@section VARIABLE LEVEL
@vindex VARIABLE LEVEL
@display
-VARIABLE LEVEL
- var_list ( SCALE | NOMINAL | ORDINAL )
- [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
- .
- .
- .
- [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
+@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 LEVEL} sets the measurement level of variables.
-Currently, this has no effect except for certain third party software.
+@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
@display
Two possible syntaxes:
- VECTOR vec_name=var_list.
- VECTOR vec_name_list(count [format]).
+ 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
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.
+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 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}.
+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
Variables within a vector may be referenced in expressions using
@code{vector(index)} syntax.
-@node WRITE FORMATS
-@section WRITE FORMATS
-@vindex WRITE FORMATS
+@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 survey question.
+
+Multiple responses are represented in one of the two following ways:
+
+@itemize @bullet
+@item
+A @dfn{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.
+
+@item
+A @dfn{multiple category set} represents a survey question where the
+respondent is instructed to list up to @var{n} choices. Each variable
+represents one of the responses.
+@end itemize
@display
-WRITE FORMATS var_list (fmt_spec).
+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
-@cmd{WRITE FORMATS} sets the write formats for the specified numeric
-variables
-to the specified format specification. Its syntax is identical to
-that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
-write formats, not print formats.
-@setfilename ignored
+
+Any number of subcommands may be specified in any order.
+
+The @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or
+replaces an existing multiple response set. The @subcmd{NAME},
+@subcmd{VARIABLES}, and
+@subcmd{VALUE} specifications are required. The others are optional:
+
+@itemize @bullet
+@item
+@var{NAME} specifies the name used in syntax for the new multiple dichotomy
+set. The name must begin with @samp{$}; it must otherwise follow the
+rules for identifiers (@pxref{Tokens}).
+
+@item
+@subcmd{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.
+
+@item
+@subcmd{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).
+
+@item
+@subcmd{CATEGORYLABELS} optionally specifies the source of the labels for each
+category in the set:
+
+@itemize @minus
+@item
+@subcmd{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.
+
+@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
+such categories cannot be distinguished in output.
+@end itemize
+
+@item
+@subcmd{LABEL} optionally specifies a label for the multiple response set. If
+neither @subcmd{LABEL} nor @subcmd{LABELSOURCE=VARLABEL} is specified, the set is
+unlabeled.
+
+@item
+@subcmd{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.
+@subcmd{LABELSOURCE=VARLABEL} must be used with @subcmd{CATEGORYLABELS=COUNTEDVALUES}.
+It is mutually exclusive with @subcmd{LABEL}.
+@end itemize
+
+The @subcmd{MCGROUP} subcommand creates a new multiple category set or
+replaces an existing multiple response set. The @subcmd{NAME} and @subcmd{VARIABLES}
+specifications are required, and @subcmd{LABEL} is optional. Their meanings
+are as described above in @subcmd{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 @subcmd{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 @subcmd{DISPLAY} subcommand displays information about defined multiple
+response sets. Its syntax is the same as the @subcmd{DELETE} subcommand.
+
+Multiple response sets are saved to and read from system files by,
+@i{e.g.}, the @cmd{SAVE} and @cmd{GET} command. Otherwise, multiple
+response sets are currently used only by third party software.
+
+@node LEAVE
+@section LEAVE
+@vindex LEAVE
+
+@cmd{LEAVE} prevents the specified variables from being
+reinitialized whenever a new case is processed.
+
+@display
+LEAVE @var{var_list}.
+@end display
+
+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.
+
+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.
+
+@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
+
+@noindent Partial output from this example:
+
+@example
+123 123.00
+404 527.00
+555 1082.00
+999 2081.00
+@end example
+
+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.
+
projects / pspp / blobdiff