@c PSPP - a program for statistical analysis.
-@c Copyright (C) 2017 Free Software Foundation, Inc.
+@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;
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 will contain as many cases as there are
+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 will be appended to
+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, will receive identical values for the destination variables.
-The number of cases in the active dataset will remain unchanged.
+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 will be sorted based 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
@subcmd{PRESORTED} to save time.
@subcmd{PRESORTED} is assumed if @subcmd{MODE=ADDVARIABLES} is used.
Specify @subcmd{DOCUMENT} to copy the documents from the active dataset into the
-aggregate file (@pxref{DOCUMENT}). Otherwise, the aggregate file will
+aggregate file (@pxref{DOCUMENT}). Otherwise, the aggregate file does
not contain any documents, even if the aggregate file replaces the
active dataset.
@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 @cmd{AGGREGATE} (and by @cmd{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 @subcmd{FOUT(@var{var_name}, @var{low}, @var{high})}
Fraction of values strictly outside the specified range of constants.
@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 @cmd{AGGREGATE} (and by @cmd{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 @subcmd{MAX(@var{var_name})}
Maximum value. The aggregation variable receives the complete
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
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 given then they
-will be allocated a value like any other. @subcmd{/BLANK} is not relevant
+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
(@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
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
used to give names to the variables created by @cmd{FLIP}. Only the
first 8 characters of the variable are used. If
@subcmd{NEWNAMES} is not
-specified then the default is a variable named CASE_LBL, if it exists.
+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.
there are no remaining possibilities. If the latter occurs then the
@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 dataset 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.
@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
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 will be considered.
-Any subsequent matches will be ignored.
+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 will be recoded
+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.
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, recoded values whose
-original value came from the @var{n}th variable in @var{src_vars} will be
+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 will be unchanged.
+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 will be automatically created if they don't already
+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} will result in @var{v1} or @var{v2} being
+@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} will result in @samp{vegetable}.
-Any other values will produce the result @samp{unknown}:
+@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).
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 will convert the string @samp{"3"} into the numeric
-value 3 (note that it will not convert @samp{three} into 3).
+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)
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)}
+@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 @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 dataset in main memory.
-If workspace is exhausted, it falls back to a merge sort algorithm that
-involves creates numerous temporary files.
+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