From d98583b9425b8a053dc21b539203406bac74adc5 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Sun, 28 Aug 2022 10:19:35 -0700 Subject: [PATCH] finish docs? --- doc/automake.mk | 2 + doc/pspp-figures/ctables32.sps | 1 - doc/pspp-figures/ctables33.sps | 1 - doc/pspp-figures/ctables34.sps | 1 - doc/pspp-figures/ctables35.sps | 11 +++++ doc/pspp-figures/ctables36.sps | 2 + doc/statistics.texi | 71 +++++++++++++++++++++++++-------- tests/language/stats/ctables.at | 36 +++++++++++++++++ 8 files changed, 105 insertions(+), 20 deletions(-) create mode 100644 doc/pspp-figures/ctables35.sps create mode 100644 doc/pspp-figures/ctables36.sps diff --git a/doc/automake.mk b/doc/automake.mk index 8a59653e0d..e80d5c5043 100644 --- a/doc/automake.mk +++ b/doc/automake.mk @@ -151,6 +151,8 @@ FIGURE_SYNTAX = \ doc/pspp-figures/ctables32.sps \ doc/pspp-figures/ctables33.sps \ doc/pspp-figures/ctables34.sps \ + doc/pspp-figures/ctables35.sps \ + doc/pspp-figures/ctables36.sps \ doc/pspp-figures/crosstabs.sps \ doc/pspp-figures/descriptives.sps \ doc/pspp-figures/flip.sps \ diff --git a/doc/pspp-figures/ctables32.sps b/doc/pspp-figures/ctables32.sps index 9ec814bc05..85617c5565 100644 --- a/doc/pspp-figures/ctables32.sps +++ b/doc/pspp-figures/ctables32.sps @@ -1,4 +1,3 @@ -GET FILE='nhtsa.sav'. DATA LIST LIST NOTABLE /x y (F1.0) z (F10.0). VARIABLE LEVEL z (SCALE). MISSING VALUES x y (9). diff --git a/doc/pspp-figures/ctables33.sps b/doc/pspp-figures/ctables33.sps index e7c9fa828f..ef768b864a 100644 --- a/doc/pspp-figures/ctables33.sps +++ b/doc/pspp-figures/ctables33.sps @@ -1,4 +1,3 @@ -GET FILE='nhtsa.sav'. DATA LIST LIST NOTABLE /x y (F1.0) z (F10.0). VARIABLE LEVEL z (SCALE). MISSING VALUES x y (9). diff --git a/doc/pspp-figures/ctables34.sps b/doc/pspp-figures/ctables34.sps index 9e96ef1e30..48f38df89f 100644 --- a/doc/pspp-figures/ctables34.sps +++ b/doc/pspp-figures/ctables34.sps @@ -1,4 +1,3 @@ -GET FILE='nhtsa.sav'. DATA LIST LIST NOTABLE /x y (F1.0) z (F10.0). VARIABLE LEVEL z (SCALE). MISSING VALUES x y (9). diff --git a/doc/pspp-figures/ctables35.sps b/doc/pspp-figures/ctables35.sps new file mode 100644 index 0000000000..7024f9d707 --- /dev/null +++ b/doc/pspp-figures/ctables35.sps @@ -0,0 +1,11 @@ +GET FILE='nhtsa.sav'. +CTABLES + /PCOMPUTE &all_drivers=EXPR([1 THRU 2] + [3 THRU 4]) + /PPROPERTIES &all_drivers LABEL='All Drivers' + /PCOMPUTE &pct_never=EXPR([5] / ([1 THRU 2] + [3 THRU 4] + [5]) * 100) + /PPROPERTIES &pct_never LABEL='% Not Drivers' FORMAT=COUNT PCT40.1 + /TABLE=qn1 BY qns3a + /CATEGORIES VARIABLES=qn1 [1 THRU 2, SUBTOTAL='Frequent Drivers', + 3 THRU 4, SUBTOTAL='Infrequent Drivers', + &all_drivers, 5, &pct_never, + MISSING, SUBTOTAL='Not Drivers or Missing']. diff --git a/doc/pspp-figures/ctables36.sps b/doc/pspp-figures/ctables36.sps new file mode 100644 index 0000000000..6ee7387aaa --- /dev/null +++ b/doc/pspp-figures/ctables36.sps @@ -0,0 +1,2 @@ +GET FILE='nhtsa.sav'. +CTABLES /HIDESMALLCOUNTS COUNT=10 /TABLE qn37. diff --git a/doc/statistics.texi b/doc/statistics.texi index b79997bc15..4c65898b8e 100644 --- a/doc/statistics.texi +++ b/doc/statistics.texi @@ -2040,19 +2040,30 @@ CTABLES /SMISSING LISTWISE /TABLE (y > x) + (z > x). @display @t{/PCOMPUTE} @t{&}@i{postcompute}@t{=EXPR(}@i{expression}@t{)} +@t{/PPROPERTIES} @t{&}@i{postcompute}@dots{} + [@t{LABEL=}@i{string}] + [@t{FORMAT=}[@i{summary} @i{format}]@dots{}] + [@t{HIDESOURCECATS=}@{@t{NO} @math{|} @t{YES}@} @end display @dfn{Computed categories}, also called @dfn{postcomputes}, are categories created using arithmetic on categories obtained from the -data. The @code{PCOMPUTE} subcommand defines computed categories, -which can then be used in two places: on @code{CATEGORIES} within an -explicit category list (@pxref{CTABLES Explicit Category List}), and on -the @code{PPROPERTIES} subcommand to define further properties for a -given postcompute. +data. The @code{PCOMPUTE} subcommand creates a postcompute, which may +then be used on @code{CATEGORIES} within an explicit category list +(@pxref{CTABLES Explicit Category List}). Optionally, +@code{PPROPERTIES} refines how a postcompute is displayed. The +following sections provide the details. + +@node CTABLES PCOMPUTE +@subsubsection PCOMPUTE + +@display +@t{/PCOMPUTE} @t{&}@i{postcompute}@t{=EXPR(}@i{expression}@t{)} +@end display -@code{PCOMPUTE} must precede the first @code{TABLE} command. It is -optional and it may be used any number of times to define multiple -postcomputes. +The @code{PCOMPUTE} subcommand, which must precede the first +@code{TABLE} command, defines computed categories. It is optional and +may be used any number of times to define multiple postcomputes. Each @code{PCOMPUTE} defines one postcompute. Its syntax consists of a name to identify the postcompute as a @pspp{} identifier prefixed by @@ -2119,10 +2130,30 @@ Normally a named postcompute is defined only once, but if a later @code{PCOMPUTE} redefines a postcompute with the same name as an earlier one, the later one take precedence. -@c TODO example +The following syntax and output shows how @code{PCOMPUTE} can compute +a total over subtotals, summing the ``Frequent Drivers'' and +``Infrequent Drivers'' subtotals to form an ``All Drivers'' +postcompute. It also shows how to calculate and display a percentage, +in this case the percentage of valid responses that report never +driving. It uses @code{PPROPERTIES} (@pxref{CTABLES PPROPERTIES}) to +display the latter in @code{PCT} format. + +@example +CTABLES + /PCOMPUTE &all_drivers=EXPR([1 THRU 2] + [3 THRU 4]) + /PPROPERTIES &all_drivers LABEL='All Drivers' + /PCOMPUTE &pct_never=EXPR([5] / ([1 THRU 2] + [3 THRU 4] + [5]) * 100) + /PPROPERTIES &pct_never LABEL='% Not Drivers' FORMAT=COUNT PCT40.1 + /TABLE=qn1 BY qns3a + /CATEGORIES VARIABLES=qn1 [1 THRU 2, SUBTOTAL='Frequent Drivers', + 3 THRU 4, SUBTOTAL='Infrequent Drivers', + &all_drivers, 5, &pct_never, + MISSING, SUBTOTAL='Not Drivers or Missing']. +@end example +@psppoutput{ctables35} -@node CTABLES Computed Category Properties -@subsection Computed Category Properties +@node CTABLES PPROPERTIES +@subsubsection PPROPERTIES @display @t{/PPROPERTIES} @t{&}@i{postcompute}@dots{} @@ -2151,7 +2182,7 @@ By default, or with @code{HIDESOURCECATS=NO}, categories referred to by computed categories are displayed like other categories. Use @code{HIDESOURCECATS=YES} to hide them. -@c TODO example +The previous section provides an example for @code{PPROPERTIES}. @node CTABLES Effective Weight @subsection Effective Weight @@ -2182,12 +2213,18 @@ with zero, missing, or negative effective weights. @end display The @code{HIDESMALLCOUNTS} subcommand is optional. If it specified, -then count values in output tables less than the value of @i{count} -are shown as @code{<@i{count}} instead of their true values. The -value of @i{count} must be an integer and must be at least 2. Case -weights are considered for deciding whether to hide a count. +then @code{COUNT}, @code{ECOUNT}, and @code{UCOUNT} values in output +tables less than the value of @i{count} are shown as @code{<@i{count}} +instead of their true values. The value of @i{count} must be an +integer and must be at least 2. + +The following syntax and example shows how to use +@code{HIDESMALLCOUNTS}: -@c TODO example +@example +CTABLES /HIDESMALLCOUNTS COUNT=10 /TABLE qn37. +@end example +@psppoutput{ctables36} @node FACTOR @section FACTOR diff --git a/tests/language/stats/ctables.at b/tests/language/stats/ctables.at index 3ca41fc249..725731c7db 100644 --- a/tests/language/stats/ctables.at +++ b/tests/language/stats/ctables.at @@ -1,5 +1,41 @@ AT_BANNER([CTABLES]) +dnl Known bugs: +dnl TOTAL interaction with PCOMPUTE, e.g. the following +dnl CTABLES +dnl /PCOMPUTE &all_drivers=EXPR([1 THRU 2] + [3 THRU 4]) +dnl /PPROPERTIES &all_drivers LABEL='All Drivers' +dnl /PCOMPUTE &pct_not_drivers=EXPR([5] / ([1 THRU 2] + [3 THRU 4] + [5]) * 100) +dnl /PPROPERTIES &pct_not_drivers LABEL='% Not Drivers' FORMAT=COUNT PCT40.1 +dnl /TABLE=qn1 BY qns3a +dnl /CATEGORIES VARIABLES=qns3a TOTAL=YES +dnl /CATEGORIES VARIABLES=qn1 [1 THRU 2, SUBTOTAL='Frequent Drivers', +dnl 3 THRU 4, SUBTOTAL='Infrequent Drivers', +dnl &all_drivers, 5, &pct_not_drivers, +dnl MISSING, SUBTOTAL='Not Drivers or Missing']. +dnl yields gaps in the Total column: +dnl ╭─────────────────────────────────────────────────────────────────────────┬──────────────────╮ +dnl │ │ S3a. GENDER: │ +dnl │ ├─────┬──────┬─────┤ +dnl │ │ Male│Female│Total│ +dnl │ ├─────┼──────┼─────┤ +dnl │ │Count│ Count│Count│ +dnl ├─────────────────────────────────────────────────────────────────────────┼─────┼──────┼─────┤ +dnl │ 1. How often do you usually drive a car or other Every day │ 2305│ 2362│ 4667│ +dnl │motor vehicle? Several days a week │ 440│ 834│ 1274│ +dnl │ Frequent Drivers │ 2745│ 3196│ │ +dnl │ Once a week or less │ 125│ 236│ 361│ +dnl │ Only certain times a │ 58│ 72│ 130│ +dnl │ year │ │ │ │ +dnl │ Infrequent Drivers │ 183│ 308│ │ +dnl │ All Drivers │ 2928│ 3504│ │ +dnl │ Never │ 192│ 348│ 540│ +dnl │ % Not Drivers │ 6.2%│ 9.0%│ │ +dnl │ Don't know │ 3│ 5│ 8│ +dnl │ Refused │ 9│ 10│ 19│ +dnl │ Not Drivers or │ 204│ 363│ │ +dnl │ Missing │ │ │ │ +dnl ╰─────────────────────────────────────────────────────────────────────────┴─────┴──────┴─────╯ dnl Features not yet implemented: dnl - Multiple response sets dnl - MRSETS subcommand. -- 2.30.2