From 4206439a4ef9a9ac125dcabae4322ea78d32e695 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Fri, 3 Jun 2022 11:40:26 -0700 Subject: [PATCH 1/1] docs --- doc/statistics.texi | 165 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 152 insertions(+), 13 deletions(-) diff --git a/doc/statistics.texi b/doc/statistics.texi index f199069c94..887277d8b2 100644 --- a/doc/statistics.texi +++ b/doc/statistics.texi @@ -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 -- 2.30.2