From 3aaf55988637cd30d00acd14d188ed5716c0eb74 Mon Sep 17 00:00:00 2001
From: John Darrington <john@darrington.wattle.id.au>
Date: Sat, 28 Nov 2020 11:29:43 +0100
Subject: [PATCH] Documentation: Add an example showing how AGGREGATE works

---
 doc/automake.mk                |  3 ++-
 doc/pspp-figures/aggregate.sps | 10 ++++++++++
 doc/transformation.texi        | 28 ++++++++++++++++++++++++++++
 3 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 doc/pspp-figures/aggregate.sps

diff --git a/doc/automake.mk b/doc/automake.mk
index 9800d5849d..7cbb819db3 100644
--- a/doc/automake.mk
+++ b/doc/automake.mk
@@ -111,7 +111,8 @@ am__TEXINFO_TEX_DIR=:$(top_srcdir)/doc:$(top_builddir)/doc
 ################# Example programs ##############################
 
 FIGURE_SYNTAX = \
- doc/pspp-figures/autorecode.sps \
+ doc/pspp-figures/aggregate.sps \
+doc/pspp-figures/autorecode.sps \
  doc/pspp-figures/chisquare.sps \
  doc/pspp-figures/compute.sps \
  doc/pspp-figures/count.sps \
diff --git a/doc/pspp-figures/aggregate.sps b/doc/pspp-figures/aggregate.sps
new file mode 100644
index 0000000000..b84620b900
--- /dev/null
+++ b/doc/pspp-figures/aggregate.sps
@@ -0,0 +1,10 @@
+get file="personnel.sav".
+
+aggregate outfile=* 
+        mode = replace
+        /break= occupation
+        /occ_mean_salaray = mean (salary)
+        /occ_median_salary = median (salary)
+        /occ_std_dev_salary = sd (salary).
+
+list.
diff --git a/doc/transformation.texi b/doc/transformation.texi
index b6c8e960c7..5161df224e 100644
--- a/doc/transformation.texi
+++ b/doc/transformation.texi
@@ -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
-- 
2.30.2