@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 variable names & descriptions.
-* DISPLAY VECTORS:: Display a list of vectors.
+* 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.
* 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.
@display
ADD VALUE LABELS
- /var_list value 'label' [value 'label']@dots{}
+ /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
@end display
@cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
@vindex DELETE VARIABLES
@display
-DELETE VARIABLES var_list.
+DELETE VARIABLES @var{var_list}.
@end display
@cmd{DELETE VARIABLES} deletes the specified variables from the
dictionary. It may not be used to delete all variables from the
dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
-@cmd{DELETE VARIABLES} should not used after defining transformations
-and before executing a procedure. If it is used in such a context, it
+@cmd{DELETE VARIABLES} should not be used after defining transformations
+but before executing a procedure. If it is used in such a context, it
causes the data to be read. If it is used while @cmd{TEMPORARY} is in
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{var_list}].
+DISPLAY [SORTED] INDEX [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] LABELS [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] VARIABLES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] SCRATCH [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]@var{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 dataset. 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 dataset, in the order that
+variables occur in the active dataset dictionary. The @subcmd{SORTED} keyword
+causes output to be sorted alphabetically by variable name. The
+@subcmd{VARIABLES} subcommand limits output to the specified variables.
@table @asis
@item NAMES
@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.
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.
-@node DISPLAY VECTORS
-@section DISPLAY VECTORS
-@vindex DISPLAY VECTORS
+@item ATTRIBUTES
+@itemx @@ATTRIBUTES
+Datafile and variable attributes are displayed.
+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
-@display
-DISPLAY VECTORS.
-@end display
+With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
+declared vectors. If the @subcmd{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
@vindex FORMATS
@display
-FORMATS var_list (fmt_spec).
+FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
@end display
@cmd{FORMATS} set both print and write formats for the specified
-numeric variables to the specified format specification.
+variables to the specified format specification.
@xref{Input and Output Formats}.
Specify a list of variables followed by a format specification in
parentheses. The print and write formats of the specified variables
-will be changed.
+will be changed. All of the variables listed together must have
+the same type and, for string variables, the same width.
-Additional lists of variables and formats may be included if they are
-delimited by a slash (@samp{/}).
+Additional lists of variables and formats may be included following
+the first one.
@cmd{FORMATS} takes effect immediately. It is not affected by
conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
@vindex LEAVE
@display
-LEAVE var_list.
+LEAVE @var{var_list}.
@end display
@cmd{LEAVE} prevents the specified variables from being
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.
After that, it retains its value between cases.
This becomes useful for counters. For instance, in the example below
-the variable SUM maintains a running total of the values in the ITEM
+the variable @code{SUM} maintains a running total of the values in the @code{ITEM}
variable.
@example
@vindex MISSING VALUES
@display
-MISSING VALUES var_list (missing_values).
-
-missing_values takes one of the following forms:
- num1
- num1, num2
- num1, num2, num3
- num1 THRU num2
- num1 THRU num2, num3
- string1
- string1, string2
- string1, string2, string3
-As part of a range, LO or LOWEST may take the place of num1;
-HI or HIGHEST may take the place of num2.
+MISSING VALUES @var{var_list} (@var{missing_values}).
+
+where @var{missing_values} takes one of the following forms:
+ @var{num1}
+ @var{num1}, @var{num2}
+ @var{num1}, @var{num2}, @var{num3}
+ @var{num1} THRU @var{num2}
+ @var{num1} THRU @var{num2}, @var{num3}
+ @var{string1}
+ @var{string1}, @var{string2}
+ @var{string1}, @var{string2}, @var{string3}
+As part of a range, @subcmd{LO} or @subcmd{LOWEST} may take the place of @var{num1};
+@subcmd{HI} or @subcmd{HIGHEST} may take the place of @var{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,
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 keyword LO or LOWEST or HI or HIGHEST.
+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
affected by conditional and looping constructs such as @cmd{DO IF} or
@display
MODIFY VARS
- /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
- /RENAME=(old_names=new_names)@dots{}
- /@{DROP,KEEP@}=var_list
+ /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (@var{var_list})@dots{}
+ /RENAME=(@var{old_names}=@var{new_names})@dots{}
+ /@{DROP,KEEP@}=@var{var_list}
/MAP
@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.
+specified more than once. @subcmd{DROP} and @subcmd{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
+The @subcmd{REORDER} subcommand changes the order of variables in the active
+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.
+keyword @subcmd{BACKWARD} before the parentheses. To put them into alphabetical
+order in the dictionary, specify keyword @subcmd{ALPHA} before the parentheses.
+@subcmd{BACKWARD} and @subcmd{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 @subcmd{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
the corresponding new variable name. Multiple parenthesized groups of
variables may be specified.
-The DROP subcommand deletes a specified list of variables from the
-active file.
+The @subcmd{DROP} subcommand deletes a specified list of variables from the
+active dataset.
-The KEEP subcommand keeps the specified list of variables in the active
-file. Any unlisted variables are deleted from the active file.
+The @subcmd{KEEP} subcommand keeps the specified list of variables in the active
+dataset. Any unlisted variables are deleted from the active dataset.
-MAP is currently ignored.
+@subcmd{MAP} is currently ignored.
-If either DROP or KEEP is specified, the data is read; otherwise it is
-not.
+If either @subcmd{DROP} or @subcmd{KEEP} is specified, the data is read;
+otherwise it is not.
@cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}).
+@node MRSETS
+@section MRSETS
+@vindex MRSETS
+
+@display
+MRSETS
+ /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
+ [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
+ [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
+
+ /MCGROUP NAME=@var{name} VARIABLES=@var{var_list} [LABEL='@var{label}']
+
+ /DELETE NAME=@{[@var{names}],ALL@}
+
+ /DISPLAY NAME=@{[@var{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 @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or
+replaces an existing multiple response set. The @subcmd{NAME},
+@subcmd{VARIABLES}, and
+@subcmd{VALUE} specifications are required. The others are optional:
+
+@itemize @bullet
+@item
+@var{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
+@subcmd{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
+@subcmd{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
+@subcmd{CATEGORYLABELS} optionally specifies the source of the labels for each
+category in the set:
+
+@itemize @minus
+@item
+@subcmd{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
+@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
+such categories cannot be distinguished in output.
+@end itemize
+
+@item
+@subcmd{LABEL} optionally specifies a label for the multiple response set. If
+neither @subcmd{LABEL} nor @subcmd{LABELSOURCE=VARLABEL} is specified, the set is
+unlabeled.
+
+@item
+@subcmd{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.
+@subcmd{LABELSOURCE=VARLABEL} must be used with @subcmd{CATEGORYLABELS=COUNTEDVALUES}.
+It is mutually exclusive with @subcmd{LABEL}.
+@end itemize
+
+The @subcmd{MCGROUP} subcommand creates a new multiple category set or
+replaces an existing multiple response set. The @subcmd{NAME} and @subcmd{VARIABLES}
+specifications are required, and @subcmd{LABEL} is optional. Their meanings
+are as described above in @subcmd{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 @subcmd{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 @subcmd{DISPLAY} subcommand displays information about defined multiple
+response sets. Its syntax is the same as the @subcmd{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 NUMERIC
@section NUMERIC
@vindex NUMERIC
@display
-NUMERIC /var_list [(fmt_spec)].
+NUMERIC /@var{var_list} [(@var{fmt_spec})].
@end display
@cmd{NUMERIC} explicitly declares new numeric variables, optionally
@vindex PRINT FORMATS
@display
-PRINT FORMATS var_list (fmt_spec).
+PRINT FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
@end display
@cmd{PRINT FORMATS} sets the print formats for the specified
-numeric variables to the specified format specification.
+variables to the specified format specification.
Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
but @cmd{PRINT FORMATS} sets only print formats, not write formats.
@vindex RENAME VARIABLES
@display
-RENAME VARIABLES (old_names=new_names)@dots{} .
+RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
@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
@display
VALUE LABELS
- /var_list value 'label' [value 'label']@dots{}
+ /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
@end display
@cmd{VALUE LABELS} allows values of numeric and short string
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.
+
+Value labels in output are normally broken into lines automatically.
+Put @samp{\n} in a label string to force a line break at that point.
+The label may still be broken into lines at additional points.
Before @cmd{VALUE LABELS} is executed, any existing value labels
are cleared from the variables specified. Use @cmd{ADD VALUE LABELS}
@vindex STRING
@display
-STRING /var_list (fmt_spec).
+STRING /@var{var_list} (@var{fmt_spec}).
@end display
@cmd{STRING} creates new string variables for use in
Created variables are initialized to spaces.
+@node VARIABLE ATTRIBUTE
+@section VARIABLE ATTRIBUTE
+@vindex VARIABLE ATTRIBUTE
+
+@display
+VARIABLE ATTRIBUTE
+ VARIABLES=@var{var_list}
+ ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
+ ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
+ DELETE=@var{name} [@var{name}]@dots{}
+ DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
+@end display
+
+@cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
+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 required @subcmd{VARIABLES} subcommand must come first. Specify the
+variables to which the following @subcmd{ATTRIBUTE} or @subcmd{DELETE} subcommand
+should apply.
+
+Use the @subcmd{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 @subcmd{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 @subcmd{DELETE} subcommand to delete an attribute from the variable
+specified on @subcmd{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 dataset, 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
@display
VARIABLE LABELS
- var_list 'var_label'
- [ /var_list 'var_label']
+ @var{var_list} '@var{var_label}'
+ [ /@var{var_list} '@var{var_label}']
.
.
.
- [ /var_list 'var_label']
+ [ /@var{var_list} '@var{var_label}']
@end display
@cmd{VARIABLE LABELS} associates explanatory names
@node VARIABLE ALIGNMENT
-@comment node-name, next, previous, u
@section VARIABLE ALIGNMENT
@vindex VARIABLE ALIGNMENT
@display
VARIABLE ALIGNMENT
- var_list ( LEFT | RIGHT | CENTER )
- [ /var_list ( LEFT | RIGHT | CENTER ) ]
+ @var{var_list} ( LEFT | RIGHT | CENTER )
+ [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
.
.
.
- [ /var_list ( LEFT | RIGHT | CENTER ) ]
+ [ /@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
-the display of variables in the PSPP output.
+the display of variables in the @pspp{} output.
@node VARIABLE WIDTH
-@comment node-name, next, previous, up
@section VARIABLE WIDTH
@vindex VARIABLE WIDTH
@display
VARIABLE WIDTH
- var_list (width)
- [ /var_list (width) ]
+ @var{var_list} (width)
+ [ /@var{var_list} (width) ]
.
.
.
- [ /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
-the display of variables in the PSPP output.
+the display of variables in the @pspp{} output.
@node VARIABLE LEVEL
-@comment node-name, next, previous, up
@section VARIABLE LEVEL
@vindex VARIABLE LEVEL
@display
VARIABLE LEVEL
- var_list ( SCALE | NOMINAL | ORDINAL )
- [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
+ @var{var_list} ( SCALE | NOMINAL | ORDINAL )
+ [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
.
.
.
- [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
+ [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
@end display
@cmd{VARIABLE LEVEL} sets the measurement level of variables.
@display
Two possible syntaxes:
- VECTOR vec_name=var_list.
- VECTOR vec_name_list(count [format]).
+ VECTOR @var{vec_name}=@var{var_list}.
+ VECTOR @var{vec_name_list}(@var{count} [@var{format}]).
@end display
@cmd{VECTOR} allows a group of variables to be accessed as if they
@vindex WRITE FORMATS
@display
-WRITE FORMATS var_list (fmt_spec).
+WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
@end display
-@cmd{WRITE FORMATS} sets the write formats for the specified numeric
-variables
+@cmd{WRITE FORMATS} sets the write formats for the specified variables
to the specified format specification. Its syntax is identical to
-that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
+that of @cmd{FORMATS} (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
write formats, not print formats.
-@setfilename ignored
projects / pspp / blobdiff