into cells according to the values of that variable. When all the
variables named on @code{TABLE} are categorical, by default each cell
displays the number of cases that it contains, so specifying a single
-variable yields a frequency table:
+variable yields a frequency table, much like the output of the
+@code{FREQUENCIES} command (@pxref{FREQUENCIES}):
@example
CTABLES /TABLE=AgeGroup.
@noindent
Specifying a row and a column categorical variable yields a
-crosstabulation:
+crosstabulation, much like the output of the @code{CROSSTABS} command
+(@pxref{CROSSTABS}):
@example
CTABLES /TABLE=AgeGroup BY qns3a.
assigned the nominal or ordinal measurement level are treated as
categorical, and scalar variables are treated as scalar.
-Use the @code{VARIABLE LEVEL} command to change a variable's
-measurement level (@pxref{VARIABLE LEVEL}). To treat a variable as
-categorical or scalar only for one use on @code{CTABLES}, add
-@samp{[C]} or @samp{[S]}, respectively, after the variable name. The
-following example shows how to analyze the scalar variable @code{qn20}
-as categorical:
+When @pspp{} reads data from a file in an external format, such as a
+text file, variables' measurement levels are often unknown. If
+@code{CTABLES} runs when a variable has an unknown measurement level,
+it makes an initial pass through the data to guess measurement levels
+using the rules described earlier in this manual (@pxref{Measurement
+Level}). Use the @code{VARIABLE LEVEL} command to set or change a
+variable's measurement level (@pxref{VARIABLE LEVEL}).
+
+To treat a variable as categorical or scalar only for one use on
+@code{CTABLES}, add @samp{[C]} or @samp{[S]}, respectively, after the
+variable name. The following example shows the output when variable
+@code{qn20} is analyzed as scalar (the default for its measurement
+level) and as categorical:
@example
-CTABLES /TABLE qn20 [C] BY qns3a.
+CTABLES
+ /TABLE qn20 BY qns3a
+ /TABLE qn20 [C] BY qns3a.
@end example
@psppoutput {ctables9}
@node CTABLES Data Summarization
@subsection Data Summarization
+@c TODO Summary function default formats
+
The @code{CTABLES} command allows the user to control how the data are
-summarized with summary specifications, which are enclosed in square
-brackets following a variable name on the @code{TABLE} subcommand.
-When all the variables are categorical, summary specifications can be
-given for the innermost nested variables on any one axis. When a
-scalar variable is present, only the scalar variable may have summary
-specifications. The following example includes a summary
-specification for column and row percentages for categorical
-variables, and mean and median for a scalar variable:
+summarized with @dfn{summary specifications}, syntax that lists one or
+more summary function names, optionally separated by commas, and which
+are enclosed in square brackets following a variable name on the
+@code{TABLE} subcommand. When all the variables are categorical,
+summary specifications can be given for the innermost nested variables
+on any one axis. When a scalar variable is present, only the scalar
+variable may have summary specifications.
+
+The following example includes a summary specification for column and
+row percentages for categorical variables, and mean and median for a
+scalar variable:
@example
CTABLES
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
@code{CATEGORIES} does not apply to scalar variables.
-@t{VARIABLES} is required. List the variables for the subcommand
+@t{VARIABLES} is required and must list the variables for the subcommand
to affect.
There are two way to specify the Categories to include and their sort
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.
+in the list takes precedence.
@item Implicit categories.
Without an explicit list of categories, @pspp{} sorts
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 scalar 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.
+of a summary function, e.g.@: @code{KEY=COUNT}.
+@ignore @c Not yet implemented
+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 scalar 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.
+@end ignore
By default, or with @code{ORDER=A}, categories are sorted in ascending
order. Specify @code{ORDER=D} to sort in descending order.
@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.
+Totals are not displayed with @code{TOTAL=NO}, which is also the
+default. 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
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.
+By default, or with @code{POSITION=AFTER}, totals are displayed in the
+output 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. Scalar
variables may be ``totaled'' indirectly by enabling totals and
subtotals on a categorical variable within which the scalar variable is
summarized.
+@c TODO Specifying summaries for totals and subtotals
+
@subsubheading Categories Without Values
Some categories might not be included in the data set being analyzed.
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}.
+values with value labels for a given variable; for explicit
+categories, they include all the values listed individually and all
+values with value labels that are covered by ranges or @code{MISSING}
+or @code{OTHERNM}.
@node CTABLES Titles
@subsection Titles
[@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.
@node CTABLES Table Formatting
@subsection Table Formatting
tables. @code{FORMAT} and all of its settings are optional.
Use @code{MINCOLWIDTH} and @code{MAXCOLWIDTH} to control the minimum
-or maximum width of columns in output tables. By default, or with
+or maximum width of columns in output tables. By default, with
@code{DEFAULT}, column width varies based on content. Otherwise,
specify a number for either or both of these settings. If both are
-specified, @code{MAXCOLWIDTH} must be bigger than @code{MINCOLWIDTH}.
-The default unit, or with @code{UNITS=POINTS}, is points (1/72 inch),
-but specify @code{UNITS=INCHES} to use inches or @code{UNITS=CM} for
-centimeters.
+specified, @code{MAXCOLWIDTH} must be greater than or equal to
+@code{MINCOLWIDTH}. The default unit, or with @code{UNITS=POINTS}, is
+points (1/72 inch), or specify @code{UNITS=INCHES} to use inches or
+@code{UNITS=CM} for centimeters.
By default, or with @code{EMPTY=ZERO}, zero values are displayed in
their usual format. Use @code{EMPTY=BLANK} to use an empty cell
@table @code
@item DEFAULT
-Uses the setting from @ref{SET TVARS}.
+Use the setting from @code{SET TVARS} (@pxref{SET TVARS}).
@item NAME
Show only a variable name.
This form evaluates to the summary statistic for @i{category}, e.g.@:
@code{[1]} evaluates to the value of the summary statistic associated
with category 1. The @i{category} may be a number, a quoted string,
-or a quoted time or date value, and all of the categories for a given
-postcompute must have the same form.
+or a quoted time or date value. All of the categories for a given
+postcompute must have the same form. The category must appear in all
+the @code{CATEGORIES} list in which the postcompute is used.
@item [@i{min} THRU @i{max}]
@itemx [LO THRU @i{max}]
@itemx [@i{min} THRU HI]
@itemx MISSING
@itemx OTHERNM
-These forms evaluate to the summary statistics for categories matching
-the given syntax, as described in previous sections (@pxref{CTABLES
-Explicit Category List}). If more than one category matches, their
-values are summed.
+These forms evaluate to the summary statistics for a category
+specified with the same syntax, as described in previous section
+(@pxref{CTABLES Explicit Category List}). The category must appear in
+all the @code{CATEGORIES} list in which the postcompute is used.
@item SUBTOTAL
The summary statistic for the subtotal category. This form is allowed
-only for variables with exactly one subtotal.
+only if the @code{CATEGORIES} lists that include this postcompute have
+exactly one subtotal.
@item SUBTOTAL[@i{index}]
The summary statistic for subtotal category @i{index}, where 1 is the
first subtotal, 2 is the second, and so on. This form may be used for
-any number of subtotals.
+@code{CATEGORIES} lists with any number of subtotals.
@item TOTAL
-The summary statistic for the total.
+The summary statistic for the total. The @code{CATEGORIES} lsits that
+include this postcompute must have a total enabled.
@item @i{a} + @i{b}
@itemx @i{a} - @i{b}
The @code{WEIGHT} subcommand is optional and must appear before
@code{TABLE}. If it appears, it must name a numeric variable, known
as the @dfn{effective base weight} or @dfn{adjustment weight}. The
-effective base weight variable is used for the @code{ECOUNT},
-@code{ETOTALN}, and @code{EVALIDN} summary functions.
-
-Cases with zero, missing, or negative effective base weight are
-excluded from all analysis.
+effective base weight variable stands in for the dictionary's weight
+variable (@pxref{WEIGHT}), if any, in most calculations in
+@code{CTABLES}. The only exceptions are the @code{COUNT},
+@code{TOTALN}, and @code{VALIDN} summary functions, which use the
+dictionary weight instead.
Weights obtained from the @pspp{} dictionary are rounded to the
-nearest integer. Effective base weights are not rounded.
+nearest integer at the case level. Effective base weights are not
+rounded. Regardless of the weighting source, @pspp{} does not analyze
+cases with zero, missing, or negative effective weights.
@node CTABLES Hiding Small Counts
@subsection Hiding Small Counts
projects / pspp / commitdiff