Documentation: Add an example showing how AGGREGATE works

[pspp] / doc / transformation.texi

diff --git a/doc/transformation.texi b/doc/transformation.texi
index a3041680fcedb0ca1e6c50a0cfbcf1b2cf1d19e2..5161df224ebcb5c63fcb684e347b6791d7765b95 100644 (file)
--- a/doc/transformation.texi
+++ b/doc/transformation.texi
@@ -1,5 +1,5 @@
 @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;
@@ -224,6 +224,34 @@ 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
@@ -369,7 +397,7 @@ 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 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.}