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.
 
 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
 
 @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.
 
 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
 
 @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
 
 @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
 
 @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
 
     [@t{CORNER=}@i{string}@dots{}]
 @end display
 

-@c TODO Describe substitution variables
-

 The @code{TITLES} subcommand sets the title, caption, and corner text
 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
 
 @node CTABLES Table Formatting
 @subsection Table Formatting