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
+using the rules described in an earlier section (@pxref{Measurement
Level}). Use the @code{VARIABLE LEVEL} command to set or change a
variable's measurement level (@pxref{VARIABLE LEVEL}).
@code{MISSING=EXCLUDE} is in effect on @code{CATEGORIES}, or
system-missing values. @code{COUNT} does not count these.
+@xref{CTABLES Missing Values for Summary Variables}, for details of
+how @code{CTABLES} summarizes missing values.
+
@item @code{VALIDN} (``Valid N'', F40.0)
The sum of valid count weights in included categories.
-@code{VALIDN} does not count missing values regardless of whether they
-are in included categories via @code{CATEGORIES}. @code{VALIDN} does
-not count valid values that are in excluded categories.
+For categorical variables, @code{VALIDN} does not count missing values
+regardless of whether they are in included categories via
+@code{CATEGORIES}. @code{VALIDN} does not count valid values that are
+in excluded categories. @xref{CTABLES Missing Values for Summary
+Variables}, for details.
@item @code{VARIANCE} (``Variance'')
The variance.
@node CTABLES Summary Functions for Adjusted Weights
@subsubsection Summary Functions for Adjusted Weights
-If the @code{WEIGHT} subcommand specified an adjustment weight
-variable, then the following summary functions use its value instead
-of the dictionary weight variable. Otherwise, they are equivalent to
-the summary function without the @samp{E}-prefix:
+If the @code{WEIGHT} subcommand specified an effective weight variable
+(@pxref{CTABLES Effective Weight}), then the following summary functions
+use its value instead of the dictionary weight variable. Otherwise,
+they are equivalent to the summary function without the
+@samp{E}-prefix:
@itemize @bullet
@item
@code{UMISSING} (``Unweighted Missing'')
@item
-@code{UMODE} (``Unweight Mode'')
+@code{UMODE} (``Unweighted Mode'')
@item
@code{U@i{area}PCT.SUM} (``Unweighted @i{Area} Sum %'', PCT40.1)
@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
-order:
+The syntax may specify the categories to include and their sort order
+either explicitly or implicitly. The following sections give the
+details of each form of syntax, followed by information on totals and
+subtotals and the @code{EMPTY} setting.
+
+@node CTABLES Explicit Categories
+@subsubsection Explicit Categories
-@table @asis
-@item Explicit categories.
@anchor{CTABLES Explicit Category List}
-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.
+
+To use @code{CTABLES} 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:
@item &@i{postcompute}
A computed category name (@pxref{CTABLES Computed Categories}).
+
+@item SUBTOTAL
+@itemx HSUBTOTAL
+A subtotal (@pxref{CTABLES Totals and Subtotals}).
@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 takes precedence.
-@item Implicit categories.
-Without an explicit list of categories, @pspp{} sorts
-categories automatically.
+The following example syntax and output show how an explicit category
+can limit the displayed categories:
+
+@example
+CTABLES /TABLE qn1.
+CTABLES /TABLE qn1 /CATEGORIES VARIABLES=qn1 [1, 2, 3].
+@end example
+@psppoutput {ctables27}
+
+@node CTABLES Implicit Categories
+@subsubsection Implicit Categories
+
+In the absence of an explicit list of categories, @code{CATEGORIES}
+allows @code{KEY}, @code{ORDER}, and @code{MISSING} to specify how to
+select and sort categories.
The @code{KEY} setting specifies the sort key. By default, or with
@code{KEY=VALUE}, categories are sorted by default. Categories may
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
+The following example syntax and output show how
+@code{MISSING=INCLUDE} causes missing values to be included in a
+category list.
-@code{CATEGORIES} also controls display of totals and subtotals.
-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.
+@example
+CTABLES /TABLE qn1.
+CTABLES /TABLE qn1 /CATEGORIES VARIABLES=qn1 MISSING=INCLUDE.
+@end example
+@psppoutput {ctables28}
+
+@node CTABLES Totals and Subtotals
+@subsubsection Totals and Subtotals
+
+@code{CATEGORIES} also controls display of totals and subtotals. By
+default, or with @code{TOTAL=NO}, totals are not displayed. Use
+@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.
+should appear. 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.
+
+The following example syntax and output show how to use
+@code{TOTAL=YES} and @code{SUBTOTAL}:
+
+@example
+CTABLES
+ /TABLE qn1
+ /CATEGORIES VARIABLES=qn1 [OTHERNM, SUBTOTAL='Valid Total',
+ MISSING, SUBTOTAL='Missing Total']
+ TOTAL=YES LABEL='Overall Total'.
+@end example
+@psppoutput {ctables29}
By default, or with @code{POSITION=AFTER}, totals are displayed in the
output after the last category and subtotals apply to categories that
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.
+subtotals on a categorical variable within which the scalar variable
+is summarized. For example, the following syntax produces a mean,
+count, and valid count across all data by adding a total on the
+categorical @code{region} variable, as shown:
+
+@example
+CTABLES /TABLE=region > qn20 [MEAN, VALIDN]
+ /CATEGORIES VARIABLES=region TOTAL=YES LABEL='All regions'.
+@end example
+@psppoutput {ctables30}
By default, @pspp{} uses the same summary functions for totals and
subtotals as other categories. To summarize totals and subtotals
@end example
@psppoutput {ctables26}
-@subsubheading Categories Without Values
+@node CTABLES Categories Without Values
+@subsubsection 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
values with value labels that are covered by ranges or @code{MISSING}
or @code{OTHERNM}.
+The following example syntax and output show the effect of
+@code{EMPTY=EXCLUDE} for the @code{qns1} variable, in which 0 is labeled
+``None'' but no cases exist with that value:
+
+@example
+CTABLES /TABLE=qns1.
+CTABLES /TABLE=qns1 /CATEGORIES VARIABLES=qns1 EMPTY=EXCLUDE.
+@end example
+@psppoutput {ctables31}
+
@node CTABLES Titles
@subsection Titles
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
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.
+@code{UNITS=CM} for centimeters. @pspp{} does not currently honor any
+of these settings.
By default, or with @code{EMPTY=ZERO}, zero values are displayed in
their usual format. Use @code{EMPTY=BLANK} to use an empty cell
kinds of variables: variables that divide tables into cells (which are
always categorical) and variables being summarized (which may be
categorical or scale). @pspp{} treats missing values differently in
-each kind of variable:
+each kind of variable, as described in the sections below.
+
+@node CTABLES Missing Values for Cell-Defining Variables
+@subsubsection Missing Values for Cell-Defining Variables
-@itemize @bullet
-@item
For variables that divide tables into cells, per-variable category
-options determine which data is analyzed. If any of the categories
-for such a variable would exclude a case, then that case is not
-included.
+options, as described in @ref{CTABLES Per-Variable Category Options},
+determine which data is analyzed. If any of the categories for such a
+variable would exclude a case, then that case is not included.
-@item
-The treatment of missing values in variables being summarized varies
-between scale and scale and categorical variables. The following
-section describes their treatment in detail.
+As an example, consider the following entirely artificial dataset, in
+which @samp{x} and @samp{y} are categorical variables with missing
+value 9, and @samp{z} is scale:
-By default, each summarized variable is considered separately for
-missing value treatment. A section below describes how to consider
-missing values listwise for summarizing scale variables.
-@end itemize
+@psppoutput{ctables32}
+
+Using @samp{x} and @samp{y} to define cells, and summarizing @samp{z},
+by default @pspp{} omits all the cases that have @samp{x} or @samp{y} (or both)
+missing:
+
+@example
+CTABLES /TABLE x > y > z [SUM].
+@end example
+@psppoutput{ctables33}
+
+If, however, we add @code{CATEGORIES} specifications to include
+missing values for @samp{y} or for @samp{x} and @samp{y}, the output
+table includes them, like so:
+
+@example
+CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=y MISSING=INCLUDE.
+CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=x y MISSING=INCLUDE.
+@end example
+@psppoutput{ctables34}
@node CTABLES Missing Values for Summary Variables
@subsubsection Missing Values for Summary Variables
@code{PCOMPUTE} redefines a postcompute with the same name as an
earlier one, the later one take precedence.
+@c TODO example
+
@node CTABLES Computed Category Properties
@subsection Computed Category Properties
output. The default label for a postcompute is the expression used to
define it.
-The @code{FORMAT} setting sets summary statistics and display formats
-for the postcomputes.
+A postcompute always uses same summary functions as the variable whose
+categories contain it, but @code{FORMAT} allows control over the
+format used to display their values. It takes a list of summary
+function names and format specifiers.
By default, or with @code{HIDESOURCECATS=NO}, categories referred to
by computed categories are displayed like other categories. Use
@code{HIDESOURCECATS=YES} to hide them.
-@node CTABLES Base Weight
-@subsection Base Weight
+@c TODO example
+
+@node CTABLES Effective Weight
+@subsection Effective Weight
@display
@t{/WEIGHT VARIABLE=}@i{variable}
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 stands in for the dictionary's weight
+as the @dfn{effective weight} or @dfn{adjustment weight}. The
+effective 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 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.
+nearest integer at the case level. Effective 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
value of @i{count} must be an integer and must be at least 2. Case
weights are considered for deciding whether to hide a count.
+@c TODO example
+
@node FACTOR
@section FACTOR
projects / pspp / blobdiff