docs
authorBen Pfaff <blp@cs.stanford.edu>
Fri, 3 Jun 2022 18:40:26 +0000 (11:40 -0700)
committerBen Pfaff <blp@cs.stanford.edu>
Fri, 3 Jun 2022 18:40:26 +0000 (11:40 -0700)
doc/statistics.texi

index f199069c94868e81d5eef8cde06ba88710841a28..887277d8b29ceae5add2d746730e242d1e1e50bf 100644 (file)
@@ -959,7 +959,6 @@ previous @code{TABLE}.  All of these subcommands are optional:
     [@t{POSITION=}@{@t{COLUMN} @math{|} @t{ROW} @math{|} @t{LAYER}@}]
     [@t{VISIBLE=}@{@t{YES} @math{|} @t{NO}@}]
 @t{/CLABELS} @{@t{AUTO} @math{|} @{@t{ROWLABELS}@math{|}@t{COLLABELS}@}@t{=}@{@t{OPPOSITE}@math{|}@t{LAYER}@}@}
-@t{/CRITERIA CILEVEL=}@i{percentage}
 @t{/CATEGORIES} @t{VARIABLES=}@i{variables}
     @{@t{[}@i{value}@t{,} @i{value}@dots{}@t{]}
    @math{|} [@t{ORDER=}@{@t{A} @math{|} @t{D}@}]
@@ -971,6 +970,8 @@ previous @code{TABLE}.  All of these subcommands are optional:
     [@t{TITLE=}@i{string}@dots{}]
     [@t{CAPTION=}@i{string}@dots{}]
     [@t{CORNER=}@i{string}@dots{}]
+@ignore  @c not yet implemented
+@t{/CRITERIA CILEVEL=}@i{percentage}
 @t{/SIGTEST TYPE=CHISQUARE}
     [@t{ALPHA=}@i{siglevel}]
     [@t{INCLUDEMRSETS=}@{@t{YES} @math{|} @t{NO}@}]
@@ -984,6 +985,7 @@ previous @code{TABLE}.  All of these subcommands are optional:
     [@t{MERGE=}@{@t{NO} @math{|} @t{YES}@}]
     [@t{STYLE=}@{@t{APA} @math{|} @t{SIMPLE}@}]
     [@t{SHOWSIG=}@{@t{NO} @math{|} @t{YES}@}]
+@end ignore
 @end display
 
 The @code{CTABLES} (aka ``custom tables'') command produces
@@ -997,11 +999,6 @@ available at @url{https://data.transportation.gov}.  @pspp{} includes
 this data set, with a slightly modified dictionary, as
 @file{examples/nhtsa.sav}.
 
-@menu
-* CTABLES Basics::
-* CTABLES Data Summarization::
-@end menu
-
 @node CTABLES Basics
 @subsection Basics
 
@@ -1019,7 +1016,6 @@ variables.  At least one must specify an axis expression.
 * CTABLES Categorical Variable Basics::
 * CTABLES Scalar Variable Basics::
 * CTABLES Overriding Measurement Level::
-* CTABLES Multiple Response Sets::
 @end menu
 
 @node CTABLES Categorical Variable Basics
@@ -1135,11 +1131,13 @@ CTABLES /TABLE qn20 [C] BY qns3a.
 @end example
 @psppoutput {ctables9}
 
+@ignore
 @node CTABLES Multiple Response Sets
 @subsubheading Multiple Response Sets
 
 The @code{CTABLES} command does not yet support multiple response
 sets.
+@end ignore
 
 @node CTABLES Data Summarization
 @subsection Data Summarization
@@ -1422,12 +1420,13 @@ CTABLES /TABLE=AgeGroup [TABLEPCT] /SLABELS VISIBLE=NO.
 @t{/CLABELS} @{@t{AUTO} @math{|} @{@t{ROWLABELS}@math{|}@t{COLLABELS}@}@t{=}@{@t{OPPOSITE}@math{|}@t{LAYER}@}@}
 @end display
 
-The @code{CLABELS} subcommand controls the position of category
-labels.  By default, category labels for a given variable nest inside
-the variable's label on the same axis.  For example, the command below
-results in age categories nesting within the age group variable on the
-rows axis and gender categories within the gender variable on the
-columns axis:
+The @code{CLABELS} subcommand controls the position of category labels
+for the @code{TABLE} subcommand that it follows.  By default, or if
+@t{AUTO} is specified, category labels for a given variable nest
+inside the variable's label on the same axis.  For example, the
+command below results in age categories nesting within the age group
+variable on the rows axis and gender categories within the gender
+variable on the columns axis:
 
 @example
 CTABLES /TABLE AgeGroup BY qns3a.
@@ -1454,9 +1453,149 @@ to the layer axis.
 @node CTABLES Per-Variable Category Options
 @subsection Per-Variable Category Options
 
+@display
+@t{/CATEGORIES} @t{VARIABLES=}@i{variables}
+    @{@t{[}@i{value}@t{,} @i{value}@dots{}@t{]}
+   @math{|} [@t{ORDER=}@{@t{A} @math{|} @t{D}@}]
+     [@t{KEY=}@{@t{VALUE} @math{|} @t{LABEL} @math{|} @i{summary}@t{(}@i{variable}@t{)}@}]
+     [@t{MISSING=}@{@t{EXCLUDE} @math{|} @t{INCLUDE}@}]@}
+    [@t{TOTAL=}@{@t{NO} @math{|} @t{YES}@} [@t{LABEL=}@i{string}] [@t{POSITION=}@{@t{AFTER} @math{|} @t{BEFORE}@}]]
+    [@t{EMPTY=}@{@t{INCLUDE} @math{|} @t{EXCLUDE}@}]
+@end display
+
+The @code{CATEGORIES} subcommand specifies, for one or more
+categorical variables, the categories to include and exclude, the sort
+order for included categories, and treatment of missing values.  It
+also controls the totals and subtotals to display.  It may be
+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.
+
+@t{VARIABLES} is required.  List the variables for the subcommand
+to affect.
+
+There are two way to specify the Categories to include and their sort
+order:
+
+@table @asis
+@item Explicit categories.
+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:
+
+@table @t
+@item @i{number}
+@itemx '@i{string}'
+A numeric or string category value, for variables that have the
+corresponding type.
+
+@item '@i{date}'
+@itemx '@i{time}'
+A date or time category value, for variables that have a date or time
+print format.
+
+@item @i{min} THRU @i{max}
+@itemx LO THRU @i{max}
+@itemx @i{min} THRU HI
+A range of category values, where @var{min} and @var{max} each takes
+one of the forms above, in increasing order.
+
+@item MISSING
+All user-missing values.  (To match individual user-missing values,
+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).
+@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 is considered to be a match.
+
+@item Implicit categories.
+Without an explicit list of categories, @pspp{} sorts
+categories automatically.
+
+The @code{KEY} setting specifies the sort key.  By default, or with
+@code{KEY=VALUE}, categories are sorted by default.  Categories may
+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
+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.
+
+By default, or with @code{ORDER=A}, categories are sorted in ascending
+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
+
+@code{CATEGORIES} also controls display of totals and subtotals.
+Totals are not displayed by default, or with @code{TOTAL=NO}.  Specify
+@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.
+
+By default, or with @code{POSITION=AFTER}, totals come 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.
+
+Only categorical variables may have totals and subtotals.  Scale
+variables may be ``totaled'' indirectly by enabling totals and
+subtotals on a categorical variable within which the scale variable is
+summarized.
+
+@subsubheading 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
+younger'' age group.  By default, or with @code{EMPTY=INCLUDE},
+@pspp{} includes these empty categories in output tables.  To exclude
+them, specify @code{EMPTY=EXCLUDE}.
+
+For implicit categories, empty categories potentially include all the
+values with labels for a given variable; for explicit categories, they
+include all the values listed individually and all labeled values
+covered by ranges or @code{MISSING} or @code{OTHERNM}.
+
 @node CTABLES Titles
 @subsection Titles
 
+@display
+@t{/TITLES}
+    [@t{TITLE=}@i{string}@dots{}]
+    [@t{CAPTION=}@i{string}@dots{}]
+    [@t{CORNER=}@i{string}@dots{}]
+@end display
+
+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.
+
 @node FACTOR
 @section FACTOR