From 9e8fca7bd38927d335b81f5f1a282deff665e024 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Sat, 27 Aug 2022 22:16:26 -0700 Subject: [PATCH] doc examples --- NEWS | 2 ++ doc/automake.mk | 4 +++ doc/pspp-figures/ctables31.sps | 3 ++ doc/pspp-figures/ctables32.sps | 16 ++++++++++ doc/pspp-figures/ctables33.sps | 16 ++++++++++ doc/pspp-figures/ctables34.sps | 18 +++++++++++ doc/statistics.texi | 58 ++++++++++++++++++++++------------ 7 files changed, 97 insertions(+), 20 deletions(-) create mode 100644 doc/pspp-figures/ctables31.sps create mode 100644 doc/pspp-figures/ctables32.sps create mode 100644 doc/pspp-figures/ctables33.sps create mode 100644 doc/pspp-figures/ctables34.sps diff --git a/NEWS b/NEWS index d6c30dd4f4..61bbf1ff75 100644 --- a/NEWS +++ b/NEWS @@ -7,6 +7,8 @@ Please send PSPP bug reports to bug-gnu-pspp@gnu.org. Changes after 1.6.2: + * The CTABLES command is now implemented. + * Building from a Git repository, which previously required GIMP, now requires rsvg-convert from librsvg2 instead. diff --git a/doc/automake.mk b/doc/automake.mk index 13fd8fdd15..8a59653e0d 100644 --- a/doc/automake.mk +++ b/doc/automake.mk @@ -147,6 +147,10 @@ FIGURE_SYNTAX = \ doc/pspp-figures/ctables28.sps \ doc/pspp-figures/ctables29.sps \ doc/pspp-figures/ctables30.sps \ + doc/pspp-figures/ctables31.sps \ + doc/pspp-figures/ctables32.sps \ + doc/pspp-figures/ctables33.sps \ + doc/pspp-figures/ctables34.sps \ doc/pspp-figures/crosstabs.sps \ doc/pspp-figures/descriptives.sps \ doc/pspp-figures/flip.sps \ diff --git a/doc/pspp-figures/ctables31.sps b/doc/pspp-figures/ctables31.sps new file mode 100644 index 0000000000..bde6fa52a8 --- /dev/null +++ b/doc/pspp-figures/ctables31.sps @@ -0,0 +1,3 @@ +GET FILE='nhtsa.sav'. +CTABLES /TABLE=qns1. +CTABLES /TABLE=qns1 /CATEGORIES VARIABLES=qns1 EMPTY=EXCLUDE. diff --git a/doc/pspp-figures/ctables32.sps b/doc/pspp-figures/ctables32.sps new file mode 100644 index 0000000000..9ec814bc05 --- /dev/null +++ b/doc/pspp-figures/ctables32.sps @@ -0,0 +1,16 @@ +GET FILE='nhtsa.sav'. +DATA LIST LIST NOTABLE /x y (F1.0) z (F10.0). +VARIABLE LEVEL z (SCALE). +MISSING VALUES x y (9). +BEGIN DATA. +1 1 1 +1 2 10 +1 9 100 +2 1 1000 +2 2 10000 +2 9 100000 +9 1 1000000 +9 2 10000000 +9 9 100000000 +END DATA. +LIST. \ No newline at end of file diff --git a/doc/pspp-figures/ctables33.sps b/doc/pspp-figures/ctables33.sps new file mode 100644 index 0000000000..e7c9fa828f --- /dev/null +++ b/doc/pspp-figures/ctables33.sps @@ -0,0 +1,16 @@ +GET FILE='nhtsa.sav'. +DATA LIST LIST NOTABLE /x y (F1.0) z (F10.0). +VARIABLE LEVEL z (SCALE). +MISSING VALUES x y (9). +BEGIN DATA. +1 1 1 +1 2 10 +1 9 100 +2 1 1000 +2 2 10000 +2 9 100000 +9 1 1000000 +9 2 10000000 +9 9 100000000 +END DATA. +CTABLES /TABLE x > y > z [SUM]. diff --git a/doc/pspp-figures/ctables34.sps b/doc/pspp-figures/ctables34.sps new file mode 100644 index 0000000000..9e96ef1e30 --- /dev/null +++ b/doc/pspp-figures/ctables34.sps @@ -0,0 +1,18 @@ +GET FILE='nhtsa.sav'. +DATA LIST LIST NOTABLE /x y (F1.0) z (F10.0). +VARIABLE LEVEL z (SCALE). +MISSING VALUES x y (9). +BEGIN DATA. +1 1 1 +1 2 10 +1 9 100 +2 1 1000 +2 2 10000 +2 9 100000 +9 1 1000000 +9 2 10000000 +9 9 100000000 +END DATA. +CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=y MISSING=INCLUDE. +CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=x y MISSING=INCLUDE. + diff --git a/doc/statistics.texi b/doc/statistics.texi index 0cfceb225a..b79997bc15 100644 --- a/doc/statistics.texi +++ b/doc/statistics.texi @@ -1781,7 +1781,15 @@ categories, they include all the values listed individually and all values with value labels that are covered by ranges or @code{MISSING} or @code{OTHERNM}. -@c TODO +The following example syntax and output show the effect of +@code{EMPTY=EXCLUDE} for the @code{qns1} variable, in which 0 is labeled +``None'' but no cases exist with that value: + +@example +CTABLES /TABLE=qns1. +CTABLES /TABLE=qns1 /CATEGORIES VARIABLES=qns1 EMPTY=EXCLUDE. +@end example +@psppoutput {ctables31} @node CTABLES Titles @subsection Titles @@ -1820,8 +1828,6 @@ The expression specified on the @code{TABLE} command. Summary and measurement level specifications are omitted, and variable labels are used in place of variable names. @end table -@c TODO example - @node CTABLES Table Formatting @subsection Table Formatting @@ -1891,8 +1897,6 @@ Show variable name and label. Show nothing. @end table -@c TODO example - @node CTABLES Missing Value Treatment @subsection Missing Value Treatment @@ -1900,26 +1904,40 @@ The @code{TABLE} subcommand on @code{CTABLES} specifies two different kinds of variables: variables that divide tables into cells (which are always categorical) and variables being summarized (which may be categorical or scale). @pspp{} treats missing values differently in -each kind of variable: +each kind of variable, as described in the sections below. + +@node CTABLES Missing Values for Cell-Defining Variables +@subsubsection Missing Values for Cell-Defining Variables -@itemize @bullet -@item For variables that divide tables into cells, per-variable category -options determine which data is analyzed. If any of the categories -for such a variable would exclude a case, then that case is not -included. +options, as described in @ref{CTABLES Per-Variable Category Options}, +determine which data is analyzed. If any of the categories for such a +variable would exclude a case, then that case is not included. -@item -The treatment of missing values in variables being summarized varies -between scale and scale and categorical variables. The following -section describes their treatment in detail. +As an example, consider the following entirely artificial dataset, in +which @samp{x} and @samp{y} are categorical variables with missing +value 9, and @samp{z} is scale: -By default, each summarized variable is considered separately for -missing value treatment. A section below describes how to consider -missing values listwise for summarizing scale variables. -@end itemize +@psppoutput{ctables32} -@c TODO example +Using @samp{x} and @samp{y} to define cells, and summarizing @samp{z}, +by default @pspp{} omits all the cases that have @samp{x} or @samp{y} (or both) +missing: + +@example +CTABLES /TABLE x > y > z [SUM]. +@end example +@psppoutput{ctables33} + +If, however, we add @code{CATEGORIES} specifications to include +missing values for @samp{y} or for @samp{x} and @samp{y}, the output +table includes them, like so: + +@example +CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=y MISSING=INCLUDE. +CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=x y MISSING=INCLUDE. +@end example +@psppoutput{ctables34} @node CTABLES Missing Values for Summary Variables @subsubsection Missing Values for Summary Variables -- 2.30.2