+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017, 2020 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 Data Manipulation
@chapter Data transformations
@cindex transformations
-The PSPP procedures examined in this chapter manipulate data and
-prepare the active file for later analyses. They do not produce output,
+The @pspp{} procedures examined in this chapter manipulate data and
+prepare the active dataset for later analyses. They do not produce output,
as a rule.
@menu
* FLIP:: Exchange variables with cases.
* IF:: Conditionally assigning a calculated value.
* RECODE:: Mapping values from one set to another.
-* SORT CASES:: Sort the active file.
+* SORT CASES:: Sort the active dataset.
@end menu
@node AGGREGATE
@vindex AGGREGATE
@display
-AGGREGATE
- OUTFILE=@{*,'file-name',file_handle@}
+AGGREGATE
+ OUTFILE=@{*,'@var{file_name}',@var{file_handle}@} [MODE=@{REPLACE, ADDVARIABLES@}]
/PRESORTED
/DOCUMENT
/MISSING=COLUMNWISE
- /BREAK=var_list
- /dest_var['label']@dots{}=agr_func(src_vars, args@dots{})@dots{}
+ /BREAK=@var{var_list}
+ /@var{dest_var}['@var{label}']@dots{}=@var{agr_func}(@var{src_vars}, @var{args}@dots{})@dots{}
@end display
@cmd{AGGREGATE} summarizes groups of cases into single cases.
variables called @dfn{break variables}. Several functions are available
for summarizing case contents.
-The OUTFILE subcommand is required and must appear first. Specify a
-system file, portable file, or scratch file by file name or file
-handle (@pxref{File Handles}).
+The @subcmd{OUTFILE} subcommand is required and must appear first. Specify a
+system file or portable file by file name or file
+handle (@pxref{File Handles}), or a dataset by its name
+(@pxref{Datasets}).
The aggregated cases are written to this file. If @samp{*} is
-specified, then the aggregated cases replace the active file. Use of
-OUTFILE to write a portable file or scratch file is a PSPP extension.
-
-By default, the active file will be sorted based on the break variables
-before aggregation takes place. If the active file is already sorted
+specified, then the aggregated cases replace the active dataset's data.
+Use of @subcmd{OUTFILE} to write a portable file is a @pspp{} extension.
+
+If @subcmd{OUTFILE=*} is given, then the subcommand @subcmd{MODE} may also be
+specified.
+The mode subcommand has two possible values: @subcmd{ADDVARIABLES} or @subcmd{REPLACE}.
+In @subcmd{REPLACE} mode, the entire active dataset is replaced by a new dataset
+which contains just the break variables and the destination varibles.
+In this mode, the new file contains as many cases as there are
+unique combinations of the break variables.
+In @subcmd{ADDVARIABLES} mode, the destination variables are appended to
+the existing active dataset.
+Cases which have identical combinations of values in their break
+variables, receive identical values for the destination variables.
+The number of cases in the active dataset remains unchanged.
+Note that if @subcmd{ADDVARIABLES} is specified, then the data @emph{must} be
+sorted on the break variables.
+
+By default, the active dataset is sorted based on the break variables
+before aggregation takes place. If the active dataset is already sorted
or otherwise grouped in terms of the break variables, specify
-PRESORTED to save time.
+@subcmd{PRESORTED} to save time.
+@subcmd{PRESORTED} is assumed if @subcmd{MODE=ADDVARIABLES} is used.
-Specify DOCUMENT to copy the documents from the active file into the
-aggregate file (@pxref{DOCUMENT}). Otherwise, the aggregate file will
+Specify @subcmd{DOCUMENT} to copy the documents from the active dataset into the
+aggregate file (@pxref{DOCUMENT}). Otherwise, the aggregate file does
not contain any documents, even if the aggregate file replaces the
-active file.
+active dataset.
-Normally, only a single case (for SD and SD., two cases) need be
+Normally, only a single case (for @subcmd{SD} and @subcmd{SD}., two cases) need be
non-missing in each group for the aggregate variable to be
-non-missing. Specifying /MISSING=COLUMNWISE inverts this behavior, so
+non-missing. Specifying @subcmd{/MISSING=COLUMNWISE} inverts this behavior, so
that the aggregate variable becomes missing if any aggregated value is
missing.
-If PRESORTED, DOCUMENT, or MISSING are specified, they must appear
-between OUTFILE and BREAK.
+If @subcmd{PRESORTED}, @subcmd{DOCUMENT}, or @subcmd{MISSING} are specified, they must appear
+between @subcmd{OUTFILE} and @subcmd{BREAK}.
-At least one break variable must be specified on BREAK, a
+At least one break variable must be specified on @subcmd{BREAK}, a
required subcommand. The values of these variables are used to divide
-the active file into groups to be summarized. In addition, at least
+the active dataset into groups to be summarized. In addition, at least
one @var{dest_var} must be specified.
One or more sets of aggregation variables must be specified. Each set
Each set must have exactly as many source variables as aggregation
variables. Each aggregation variable receives the results of applying
the specified aggregation function to the corresponding source
-variable. The MEAN, MEDIAN, SD, and SUM aggregation functions may only be
+variable. The @subcmd{MEAN}, @subcmd{MEDIAN}, @subcmd{SD}, and @subcmd{SUM}
+aggregation functions may only be
applied to numeric variables. All the rest may be applied to numeric
-and short and long string variables.
+and string variables.
The available aggregation functions are as follows:
@table @asis
-@item FGT(var_name, value)
+@item @subcmd{FGT(@var{var_name}, @var{value})}
Fraction of values greater than the specified constant. The default
format is F5.3.
-@item FIN(var_name, low, high)
+@item @subcmd{FIN(@var{var_name}, @var{low}, @var{high})}
Fraction of values within the specified inclusive range of constants.
The default format is F5.3.
-@item FLT(var_name, value)
+@item @subcmd{FLT(@var{var_name}, @var{value})}
Fraction of values less than the specified constant. The default
format is F5.3.
-@item FIRST(var_name)
+@item @subcmd{FIRST(@var{var_name})}
First non-missing value in break group. The aggregation variable
receives the complete dictionary information from the source variable.
-The sort performed by AGGREGATE (and by SORT CASES) is stable, so that
+The sort performed by @cmd{AGGREGATE} (and by @cmd{SORT CASES}) is stable.
+This means that
the first case with particular values for the break variables before
-sorting will also be the first case in that break group after sorting.
+sorting is also the first case in that break group after sorting.
-@item FOUT(var_name, low, high)
+@item @subcmd{FOUT(@var{var_name}, @var{low}, @var{high})}
Fraction of values strictly outside the specified range of constants.
The default format is F5.3.
-@item LAST(var_name)
+@item @subcmd{LAST(@var{var_name})}
Last non-missing value in break group. The aggregation variable
receives the complete dictionary information from the source variable.
-The sort performed by AGGREGATE (and by SORT CASES) is stable, so that
-the last case with particular values for the break variables before
-sorting will also be the last case in that break group after sorting.
+The sort performed by @cmd{AGGREGATE} (and by @cmd{SORT CASES}) is stable.
-@item MAX(var_name)
+@item @subcmd{MAX(@var{var_name})}
Maximum value. The aggregation variable receives the complete
dictionary information from the source variable.
-@item MEAN(var_name)
+@item @subcmd{MEAN(@var{var_name})}
Arithmetic mean. Limited to numeric values. The default format is
F8.2.
-@item MEDIAN(var_name)
+@item @subcmd{MEDIAN(@var{var_name})}
The median value. Limited to numeric values. The default format is F8.2.
-@item MIN(var_name)
+@item @subcmd{MIN(@var{var_name})}
Minimum value. The aggregation variable receives the complete
dictionary information from the source variable.
-@item N(var_name)
+@item @subcmd{N(@var{var_name})}
Number of non-missing values. The default format is F7.0 if weighting
is not enabled, F8.2 if it is (@pxref{WEIGHT}).
-@item N
+@item @subcmd{N}
Number of cases aggregated to form this group. The default format is
F7.0 if weighting is not enabled, F8.2 if it is (@pxref{WEIGHT}).
-@item NMISS(var_name)
+@item @subcmd{NMISS(@var{var_name})}
Number of missing values. The default format is F7.0 if weighting is
not enabled, F8.2 if it is (@pxref{WEIGHT}).
-@item NU(var_name)
+@item @subcmd{NU(@var{var_name})}
Number of non-missing values. Each case is considered to have a weight
of 1, regardless of the current weighting variable (@pxref{WEIGHT}).
The default format is F7.0.
-@item NU
+@item @subcmd{NU}
Number of cases aggregated to form this group. Each case is considered
to have a weight of 1, regardless of the current weighting variable.
The default format is F7.0.
-@item NUMISS(var_name)
+@item @subcmd{NUMISS(@var{var_name})}
Number of missing values. Each case is considered to have a weight of
1, regardless of the current weighting variable. The default format is F7.0.
-@item PGT(var_name, value)
+@item @subcmd{PGT(@var{var_name}, @var{value})}
Percentage between 0 and 100 of values greater than the specified
constant. The default format is F5.1.
-@item PIN(var_name, low, high)
+@item @subcmd{PIN(@var{var_name}, @var{low}, @var{high})}
Percentage of values within the specified inclusive range of
constants. The default format is F5.1.
-@item PLT(var_name, value)
+@item @subcmd{PLT(@var{var_name}, @var{value})}
Percentage of values less than the specified constant. The default
format is F5.1.
-@item POUT(var_name, low, high)
+@item @subcmd{POUT(@var{var_name}, @var{low}, @var{high})}
Percentage of values strictly outside the specified range of
constants. The default format is F5.1.
-@item SD(var_name)
+@item @subcmd{SD(@var{var_name})}
Standard deviation of the mean. Limited to numeric values. The
default format is F8.2.
-@item SUM(var_name)
+@item @subcmd{SUM(@var{var_name})}
Sum. Limited to numeric values. The default format is F8.2.
@end table
Aggregation functions compare string values in terms of internal
-character codes. On most modern computers, this is a form of ASCII.
+character codes.
+On most modern computers, this is @acronym{ASCII} or a superset thereof.
The aggregation functions listed above exclude all user-missing values
from calculations. To include user-missing values, insert a period
-(@samp{.}) at the end of the function name. (e.g.@: @samp{SUM.}).
+(@samp{.}) at the end of the function name. (@i{e.g.}@: @samp{SUM.}).
(Be aware that specifying such a function as the last token on a line
-will cause the period to be interpreted as the end of the command.)
+causes the period to be interpreted as the end of the command.)
@cmd{AGGREGATE} both ignores and cancels the current @cmd{SPLIT FILE}
settings (@pxref{SPLIT FILE}).
+@subsection Aggregate Example
+
+The @file{personnel.sav} dataset provides the occupations and salaries of
+many individuals. For many purposes however such detailed information is
+not interesting, but often the aggregated statistics of each occupation are
+of interest. In @ref{aggregate:ex} the @cmd{AGGREGATE} command is used
+to calculate the mean, the median and the standard deviation of each
+occupation.
+
+@float Example, aggregate:ex
+@psppsyntax {aggregate.sps}
+@caption {Calculating aggregated statistics from the @file{personnel.sav} file.}
+@end float
+
+Since we chose the @samp{MODE = REPLACE} option, in @ref{aggregate:res} cases
+for the individual persons are no longer present. They have each been replaced
+by a single case per aggregated value.
+
+@float Results, aggregate:res
+@psppoutput {aggregate}
+@caption {Aggregated mean, median and standard deviation per @exvar{occupation}.}
+@end float
+
+Note that some values for the standard deviation are blank.
+This is because there is only one case with the respective
+occupation.
+
+
@node AUTORECODE
@section AUTORECODE
@vindex AUTORECODE
@display
-AUTORECODE VARIABLES=src_vars INTO dest_vars
- /DESCENDING
- /PRINT
+AUTORECODE VARIABLES=@var{src_vars} INTO @var{dest_vars}
+ [ /DESCENDING ]
+ [ /PRINT ]
+ [ /GROUP ]
+ [ /BLANK = @{VALID, MISSING@} ]
@end display
The @cmd{AUTORECODE} procedure considers the @var{n} values that a variable
takes on and maps them onto values 1@dots{}@var{n} on a new numeric
variable.
-Subcommand VARIABLES is the only required subcommand and must come
-first. Specify VARIABLES, an equals sign (@samp{=}), a list of source
-variables, INTO, and a list of target variables. There must the same
+Subcommand @subcmd{VARIABLES} is the only required subcommand and must come
+first. Specify @subcmd{VARIABLES}, an equals sign (@samp{=}), a list of source
+variables, @subcmd{INTO}, and a list of target variables. There must the same
number of source and target variables. The target variables must not
already exist.
-By default, increasing values of a source variable (for a string, this
-is based on character code comparisons) are recoded to increasing values
-of its target variable. To cause increasing values of a source variable
-to be recoded to decreasing values of its target variable (@var{n} down
-to 1), specify DESCENDING.
-
-PRINT is currently ignored.
+@cmd{AUTORECODE} ordinarily assigns each increasing non-missing value
+of a source variable (for a string, this is based on character code
+comparisons) to consecutive values of its target variable. For
+example, the smallest non-missing value of the source variable is
+recoded to value 1, the next smallest to 2, and so on. If the source
+variable has user-missing values, they are recoded to
+consecutive values just above the non-missing values. For example, if
+a source variables has seven distinct non-missing values, then the
+smallest missing value would be recoded to 8, the next smallest to 9,
+and so on.
+
+Use @subcmd{DESCENDING} to reverse the sort order for non-missing
+values, so that the largest non-missing value is recoded to 1, the
+second-largest to 2, and so on. Even with @subcmd{DESCENDING},
+user-missing values are still recoded in ascending order just above
+the non-missing values.
+
+The system-missing value is always recoded into the system-missing
+variable in target variables.
+
+If a source value has a value label, then that value label is retained
+for the new value in the target variable. Otherwise, the source value
+itself becomes each new value's label.
+
+Variable labels are copied from the source to target variables.
+
+@subcmd{PRINT} is currently ignored.
+
+The @subcmd{GROUP} subcommand is relevant only if more than one variable is to be
+recoded. It causes a single mapping between source and target values to
+be used, instead of one map per variable. With @subcmd{GROUP},
+user-missing values are taken from the first source variable that has
+any user-missing values.
+
+If @subcmd{/BLANK=MISSING} is given, then string variables which contain only
+whitespace are recoded as SYSMIS. If @subcmd{/BLANK=VALID} is specified then they
+are allocated a value like any other. @subcmd{/BLANK} is not relevant
+to numeric values. @subcmd{/BLANK=VALID} is the default.
@cmd{AUTORECODE} is a procedure. It causes the data to be read.
+@subsection Autorecode Example
+
+In the file @file{personnel.sav}, the variable @exvar{occupation} is a string
+variable. Except for data of a purely commentary nature, string variables
+are generally a bad idea. One reason is that data entry errors are easily
+overlooked. This has happened in @file{personnel.sav}; one entry which should
+read ``Scientist'' has been mistyped as ``Scrientist''. In @ref{autorecode:ex}
+first, this error is corrected by the @cmd{DO IF} clause,
+@footnote{One must use care when correcting such data input errors rather than
+msimply marking them as missing. For example, if an occupation has been entered
+``Barister'', did the person mean ``Barrister'' or did she mean ``Barista''?}
+then we use @cmd{AUTORECODE} to
+create a new numeric variable which takes recoded values of @exvar{occupation}.
+Finally, we remove the old variable and rename the new variable to
+the name of the old variable.
+
+@float Example, autorecode:ex
+@psppsyntax {autorecode.sps}
+@caption {Changing a string variable to a numeric variable using @cmd{AUTORECODE}
+after correcting a data entry error}
+@end float
+
+
+@float Screenshot, autorecode:scr
+@psppimage {autorecode}
+@caption {Autorecode dialog box set to recode @exvar{occupation} to @exvar{occ}}
+@end float
+
+Notice in @ref{autorecode:res}, how the new variable has been automatically
+allocated value labels which correspond to the strings of the old variable.
+This means that in future analyses the descriptive strings are reported instead
+of the numeric values.
+
+@float Result, autorecode:res
+@psppoutput {autorecode}
+@caption {The properties of the @exvar{occupation} variable following @cmd{AUTORECODE}}
+@end float
+
+
@node COMPUTE
@section COMPUTE
@vindex COMPUTE
@display
-COMPUTE variable = expression.
+COMPUTE @var{variable} = @var{expression}.
+@end display
or
-COMPUTE vector(index) = expression.
+@display
+COMPUTE vector(@var{index}) = @var{expression}.
@end display
@cmd{COMPUTE} assigns the value of an expression to a target
variable. For each case, the expression is evaluated and its value
-assigned to the target variable. Numeric and short and long string
+assigned to the target variable. Numeric and string
variables may be assigned. When a string expression's width differs
from the target variable's width, the string result of the expression
is truncated or padded with spaces on the right as necessary. The
they can be used as targets for @cmd{COMPUTE}.
The target variable may be specified as an element of a vector
-(@pxref{VECTOR}). In this case, a vector index expression must be
-specified in parentheses following the vector name. The index
-expression must evaluate to a numeric value that, after rounding down
+(@pxref{VECTOR}). In this case, an expression @var{index} must be
+specified in parentheses following the vector name. The expression @var{index}
+must evaluate to a numeric value that, after rounding down
to the nearest integer, is a valid index for the named vector.
Using @cmd{COMPUTE} to assign to a variable specified on @cmd{LEAVE}
(@pxref{LEAVE}) resets the variable's left state. Therefore,
@code{LEAVE} should be specified following @cmd{COMPUTE}, not before.
-@cmd{COMPUTE} is a transformation. It does not cause the active file to be
+@cmd{COMPUTE} is a transformation. It does not cause the active dataset to be
read.
When @cmd{COMPUTE} is specified following @cmd{TEMPORARY}
(@pxref{TEMPORARY}), the @cmd{LAG} function may not be used
(@pxref{LAG}).
+@subsection Compute Examples
+
+The dataset @file{physiology.sav} contains the height and weight of persons.
+For some purposes, neither height nor weight alone is of interest.
+Epidemiologists are often more interested in the @dfn{body mass index} which
+can sometimes be used as a predictor for clinical conditions.
+The body mass index is defined as the weight of the person in kilograms divided
+by the square of the person's height in metres.
+@footnote{Since BMI is a quantity with a ratio scale and has units, the term ``index''
+is a misnomer, but that is what it is called.}
+
+@float Example, bmi:ex
+@psppsyntax {compute.sps}
+@caption {Computing the body mass index from @exvar{weight} and @exvar{height}}
+@end float
+
+@ref{bmi:ex} shows how you can use @cmd{COMPUTE} to generate a new variable called
+@exvar{bmi} and have every case's value calculated from the existing values of
+@exvar{weight} and @exvar{height}.
+It also shows how you can add a label to this new variable (@pxref{VARIABLE LABELS}),
+so that a more descriptive label appears in subsequent analyses, and this can be seen
+in the ouput from the @cmd{DESCRIPTIVES} command in @ref{bmi:res}.
+
+@float Screenshot, bmi:scr
+@psppimage {compute}
+@caption {Using the dialog box to generate a new variable and compute its values}
+@end float
+
+The expression which follows the @samp{=} sign can be as complicated as necessary.
+@xref{Expressions} for a precise description of the language accepted.
+Normally it is easiest to enter the code directly, however there is a dialog box
+available if desired. This is illustrated in @ref{bmi:scr}.
+One advantage is that it offers a list of mathematical
+functions which can be selected and pasted into the expression.
+
+@float Results, bmi:res
+@psppoutput {compute}
+@caption {An analysis which includes @exvar{bmi} in its results}
+@end float
+
+
+
@node COUNT
@section COUNT
@vindex COUNT
@display
-COUNT var_name = var@dots{} (value@dots{}).
+COUNT @var{var_name} = @var{var}@dots{} (@var{value}@dots{})
+ [/@var{var_name} = @var{var}@dots{} (@var{value}@dots{})]@dots{}
-Each value takes one of the following forms:
- number
- string
- num1 THRU num2
+Each @var{value} takes one of the following forms:
+ @var{number}
+ @var{string}
+ @var{num1} THRU @var{num2}
MISSING
SYSMIS
-In addition, num1 and num2 can be LO or LOWEST, or HI or HIGHEST,
-respectively.
+where @var{num1} is a numeric expression or the words @subcmd{LO} or @subcmd{LOWEST}
+ and @var{num2} is a numeric expression or @subcmd{HI} or @subcmd{HIGHEST}.
@end display
@cmd{COUNT} creates or replaces a numeric @dfn{target} variable that
The target variable values are always nonnegative integers. They are
never missing. The target variable is assigned an F8.2 output format.
-@xref{Input and Output Formats}. Any variables, including long and short
+@xref{Input and Output Formats}. Any variables, including
string variables, may be test variables.
User-missing values of test variables are treated just like any other
values. They are @strong{not} treated as system-missing values.
User-missing values that are criterion values or inside ranges of
criterion values are counted as any other values. However (for numeric
-variables), keyword MISSING may be used to refer to all system-
+variables), keyword @subcmd{MISSING} may be used to refer to all system-
and user-missing values.
@cmd{COUNT} target variables are assigned values in the order
-specified. In the command @code{COUNT A=A B(1) /B=A B(2).}, the
+specified. In the command @subcmd{COUNT @var{A}=@var{A} @var{B}(1) /@var{B}=@var{A} @var{B}(2).}, the
following actions occur:
@itemize @minus
@item
-The number of occurrences of 1 between @code{A} and @code{B} is counted.
+The number of occurrences of 1 between @var{A} and @var{B} is counted.
@item
-@code{A} is assigned this value.
+@var{A} is assigned this value.
@item
-The number of occurrences of 1 between @code{B} and the @strong{new}
-value of @code{A} is counted.
+The number of occurrences of 1 between @var{B} and the @strong{new}
+value of @var{A} is counted.
@item
-@code{B} is assigned this value.
+@var{B} is assigned this value.
@end itemize
Despite this ordering, all @cmd{COUNT} criterion variables must exist
variables earlier in the command! Break such a command into two
separate commands.
-The examples below may help to clarify.
+@subsection Count Examples
+
+In the survey results in dataset @file{hotel.sav} a manager wishes
+to know how many respondents answered with low valued answers to questions
+@exvar{v1}, @exvar{v2} and @exvar{v3}. This can be found using the code
+in @ref{count:ex}. Specifically, this code creates a new variable, and
+populates it with the number of values in @exvar{v1}--@exvar{v2} which
+are 2 or lower.
+
+@float Example, count:ex
+@psppsyntax {count.sps}
+@caption {Counting low values to responses @exvar{v1}, @exvar{v2} and @exvar{v3}}
+@end float
+
+In @ref{count:ex} the @cmd{COUNT} transformation creates a new variable, @exvar{low_counts} and
+its values are shown using the @cmd{LIST} command.
+
+If using the graphic user interface, a two step process must be used to set
+up the @cmd{COUNT} transformation. The first dialog box (@ref{count:scr}) provides for the
+variables to be chosen.
+Then, one must click on the button marked ``Define Values...'' to reveal
+the dialog box for selecting the values to count.
+
+@float Screenshot, count:scr
+@psppimage {count}
+@caption {The variables @exvar{v1}, @exvar{v2} and @exvar{v3} selected, ready
+to define values to count}
+@end float
+
+In this dialog box, you must select the values you wish to count
+--- in this case all values up to and including 2 --- as shown in @ref{count-define:scr}
+and click ``Add''. As many ranges or may be added as you desire.
+When all desired ranges have been added click ``Continue''.
+
+@float Screenshot, count-define:scr
+@psppimage {count-define}
+@caption {Count ``Define Values'' dialog with @samp{lowest thru 2} selected}
+@end float
+
+In @ref{count:res} we can see the values of @exvar{low_counts} after the @cmd{COUNT}
+transformation has completed. The first value is 1, because there is only one
+variable amoung @exvar{v1}, @exvar{v2} and @exvar{3} which has a value of 2 or less.
+The second value is 2, because both @exvar{v1} and @exvar{v2} are 2 or less.
+
+@float Result, count:res
+@psppoutput {count}
+@caption {The values of @exvar{v1}, @exvar{v2}, @exvar{v3} and @exvar{low_counts} after
+the @cmd{COUNT} transformation has run}
+@end float
-@enumerate A
-@item
-Assuming @code{Q0}, @code{Q2}, @dots{}, @code{Q9} are numeric variables,
-the following commands:
-
-@enumerate
-@item
-Count the number of times the value 1 occurs through these variables
-for each case and assigns the count to variable @code{QCOUNT}.
-
-@item
-Print out the total number of times the value 1 occurs throughout
-@emph{all} cases using @cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for
-details.
-@end enumerate
-
-@example
-COUNT QCOUNT=Q0 TO Q9(1).
-DESCRIPTIVES QCOUNT /STATISTICS=SUM.
-@end example
-
-@item
-Given these same variables, the following commands:
-
-@enumerate
-@item
-Count the number of valid values of these variables for each case and
-assigns the count to variable @code{QVALID}.
-
-@item
-Multiplies each value of @code{QVALID} by 10 to obtain a percentage of
-valid values, using @cmd{COMPUTE}. @xref{COMPUTE}, for details.
-
-@item
-Print out the percentage of valid values across all cases, using
-@cmd{DESCRIPTIVES}. @xref{DESCRIPTIVES}, for details.
-@end enumerate
-
-@example
-COUNT QVALID=Q0 TO Q9 (LO THRU HI).
-COMPUTE QVALID=QVALID*10.
-DESCRIPTIVES QVALID /STATISTICS=MEAN.
-@end example
-@end enumerate
@node FLIP
@section FLIP
@vindex FLIP
@display
-FLIP /VARIABLES=var_list /NEWNAMES=var_name.
+FLIP /VARIABLES=@var{var_list} /NEWNAMES=@var{var_name}.
@end display
-@cmd{FLIP} transposes rows and columns in the active file. It
+@cmd{FLIP} transposes rows and columns in the active dataset. It
causes cases to be swapped with variables, and vice versa.
-All variables in the transposed active file are numeric. String
+All variables in the transposed active dataset are numeric. String
variables take on the system-missing value in the transposed file.
-No subcommands are required. If specified, the VARIABLES subcommand
+@subcmd{N} subcommands are required. If specified, the @subcmd{VARIABLES} subcommand
selects variables to be transformed into cases, and variables not
-specified are discarded. If the VARIABLES subcommand is omitted, all
+specified are discarded. If the @subcmd{VARIABLES} subcommand is omitted, all
variables are selected for transposition.
-The variables specified by NEWNAMES, which must be a string variable, is
+The variables specified by @subcmd{NEWNAMES}, which must be a
+string variable, is
used to give names to the variables created by @cmd{FLIP}. Only the
first 8 characters of the variable are used. If
-NEWNAMES is not
-specified then the default is a variable named CASE_LBL, if it exists.
-If it does not then the variables created by FLIP are named VAR000
+@subcmd{NEWNAMES} is not
+specified then the default is a variable named @exvar{CASE_LBL}, if it exists.
+If it does not then the variables created by @cmd{FLIP} are named VAR000
through VAR999, then VAR1000, VAR1001, and so on.
-When a NEWNAMES variable is available, the names must be canonicalized
+When a @subcmd{NEWNAMES} variable is available, the names must be canonicalized
before becoming variable names. Invalid characters are replaced by
letter @samp{V} in the first position, or by @samp{_} in subsequent
positions. If the name thus generated is not unique, then numeric
extensions are added, starting with 1, until a unique name is found or
there are no remaining possibilities. If the latter occurs then the
-FLIP operation aborts.
+@cmd{FLIP} operation aborts.
-The resultant dictionary contains a CASE_LBL variable, a string
+The resultant dictionary contains a @exvar{CASE_LBL} variable, a string
variable of width 8, which stores the names of the variables in the
dictionary before the transposition. Variables names longer than 8
-characters are truncated. If the active file is subsequently
-transposed using @cmd{FLIP}, this variable can be used to recreate the
-original variable names.
+characters are truncated. If @cmd{FLIP} is called again on
+this dataset, the @exvar{CASE_LBL} variable can be passed to the @subcmd{NEWNAMES}
+subcommand to recreate the original variable names.
-FLIP honors @cmd{N OF CASES} (@pxref{N OF CASES}). It ignores
+@cmd{FLIP} honors @cmd{N OF CASES} (@pxref{N OF CASES}). It ignores
@cmd{TEMPORARY} (@pxref{TEMPORARY}), so that ``temporary''
transformations become permanent.
+@subsection Flip Examples
+
+
+In @ref{flip:ex}, data has been entered using @cmd{DATA LIST} (@pxref{DATA LIST})
+such that the first variable in the dataset is a string variable containing
+a description of the other data for the case.
+Clearly this is not a convenient arrangement for performing statistical analyses,
+so it would have been better to think a little more carefully about how the data
+should have been arranged.
+However often the data is provided by some third party source, and you have
+no control over the form.
+Fortunately, we can use @cmd{FLIP} to exchange the variables
+and cases in the active dataset.
+
+@float Example, flip:ex
+@psppsyntax {flip.sps}
+@caption {Using @cmd{FLIP} to exchange variables and cases in a dataset}
+@end float
+
+As you can see in @ref{flip:res} before the @cmd{FLIP} command has run there
+are seven variables (six containing data and one for the heading) and three cases.
+Afterwards there are four variables (one per case, plus the @exvar{CASE_LBL} variable)
+and six cases.
+You can delete the @exvar{CASE_LBL} variable (@pxref{DELETE VARIABLES}) if you don't need it.
+
+@float Results, flip:res
+@psppoutput {flip}
+@caption {The results of using @cmd{FLIP} to exchange variables and cases in a dataset}
+@end float
+
+
@node IF
@section IF
@vindex IF
@display
-IF condition variable=expression.
+IF @var{condition} @var{variable}=@var{expression}.
+@end display
or
-IF condition vector(index)=expression.
+@display
+IF @var{condition} vector(@var{index})=@var{expression}.
@end display
The @cmd{IF} transformation conditionally assigns the value of a target
expression.
Specify a boolean-valued expression (@pxref{Expressions}) to be tested
-following the IF keyword. This expression is evaluated for each case.
+following the @cmd{IF} keyword. This expression is evaluated for each case.
If the value is true, then the value of the expression is computed and
assigned to the specified variable. If the value is false or missing,
-nothing is done. Numeric and short and long string variables may be
+nothing is done. Numeric and string variables may be
assigned. When a string expression's width differs from the target
variable's width, the string result of the expression is truncated or
padded with spaces on the right as necessary. The expression and
@section RECODE
@vindex RECODE
+The @cmd{RECODE} command is used to transform existing values into other,
+user specified values.
+The general form is:
+
@display
-RECODE var_list (src_value@dots{}=dest_value)@dots{} [INTO var_list].
+RECODE @var{src_vars}
+ (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
+ (@var{src_value} @var{src_value} @dots{} = @var{dest_value})
+ (@var{src_value} @var{src_value} @dots{} = @var{dest_value}) @dots{}
+ [INTO @var{dest_vars}].
+@end display
-src_value may take the following forms:
- number
- string
- num1 THRU num2
- MISSING
- SYSMIS
- ELSE
-Open-ended ranges may be specified using LO or LOWEST for num1
-or HI or HIGHEST for num2.
+Following the @cmd{RECODE} keyword itself comes @var{src_vars} which is a list
+of variables whose values are to be transformed.
+These variables may be string variables or they may be numeric.
+However the list must be homogeneous; you may not mix string variables and
+numeric variables in the same recoding.
+
+After the list of source variables, there should be one or more @dfn{mappings}.
+Each mapping is enclosed in parentheses, and contains the source values and
+a destination value separated by a single @samp{=}.
+The source values are used to specify the values in the dataset which
+need to change, and the destination value specifies the new value
+to which they should be changed.
+Each @var{src_value} may take one of the following forms:
+@table @asis
+@item @var{number}
+If the source variables are numeric then @var{src_value} may be a literal
+number.
+@item @var{string}
+If the source variables are string variables then @var{src_value} may be a
+literal string (like all strings, enclosed in single or double quotes).
+@item @var{num1} THRU @var{num2}
+This form is valid only when the source variables are numeric.
+It specifies all values in the range between @var{num1} and @var{num2},
+including both endpoints of the range. By convention, @var{num1}
+should be less than @var{num2}.
+Open-ended ranges may be specified using @samp{LO} or @samp{LOWEST}
+for @var{num1}
+or @samp{HI} or @samp{HIGHEST} for @var{num2}.
+@item @samp{MISSING}
+The literal keyword @samp{MISSING} matches both system missing and user
+missing values.
+It is valid for both numeric and string variables.
+@item @samp{SYSMIS}
+The literal keyword @samp{SYSMIS} matches system missing
+values.
+It is valid for both numeric variables only.
+@item @samp{ELSE}
+The @samp{ELSE} keyword may be used to match any values which are
+not matched by any other @var{src_value} appearing in the command.
+If this keyword appears, it should be used in the last mapping of the
+command.
+@end table
-dest_value may take the following forms:
- num
- string
- SYSMIS
- COPY
-@end display
+After the source variables comes an @samp{=} and then the @var{dest_value}.
+The @var{dest_value} may take any of the following forms:
+@table @asis
+@item @var{number}
+A literal numeric value to which the source values should be changed.
+This implies the destination variable must be numeric.
+@item @var{string}
+A literal string value (enclosed in quotation marks) to which the source
+values should be changed.
+This implies the destination variable must be a string variable.
+@item @samp{SYSMIS}
+The keyword @samp{SYSMIS} changes the value to the system missing value.
+This implies the destination variable must be numeric.
+@item @samp{COPY}
+The special keyword @samp{COPY} means that the source value should not be
+modified, but
+copied directly to the destination value.
+This is meaningful only if @samp{INTO @var{dest_vars}} is specified.
+@end table
+
+Mappings are considered from left to right.
+Therefore, if a value is matched by a @var{src_value} from more than
+one mapping, the first (leftmost) mapping which matches is considered.
+Any subsequent matches are ignored.
+
+The clause @samp{INTO @var{dest_vars}} is optional.
+The behaviour of the command is slightly different depending on whether it
+appears or not.
+
+If @samp{INTO @var{dest_vars}} does not appear, then values are recoded
+``in place''.
+This means that the recoded values are written back to the
+source variables from whence the original values came.
+In this case, the @var{dest_value} for every mapping must imply a value which
+has the same type as the @var{src_value}.
+For example, if the source value is a string value, it is not permissible for
+@var{dest_value} to be @samp{SYSMIS} or another forms which implies a numeric
+result.
+It is also not permissible for @var{dest_value} to be longer than the width
+of the source variable.
+
+The following example two numeric variables @var{x} and @var{y} are recoded
+in place.
+Zero is recoded to 99, the values 1 to 10 inclusive are unchanged,
+values 1000 and higher are recoded to the system-missing value and all other
+values are changed to 999:
+@example
+recode @var{x} @var{y}
+ (0 = 99)
+ (1 THRU 10 = COPY)
+ (1000 THRU HIGHEST = SYSMIS)
+ (ELSE = 999).
+@end example
-@cmd{RECODE} translates data from one range of values to
-another, via flexible user-specified mappings. Data may be remapped
-in-place or copied to new variables. Numeric, short string, and long
-string data can be recoded.
-
-Specify the list of source variables, followed by one or more mapping
-specifications each enclosed in parentheses. If the data is to be
-copied to new variables, specify INTO, then the list of target
-variables. String target variables must already have been declared
-using @cmd{STRING} or another transformation, but numeric target
-variables can
-be created on the fly. There must be exactly as many target variables
-as source variables. Each source variable is remapped into its
-corresponding target variable.
-
-When INTO is not used, the input and output variables must be of the
-same type. Otherwise, string values can be recoded into numeric values,
-and vice versa. When this is done and there is no mapping for a
-particular value, either a value consisting of all spaces or the
-system-missing value is assigned, depending on variable type.
-
-Mappings are considered from left to right. The first src_value that
-matches the value of the source variable causes the target variable to
-receive the value indicated by the dest_value. Literal number, string,
-and range src_value's should be self-explanatory. MISSING as a
-src_value matches any user- or system-missing value. SYSMIS matches the
-system missing value only. ELSE is a catch-all that matches anything.
-It should be the last src_value specified.
-
-Numeric and string dest_value's should be self-explanatory. COPY
-causes the input values to be copied to the output. This is only valid
-if the source and target variables are of the same type. SYSMIS
-indicates the system-missing value.
-
-If the source variables are strings and the target variables are
-numeric, then there is one additional mapping available: (CONVERT),
-which must be the last specified mapping. CONVERT causes a number
-specified as a string to be converted to a numeric value. If the string
-cannot be parsed as a number, then the system-missing value is assigned.
-
-Multiple recodings can be specified on a single @cmd{RECODE} invocation.
+If @samp{INTO @var{dest_vars}} is given, then recoded values are written
+into the variables specified in @var{dest_vars}, which must therefore
+ contain a list of valid variable names.
+The number of variables in @var{dest_vars} must be the same as the number
+of variables in @var{src_vars}
+and the respective order of the variables in @var{dest_vars} corresponds to
+the order of @var{src_vars}.
+That is to say, the recoded value whose
+original value came from the @var{n}th variable in @var{src_vars} is
+placed into the @var{n}th variable in @var{dest_vars}.
+The source variables are unchanged.
+If any mapping implies a string as its destination value, then the respective
+destination variable must already exist, or
+have been declared using @cmd{STRING} or another transformation.
+Numeric variables however are automatically created if they don't already
+exist.
+The following example deals with two source variables, @var{a} and @var{b}
+which contain string values. Hence there are two destination variables
+@var{v1} and @var{v2}.
+Any cases where @var{a} or @var{b} contain the values @samp{apple},
+@samp{pear} or @samp{pomegranate} result in @var{v1} or @var{v2} being
+filled with the string @samp{fruit} whilst cases with
+@samp{tomato}, @samp{lettuce} or @samp{carrot} result in @samp{vegetable}.
+Any other values produce the result @samp{unknown}:
+@example
+string @var{v1} (a20).
+string @var{v2} (a20).
+
+recode @var{a} @var{b}
+ ("apple" "pear" "pomegranate" = "fruit")
+ ("tomato" "lettuce" "carrot" = "vegetable")
+ (ELSE = "unknown")
+ into @var{v1} @var{v2}.
+@end example
+
+There is one very special mapping, not mentioned above.
+If the source variable is a string variable
+then a mapping may be specified as @samp{(CONVERT)}.
+This mapping, if it appears must be the last mapping given and
+the @samp{INTO @var{dest_vars}} clause must also be given and
+must not refer to a string variable.
+@samp{CONVERT} causes a number specified as a string to
+be converted to a numeric value.
+For example it converts the string @samp{"3"} into the numeric
+value 3 (note that it does not convert @samp{three} into 3).
+If the string cannot be parsed as a number, then the system-missing value
+is assigned instead.
+In the following example, cases where the value of @var{x} (a string variable)
+is the empty string, are recoded to 999 and all others are converted to the
+numeric equivalent of the input value. The results are placed into the
+numeric variable @var{y}:
+@example
+recode @var{x}
+ ("" = 999)
+ (convert)
+ into @var{y}.
+@end example
+
+It is possible to specify multiple recodings on a single command.
Introduce additional recodings with a slash (@samp{/}) to
-separate them from the previous recodings.
+separate them from the previous recodings:
+@example
+recode
+ @var{a} (2 = 22) (else = 99)
+ /@var{b} (1 = 3) into @var{z}
+ .
+@end example
+@noindent Here we have two recodings. The first affects the source variable
+@var{a} and recodes in-place the value 2 into 22 and all other values to 99.
+The second recoding copies the values of @var{b} into the variable @var{z},
+changing any instances of 1 into 3.
@node SORT CASES
@section SORT CASES
@vindex SORT CASES
@display
-SORT CASES BY var_list[(@{D|A@}] [ var_list[(@{D|A@}] ] ...
+SORT CASES BY @var{var_list}[(@{D|A@}] [ @var{var_list}[(@{D|A@}] ] ...
@end display
-@cmd{SORT CASES} sorts the active file by the values of one or more
+@cmd{SORT CASES} sorts the active dataset by the values of one or more
variables.
-Specify BY and a list of variables to sort by. By default, variables
-are sorted in ascending order. To override sort order, specify (D) or
-(DOWN) after a list of variables to get descending order, or (A) or (UP)
+Specify @subcmd{BY} and a list of variables to sort by. By default, variables
+are sorted in ascending order. To override sort order, specify @subcmd{(D)} or
+@subcmd{(DOWN)} after a list of variables to get descending order, or @subcmd{(A)}
+or @subcmd{(UP)}
for ascending order. These apply to all the listed variables
-up until the preceding (A), (D), (UP) or (DOWN).
+up until the preceding @subcmd{(A)}, @subcmd{(D)}, @subcmd{(UP)} or @subcmd{(DOWN)}.
-The sort algorithms used by @cmd{SORT CASES} are stable. That is,
-records that have equal values of the sort variables will have the
-same relative order before and after sorting. As a special case,
-re-sorting an already sorted file will not affect the ordering of
+The sort algorithms used by @cmd{SORT CASES} are stable. This means
+records which have equal values of the sort variables have the
+same relative order before and after sorting. Thus,
+re-sorting an already sorted file does not affect the ordering of
cases.
@cmd{SORT CASES} is a procedure. It causes the data to be read.
-@cmd{SORT CASES} attempts to sort the entire active file in main memory.
-If workspace is exhausted, it falls back to a merge sort algorithm that
-involves creates numerous temporary files.
-
-@cmd{SORT CASES} may not be specified following TEMPORARY.
-@setfilename ignored
+@cmd{SORT CASES} attempts to sort the entire active dataset in main memory.
+If workspace is exhausted, it falls back to a merge sort algorithm which
+creates numerous temporary files.
+
+@cmd{SORT CASES} may not be specified following @cmd{TEMPORARY}.
+
+@subsection Sorting Example
+
+In @ref{sort-cases:ex} the data from the file @file {physiology.sav} is sorted
+by two variables, @i{viz@:} @exvar{sex} in descending order and @exvar{temperature} in
+ascending order.
+
+@float Example, sort-cases:ex
+@psppsyntax {sort-cases.sps}
+@caption {Sorting cases by two variables.}
+@end float
+
+In @ref{sort-cases:res} you can see that all the cases with a @exvar{sex} of
+@samp{1} (female) appear before those with a sex of @samp{0} (male).
+This is because they have been sorted in descending order.
+Within each sex, the data is sorted on the @exvar{temperature} variable,
+this time in ascending order.
+
+@float Results, sort-cases:res
+@psppoutput {sort-cases}
+@caption {The @file{physiology.sav} file after sorting.}
+@end float
+
+Note that @cmd{SORT CASES}, like all other transformations, affects only the active file.
+It does not have any effect upon the @file{physiology.sav} file itself. For that, you
+would have to rewrite the file using the @cmd{SAVE} command (@pxref{SAVE}).
+
+When using the graphic user interface, it is often simpler to perform a sort
+directly from the data view.
+To do this, switch to the data view. Select the column corresponding to the
+variable by which you want to sort and click button 1 and then click button 3.
+A popup menu will appear like that shown in @ref{sort-simple:scr}. Select
+either ``Sort Ascending'' or ``Sort Descending'' from this menu.
+
+@float Screenshot, sort-simple:scr
+@psppimage {sort-simple}
+@caption {Sorting the data on a single variable @exvar{height}}
+@end float
+
+However, sometimes you will want to sort on two or more variables, and that is
+not possible using this method. In this case, you must either use some code or
+the ``Sort Cases'' dialog from the Data menu. @ref{sort:scr} shows the dialog
+box set up to perform a sort on both @exvar{sex} and @exvar{height}.
+Note that the order in which you enter the variables is important. In this case,
+the data will be first sorted on @exvar{sex}, and then all cases for which @exvar{sex}
+is the same will then be sorted by @exvar{height}.
+
+@float Screenshot, sort:scr
+@psppimage {sort}
+@caption {Sorting the data on two variables @exvar{sex} and @exvar{height}}
+@end float
projects / pspp / blobdiff