From 5f832a7feba823b45f0e692f4052a3ceb081df65 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Fri, 3 Jun 2022 14:57:36 -0700 Subject: [PATCH] docs --- doc/statistics.texi | 127 ++++++++++++++++++++++++++++++-- doc/utilities.texi | 1 + tests/language/stats/ctables.at | 2 +- 3 files changed, 123 insertions(+), 7 deletions(-) diff --git a/doc/statistics.texi b/doc/statistics.texi index 887277d8b2..8c4a2dde44 100644 --- a/doc/statistics.texi +++ b/doc/statistics.texi @@ -940,7 +940,9 @@ optional: @t{/VLABELS} @t{VARIABLES=}@i{variables} @t{DISPLAY}=@{@t{DEFAULT} @math{|} @t{NAME} @math{|} @t{LABEL} @math{|} @t{BOTH} @math{|} @t{NONE}@} +@ignore @c not yet implemented @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{} @@ -1076,7 +1078,7 @@ CTABLES /TABLE (qn26 + qn27) > qns3a. @subsubsection Scalar Variables For a categorical variable, @code{CTABLES} divides the table into a -cell per category. For a scalar variables, @code{CTABLES} instead +cell per category. For a scalar variable, @code{CTABLES} instead calculates a summary measure, by default the mean, of the values that fall into a cell. For example, if the only variable specified is a scalar variable, then the output is a single cell that holds the mean @@ -1250,7 +1252,7 @@ A percentage of valid values within the specified @var{area}. A percentage of total values within the specified @var{area}. @end table -The following summary functions apply only to scale variables: +The following summary functions apply only to scalar variables: @table @asis @item @code{MAXIMUM} (``Maximum'') @@ -1471,7 +1473,7 @@ specified any number of times, each time for a different set of variables. @code{CATEGORIES} applies to the table produced by the @code{TABLE} subcommand that it follows. -@code{CATEGORIES} does not apply to scale variables. +@code{CATEGORIES} does not apply to scalar variables. @t{VARIABLES} is required. List the variables for the subcommand to affect. @@ -1481,6 +1483,7 @@ order: @table @asis @item Explicit categories. +@anchor{CTABLE Explicit Category List} To explicitly specify categories to include, list the categories within square brackets in the desired sort order. Use spaces or commas to separate values. Categories not covered by the list are @@ -1512,6 +1515,9 @@ specify their category values.) @item OTHERNM 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} +A computed category name (@pxref{CTABLES Computed Categories}). @end table Additional forms, described later, allow for subtotals. @@ -1528,7 +1534,7 @@ also be sorted by value label, with @code{KEY=LABEL}, or by the value of a summary function, e.g.@: @code{KEY=COUNT}. For summary functions, a variable name may be specified in parentheses, e.g.@: @code{KEY=MAXIUM(qnd1)}, and this is required for functions that apply -only to scale variables. The @code{PTILE} function also requires a +only to scalar variables. The @code{PTILE} function also requires a percentage argument, e.g.@: @code{KEY=PTILE(qnd1, 90)}. Only summary functions used in the table may be used, except that @code{COUNT} is always allowed. @@ -1562,9 +1568,9 @@ category and subtotals apply to categories that precede them. With @code{POSITION=BEFORE}, totals come before the first category and subtotals apply to categories that follow them. -Only categorical variables may have totals and subtotals. Scale +Only categorical variables may have totals and subtotals. Scalar variables may be ``totaled'' indirectly by enabling totals and -subtotals on a categorical variable within which the scale variable is +subtotals on a categorical variable within which the scalar variable is summarized. @subsubheading Categories Without Values @@ -1596,6 +1602,115 @@ title appears above the table, the caption below the table, and the corner text appears in the table's upper left corner. By default, the title is ``Custom Tables'' and the caption and corner text are empty. +@node CTABLES Table Formatting +@subsection Table Formatting + +@display +@t{/FORMAT} + [@t{MINCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}] + [@t{MAXCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}] + [@t{UNITS=}@{@t{POINTS} @math{|} @t{INCHES} @math{|} @t{CM}@}] + [@t{EMPTY=}@{@t{ZERO} @math{|} @t{BLANK} @math{|} @i{string}@}] + [@t{MISSING=}@i{string}] +@end display + +The @code{FORMAT} subcommand, which must precede the first +@code{TABLE} subcommand, controls formatting for all the output +tables. @code{FORMAT} and all of its settings are optional. + +Use @code{MINCOLWIDTH} and @code{MAXCOLWIDTH} to control the minimum +or maximum width of columns in output tables. By default, or with +@code{DEFAULT}, column width varies based on content. Otherwise, +specify a number for either or both of these settings. If both are +specified, @code{MAXCOLWIDTH} must be bigger than @code{MINCOLWIDTH}. +The default unit, or with @code{UNITS=POINTS}, is points (1/72 inch), +but specify @code{UNITS=INCHES} to use inches or @code{UNITS=CM} for +centimeters. + +By default, or with @code{EMPTY=ZERO}, zero values are displayed in +their usual format. Use @code{EMPTY=BLANK} to use an empty cell +instead, or @code{EMPTY="@i{string}"} to use the specified string. + +By default, missing values are displayed as @samp{.}, the same as in +other tables. Specify @code{MISSING="@i{string}"} to instead use a +custom string. + +@node CTABLES Display of Variable Labels +@subsection Display of Variable Labels + +@display +@t{/VLABELS} + @t{VARIABLES=}@i{variables} + @t{DISPLAY}=@{@t{DEFAULT} @math{|} @t{NAME} @math{|} @t{LABEL} @math{|} @t{BOTH} @math{|} @t{NONE}@} +@end display + +The @code{VLABELS} subcommand, which must precede the first +@code{TABLE} subcommand, controls display of variable labels in all +the output tables. @code{VLABELS} is optional. It may appear +multiple times to adjust settings for different variables. + +@code{VARIABLES} and @code{DISPLAY} are required. The value of +@code{DISPLAY} controls how variable labels are displayed for the +variables listed on @code{VARIABLES}. The supported values are: + +@table @code +@item DEFAULT +Uses the setting from @ref{SET TVARS}. + +@item NAME +Show only a variable name. + +@item LABEL +Show only a variable label. + +@item BOTH +Show variable name and label. + +@item NONE +Show nothing. +@end table + +@node CTABLES Missing Value Treatment +@subsection Missing Value Treatment + +@display +@t{/SMISSING} @{@t{VARIABLE} @math{|} @t{LISTWISE}@} +@end display + +The @code{SMISSING} subcommand, which must precede the first +@code{TABLE} subcommand, controls treatment of missing values for +scalar variables in producing all the output tables. @code{SMISSING} +is optional. + +With @code{SMISSING=VARIABLE}, which is the default, missing values +are excluded on a variable-by-variable basis. With +@code{SMISSING=LISTWISE}, when scalar variables are stacked, a missing +value for any of the scalar variables causes the case to be excluded +for all of them. + +@node CTABLES Computed Categories +@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}@} +@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{CTABLE Explicit Category List}), and on +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 +postcomputes. + @node FACTOR @section FACTOR diff --git a/doc/utilities.texi b/doc/utilities.texi index c20410384e..8dce637cc8 100644 --- a/doc/utilities.texi +++ b/doc/utilities.texi @@ -845,6 +845,7 @@ If the value has no label, then the literal value is used for display. If @subcmd{TNUMBERS} is set to @subcmd{BOTH}, then values are displayed with both their label (if any) and their literal value in parentheses. @item TVARS +@anchor{SET TVARS} The @subcmd{TVARS} option sets the way in which variables are displayed in output tables. The valid settings are @subcmd{NAMES}, @subcmd{LABELS} and @subcmd{BOTH}. If @subcmd{TVARS} is set to @subcmd{NAMES}, then all variables are displayed using their names. diff --git a/tests/language/stats/ctables.at b/tests/language/stats/ctables.at index ec89cab1a5..196afe06a8 100644 --- a/tests/language/stats/ctables.at +++ b/tests/language/stats/ctables.at @@ -35,7 +35,7 @@ dnl * MINCOLWIDTH, MAXCOLWIDTH, UNITS. dnl * EMPTY. dnl * MISSING. dnl - VLABELS. -dnl - SMISSING. +dnl - SMISSING (see documentation). dnl - Test WEIGHT and adjustment weights. dnl - Test PCOMPUTE and PPROPERTIES. dnl - PCOMPUTE: -- 2.30.2