@node Variable Attributes
@chapter Manipulating variables
-The variables in the active file dictionary are important. There are
+The variables in the active dataset dictionary are important. There are
several utility functions for examining and adjusting them.
@menu
* ADD VALUE LABELS:: Add value labels to variables.
* DELETE VARIABLES:: Delete variables.
-* DISPLAY:: Display information about the active file.
+* DISPLAY:: Display information about the active dataset.
* 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.
DISPLAY [SORTED] VECTORS.
@end display
-@cmd{DISPLAY} displays information about the active file. A variety
+@cmd{DISPLAY} displays information about the active dataset. A variety
of different forms of information can be requested.
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
+displayed about all variable in the active dataset, in the order that
+variables occur in the active dataset dictionary. The SORTED keyword
causes output to be sorted alphabetically by variable name. The
VARIABLES subcommand limits output to the specified variables.
@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.
reinitialized whenever a new case is processed.
Normally, when a data file is processed, every variable in the active
-file is initialized to the system-missing value or spaces at the
+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.
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,
@end display
@cmd{MODIFY VARS} reorders, renames, and deletes variables in the
-active file.
+active dataset.
At least one subcommand must be specified, and no subcommand may be
specified more than once. DROP and KEEP may not both be specified.
The REORDER subcommand changes the order of variables in the active
-file. Specify one or more lists of variable names in parentheses. By
+dataset. 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.
-To rename variables in the active file, specify RENAME, an equals sign
+To rename variables in the active dataset, 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
variables may be specified.
The DROP subcommand deletes a specified list of variables from the
-active file.
+active dataset.
The KEEP subcommand keeps the specified list of variables in the active
-file. Any unlisted variables are deleted from the active file.
+dataset. Any unlisted variables are deleted from the active dataset.
MAP is currently ignored.
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
@end display
@cmd{RENAME VARIABLES} changes the names of variables in the active
-file. Specify lists of the old variable names and new
+dataset. 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
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}
@end display
@cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
-attributes associated with variables in the active file. Custom
+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.
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
+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
projects / pspp-builds.git / blobdiff