wokr on documenting missing value treatment

[pspp] / doc / statistics.texi

diff --git a/doc/statistics.texi b/doc/statistics.texi
index 473e57aeb238bce42934774dc683834662a4eeb2..602f0ad57444d76cc4a701c4c900e495e6a36a81 100644 (file)
--- a/doc/statistics.texi
+++ b/doc/statistics.texi
@@ -1014,12 +1014,6 @@ In @code{TABLE}, each of @var{rows}, @var{columns}, and @var{layers}
 is either empty or an axis expression that specifies one or more
 variables.  At least one must specify an axis expression.
 
-@menu
-* CTABLES Categorical Variable Basics::
-* CTABLES Scalar Variable Basics::
-* CTABLES Overriding Measurement Level::
-@end menu
-
 @node CTABLES Categorical Variable Basics
 @subsubsection Categorical Variables
 
@@ -1229,13 +1223,6 @@ each function's name is given its default label and format.  If no
 format is listed, then the default format is the print format for the
 variable being summarized.
 
-@menu
-* CTABLES Summary Functions for Individual Cells::
-* CTABLES Summary Functions for Groups of Cells::
-* CTABLES Summary Functions for Adjusted Weights::
-* CTABLES Unweighted Summary Functions::
-@end menu
-
 @node CTABLES Summary Functions for Individual Cells
 @subsubsection Summary Functions for Individual Cells
 
@@ -1461,7 +1448,53 @@ counts:
 @code{UVARIANCE} (``Unweighted Variance'', F40.0)
 @end itemize
 
-@c TODO missing value treatment
+@node CTABLES Summarizing Missing Values
+@subsubsection Summarizing Missing Values
+
+CTABLES treats missing values in categorical and scale variables
+differently.  For categorical variables, in most cases values that are
+valid and in included categories are analyzed, and values that are
+missing or in excluded categories are not analyzed.  (@xref{CTABLES
+Per-Variable Category Options}), for information on included and
+excluded categories.)  The following chart, in which cells that
+contain ``yes'' indicate that a value is analyzed, and the notes below
+it give the exact rules:
+
+@multitable {@headitemfont{System-Missing}} {Included Category} {Excluded Category}
+@headitem                           @tab Included Category    @tab Excluded Category
+@item @headitemfont{Valid}          @tab yes                  @tab ---
+@item @headitemfont{User-Missing}   @tab yes [*]              @tab --- [+]
+@item @headitemfont{System-Missing} @tab n/a [#]              @tab --- [+]
+@end multitable
+
+@table @asis
+@item [*]
+Exceptions: The ``@t{VALIDN}'' summary functions (@code{VALIDN},
+@code{EVALIDN}, @code{UVALIDN}, @code{@i{area}PCT.VALIDN}, and
+@code{U@i{area}PCT.VALIDN}), which only count valid values in included
+categories.
+
+@item [+]
+Exceptions: The ``@t{TOTALN}'' summary functions (@code{TOTALN},
+@code{ETOTALN}, @code{UTOTALN}, @code{@i{area}PCT.TOTALN}), and
+@code{U@i{area}PCT.TOTALN}, which count all values (valid and missing)
+in included categories and missing (but not valid) values in excluded
+categories.
+
+@item [#]
+System-missing values are never in included categories.
+@end table
+
+@noindent
+The following table provides another view of the same information:
+
+@multitable {Missing values in excluded categories} {@code{VALIDN}} {other} {@code{TOTALN}}
+@headitem @tab @code{VALIDN} @tab other @tab @code{TOTALN}
+@item Valid values in included categories   @tab yes @tab yes @tab yes
+@item Missing values in included categories @tab --- @tab yes @tab yes
+@item Missing values in excluded categories @tab --- @tab --- @tab yes
+@item Valid values in excluded categories   @tab --- @tab --- @tab ---
+@end multitable
 
 @node CTABLES Statistics Positions and Labels
 @subsection Statistics Positions and Labels
@@ -1738,14 +1771,34 @@ or @code{OTHERNM}.
     [@t{CORNER=}@i{string}@dots{}]
 @end display
 
-@c TODO Describe substitution variables
-
 The @code{TITLES} subcommand sets the title, caption, and corner text
-for the table output for the previous @code{TABLE} subcommand.  The
-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.
-With some table output styles, the corner text is not displayed.
+for the table output for the previous @code{TABLE} subcommand.  Any
+number of strings may be specified for each kind of text, with each
+string appearing on a separate line in the output.  The 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.  With
+some table output styles, the corner text is not displayed.
+
+The strings provided in this subcommand may contain the following
+macro-like keywords that @pspp{} substitutes at the time that it runs
+the command:
+
+@table @code @c (
+@item )DATE
+The current date, e.g.@: MM/DD/YY.  The format is locale-dependent.
+
+@c (
+@item )TIME
+The current time, e.g.@: HH:MM:SS.  The format is locale-dependent.
+
+@c (
+@item )TABLE
+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