From: Ben Pfaff Date: Sat, 27 Aug 2022 06:36:29 +0000 (-0700) Subject: documentation X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?p=pspp;a=commitdiff_plain;h=fb429d05d61e959fcd4a0116e9b4327967845f9d documentation --- diff --git a/doc/statistics.texi b/doc/statistics.texi index 82855902f2..2e4c96c6a1 100644 --- a/doc/statistics.texi +++ b/doc/statistics.texi @@ -1605,16 +1605,20 @@ variables. @code{CATEGORIES} applies to the table produced by the @t{VARIABLES} is required and must list the variables for the subcommand to affect. -There are two way to specify the Categories to include and their sort -order: +The syntax may specify the categories to include and their sort order +either explicitly or implicitly. The following sections give the +details of each form of syntax, followed by information on totals and +subtotals and the @code{EMPTY} setting. + +@node CTABLES Explicit Categories +@subsubsection Explicit Categories -@table @asis -@item Explicit categories. @anchor{CTABLES 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 -excluded from analysis. + +To use @code{CTABLES} 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 excluded from analysis. Each element of the list takes one of the following forms: @@ -1645,15 +1649,23 @@ Any non-missing value not covered by any other element of the list @item &@i{postcompute} A computed category name (@pxref{CTABLES Computed Categories}). + +@item SUBTOTAL +@itemx HSUBTOTAL +A subtotal (@pxref{CTABLES Totals and Subtotals}). @end table -Additional forms, described later, allow for subtotals. If multiple elements of the list cover a given category, the last one in the list takes precedence. -@item Implicit categories. -Without an explicit list of categories, @pspp{} sorts -categories automatically. +@c TODO example + +@node CTABLES Implicit Categories +@subsubsection Implicit Categories + +In the absence of an explicit list of categories, @code{CATEGORIES} +allows @code{KEY}, @code{ORDER}, and @code{MISSING} to specify how to +select and sort categories. The @code{KEY} setting specifies the sort key. By default, or with @code{KEY=VALUE}, categories are sorted by default. Categories may @@ -1674,35 +1686,42 @@ order. Specify @code{ORDER=D} to sort in descending order. User-missing values are excluded by default, or with @code{MISSING=EXCLUDE}. Specify @code{MISSING=INCLUDE} to include user-missing values. The system-missing value is always excluded. -@end table -@subsubheading Totals and Subtotals +@c TODO example + +@node CTABLES Totals and Subtotals +@subsubsection Totals and Subtotals -@code{CATEGORIES} also controls display of totals and subtotals. -Totals are not displayed with @code{TOTAL=NO}, which is also the -default. Specify @code{TOTAL=YES} to display a total. By default, -the total is labeled ``Total''; use @code{LABEL="@i{label}"} to -override it. +@code{CATEGORIES} also controls display of totals and subtotals. By +default, or with @code{TOTAL=NO}, totals are not displayed. Use +@code{TOTAL=YES} to display a total. By default, the total is labeled +``Total''; use @code{LABEL="@i{label}"} to override it. Subtotals are also not displayed by default. To add one or more subtotals, use an explicit category list and insert @code{SUBTOTAL} or @code{HSUBTOTAL} in the position or positions where the subtotal -should appear. With @code{SUBTOTAL}, the subtotal becomes an extra -row or column or layer; @code{HSUBTOTAL} additionally hides the -categories that make up the subtotal. Either way, the default label -is ``Subtotal'', use @code{SUBTOTAL="@i{label}"} or -@code{HSUBTOTAL="@i{label}"} to specify a custom label. +should appear. The subtotal becomes an extra row or column or layer. +@code{HSUBTOTAL} additionally hides the categories that make up the +subtotal. Either way, the default label is ``Subtotal'', use +@code{SUBTOTAL="@i{label}"} or @code{HSUBTOTAL="@i{label}"} to specify +a custom label. + +@c TODO By default, or with @code{POSITION=AFTER}, totals are displayed in the output after the last 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. +@c TODO + 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 scalar variable is summarized. +@c TODO + By default, @pspp{} uses the same summary functions for totals and subtotals as other categories. To summarize totals and subtotals differently, specify the summary functions for totals and subtotals @@ -1718,7 +1737,8 @@ CTABLES @end example @psppoutput {ctables26} -@subsubheading Categories Without Values +@node CTABLES Categories Without Values +@subsubsection Categories Without Values Some categories might not be included in the data set being analyzed. For example, our example data set has no cases in the ``15 or @@ -1732,6 +1752,8 @@ 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 + @node CTABLES Titles @subsection Titles @@ -1794,7 +1816,8 @@ specify a number for either or both of these settings. If both are specified, @code{MAXCOLWIDTH} must be greater than or equal to @code{MINCOLWIDTH}. The default unit, or with @code{UNITS=POINTS}, is points (1/72 inch), or specify @code{UNITS=INCHES} to use inches or -@code{UNITS=CM} for centimeters. +@code{UNITS=CM} for centimeters. @pspp{} does not currently honor any +of these settings. By default, or with @code{EMPTY=ZERO}, zero values are displayed in their usual format. Use @code{EMPTY=BLANK} to use an empty cell @@ -1839,6 +1862,8 @@ Show variable name and label. Show nothing. @end table +@c TODO example + @node CTABLES Missing Value Treatment @subsection Missing Value Treatment @@ -1865,6 +1890,8 @@ missing value treatment. A section below describes how to consider missing values listwise for summarizing scale variables. @end itemize +@c TODO example + @node CTABLES Missing Values for Summary Variables @subsubsection Missing Values for Summary Variables @@ -2045,6 +2072,8 @@ 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 + @node CTABLES Computed Category Properties @subsection Computed Category Properties @@ -2066,13 +2095,17 @@ All of the settings on @code{PPROPERTIES} are optional. Use 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. +A postcompute always uses same summary functions as the variable whose +categories contain it, but @code{FORMAT} allows control over the +format used to display their values. It takes a list of summary +function names and format specifiers. 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 + @node CTABLES Effective Weight @subsection Effective Weight @@ -2107,6 +2140,8 @@ 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. +@c TODO example + @node FACTOR @section FACTOR