From c2bb9cc94805a9cecaa02ff6171115c484aef063 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Fri, 3 Jun 2022 16:33:01 -0700 Subject: [PATCH] doc first draft is done --- doc/statistics.texi | 136 +++++++++++++++++++++++++++++--- tests/language/stats/ctables.at | 3 + 2 files changed, 130 insertions(+), 9 deletions(-) diff --git a/doc/statistics.texi b/doc/statistics.texi index 8c4a2dde44..adf1f67d95 100644 --- a/doc/statistics.texi +++ b/doc/statistics.texi @@ -944,8 +944,8 @@ optional: @t{/MRSETS COUNTDUPLICATES=}@{@t{YES} @math{|} @t{NO}@} @end ignore @t{/SMISSING} @{@t{VARIABLE} @math{|} @t{LISTWISE}@} -@t{/PCOMPUTE} @t{&}@i{category}@t{=EXPR(}@i{expression}@t{)} -@t{/PPROPERTIES} @t{&}@i{category}@dots{} +@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}@} @@ -1516,7 +1516,7 @@ specify their category values.) Any non-missing value not covered by any other element of the list (regardless of where @t{OTHERNM} is placed in the list). -@item &@i{pcompute} +@item &@i{postcompute} A computed category name (@pxref{CTABLES Computed Categories}). @end table @@ -1692,11 +1692,7 @@ for all of them. @subsection Computed Categories @display -@t{/PCOMPUTE} @t{&}@i{category}@t{=EXPR(}@i{expression}@t{)} -@t{/PPROPERTIES} @t{&}@i{category}@dots{} - [@t{LABEL=}@i{string}] - [@t{FORMAT=}[@i{summary} @i{format}]@dots{}] - [@t{HIDESOURCECATS=}@{@t{NO} @math{|} @t{YES}@} +@t{/PCOMPUTE} @t{&}@i{postcompute}@t{=EXPR(}@i{expression}@t{)} @end display @dfn{Computed categories}, also called @dfn{postcomputes}, are @@ -1708,9 +1704,131 @@ the @code{PPROPERTIES} subcommand to define further properties for a given postcompute. @code{PCOMPUTE} must precede the first @code{TABLE} command. It is -optional and it may be used multiple times to define multiple +optional and it 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 +@samp{&}, followed by @samp{=} and a postcompute expression enclosed +in @code{EXPR(@dots{})}. A postcompute expression consists of: + +@table @t +@item [@i{category}] +This form evaluates to the summary statistic for @i{category}, e.g.@: +@code{[1]} evaluates to the value of the summary statistic associated +with category 1. The @i{category} may be a number, a quoted string, +or a quoted time or date value, and all of the categories for a given +postcompute must have the same form. + +@item [@i{min} THRU @i{max}] +@itemx [LO THRU @i{max}] +@itemx [@i{min} THRU HI] +@itemx MISSING +@itemx OTHERNM +These forms evaluate to the summary statistics for categories matching +the given syntax, as described in previous sections (@pxref{CTABLE +Explicit Category List}). If more than one category matches, their +values are summed. + +@item SUBTOTAL +The summary statistic for the subtotal category. This form is allowed +only for variables with exactly one subtotal. + +@item SUBTOTAL[@i{index}] +The summary statistic for subtotal category @i{index}, where 1 is the +first subtotal, 2 is the second, and so on. This form may be used for +any number of subtotals. + +@item TOTAL +The summary statistic for the total. + +@item @i{a} + @i{b} +@itemx @i{a} - @i{b} +@itemx @i{a} * @i{b} +@itemx @i{a} / @i{b} +@itemx @i{a} ** @i{b} +These forms perform arithmetic on the values of postcompute +expressions @i{a} and @i{b}. The usual operator precedence rules +apply. + +@item @i{number} +Numeric constants may be used in postcompute expressions. + +@item (@i{a}) +Parentheses override operator precedence. +@end table + +A postcompute is not associated with any particular variable. +Instead, it may be referenced within @code{CATEGORIES} for any +suitable variable (e.g.@: only a string variable is suitable for a +postcompute expression that refers to a string category, only a +variable with subtotals for an expression that refers to subtotals, +@dots{}). + +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. + +@node CTABLES Computed Category Properties +@subsection Computed Category Properties + +@display +@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 + +The @code{PPROPERTIES} subcommand, which must appear before +@code{TABLE}, sets properties for one or more postcomputes defined on +prior @code{PCOMPUTE} subcommands. The subcommand syntax begins with +the list of postcomputes, each prefixed with @samp{&} as specified on +@code{PCOMPUTE}. + +All of the settings on @code{PPROPERTIES} are optional. Use +@code{LABEL} to set the label shown for the postcomputes in table +output. The default label for a postcompute is the expression used to +define it. + +The @code{FORMAT} setting sets summary statistics and display formats +for the postcomputes. + +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. + +@node CTABLES Base Weight +@subsection Base Weight + +@display +@t{/WEIGHT VARIABLE=}@i{variable} +@end display + +The @code{WEIGHT} subcommand is optional and must appear before +@code{TABLE}. If it appears, it must name a numeric variable, known +as the @dfn{effective base weight} or @dfn{adjustment weight}. The +effective base weight variable is used for the @code{ECOUNT}, +@code{ETOTALN}, and @code{EVALIDN} summary functions. + +Cases with zero, missing, or negative effective base weight are +excluded from all analysis. + +Weights obtained from the @pspp{} dictionary are rounded to the +nearest integer. Effective base weights are not rounded. + +@node CTABLES Hiding Small Counts +@subsection Hiding Small Counts + +@display +@t{/HIDESMALLCOUNTS COUNT=@i{count}} +@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. + @node FACTOR @section FACTOR diff --git a/tests/language/stats/ctables.at b/tests/language/stats/ctables.at index 196afe06a8..34f2605b40 100644 --- a/tests/language/stats/ctables.at +++ b/tests/language/stats/ctables.at @@ -42,6 +42,9 @@ dnl - PCOMPUTE: dnl * multi-dimensional dnl * MISSING, OTHERNM dnl * strings +dnl - PPROPERTIES: +dnl * )LABEL[N]. +dnl * summary statistics and formats? dnl - HIDESMALLCOUNTS. dnl - Are string ranges a thing? dnl -- 2.30.2