@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;
@display
AGGREGATE
- OUTFILE=@{*,'@var{file_name}',@var{file_handle}@} [MODE=@{REPLACE, ADDVARIABLES@}]
- /PRESORTED
- /DOCUMENT
- /MISSING=COLUMNWISE
- /BREAK=@var{var_list}
- /@var{dest_var}['@var{label}']@dots{}=@var{agr_func}(@var{src_vars}, @var{args}@dots{})@dots{}
+ [OUTFILE=@{*,'@var{file_name}',@var{file_handle}@} [MODE=@{REPLACE,ADDVARIABLES@}]]
+ [/MISSING=COLUMNWISE]
+ [/PRESORTED]
+ [/DOCUMENT]
+ [/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.
-Cases are divided into groups that have the same values for one or more
+It divides cases into groups that have the same values for one or more
variables called @dfn{break variables}. Several functions are available
for summarizing case contents.
-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 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
+The @cmd{AGGREGATE} syntax consists of subcommands to control its
+behavior, all of which are optional, followed by one or more
+destination variable assigments, each of which uses an aggregation
+function to define how it is calculated.
+
+The @subcmd{OUTFILE} subcommand, which must be first, names the
+destination for @cmd{AGGREGATE} output. It may name a system file by
+file name or file handle (@pxref{File Handles}), a dataset by its name
+(@pxref{Datasets}), or @samp{*} to replace the active dataset.
+@cmd{AGGREGATE} writes its output to this file.
+
+With @subcmd{OUTFILE=*} only, @code{MODE} may be specified immediately
+afterward with the value @code{ADDVARIABLES} or @code{REPLACE}:
+
+@itemize
+@item
+With @code{REPLACE}, the default, the 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
+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
+
+@item
+With @code{ADDVARIABLES}, the destination variables are added to those in
the existing active dataset.
-Cases which have identical combinations of values in their break
-variables, receive identical values for the destination variables.
+Cases that have the same combination 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.
+The data must be
+sorted on the break variables, that is, @code{ADDVARIABLES} implies @code{PRESORTED}
+@end itemize
-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
+If @code{OUTFILE} is omitted, @cmd{AGGREGATE} acts as if
+@code{OUTFILE=* MODE=ADDVARIABLES} were specified.
+
+By default, @cmd{AGGREGATE} first sorts the data on the break variables.
+If the active dataset is already sorted
+or grouped by the break variables, specify
@subcmd{PRESORTED} to save time.
-@subcmd{PRESORTED} is assumed if @subcmd{MODE=ADDVARIABLES} is used.
+With @subcmd{MODE=ADDVARIABLES}, the data must be pre-sorted.
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 dataset.
-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 @subcmd{/MISSING=COLUMNWISE} inverts this behavior, so
-that the aggregate variable becomes missing if any aggregated value is
-missing.
+Normally, @code{AGGREGATE} produces a non-missing value whenever there
+is enough non-missing data for the aggregation function in use, that
+is, just one non-missing value or, for the @code{SD} and @code{SD.}
+aggregation functions, two non-missing values. Specify
+@code{/MISSING=COLUMNWISE} to make @code{AGGREGATE} output a missing
+value when one or more of the input values are missing.
-If @subcmd{PRESORTED}, @subcmd{DOCUMENT}, or @subcmd{MISSING} are specified, they must appear
-between @subcmd{OUTFILE} and @subcmd{BREAK}.
+The @subcmd{BREAK} subcommand is optionally but usually present. On
+@subcmd{BREAK}, list the variables used to divide the active dataset
+into groups to be summarized.
-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 dataset into groups to be summarized. In addition, at least
-one @var{dest_var} must be specified.
+@cmd{AGGREGATE} is particular about the order of subcommands.
+@subcmd{OUTFILE} must be first, followed by @subcmd{MISSING}.
+@subcmd{PRESORTED} and @subcmd{DOCUMENT} follow @subcmd{MISSING}, in
+either order, followed by @subcmd{BREAK}, then followed by aggregation
+variable specifications.
-One or more sets of aggregation variables must be specified. Each set
+At least one set of aggregation variables is required. Each set
comprises a list of aggregation variables, an equals sign (@samp{=}),
the name of an aggregation function (see the list below), and a list
-of source variables in parentheses. Some aggregation functions expect
-additional arguments following the source variable names.
+of source variables in parentheses. A few aggregation functions do
+not accept source variables, and some aggregation functions expect
+additional arguments after the source variable names.
-Aggregation variables typically are created with no variable label,
-value labels, or missing values. Their default print and write
-formats depend on the aggregation function used, with details given in
-the table below. A variable label for an aggregation variable may be
-specified just after the variable's name in the aggregation variable
-list.
+@cmd{AGGREGATE} typically creates aggregation variables with no
+variable label, value labels, or missing values. Their default print
+and write formats depend on the aggregation function used, with
+details given in the table below. A variable label for an aggregation
+variable may be specified just after the variable's name in the
+aggregation variable list.
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 @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 string variables.
+variable.
-The available aggregation functions are as follows:
+The following aggregation functions may be applied only to numeric
+variables:
@table @asis
-@item @subcmd{FGT(@var{var_name}, @var{value})}
-Fraction of values greater than the specified constant. The default
-format is F5.3.
+@item @subcmd{MEAN(@var{var_name}@dots{})}
+Arithmetic mean. Limited to numeric values. The default format is
+F8.2.
-@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 @subcmd{MEDIAN(@var{var_name}@dots{})}
+The median value. Limited to numeric values. The default format is F8.2.
-@item @subcmd{FLT(@var{var_name}, @var{value})}
-Fraction of values less than the specified constant. The default
-format is F5.3.
+@item @subcmd{SD(@var{var_name}@dots{})}
+Standard deviation of the mean. Limited to numeric values. The
+default format is F8.2.
-@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.
-This means that
-the first case with particular values for the break variables before
-sorting is also the first case in that break group after sorting.
+@item @subcmd{SUM(@var{var_name}@dots{})}
+Sum. Limited to numeric values. The default format is F8.2.
+@end table
-@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.
+These aggregation functions may be applied to numeric and string variables:
-@item @subcmd{LAST(@var{var_name})}
-Last non-missing value in break group. The aggregation variable
+@table @asis
+@item @subcmd{CGT(@var{var_name}@dots{}, @var{value})}
+@itemx @subcmd{CLT(@var{var_name}@dots{}, @var{value})}
+@itemx @subcmd{CIN(@var{var_name}@dots{}, @var{low}, @var{high})}
+@itemx @subcmd{COUT(@var{var_name}@dots{}, @var{low}, @var{high})}
+Total weight of cases greater than or less than @var{value} or inside
+or outside the closed range [@var{low},@var{high}], respectively. The
+default format is F5.3.
+
+@item @subcmd{FGT(@var{var_name}@dots{}, @var{value})}
+@itemx @subcmd{FLT(@var{var_name}@dots{}, @var{value})}
+@itemx @subcmd{FIN(@var{var_name}@dots{}, @var{low}, @var{high})}
+@itemx @subcmd{FOUT(@var{var_name}@dots{}, @var{low}, @var{high})}
+Fraction of values greater than or less than @var{value} or inside or
+outside the closed range [@var{low},@var{high}], respectively. The
+default format is F5.3.
+
+@item @subcmd{FIRST(@var{var_name}@dots{})}
+@itemx @subcmd{LAST(@var{var_name}@dots{})}
+First or last non-missing value, respectively, 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.
+This means that
+the first (or last) case with particular values for the break variables before
+sorting is also the first (or last) case in that break group after sorting.
-@item @subcmd{MAX(@var{var_name})}
-Maximum value. The aggregation variable receives the complete
-dictionary information from the source variable.
-
-@item @subcmd{MEAN(@var{var_name})}
-Arithmetic mean. Limited to numeric values. The default format is
-F8.2.
-
-@item @subcmd{MEDIAN(@var{var_name})}
-The median value. Limited to numeric values. The default format is F8.2.
+@item @subcmd{MIN(@var{var_name}@dots{})}
+@itemx @subcmd{MAX(@var{var_name}@dots{})}
+Minimum or maximum value, respectively. The aggregation variable
+receives the complete dictionary information from the source variable.
-@item @subcmd{MIN(@var{var_name})}
-Minimum value. The aggregation variable receives the complete
-dictionary information from the source variable.
+@item @subcmd{N(@var{var_name}@dots{})}
+@itemx @subcmd{NMISS(@var{var_name}@dots{})}
+Total weight of non-missing or missing values, respectively. The
+default format is F7.0 if weighting is not enabled, F8.2 if it is
+(@pxref{WEIGHT}).
+
+@item @subcmd{NU(@var{var_name}@dots{})}
+@itemx @subcmd{NUMISS(@var{var_name}@dots{})}
+Count of non-missing or missing values, respectively, ignoring case
+weights. The default format is F7.0.
+
+@item @subcmd{PGT(@var{var_name}@dots{}, @var{value})}
+@itemx @subcmd{PLT(@var{var_name}@dots{}, @var{value})}
+@itemx @subcmd{PIN(@var{var_name}@dots{}, @var{low}, @var{high})}
+@itemx @subcmd{POUT(@var{var_name}@dots{}, @var{low}, @var{high})}
+Percentage between 0 and 100 of values greater than or less than
+@var{VALUE} or inside or outside the closed range
+[@var{low},@var{high}], respectively. The default format is F5.1.
+@end table
-@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}).
+These aggregation functions do not accept source variables:
+@table @asis
@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 @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 @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.
+Total weight 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 @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.
+Count of cases aggregated to form this group, ignoring case weights.
The default format is F7.0.
-
-@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 @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 @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 @subcmd{PLT(@var{var_name}, @var{value})}
-Percentage of values less than the specified constant. The default
-format is F5.1.
-
-@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 @subcmd{SD(@var{var_name})}
-Standard deviation of the mean. Limited to numeric values. The
-default format is F8.2.
-
-@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
@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
@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
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 kg divided
+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.}
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}
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.
@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