X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fvariables.texi;h=a47de44afdcc471e93645da3b32fcb1b8b24b216;hb=308c33df7c1be1edd6b2ebdf10b901fe05903438;hp=68a996681d1db8830c4d256ab65c15ff2d701947;hpb=4dc6293d51b59324286be41465587a72f133ea0b;p=pspp diff --git a/doc/variables.texi b/doc/variables.texi index 68a996681d..a47de44afd 100644 --- a/doc/variables.texi +++ b/doc/variables.texi @@ -1,3 +1,12 @@ +@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 @@ -16,6 +25,7 @@ several utility functions for examining and adjusting them. * 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. @@ -32,7 +42,7 @@ several utility functions for examining and adjusting them. @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 @@ -110,7 +120,7 @@ Variables}). @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 @@ -224,7 +234,7 @@ 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 +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 @@ -235,12 +245,12 @@ affected by conditional and looping constructs such as @cmd{DO IF} or @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 @@ -265,8 +275,10 @@ same number of old and new variable names. Each old variable is renamed to the corresponding new variable name. Multiple parenthesized groups of variables may be specified. -The @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. @@ -284,7 +296,7 @@ otherwise it is not. @vindex MRSETS @display -MRSETS +MRSETS /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value} [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}] [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}] @@ -349,7 +361,7 @@ variable labels, variable names. @pspp{} warns if two variables have the 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 @@ -392,15 +404,15 @@ response sets are currently used only by third party software. @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 @@ -443,11 +455,87 @@ 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 @@ -487,7 +575,7 @@ transformations. 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. @@ -580,7 +668,7 @@ by conditional and looping structures such as @cmd{DO IF} or @display VARIABLE LABELS - @var{var_list} '@var{var_label}' + @var{var_list} '@var{var_label}' [ /@var{var_list} '@var{var_label}'] . . @@ -592,9 +680,9 @@ VARIABLE LABELS 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{/}). @@ -612,8 +700,8 @@ VARIABLE ALIGNMENT [ /@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. @@ -625,15 +713,15 @@ 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. @@ -705,18 +793,20 @@ 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. +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