+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017 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 Variable Attributes
@chapter Manipulating variables
* NUMERIC:: Create new numeric variables.
* PRINT FORMATS:: Set variable print formats.
* RENAME VARIABLES:: Rename variables.
+* SORT VARIABLES:: Reorder variables.
* VALUE LABELS:: Set value labels for variables.
* STRING:: Create new string 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.
@end menu
@section ADD VALUE LABELS
@vindex ADD VALUE LABELS
-@display
+@display
ADD VALUE LABELS
/@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
@end display
@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
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
@section MODIFY VARS
@vindex MODIFY VARS
-@display
+@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
+ /MAP
@end display
@cmd{MODIFY VARS} reorders, renames, and deletes variables in the
the corresponding new variable name. Multiple parenthesized groups of
variables may be specified.
-The @subcmd{DROP} subcommand deletes a specified list of variables from the
-active dataset.
+The @subcmd{DROP} subcommand deletes a specified list of variables
+from the active dataset. @cmd{MODIFY VARS} may not be used to delete
+all variables from the dictionary; use @cmd{NEW FILE} to do that
+(@pxref{NEW FILE}).
The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
dataset. Any unlisted variables are deleted from the active dataset.
@vindex MRSETS
@display
-MRSETS
+MRSETS
/MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
[CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
[@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
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
@vindex NUMERIC
@display
-NUMERIC /@var{var_list} [(@var{fmt_spec})].
+NUMERIC @var{var_list} [(@var{fmt_spec})] [/@var{var_list} [(@var{fmt_spec})]]@dots{}
@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
+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
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
+
+@display
+SORT VARIABLES [BY]
+ (NAME | TYPE | FORMAT | LABEL | VALUES | MISSING | MEASURE
+ | ROLE | COLUMNS | ALIGNMENT | ATTRIBUTE @var{name})
+ [(D)].
+@end display
+
+@cmd{SORT VARIABLES} reorders the variables in the active dataset.
+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 VALUE LABELS
@section VALUE LABELS
@vindex VALUE LABELS
-@display
+@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
+@cmd{VALUE LABELS} allows values of
variables to be associated with labels. In this way, a short value can
-stand for a long value.
+stand for a longer, more descriptive label.
-To set up value labels for a set of variables, specify the
+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.
+
+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.
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}).
+parentheses (@pxref{Input and Output Formats}).
Variable widths are
implicitly derived from the specified output formats.
The created variables will be initialized to spaces.
@display
VARIABLE LABELS
- @var{var_list} '@var{var_label}'
+ @var{var_list} '@var{var_label}'
[ /@var{var_list} '@var{var_label}']
.
.
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
+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,
+To assign different labels to different variables in the same command,
precede the subsequent variable list with a slash (@samp{/}).
[ /@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
+@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.
@display
VARIABLE WIDTH
@var{var_list} (width)
- [ /@var{var_list} (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
+purposes. This only affects third party software. It does not affect
the display of variables in the @pspp{} output.
Currently, this has no effect except for certain third party software.
+@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
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
projects / pspp / blobdiff