X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fvariables.texi;h=6b4e574e724903a2dc9a42a5deecbfe00f2e4523;hb=c75794cffb05769b71a346af8513a3e8dde55f94;hp=46c6df8f6cac9037fdfe42aef55b0c2f83501bdb;hpb=43b1296aafe7582e7dbe6c2b6a8b478d7d9b0fcf;p=pspp diff --git a/doc/variables.texi b/doc/variables.texi index 46c6df8f6c..6b4e574e72 100644 --- a/doc/variables.texi +++ b/doc/variables.texi @@ -7,17 +7,18 @@ several utility functions for examining and adjusting them. @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. +* DISPLAY:: Display information about the active file. * 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. * RENAME VARIABLES:: Rename variables. * VALUE LABELS:: Set value labels for variables. * STRING:: Create new string 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. @@ -61,15 +62,26 @@ effect, it causes the temporary transformations to become permanent. @vindex DISPLAY @display -DISPLAY @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH@} - [SORTED] [var_list] +DISPLAY [SORTED] NAMES [[/VARIABLES=]var_list]. +DISPLAY [SORTED] INDEX [[/VARIABLES=]var_list]. +DISPLAY [SORTED] LABELS [[/VARIABLES=]var_list]. +DISPLAY [SORTED] VARIABLES [[/VARIABLES=]var_list]. +DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]var_list]. +DISPLAY [SORTED] SCRATCH [[/VARIABLES=]var_list]. +DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]var_list]. +DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]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. +@cmd{DISPLAY} displays information about the active file. A variety +of different forms of information can be requested. -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 file, in the order that +variables occur in the active file dictionary. The SORTED keyword +causes output to be sorted alphabetically by variable name. The +VARIABLES subcommand limits output to the specified variables. @table @asis @item NAMES @@ -91,23 +103,24 @@ Variable names, positions, print and write formats, missing values, 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 +Datafile and variable attributes are displayed, except that attributes +whose names begin with @code{@@} or @code{$@@} are omitted. -@node DISPLAY VECTORS -@section DISPLAY VECTORS -@vindex DISPLAY VECTORS +@itemx @@ATTRIBUTES +All datafile and variable attributes are displayed. +@end table -@display -DISPLAY VECTORS. -@end display +With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently +declared vectors. If the 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. -@cmd{DISPLAY VECTORS} lists all the currently declared vectors. +For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY +FILE LABEL}. @node FORMATS @section FORMATS @@ -200,9 +213,10 @@ As part of a range, LO or LOWEST may take the place of num1; HI or HIGHEST may take the place of num2. @end display -@cmd{MISSING VALUES} sets user-missing values for numeric and -short string variables. Long string variables may not have missing -values. +@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. 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, @@ -280,6 +294,113 @@ Formats}); otherwise, the default is F8.2. Variables created with @cmd{NUMERIC} are initialized to the system-missing value. +@node MRSETS +@section MRSETS +@vindex MRSETS + +@display +MRSETS + /MDGROUP NAME=name VARIABLES=var_list VALUE=value + [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}] + [@{LABEL='label',LABELSOURCE=VARLABEL@}] + + /MCGROUP NAME=name VARIABLES=var_list [LABEL='label'] + + /DELETE NAME=@{[names],ALL@} + + /DISPLAY NAME=@{[names],ALL@} +@end display + +@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: + +@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 + +Any number of subcommands may be specified in any order. + +The MDGROUP subcommand creates a new multiple dichotomy set or +replaces an existing multiple response set. The NAME, VARIABLES, and +VALUE specifications are required. The others are optional: + +@itemize @bullet +@item +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 +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 +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 +CATEGORYLABELS optionally specifies the source of the labels for each +category in the set: + +@itemize @minus +@item +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 +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 +LABEL optionally specifies a label for the multiple response set. If +neither LABEL nor LABELSOURCE=VARLABEL is specified, the set is +unlabeled. + +@item +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. +LABELSOURCE=VARLABEL must be used with CATEGORYLABELS=COUNTEDVALUES. +It is mutually exclusive with LABEL. +@end itemize + +The MCGROUP subcommand creates a new multiple category set or +replaces an existing multiple response set. The NAME and VARIABLES +specifications are required, and LABEL is optional. Their meanings +are as described above to 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 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 DISPLAY subcommand displays information about defined multiple +response sets. Its syntax is the same as the 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 +response sets are currently used only by third party software. + @node PRINT FORMATS @section PRINT FORMATS @vindex PRINT FORMATS @@ -330,8 +451,7 @@ 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. Long string -variables may not be specified. +and their associated labels, separated by spaces. Before @cmd{VALUE LABELS} is executed, any existing value labels are cleared from the variables specified. Use @cmd{ADD VALUE LABELS} @@ -357,6 +477,60 @@ 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_list + ATTRIBUTE=name('value') [name('value')]@dots{} + ATTRIBUTE=name@b{[}index@b{]}('value') [name@b{[}index@b{]}('value')]@dots{} + DELETE=name [name]@dots{} + DELETE=name@b{[}index@b{]} [name@b{[}index@b{]}]@dots{} +@end display + +@cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined +attributes associated with variables in the active file. 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 VARIABLES subcommand must come first. Specify the +variables to which the following ATTRIBUTE or DELETE subcommand +should apply. + +Use the 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 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 DELETE subcommand to delete an attribute from the variable +specified on 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 file, 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 @@ -378,7 +552,7 @@ 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, -preceed the subsequent variable list with a slash (@samp{/}). +precede the subsequent variable list with a slash (@samp{/}). @node VARIABLE ALIGNMENT @@ -489,4 +663,3 @@ 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