+@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.
@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
@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.
+
+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 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.
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.
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