work on docs

[pspp] / doc / statistics.texi

diff --git a/doc/statistics.texi b/doc/statistics.texi
index 44db27aad129f0585f8027c1ad88df8a2e5a319d..b1e040283d1b6dcf19231f9e5cf87607df71124f 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
 


@@ -1186,7 +1180,30 @@ CTABLES /TABLE=AgeGroup [COLPCT 'Gender %' PCT5.0,
 @end example
 @psppoutput {ctables11}
 
 @end example
 @psppoutput {ctables11}
 

-@c TODO special CTABLES formats
+In addition to the standard formats, @code{CTABLES} allows the user to
+specify the following special formats:
+
+@multitable {@code{NEGPAREN@i{w}.@i{d}}} {Encloses all numbers in parentheses.} {@t{(42.96%)}} {@t{(-42.96%)}}
+@item @code{NEGPAREN@i{w}.@i{d}}
+@tab Encloses negative numbers in parentheses.
+@tab @t{@w{    }42.96}
+@tab @t{@w{  }(42.96)}
+
+@item @code{NEQUAL@i{w}.@i{d}}
+@tab Adds a @code{N=} prefix.
+@tab @t{@w{  }N=42.96}
+@tab @t{@w{ }N=-42.96}
+
+@item @code{@code{PAREN@i{w}.@i{d}}}
+@tab Encloses all numbers in parentheses.
+@tab @t{@w{  }(42.96)}
+@tab @t{@w{ }(-42.96)}
+
+@item @code{PCTPAREN@i{w}.@i{d}}
+@tab Encloses all numbers in parentheses with a @samp{%} suffix.
+@tab @t{@w{ }(42.96%)}
+@tab @t{(-42.96%)}
+@end multitable

 
 Parentheses provide a shorthand to apply summary specifications to
 multiple variables.  For example, both of these commands:
 
 Parentheses provide a shorthand to apply summary specifications to
 multiple variables.  For example, both of these commands:


@@ -1206,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
 


@@ -1504,8 +1514,8 @@ CTABLES /TABLE AgeGroup BY qns3a.
 
 @t{ROWLABELS=OPPOSITE} or @t{COLLABELS=OPPOSITE} move row or column
 variable category labels, respectively, to the opposite axis.  The
 
 @t{ROWLABELS=OPPOSITE} or @t{COLLABELS=OPPOSITE} move row or column
 variable category labels, respectively, to the opposite axis.  The

-setting affects only the innermost variable on the given axis.  For
-example:
+setting affects only the innermost variable or variables, which must
+be categorical, on the given axis.  For example:

 
 @example
 CTABLES /TABLE AgeGroup BY qns3a /CLABELS ROWLABELS=OPPOSITE.
 
 @example
 CTABLES /TABLE AgeGroup BY qns3a /CLABELS ROWLABELS=OPPOSITE.


@@ -1519,8 +1529,6 @@ column variable category labels, respectively, to the layer axis.
 Only one axis's labels may be moved, whether to the opposite axis or
 to the layer axis.
 
 Only one axis's labels may be moved, whether to the opposite axis or
 to the layer axis.
 

-@c TODO Moving category labels for stacked variables
-

 @subsubheading Effect on Summary Statistics
 
 @code{CLABELS} primarily affects the appearance of tables, not the
 @subsubheading Effect on Summary Statistics
 
 @code{CLABELS} primarily affects the appearance of tables, not the


@@ -1548,6 +1556,23 @@ CTABLES
 @end example
 @psppoutput {ctables24}
 
 @end example
 @psppoutput {ctables24}
 

+@subsubheading Moving Categories for Stacked Variables
+
+If @code{CLABELS} moves category labels from an axis with stacked
+variables, the variables that are moved must have the same category
+specifications (@pxref{CTABLES Per-Variable Category Options}) and the
+same value labels.
+
+The following shows both moving stacked category variables and
+adapting to the changing definitions of rows and columns:
+
+@example
+CTABLES /TABLE (qn105ba + qn105bb) [COLPCT].
+CTABLES /TABLE (qn105ba + qn105bb) [ROWPCT]
+  /CLABELS ROW=OPPOSITE.
+@end example
+@psppoutput {ctables25}
+

 @node CTABLES Per-Variable Category Options
 @subsection Per-Variable Category Options
 
 @node CTABLES Per-Variable Category Options
 @subsection Per-Variable Category Options
 


@@ -1698,14 +1723,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


@@ -1778,6 +1823,60 @@ Show nothing.
 @node CTABLES Missing Value Treatment
 @subsection Missing Value Treatment
 
 @node CTABLES Missing Value Treatment
 @subsection Missing Value Treatment
 

+
+
+The sections below describe how @code{CTABLES} treats missing values
+in categorical and scale variables.
+
+@node CTABLES Categorical Missing Values
+@subsubsection Categorical Missing Values
+
+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 exact rules are shown in the following chart, in
+which cells that contain ``yes'' indicate that a value is analyzed:
+
+@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 Scale Missing Values
+@subsubsection Scale Missing Values
+

 @display
 @t{/SMISSING} @{@t{VARIABLE} @math{|} @t{LISTWISE}@}
 @end display
 @display
 @t{/SMISSING} @{@t{VARIABLE} @math{|} @t{LISTWISE}@}
 @end display