[pspp] / doc / statistics.texi

@c PSPP - a program for statistical analysis.
@c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.3
@c or any later version published by the Free Software Foundation;
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
@c A copy of the license is included in the section entitled "GNU
@c Free Documentation License".
@c
@node Statistics
@chapter Statistics

This chapter documents the statistical procedures that @pspp{} supports so
far.

@menu
* DESCRIPTIVES::                Descriptive statistics.
* FREQUENCIES::                 Frequency tables.
* EXAMINE::                     Testing data for normality.
* GRAPH::                       Plot data.
* CORRELATIONS::                Correlation tables.
* CROSSTABS::                   Crosstabulation tables.
* CTABLES::                     Custom tables.
* FACTOR::                      Factor analysis and Principal Components analysis.
* GLM::                         Univariate Linear Models.
* LOGISTIC REGRESSION::         Bivariate Logistic Regression.
* MEANS::                       Average values and other statistics.
* NPAR TESTS::                  Nonparametric tests.
* T-TEST::                      Test hypotheses about means.
* ONEWAY::                      One way analysis of variance.
* QUICK CLUSTER::               K-Means clustering.
* RANK::                        Compute rank scores.
* RELIABILITY::                 Reliability analysis.
* ROC::                         Receiver Operating Characteristic.
@end menu

@node DESCRIPTIVES
@section DESCRIPTIVES

@vindex DESCRIPTIVES
@display
DESCRIPTIVES
        /VARIABLES=@var{var_list}
        /MISSING=@{VARIABLE,LISTWISE@} @{INCLUDE,NOINCLUDE@}
        /FORMAT=@{LABELS,NOLABELS@} @{NOINDEX,INDEX@} @{LINE,SERIAL@}
        /SAVE
        /STATISTICS=@{ALL,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,
                     SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,DEFAULT,
                     SESKEWNESS,SEKURTOSIS@}
        /SORT=@{NONE,MEAN,SEMEAN,STDDEV,VARIANCE,KURTOSIS,SKEWNESS,
               RANGE,MINIMUM,MAXIMUM,SUM,SESKEWNESS,SEKURTOSIS,NAME@}
              @{A,D@}
@end display

The @cmd{DESCRIPTIVES} procedure reads the active dataset and outputs
linear descriptive statistics requested by the user.  In addition, it can optionally
compute Z-scores.

The @subcmd{VARIABLES} subcommand, which is required, specifies the list of
variables to be analyzed.  Keyword @subcmd{VARIABLES} is optional.

All other subcommands are optional:

The @subcmd{MISSING} subcommand determines the handling of missing variables.  If
@subcmd{INCLUDE} is set, then user-missing values are included in the
calculations.  If @subcmd{NOINCLUDE} is set, which is the default, user-missing
values are excluded.  If @subcmd{VARIABLE} is set, then missing values are
excluded on a variable by variable basis; if @subcmd{LISTWISE} is set, then
the entire case is excluded whenever any value in that case has a
system-missing or, if @subcmd{INCLUDE} is set, user-missing value.

The @subcmd{FORMAT} subcommand has no effect.  It is accepted for
backward compatibility.

The @subcmd{SAVE} subcommand causes @cmd{DESCRIPTIVES} to calculate Z scores for all
the specified variables.  The Z scores are saved to new variables.
Variable names are generated by trying first the original variable name
with Z prepended and truncated to a maximum of 8 characters, then the
names ZSC000 through ZSC999, STDZ00 through STDZ09, ZZZZ00 through
ZZZZ09, ZQZQ00 through ZQZQ09, in that sequence.  In addition, Z score
variable names can be specified explicitly on @subcmd{VARIABLES} in the variable
list by enclosing them in parentheses after each variable.
When Z scores are calculated, @pspp{} ignores @cmd{TEMPORARY},
treating temporary transformations as permanent.

The @subcmd{STATISTICS} subcommand specifies the statistics to be displayed:

@table @code
@item @subcmd{ALL}
All of the statistics below.
@item @subcmd{MEAN}
Arithmetic mean.
@item @subcmd{SEMEAN}
Standard error of the mean.
@item @subcmd{STDDEV}
Standard deviation.
@item @subcmd{VARIANCE}
Variance.
@item @subcmd{KURTOSIS}
Kurtosis and standard error of the kurtosis.
@item @subcmd{SKEWNESS}
Skewness and standard error of the skewness.
@item @subcmd{RANGE}
Range.
@item MINIMUM
Minimum value.
@item MAXIMUM
Maximum value.
@item SUM
Sum.
@item DEFAULT
Mean, standard deviation of the mean, minimum, maximum.
@item SEKURTOSIS
Standard error of the kurtosis.
@item SESKEWNESS
Standard error of the skewness.
@end table

The @subcmd{SORT} subcommand specifies how the statistics should be sorted.  Most
of the possible values should be self-explanatory.  @subcmd{NAME} causes the
statistics to be sorted by name.  By default, the statistics are listed
in the order that they are specified on the @subcmd{VARIABLES} subcommand.
The @subcmd{A} and @subcmd{D} settings request an ascending or descending
sort order, respectively.

@subsection Descriptives Example

The @file{physiology.sav} file contains various physiological data for a sample
of persons.   Running the @cmd{DESCRIPTIVES} command on the variables @exvar{height}
and @exvar{temperature} with the default options allows one to see simple linear
statistics for these two variables.  In @ref{descriptives:ex}, these variables
are specfied on the @subcmd{VARIABLES} subcommand and the @subcmd{SAVE} option
has been used, to request that Z scores be calculated.

After the command has completed, this example runs @cmd{DESCRIPTIVES} again, this
time on the @exvar{zheight} and @exvar{ztemperature} variables,
which are the two normalized (Z-score) variables generated by the
first @cmd{DESCRIPTIVES} command.

@float Example, descriptives:ex
@psppsyntax {descriptives.sps}
@caption {Running two @cmd{DESCRIPTIVES} commands, one with the @subcmd{SAVE} subcommand}
@end float

@float Screenshot, descriptives:scr
@psppimage {descriptives}
@caption {The Descriptives dialog box with two variables and Z-Scores option selected}
@end float

In @ref{descriptives:res}, we can see that there are 40 valid data for each of the variables
and no missing values.   The mean average of the height and temperature is 16677.12
and 37.02 respectively.  The descriptive statistics for temperature seem reasonable.
However there is a very high standard deviation for @exvar{height} and a suspiciously
low minimum.  This is due to a data entry error in the
data (@pxref{Identifying incorrect data}).

In the second Descriptive Statistics command, one can see that the mean and standard
deviation of both Z score variables is 0 and 1 respectively.  All Z score statistics
should have these properties since they are normalized versions of the original scores.

@float Result, descriptives:res
@psppoutput {descriptives}
@caption {Descriptives statistics including two normalized variables (Z-scores)}
@end float

@node FREQUENCIES
@section FREQUENCIES

@vindex FREQUENCIES
@display
FREQUENCIES
        /VARIABLES=@var{var_list}
        /FORMAT=@{TABLE,NOTABLE,LIMIT(@var{limit})@}
                @{AVALUE,DVALUE,AFREQ,DFREQ@}
        /MISSING=@{EXCLUDE,INCLUDE@}
        /STATISTICS=@{DEFAULT,MEAN,SEMEAN,MEDIAN,MODE,STDDEV,VARIANCE,
                     KURTOSIS,SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,
                     SESKEWNESS,SEKURTOSIS,ALL,NONE@}
        /NTILES=@var{ntiles}
        /PERCENTILES=percent@dots{}
        /HISTOGRAM=[MINIMUM(@var{x_min})] [MAXIMUM(@var{x_max})]
                   [@{FREQ[(@var{y_max})],PERCENT[(@var{y_max})]@}] [@{NONORMAL,NORMAL@}]
        /PIECHART=[MINIMUM(@var{x_min})] [MAXIMUM(@var{x_max})]
                  [@{FREQ,PERCENT@}] [@{NOMISSING,MISSING@}]
        /BARCHART=[MINIMUM(@var{x_min})] [MAXIMUM(@var{x_max})]
                  [@{FREQ,PERCENT@}]
        /ORDER=@{ANALYSIS,VARIABLE@}


(These options are not currently implemented.)
        /HBAR=@dots{}
        /GROUPED=@dots{}
@end display

The @cmd{FREQUENCIES} procedure outputs frequency tables for specified
variables.
@cmd{FREQUENCIES} can also calculate and display descriptive statistics
(including median and mode) and percentiles, and various graphical representations
of the frequency distribution.

The @subcmd{VARIABLES} subcommand is the only required subcommand.  Specify the
variables to be analyzed.

The @subcmd{FORMAT} subcommand controls the output format.  It has several
possible settings:

@itemize @subcmd{}
@item
@subcmd{TABLE}, the default, causes a frequency table to be output for every
variable specified.  @subcmd{NOTABLE} prevents them from being output.  @subcmd{LIMIT}
with a numeric argument causes them to be output except when there are
more than the specified number of values in the table.

@item
Normally frequency tables are sorted in ascending order by value.  This
is @subcmd{AVALUE}.  @subcmd{DVALUE} tables are sorted in descending order by value.
@subcmd{AFREQ} and @subcmd{DFREQ} tables are sorted in ascending and descending order,
respectively, by frequency count.
@end itemize

The @subcmd{MISSING} subcommand controls the handling of user-missing values.
When @subcmd{EXCLUDE}, the default, is set, user-missing values are not included
in frequency tables or statistics.  When @subcmd{INCLUDE} is set, user-missing
are included.  System-missing values are never included in statistics,
but are listed in frequency tables.

The available @subcmd{STATISTICS} are the same as available
in @cmd{DESCRIPTIVES} (@pxref{DESCRIPTIVES}), with the addition
of @subcmd{MEDIAN}, the data's median
value, and MODE, the mode.  (If there are multiple modes, the smallest
value is reported.)  By default, the mean, standard deviation of the
mean, minimum, and maximum are reported for each variable.

@cindex percentiles
@subcmd{PERCENTILES} causes the specified percentiles to be reported.
The percentiles should  be presented at a list of numbers between 0
and 100 inclusive.
The @subcmd{NTILES} subcommand causes the percentiles to be reported at the
boundaries of the data set divided into the specified number of ranges.
For instance, @subcmd{/NTILES=4} would cause quartiles to be reported.

@cindex histogram
The @subcmd{HISTOGRAM} subcommand causes the output to include a histogram for
each specified numeric variable.  The X axis by default ranges from
the minimum to the maximum value observed in the data, but the @subcmd{MINIMUM}
and @subcmd{MAXIMUM} keywords can set an explicit range.
@footnote{The number of
bins is chosen according to the Freedman-Diaconis rule:
@math{2 \times IQR(x)n^{-1/3}}, where @math{IQR(x)} is the interquartile range of @math{x}
and @math{n} is the number of samples.    Note that
@cmd{EXAMINE} uses a different algorithm to determine bin sizes.}
Histograms are not created for string variables.

Specify @subcmd{NORMAL} to superimpose a normal curve on the
histogram.

@cindex piechart
The @subcmd{PIECHART} subcommand adds a pie chart for each variable to the data.  Each
slice represents one value, with the size of the slice proportional to
the value's frequency.  By default, all non-missing values are given
slices.
The @subcmd{MINIMUM} and @subcmd{MAXIMUM} keywords can be used to limit the
displayed slices to a given range of values.
The keyword @subcmd{NOMISSING} causes missing values to be omitted from the
piechart.  This is the default.
If instead, @subcmd{MISSING} is specified, then the pie chart includes
a single slice representing all system missing and user-missing cases.

@cindex bar chart
The @subcmd{BARCHART} subcommand produces a bar chart for each variable.
The @subcmd{MINIMUM} and @subcmd{MAXIMUM} keywords can be used to omit
categories whose counts which lie outside the specified limits.
The @subcmd{FREQ} option (default) causes the ordinate to display the frequency
of each category, whereas the @subcmd{PERCENT} option displays relative
percentages.

The @subcmd{FREQ} and @subcmd{PERCENT} options on @subcmd{HISTOGRAM} and
@subcmd{PIECHART} are accepted but not currently honoured.

The @subcmd{ORDER} subcommand is accepted but ignored.

@subsection Frequencies Example

@ref{frequencies:ex} runs a frequency analysis on the @exvar{sex}
and @exvar{occupation} variables from the @file{personnel.sav} file.
This is useful to get an general idea of the way in which these nominal
variables are distributed.

@float Example, frequencies:ex
@psppsyntax {frequencies.sps}
@caption {Running frequencies on the @exvar{sex} and @exvar{occupation} variables}
@end float

If you are using the graphic user interface, the dialog box is set up such that
by default, several statistics are calculated.   Some are not particularly useful
for categorical variables, so you may want to disable those.

@float Screenshot, frequencies:scr
@psppimage {frequencies}
@caption {The frequencies dialog box with the @exvar{sex} and @exvar{occupation} variables selected}
@end float

From @ref{frequencies:res} it is evident that there are 33 males, 21 females and
2 persons for whom their sex has not been entered.

One can also see how many of each occupation there are in the data.
When dealing with string variables used as nominal values, running a frequency
analysis is useful to detect data input entries.  Notice that
one @exvar{occupation} value has been mistyped as ``Scrientist''.  This entry should
be corrected, or marked as missing before using the data.

@float Result, frequencies:res
@psppoutput {frequencies}
@caption {The relative frequencies of @exvar{sex} and @exvar{occupation}}
@end float

@node EXAMINE
@section EXAMINE

@vindex EXAMINE
@cindex Exploratory data analysis
@cindex normality, testing

@display
EXAMINE
        VARIABLES= @var{var1} [@var{var2}] @dots{} [@var{varN}]
           [BY @var{factor1} [BY @var{subfactor1}]
             [ @var{factor2} [BY @var{subfactor2}]]
             @dots{}
             [ @var{factor3} [BY @var{subfactor3}]]
            ]
        /STATISTICS=@{DESCRIPTIVES, EXTREME[(@var{n})], ALL, NONE@}
        /PLOT=@{BOXPLOT, NPPLOT, HISTOGRAM, SPREADLEVEL[(@var{t})], ALL, NONE@}
        /CINTERVAL @var{p}
        /COMPARE=@{GROUPS,VARIABLES@}
        /ID=@var{identity_variable}
        /@{TOTAL,NOTOTAL@}
        /PERCENTILE=[@var{percentiles}]=@{HAVERAGE, WAVERAGE, ROUND, AEMPIRICAL, EMPIRICAL @}
        /MISSING=@{LISTWISE, PAIRWISE@} [@{EXCLUDE, INCLUDE@}]
                [@{NOREPORT,REPORT@}]

@end display

The @cmd{EXAMINE} command is used to perform exploratory data analysis.
In particular, it is useful for testing how closely a distribution follows a
normal distribution, and for finding outliers and extreme values.

The @subcmd{VARIABLES} subcommand is mandatory.
It specifies the dependent variables and optionally variables to use as
factors for the analysis.
Variables listed before the first @subcmd{BY} keyword (if any) are the
dependent variables.
The dependent variables may optionally be followed by a list of
factors which tell @pspp{} how to break down the analysis for each
dependent variable.

Following the dependent variables, factors may be specified.
The factors (if desired) should be preceded by a single @subcmd{BY} keyword.
The format for each factor is
@display
@var{factorvar} [BY @var{subfactorvar}].
@end display
Each unique combination of the values of  @var{factorvar} and
@var{subfactorvar} divide the dataset into @dfn{cells}.
Statistics are calculated for each cell
and for the entire dataset (unless @subcmd{NOTOTAL} is given).

The @subcmd{STATISTICS} subcommand specifies which statistics to show.
@subcmd{DESCRIPTIVES} produces a table showing some parametric and
non-parametrics statistics.
@subcmd{EXTREME} produces a table showing the extremities of each cell.
A number in parentheses, @var{n} determines
how many upper and lower extremities to show.
The default number is 5.

The subcommands @subcmd{TOTAL} and @subcmd{NOTOTAL} are mutually exclusive.
If @subcmd{TOTAL} appears, then statistics for the entire dataset
as well as for each cell are produced.
If @subcmd{NOTOTAL} appears, then statistics are produced only for the cells
(unless no factor variables have been given).
These subcommands have no effect if there have  been no factor variables
specified.

@cindex boxplot
@cindex histogram
@cindex npplot
@cindex spreadlevel plot
The @subcmd{PLOT} subcommand specifies which plots are to be produced if any.
Available plots are @subcmd{HISTOGRAM}, @subcmd{NPPLOT},  @subcmd{BOXPLOT} and
@subcmd{SPREADLEVEL}.
The first three can be used to visualise how closely each cell conforms to a
normal distribution, whilst the spread vs.@: level plot can be useful to visualise
how the variance differs between factors.
Boxplots show you the outliers and extreme values.
@footnote{@subcmd{HISTOGRAM} uses Sturges' rule to determine the number of
bins, as approximately @math{1 + \log2(n)}, where @math{n} is the number of samples.
Note that @cmd{FREQUENCIES} uses a different algorithm to find the bin size.}

The @subcmd{SPREADLEVEL} plot displays the interquartile range versus the
median.  It takes an optional parameter @var{t}, which specifies how the data
should be transformed prior to plotting.
The given value @var{t} is a power to which the data are raised.  For example, if
@var{t} is given as 2, then the square of the data is used.
Zero, however is a special value.  If @var{t} is 0 or
is omitted, then data are transformed by taking its natural logarithm instead of
raising to the power of @var{t}.

@cindex Shapiro-Wilk
When one or more plots are requested, @subcmd{EXAMINE} also performs the
Shapiro-Wilk test for each category.
There are however a number of provisos:
@itemize
@item All weight values must be integer.
@item The cumulative weight value must be in the range [3, 5000]
@end itemize

The @subcmd{COMPARE} subcommand is only relevant if producing boxplots, and it is only
useful there is more than one dependent variable and at least one factor.
If
@subcmd{/COMPARE=GROUPS} is specified, then one plot per dependent variable is produced,
each of which contain boxplots for all the cells.
If @subcmd{/COMPARE=VARIABLES} is specified, then one plot per cell is produced,
each containing one boxplot per dependent variable.
If the @subcmd{/COMPARE} subcommand is omitted, then @pspp{} behaves as if
@subcmd{/COMPARE=GROUPS} were given.

The @subcmd{ID} subcommand is relevant only if @subcmd{/PLOT=BOXPLOT} or
@subcmd{/STATISTICS=EXTREME} has been given.
If given, it should provide the name of a variable which is to be used
to labels extreme values and outliers.
Numeric or string variables are permissible.
If the @subcmd{ID} subcommand is not given, then the case number is used for
labelling.

The @subcmd{CINTERVAL} subcommand specifies the confidence interval to use in
calculation of the descriptives command.  The default is 95%.

@cindex percentiles
The @subcmd{PERCENTILES} subcommand specifies which percentiles are to be calculated,
and which algorithm to use for calculating them.  The default is to
calculate the 5, 10, 25, 50, 75, 90, 95 percentiles using the
@subcmd{HAVERAGE} algorithm.

The @subcmd{TOTAL} and @subcmd{NOTOTAL} subcommands are mutually exclusive.  If @subcmd{NOTOTAL}
is given and factors have been specified in the @subcmd{VARIABLES} subcommand,
then statistics for the unfactored dependent variables are
produced in addition to the factored variables.  If there are no
factors specified then @subcmd{TOTAL} and @subcmd{NOTOTAL} have no effect.


The following example generates descriptive statistics and histograms for
two variables @var{score1} and @var{score2}.
Two factors are given, @i{viz}: @var{gender} and @var{gender} BY @var{culture}.
Therefore, the descriptives and histograms are generated for each
distinct  value
of @var{gender} @emph{and} for each distinct combination of the values
of @var{gender} and @var{race}.
Since the @subcmd{NOTOTAL} keyword is given, statistics and histograms for
@var{score1} and @var{score2} covering the  whole dataset are not produced.
@example
EXAMINE @var{score1} @var{score2} BY
        @var{gender}
        @var{gender} BY @var{culture}
        /STATISTICS = DESCRIPTIVES
        /PLOT = HISTOGRAM
        /NOTOTAL.
@end example

Here is a second example showing how the @cmd{examine} command can be used to find extremities.
@example
EXAMINE @var{height} @var{weight} BY
        @var{gender}
        /STATISTICS = EXTREME (3)
        /PLOT = BOXPLOT
        /COMPARE = GROUPS
        /ID = @var{name}.
@end example
In this example, we look at the height and weight of a sample of individuals and
how they differ between male and female.
A table showing the 3 largest and the 3 smallest values of @exvar{height} and
@exvar{weight} for each gender, and for the whole dataset as are shown.
In addition, the @subcmd{/PLOT} subcommand requests boxplots.
Because @subcmd{/COMPARE = GROUPS} was specified, boxplots for male and female are
shown in juxtaposed in the same graphic, allowing us to easily see the difference between
the genders.
Since the variable @var{name} was specified on the @subcmd{ID} subcommand,
values of the @var{name} variable are used to label the extreme values.

@strong{Warning!}
If you specify many dependent variables or factor variables
for which there are many distinct values, then @cmd{EXAMINE} will produce a very
large quantity of output.

@node GRAPH
@section GRAPH

@vindex GRAPH
@cindex Exploratory data analysis
@cindex normality, testing

@display
GRAPH
        /HISTOGRAM [(NORMAL)]= @var{var}
        /SCATTERPLOT [(BIVARIATE)] = @var{var1} WITH @var{var2} [BY @var{var3}]
        /BAR = @{@var{summary-function}(@var{var1}) | @var{count-function}@} BY @var{var2} [BY @var{var3}]
        [ /MISSING=@{LISTWISE, VARIABLE@} [@{EXCLUDE, INCLUDE@}] ]
                [@{NOREPORT,REPORT@}]

@end display

The @cmd{GRAPH} command produces graphical plots of data. Only one of the subcommands
@subcmd{HISTOGRAM}, @subcmd{BAR} or @subcmd{SCATTERPLOT} can be specified, @i{i.e.} only one plot
can be produced per call of @cmd{GRAPH}. The @subcmd{MISSING} is optional.

@menu
* SCATTERPLOT::             Cartesian Plots
* HISTOGRAM::               Histograms
* BAR CHART::               Bar Charts
@end menu

@node SCATTERPLOT
@subsection Scatterplot
@cindex scatterplot

The subcommand @subcmd{SCATTERPLOT} produces an xy plot of the
data.
@cmd{GRAPH} uses the third variable @var{var3}, if specified, to determine
the colours and/or markers for the plot.
The following is an example for producing a scatterplot.

@example
GRAPH
        /SCATTERPLOT = @var{height} WITH @var{weight} BY @var{gender}.
@end example

This example produces a scatterplot where @var{height} is plotted versus @var{weight}. Depending
on the value of the @var{gender} variable, the colour of the datapoint is different. With
this plot it is possible to analyze gender differences for @var{height} versus @var{weight} relation.

@node HISTOGRAM
@subsection Histogram
@cindex histogram

The subcommand @subcmd{HISTOGRAM} produces a histogram. Only one variable is allowed for
the histogram plot.
The keyword @subcmd{NORMAL} may be specified in parentheses, to indicate that the ideal normal curve
should be superimposed over the histogram.
For an alternative method to produce histograms @pxref{EXAMINE}. The
following example produces a histogram plot for the variable @var{weight}.

@example
GRAPH
        /HISTOGRAM = @var{weight}.
@end example

@node BAR CHART
@subsection Bar Chart
@cindex bar chart

The subcommand @subcmd{BAR} produces a bar chart.
This subcommand requires that a @var{count-function} be specified (with no arguments) or a @var{summary-function} with a variable @var{var1} in parentheses.
Following the summary or count function, the keyword @subcmd{BY} should be specified and then a catagorical variable, @var{var2}.
The values of the variable @var{var2} determine the labels of the bars to be plotted.
Optionally a second categorical variable @var{var3} may be specified in which case a clustered (grouped) bar chart is produced.

Valid count functions are
@table @subcmd
@item COUNT
The weighted counts of the cases in each category.
@item PCT
The weighted counts of the cases in each category expressed as a percentage of the total weights of the cases.
@item CUFREQ
The cumulative weighted counts of the cases in each category.
@item CUPCT
The cumulative weighted counts of the cases in each category expressed as a percentage of the total weights of the cases.
@end table

The summary function is applied to @var{var1} across all cases in each category.
The recognised summary functions are:
@table @subcmd
@item SUM
The sum.
@item MEAN
The arithmetic mean.
@item MAXIMUM
The maximum value.
@item MINIMUM
The minimum value.
@end table

The following examples assume a dataset which is the results of a survey.
Each respondent has indicated annual income, their sex and city of residence.
One could create a bar chart showing how the mean income varies between of residents of different cities, thus:
@example
GRAPH  /BAR  = MEAN(@var{income}) BY @var{city}.
@end example

This can be extended to also indicate how income in each city differs between the sexes.
@example
GRAPH  /BAR  = MEAN(@var{income}) BY @var{city} BY @var{sex}.
@end example

One might also want to see how many respondents there are from each city.  This can be achieved as follows:
@example
GRAPH  /BAR  = COUNT BY @var{city}.
@end example

Bar charts can also be produced using the @ref{FREQUENCIES} and @ref{CROSSTABS} commands.

@node CORRELATIONS
@section CORRELATIONS

@vindex CORRELATIONS
@display
CORRELATIONS
     /VARIABLES = @var{var_list} [ WITH @var{var_list} ]
     [
      .
      .
      .
      /VARIABLES = @var{var_list} [ WITH @var{var_list} ]
      /VARIABLES = @var{var_list} [ WITH @var{var_list} ]
     ]

     [ /PRINT=@{TWOTAIL, ONETAIL@} @{SIG, NOSIG@} ]
     [ /STATISTICS=DESCRIPTIVES XPROD ALL]
     [ /MISSING=@{PAIRWISE, LISTWISE@} @{INCLUDE, EXCLUDE@} ]
@end display

@cindex correlation
The @cmd{CORRELATIONS} procedure produces tables of the Pearson correlation coefficient
for a set of variables.  The significance of the coefficients are also given.

At least one @subcmd{VARIABLES} subcommand is required. If you specify the @subcmd{WITH}
keyword, then a non-square correlation table is produced.
The variables preceding @subcmd{WITH}, are used as the rows of the table,
and the variables following @subcmd{WITH} are used as the columns of the table.
If no @subcmd{WITH} subcommand is specified, then @cmd{CORRELATIONS} produces a
square, symmetrical table using all variables.

The @cmd{MISSING} subcommand determines the handling of missing variables.
If @subcmd{INCLUDE} is set, then user-missing values are included in the
calculations, but system-missing values are not.
If @subcmd{EXCLUDE} is set, which is the default, user-missing
values are excluded as well as system-missing values.

If @subcmd{LISTWISE} is set, then the entire case is excluded from analysis
whenever any variable  specified in any @cmd{/VARIABLES} subcommand
contains a missing value.
If @subcmd{PAIRWISE} is set, then a case is considered missing only if either of the
values  for the particular coefficient are missing.
The default is @subcmd{PAIRWISE}.

The @subcmd{PRINT} subcommand is used to control how the reported significance values are printed.
If the @subcmd{TWOTAIL} option is used, then a two-tailed test of significance is
printed.  If the @subcmd{ONETAIL} option is given, then a one-tailed test is used.
The default is @subcmd{TWOTAIL}.

If the @subcmd{NOSIG} option is specified, then correlation coefficients with significance less than
0.05 are highlighted.
If @subcmd{SIG} is specified, then no highlighting is performed.  This is the default.

@cindex covariance
The @subcmd{STATISTICS} subcommand requests additional statistics to be displayed.  The keyword
@subcmd{DESCRIPTIVES} requests that the mean, number of non-missing cases, and the non-biased
estimator of the standard deviation are displayed.
These statistics are displayed in a separated table, for all the variables listed
in any @subcmd{/VARIABLES} subcommand.
The @subcmd{XPROD} keyword requests cross-product deviations and covariance estimators to
be displayed for each pair of variables.
The keyword @subcmd{ALL} is the union of @subcmd{DESCRIPTIVES} and @subcmd{XPROD}.

@node CROSSTABS
@section CROSSTABS

@vindex CROSSTABS
@display
CROSSTABS
        /TABLES=@var{var_list} BY @var{var_list} [BY @var{var_list}]@dots{}
        /MISSING=@{TABLE,INCLUDE,REPORT@}
        /FORMAT=@{TABLES,NOTABLES@}
                @{AVALUE,DVALUE@}
        /CELLS=@{COUNT,ROW,COLUMN,TOTAL,EXPECTED,RESIDUAL,SRESIDUAL,
                ASRESIDUAL,ALL,NONE@}
        /COUNT=@{ASIS,CASE,CELL@}
               @{ROUND,TRUNCATE@}
        /STATISTICS=@{CHISQ,PHI,CC,LAMBDA,UC,BTAU,CTAU,RISK,GAMMA,D,
                     KAPPA,ETA,CORR,ALL,NONE@}
        /BARCHART

(Integer mode.)
        /VARIABLES=@var{var_list} (@var{low},@var{high})@dots{}
@end display

The @cmd{CROSSTABS} procedure displays crosstabulation
tables requested by the user.  It can calculate several statistics for
each cell in the crosstabulation tables.  In addition, a number of
statistics can be calculated for each table itself.

The @subcmd{TABLES} subcommand is used to specify the tables to be reported.  Any
number of dimensions is permitted, and any number of variables per
dimension is allowed.  The @subcmd{TABLES} subcommand may be repeated as many
times as needed.  This is the only required subcommand in @dfn{general
mode}.

Occasionally, one may want to invoke a special mode called @dfn{integer
mode}.  Normally, in general mode, @pspp{} automatically determines
what values occur in the data.  In integer mode, the user specifies the
range of values that the data assumes.  To invoke this mode, specify the
@subcmd{VARIABLES} subcommand, giving a range of data values in parentheses for
each variable to be used on the @subcmd{TABLES} subcommand.  Data values inside
the range are truncated to the nearest integer, then assigned to that
value.  If values occur outside this range, they are discarded.  When it
is present, the @subcmd{VARIABLES} subcommand must precede the @subcmd{TABLES}
subcommand.

In general mode, numeric and string variables may be specified on
TABLES.  In integer mode, only numeric variables are allowed.

The @subcmd{MISSING} subcommand determines the handling of user-missing values.
When set to @subcmd{TABLE}, the default, missing values are dropped on a table by
table basis.  When set to @subcmd{INCLUDE}, user-missing values are included in
tables and statistics.  When set to @subcmd{REPORT}, which is allowed only in
integer mode, user-missing values are included in tables but marked with
a footnote and excluded from statistical calculations.

The @subcmd{FORMAT} subcommand controls the characteristics of the
crosstabulation tables to be displayed.  It has a number of possible
settings:

@itemize @w{}
@item
@subcmd{TABLES}, the default, causes crosstabulation tables to be output.
@subcmd{NOTABLES}, which is equivalent to @code{CELLS=NONE}, suppresses them.

@item
@subcmd{AVALUE}, the default, causes values to be sorted in ascending order.
@subcmd{DVALUE} asserts a descending sort order.
@end itemize

The @subcmd{CELLS} subcommand controls the contents of each cell in the displayed
crosstabulation table.  The possible settings are:

@table @asis
@item COUNT
Frequency count.
@item ROW
Row percent.
@item COLUMN
Column percent.
@item TOTAL
Table percent.
@item EXPECTED
Expected value.
@item RESIDUAL
Residual.
@item SRESIDUAL
Standardized residual.
@item ASRESIDUAL
Adjusted standardized residual.
@item ALL
All of the above.
@item NONE
Suppress cells entirely.
@end table

@samp{/CELLS} without any settings specified requests @subcmd{COUNT}, @subcmd{ROW},
@subcmd{COLUMN}, and @subcmd{TOTAL}.
If @subcmd{CELLS} is not specified at all then only @subcmd{COUNT}
is selected.

By default, crosstabulation and statistics use raw case weights,
without rounding.  Use the @subcmd{/COUNT} subcommand to perform
rounding: CASE rounds the weights of individual weights as cases are
read, CELL rounds the weights of cells within each crosstabulation
table after it has been constructed, and ASIS explicitly specifies the
default non-rounding behavior.  When rounding is requested, ROUND, the
default, rounds to the nearest integer and TRUNCATE rounds toward
zero.

The @subcmd{STATISTICS} subcommand selects statistics for computation:

@table @asis
@item CHISQ
@cindex chi-square

Pearson chi-square, likelihood ratio, Fisher's exact test, continuity
correction, linear-by-linear association.
@item PHI
Phi.
@item CC
Contingency coefficient.
@item LAMBDA
Lambda.
@item UC
Uncertainty coefficient.
@item BTAU
Tau-b.
@item CTAU
Tau-c.
@item RISK
Risk estimate.
@item GAMMA
Gamma.
@item D
Somers' D.
@item KAPPA
Cohen's Kappa.
@item ETA
Eta.
@item CORR
Spearman correlation, Pearson's r.
@item ALL
All of the above.
@item NONE
No statistics.
@end table

Selected statistics are only calculated when appropriate for the
statistic.  Certain statistics require tables of a particular size, and
some statistics are calculated only in integer mode.

@samp{/STATISTICS} without any settings selects CHISQ.  If the
@subcmd{STATISTICS} subcommand is not given, no statistics are calculated.

@cindex bar chart
The @samp{/BARCHART} subcommand produces a clustered bar chart for the first two
variables on each table.
If a table has more than two variables, the counts for the third and subsequent levels
are aggregated and the chart is produced as if there were only two variables.


@strong{Please note:} Currently the implementation of @cmd{CROSSTABS} has the
following limitations:

@itemize @bullet
@item
Significance of some symmetric and directional measures is not calculated.
@item
Asymptotic standard error is not calculated for
Goodman and Kruskal's tau or symmetric Somers' d.
@item
Approximate T is not calculated for symmetric uncertainty coefficient.
@end itemize

Fixes for any of these deficiencies would be welcomed.

@subsection Crosstabs Example

@cindex chi-square test of independence

A researcher wishes to know if, in an industry, a person's sex is related to
the person's occupation.  To investigate this, she has determined that the
@file{personnel.sav} is a representative, randomly selected sample of persons.
The researcher's null hypothesis is that a person's sex has no relation to a
person's occupation. She uses a chi-squared test of independence to investigate
the hypothesis.

@float Example, crosstabs:ex
@psppsyntax {crosstabs.sps}
@caption {Running crosstabs on the @exvar{sex} and @exvar{occupation} variables}
@end float

The syntax in @ref{crosstabs:ex} conducts a chi-squared test of independence.
The line @code{/tables = occupation by sex} indicates that @exvar{occupation}
and @exvar{sex} are the variables to be tabulated.  To do this using the @gui{}
you must place these variable names respectively in the @samp{Row} and
@samp{Column} fields as shown in @ref{crosstabs:scr}.

@float Screenshot, crosstabs:scr
@psppimage {crosstabs}
@caption {The Crosstabs dialog box with the @exvar{sex} and @exvar{occupation} variables selected}
@end float

Similarly, the @samp{Cells} button shows a dialog box to select the @code{count}
and @code{expected} options.  All other cell options can be deselected for this
test.

You would use the @samp{Format} and @samp{Statistics}  buttons to select options
for the @subcmd{FORMAT} and @subcmd{STATISTICS} subcommands.  In this example,
the @samp{Statistics} requires only the @samp{Chisq} option to be checked.  All
other options should be unchecked.  No special settings are required from the
@samp{Format} dialog.

As shown in @ref{crosstabs:res} @cmd{CROSSTABS} generates a contingency table
containing the observed count and the expected count of each sex and each
occupation.  The expected count is the count which would be observed if the
null hypothesis were true.

The significance of the Pearson Chi-Square value is very much larger than the
normally accepted value of 0.05 and so one cannot reject the null hypothesis.
Thus the researcher must conclude that a person's sex has no relation to the
person's occupation.

@float Results, crosstabs:res
@psppoutput {crosstabs}
@caption {The results of a test of independence between @exvar{sex} and @exvar{occupation}}
@end float

@node CTABLES
@section CTABLES

@vindex CTABLES
@cindex custom tables
@cindex tables, custom

@code{CTABLES} has the following overall syntax.  At least one
@code{TABLE} subcommand is required:

@display
@t{CTABLES}
  @dots{}@i{global subcommands}@dots{}
  [@t{/TABLE} @i{axis} [@t{BY} @i{axis} [@t{BY} @i{axis}]]
   @dots{}@i{per-table subcommands}@dots{}]@dots{}
@end display

@noindent
where each @i{axis} may be empty or take one of the following forms:

@display
@i{variable}
@i{variable} @t{[}@{@t{C} @math{|} @t{S}@}@t{]}
@i{axis} + @i{axis}
@i{axis} > @i{axis}
(@i{axis})
@i{axis} @t{[}@i{summary} [@i{string}] [@i{format}]@t{]}
@end display

The following subcommands precede the first @code{TABLE} subcommand
and apply to all of the output tables.  All of these subcommands are
optional:

@display
@t{/FORMAT}
    [@t{MINCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
    [@t{MAXCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
    [@t{UNITS=}@{@t{POINTS} @math{|} @t{INCHES} @math{|} @t{CM}@}]
    [@t{EMPTY=}@{@t{ZERO} @math{|} @t{BLANK} @math{|} @i{string}@}]
    [@t{MISSING=}@i{string}]
@t{/VLABELS}
    @t{VARIABLES=}@i{variables}
    @t{DISPLAY}=@{@t{DEFAULT} @math{|} @t{NAME} @math{|} @t{LABEL} @math{|} @t{BOTH} @math{|} @t{NONE}@}
@ignore @c not yet implemented
@t{/MRSETS COUNTDUPLICATES=}@{@t{YES} @math{|} @t{NO}@}
@end ignore
@t{/SMISSING} @{@t{VARIABLE} @math{|} @t{LISTWISE}@}
@t{/PCOMPUTE} @t{&}@i{postcompute}@t{=EXPR(}@i{expression}@t{)}
@t{/PPROPERTIES} @t{&}@i{postcompute}@dots{}
    [@t{LABEL=}@i{string}]
    [@t{FORMAT=}[@i{summary} @i{format}]@dots{}]
    [@t{HIDESOURCECATS=}@{@t{NO} @math{|} @t{YES}@}
@t{/WEIGHT VARIABLE=}@i{variable}
@t{/HIDESMALLCOUNTS COUNT=@i{count}}
@end display

The following subcommands follow @code{TABLE} and apply only to the
previous @code{TABLE}.  All of these subcommands are optional:

@display
@t{/SLABELS}
    [@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{/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}@}]
@t{/TITLES}
    [@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}@}]
    [@t{CATEGORIES=}@{@t{ALLVISIBLE} @math{|} @t{SUBTOTALS}@}]
@t{/COMPARETEST TYPE=}@{@t{PROP} @math{|} @t{MEAN}@}
    [@t{ALPHA=}@i{value}[@t{,} @i{value}]]
    [@t{ADJUST=}@{@t{BONFERRONI} @math{|} @t{BH} @math{|} @t{NONE}@}]
    [@t{INCLUDEMRSETS=}@{@t{YES} @math{|} @t{NO}@}]
    [@t{MEANSVARIANCE=}@{@t{ALLCATS} @math{|} @t{TESTEDCATS}@}]
    [@t{CATEGORIES=}@{@t{ALLVISIBLE} @math{|} @t{SUBTOTALS}@}]
    [@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
multi-dimensional tables from categorical and scale data.  It offers
many options for data summarization and formatting.

This section's examples use data from the 2008 (USA) National Survey
of Drinking and Driving Attitudes and Behaviors, a public domain data
set from the (USA) National Highway Traffic Administration and
available at @url{https://data.transportation.gov}.  @pspp{} includes
this data set, with a slightly modified dictionary, as
@file{examples/nhtsa.sav}.

@node CTABLES Basics
@subsection Basics

The only required subcommand is @code{TABLE}, which specifies the
variables to include along each axis:
@display
@t{/TABLE} @i{rows} [@t{BY} @i{columns} [@t{BY} @i{layers}]]
@end display
@noindent
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.

@node CTABLES Categorical Variable Basics
@subsubsection Categorical Variables

An axis expression that names a categorical variable divides the data
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, much like the output of the
@code{FREQUENCIES} command (@pxref{FREQUENCIES}):

@example
CTABLES /TABLE=AgeGroup.
@end example
@psppoutput {ctables1}

@noindent
Specifying a row and a column categorical variable yields a
crosstabulation, much like the output of the @code{CROSSTABS} command
(@pxref{CROSSTABS}):

@example
CTABLES /TABLE=AgeGroup BY qns3a.
@end example
@psppoutput {ctables2}

@noindent
The @samp{>} ``nesting'' operator nests multiple variables on a single
axis, e.g.:

@example
CTABLES /TABLE qn105ba BY AgeGroup > qns3a.
@end example
@psppoutput {ctables3}

@noindent
The @samp{+} ``stacking'' operator allows a single output table to
include multiple data analyses.  With @samp{+}, @code{CTABLES} divides
the output table into multiple @dfn{sections}, each of which includes
an analysis of the full data set.  For example, the following command
separately tabulates age group and driving frequency by gender:

@example
CTABLES /TABLE AgeGroup + qn1 BY qns3a.
@end example
@psppoutput {ctables4}

@noindent
When @samp{+} and @samp{>} are used together, @samp{>} binds more
tightly.  Use parentheses to override operator precedence.  Thus:

@example
CTABLES /TABLE qn26 + qn27 > qns3a.
CTABLES /TABLE (qn26 + qn27) > qns3a.
@end example
@psppoutput {ctables5}

@node CTABLES Scalar Variable Basics
@subsubsection Scalar Variables

For a categorical variable, @code{CTABLES} divides the table into a
cell per category.  For a scalar variable, @code{CTABLES} instead
calculates a summary measure, by default the mean, of the values that
fall into a cell.  For example, if the only variable specified is a
scalar variable, then the output is a single cell that holds the mean
of all of the data:

@example
CTABLES /TABLE qnd1.
@end example
@psppoutput {ctables6}

A scalar variable may nest with categorical variables.  The following
example shows the mean age of survey respondents across gender and
language groups:

@example
CTABLES /TABLE qns3a > qnd1 BY region.
@end example
@psppoutput {ctables7}

The order of nesting of scalar and categorical variables affects table
labeling, but it does not affect the data displayed in the table.  The
following example shows how the output changes when the nesting order
of the scalar and categorical variable are interchanged:

@example
CTABLES /TABLE qnd1 > qns3a BY region.
@end example
@psppoutput {ctables8}

Only a single scalar variable may appear in each section; that is, a
scalar variable may not nest inside a scalar variable directly or
indirectly.  Scalar variables may only appear on one axis within
@code{TABLE}.

@node CTABLES Overriding Measurement Level
@subsubsection Overriding Measurement Level

By default, @code{CTABLES} uses a variable's measurement level to
decide whether to treat it as categorical or scalar.  Variables
assigned the nominal or ordinal measurement level are treated as
categorical, and scalar variables are treated as scalar.

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 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}).

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 BY qns3a
    /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

The @code{CTABLES} command allows the user to control how the data are
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
    /TABLE=qnd1 [MEAN, MEDIAN] BY qns3a
    /TABLE=AgeGroup [COLPCT, ROWPCT] BY qns3a.
@end example
@psppoutput {ctables10}

A summary specification may override the default label and format by
appending a string or format specification or both (in that order) to
the summary function name.  For example:

@example
CTABLES /TABLE=AgeGroup [COLPCT 'Gender %' PCT5.0,
                         ROWPCT 'Age Group %' PCT5.0]
               BY qns3a.
@end example
@psppoutput {ctables11}

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:

@example
CTABLES /TABLE=AgeGroup[COLPCT] + qns1[COLPCT] BY qns3a.
CTABLES /TABLE=(AgeGroup + qns1)[COLPCT] BY qns3a.
@end example

@noindent
produce the same output shown below:

@psppoutput {ctables12}

The following sections list the available summary functions.  After
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.

@node CTABLES Summary Functions for Individual Cells
@subsubsection Summary Functions for Individual Cells

This section lists the summary functions that consider only an
individual cell in @code{CTABLES}.  Only one such summary function,
@code{COUNT}, may be applied to both categorical and scale variables:

@table @asis
@item @code{COUNT} (``Count'', F40.0)
The sum of weights in a cell.

If @code{CATEGORIES} for one or more of the variables in a table
include missing values (@pxref{CTABLES Per-Variable Category
Options}), then some or all of the categories for a cell might be
missing values.  @code{COUNT} counts data included in a cell
regardless of whether its categories are missing.
@end table

The following summary functions apply only to scale variables or
totals and subtotals for categorical variables.  Be cautious about
interpreting the summary value in the latter case, because it is not
necessarily meaningful; however, the mean of a Likert scale, etc.@:
may have a straightforward interpreation.

@table @asis
@item @code{MAXIMUM} (``Maximum'')
The largest value.

@item @code{MEAN} (``Mean'')
The mean.

@item @code{MEDIAN} (``Median'')
The median value.

@item @code{MINIMUM} (``Minimum'')
The smallest value.

@item @code{MISSING} (``Missing'')
Sum of weights of user- and system-missing values.

@item @code{MODE} (``Mode'')
The highest-frequency value.  Ties are broken by taking the smallest mode.

@item @code{PTILE} @i{n} (``Percentile @i{n}'')
The @var{n}th percentile, where @math{0 @leq{} @var{n} @leq{} 100}.

@item @code{RANGE} (``Range'')
The maximum minus the minimum.

@item @code{SEMEAN} (``Std Error of Mean'')
The standard error of the mean.

@item @code{STDDEV} (``Std Deviation'')
The standard deviation.

@item @code{SUM} (``Sum'')
The sum.

@item @code{TOTALN} (``Total N'', F40.0)
The sum of weights in a cell.

For scale data, @code{COUNT} and @code{TOTALN} are the same.

For categorical data, @code{TOTALN} counts missing values in excluded
categories, that is, user-missing values not in an explicit category
list on @code{CATEGORIES} (@pxref{CTABLES Per-Variable Category
Options}), or user-missing values excluded because
@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.

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.
@end table

@node CTABLES Summary Functions for Groups of Cells
@subsubsection Summary Functions for Groups of Cells

These summary functions summarize over multiple cells within an area
of the output chosen by the user and specified as part of the function
name.  The following basic @var{area}s are supported, in decreasing
order of size:

@table @code
@item TABLE
A @dfn{section}.  Stacked variables divide sections of the output from
each other.  sections may span multiple layers.

@item LAYER
A section within a single layer.

@item SUBTABLE
A @dfn{subtable}, whose contents are the cells that pair an innermost
row variable and an innermost column variable within a single layer.
@end table

The following shows how the output for the table expression @code{qn61
> qn57 BY qnd7a > qn86 + qn64b BY qns3a}@footnote{This is not
necessarily a meaningful table, so for clarity variable labels are
omitted.} is divided up into @code{TABLE}, @code{LAYER}, and
@code{SUBTABLE} areas.  Each unique value for Table ID is one section,
and similarly for Layer ID and Subtable ID.  Thus, this output has two
@code{TABLE} areas (one for @code{qnd7a} and one for @code{qn64b}),
four @code{LAYER} areas (for those two variables, per layer), and 12
@code{SUBTABLE} areas.
@psppoutput {ctables22}

@code{CTABLES} also supports the following @var{area}s that further
divide a subtable or a layer within a section:

@table @code
@item LAYERROW
@itemx LAYERCOL
A row or column, respectively, in one layer of a section.

@item ROW
@itemx COL
A row or column, respectively, in a subtable.
@end table

The following summary functions for groups of cells are available for
each @var{area} described above, for both categorical and scale
variables:

@table @asis
@item @code{@i{area}PCT} or @code{@i{area}PCT.COUNT} (``@i{Area} %'', PCT40.1)
A percentage of total counts within @var{area}.

@item @code{@i{area}PCT.VALIDN} (``@i{Area} Valid N %'', PCT40.1)
A percentage of total counts for valid values within @var{area}.

@item @code{@i{area}PCT.TOTALN} (``@i{Area} Total N %'', PCT40.1)
A percentage of total counts for all values within @var{area}.
@end table

Scale variables and totals and subtotals for categorical variables may
use the following additional group cell summary function:

@table @asis
@item @code{@i{area}PCT.SUM} (``@i{Area} Sum %'', PCT40.1)
Percentage of the sum of the values within @var{area}.
@end table

@node CTABLES Summary Functions for Adjusted Weights
@subsubsection Summary Functions for Adjusted Weights

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{ECOUNT} (``Adjusted Count'', F40.0)

@item
@code{ETOTALN} (``Adjusted Total N'', F40.0)

@item
@code{EVALIDN} (``Adjusted Valid N'', F40.0)
@end itemize

@node CTABLES Unweighted Summary Functions
@subsubsection Unweighted Summary Functions

The following summary functions with a @samp{U}-prefix are equivalent
to the same ones without the prefix, except that they use unweighted
counts:

@itemize @bullet
@item
@code{UCOUNT} (``Unweighted Count'', F40.0)

@item
@code{U@i{area}PCT} or @code{U@i{area}PCT.COUNT} (``Unweighted @i{Area} %'', PCT40.1)

@item
@code{U@i{area}PCT.VALIDN} (``Unweighted @i{Area} Valid N %'', PCT40.1)

@item
@code{U@i{area}PCT.TOTALN} (``Unweighted @i{Area} Total N %'', PCT40.1)

@item
@code{UMEAN} (``Unweighted Mean'')

@item
@code{UMEDIAN} (``Unweighted Median'')

@item
@code{UMISSING} (``Unweighted Missing'')

@item
@code{UMODE} (``Unweighted Mode'')

@item
@code{U@i{area}PCT.SUM} (``Unweighted @i{Area} Sum %'', PCT40.1)

@item
@code{UPTILE} @i{n} (``Unweighted Percentile @i{n}'') 

@item
@code{USEMEAN} (``Unweighted Std Error of Mean'')

@item
@code{USTDDEV} (``Unweighted Std Deviation'')

@item
@code{USUM} (``Unweighted Sum'')

@item
@code{UTOTALN} (``Unweighted Total N'', F40.0)

@item
@code{UVALIDN} (``Unweighted Valid N'', F40.0)

@item
@code{UVARIANCE} (``Unweighted Variance'', F40.0)
@end itemize

@node CTABLES Statistics Positions and Labels
@subsection Statistics Positions and Labels

@display
@t{/SLABELS}
    [@t{POSITION=}@{@t{COLUMN} @math{|} @t{ROW} @math{|} @t{LAYER}@}]
    [@t{VISIBLE=}@{@t{YES} @math{|} @t{NO}@}]
@end display

The @code{SLABELS} subcommand controls the position and visibility of
summary statistics for the @code{TABLE} subcommand that it follows.

@code{POSITION} sets the axis on which summary statistics appear.
With @t{POSITION=COLUMN}, which is the default, each summary statistic
appears in a column.  For example:

@example
CTABLES /TABLE=qnd1 [MEAN, MEDIAN] BY qns3a.
@end example
@psppoutput {ctables13}

@noindent
With @t{POSITION=ROW}, each summary statistic appears in a row, as
shown below:

@example
CTABLES /TABLE=qnd1 [MEAN, MEDIAN] BY qns3a /SLABELS POSITION=ROW.
@end example
@psppoutput {ctables14}

@noindent
@t{POSITION=LAYER} is also available to place each summary statistic in
a separate layer.

Labels for summary statistics are shown by default.  Use
@t{VISIBLE=NO} to suppress them.  Because unlabeled data can cause
confusion, it should only be considered if the meaning of the data is
evident, as in a simple case like this:

@example
CTABLES /TABLE=AgeGroup [TABLEPCT] /SLABELS VISIBLE=NO.
@end example
@psppoutput {ctables15}

@node CTABLES Category Label Positions
@subsection Category Label Positions

@display
@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
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.
@end example
@psppoutput {ctables16}

@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 or variables, which must
be categorical, on the given axis.  For example:

@example
CTABLES /TABLE AgeGroup BY qns3a /CLABELS ROWLABELS=OPPOSITE.
CTABLES /TABLE AgeGroup BY qns3a /CLABELS COLLABELS=OPPOSITE.
@end example
@psppoutput {ctables17}

@t{ROWLABELS=LAYER} or @t{COLLABELS=LAYER} move the innermost row or
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.

@subsubheading Effect on Summary Statistics

@code{CLABELS} primarily affects the appearance of tables, not the
data displayed in them.  However, @code{CTABLES} can affect the values
displayed for statistics that summarize areas of a table, since it can
change the definitions of these areas.

For example, consider the following syntax and output:

@example
CTABLES /TABLE AgeGroup BY qns3a [ROWPCT, COLPCT].
@end example
@psppoutput {ctables23}

@noindent
Using @code{COLLABELS=OPPOSITE} changes the definitions of rows and
columns, so that column percentages display what were previously row
percentages and the new row percentages become meaningless (because
there is only one cell per row):

@example
CTABLES
    /TABLE AgeGroup BY qns3a [ROWPCT, COLPCT]
    /CLABELS COLLABELS=OPPOSITE.
@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

@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 scalar variables.

@t{VARIABLES} is required and must list the variables for the subcommand
to affect.

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

@anchor{CTABLES Explicit Category List}

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:

@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).

@item &@i{postcompute}
A computed category name (@pxref{CTABLES Computed Categories}).

@item SUBTOTAL
@itemx HSUBTOTAL
A subtotal (@pxref{CTABLES Totals and Subtotals}).
@end table

If multiple elements of the list cover a given category, the last one
in the list takes precedence.

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
also be sorted by value label, with @code{KEY=LABEL}, or by the value
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.

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.

The following example syntax and output show how
@code{MISSING=INCLUDE} causes missing values to be included in a
category list.

@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.  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
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.  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
differently, specify the summary functions for totals and subtotals
after the ordinary summary functions inside a nested set of @code{[]}
following @code{TOTALS}.  For example, the following syntax displays
@code{COUNT} for individual categories and totals and @code{VALIDN}
for totals, as shown:

@example
CTABLES
    /TABLE qnd7a [COUNT, TOTALS[COUNT, VALIDN]]
    /CATEGORIES VARIABLES=qnd7a TOTAL=YES MISSING=INCLUDE.
@end example
@psppoutput {ctables26}

@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
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 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}.

@c TODO

@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.  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

@display
@t{/FORMAT}
    [@t{MINCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
    [@t{MAXCOLWIDTH=}@{@t{DEFAULT} @math{|} @i{width}@}]
    [@t{UNITS=}@{@t{POINTS} @math{|} @t{INCHES} @math{|} @t{CM}@}]
    [@t{EMPTY=}@{@t{ZERO} @math{|} @t{BLANK} @math{|} @i{string}@}]
    [@t{MISSING=}@i{string}]
@end display

The @code{FORMAT} subcommand, which must precede the first
@code{TABLE} subcommand, controls formatting for all the output
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, 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 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.  @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
instead, or @code{EMPTY="@i{string}"} to use the specified string.

By default, missing values are displayed as @samp{.}, the same as in
other tables.  Specify @code{MISSING="@i{string}"} to instead use a
custom string.

@node CTABLES Display of Variable Labels
@subsection Display of Variable Labels

@display
@t{/VLABELS}
    @t{VARIABLES=}@i{variables}
    @t{DISPLAY}=@{@t{DEFAULT} @math{|} @t{NAME} @math{|} @t{LABEL} @math{|} @t{BOTH} @math{|} @t{NONE}@}
@end display

The @code{VLABELS} subcommand, which must precede the first
@code{TABLE} subcommand, controls display of variable labels in all
the output tables.  @code{VLABELS} is optional.  It may appear
multiple times to adjust settings for different variables.

@code{VARIABLES} and @code{DISPLAY} are required.  The value of
@code{DISPLAY} controls how variable labels are displayed for the
variables listed on @code{VARIABLES}.  The supported values are:

@table @code
@item DEFAULT
Use the setting from @code{SET TVARS} (@pxref{SET TVARS}).

@item NAME
Show only a variable name.

@item LABEL
Show only a variable label.

@item BOTH
Show variable name and label.

@item NONE
Show nothing.
@end table

@c TODO example

@node CTABLES Missing Value Treatment
@subsection Missing Value Treatment

The @code{TABLE} subcommand on @code{CTABLES} specifies two different
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:

@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.

@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.

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

@c TODO example

@node CTABLES Missing Values for Summary Variables
@subsubsection Missing Values for Summary Variables

For summary variables, values that are valid and in included
categories are analyzed, and values that are missing or in excluded
categories are not analyzed, with the following exceptions:

@itemize @bullet
@item
The ``@t{VALIDN}'' summary functions (@code{VALIDN}, @code{EVALIDN},
@code{UVALIDN}, @code{@i{area}PCT.VALIDN}, and
@code{U@i{area}PCT.VALIDN}) only count valid values in included
categories (not missing values in included categories).

@item
The ``@t{TOTALN}'' summary functions (@code{TOTALN}, @code{ETOTALN},
@code{UTOTALN}, @code{@i{area}PCT.TOTALN}), and
@code{U@i{area}PCT.TOTALN} count all values (valid and missing) in
included categories and missing (but not valid) values in excluded
categories.
@end itemize

@noindent
For categorical variables, system-missing values are never in included
categories.  For scale variables, there is no notion of included and
excluded categories, so all values are effectively included.

The following table provides another view of the above rules:

@multitable {@w{ }@w{ }@w{ }@w{ }Missing values in excluded categories} {@t{VALIDN}} {other} {@t{TOTALN}}
@headitem @tab @t{VALIDN} @tab other @tab @t{TOTALN}
@item @headitemfont{Categorical variables:}
@item @w{ }@w{ }@w{ }@w{ }Valid values in included categories   @tab yes @tab yes @tab yes
@item @w{ }@w{ }@w{ }@w{ }Missing values in included categories @tab --- @tab yes @tab yes
@item @w{ }@w{ }@w{ }@w{ }Missing values in excluded categories @tab --- @tab --- @tab yes
@item @w{ }@w{ }@w{ }@w{ }Valid values in excluded categories   @tab --- @tab --- @tab ---
@item @headitemfont{Scale variables:}
@item @w{ }@w{ }@w{ }@w{ }Valid values                          @tab yes @tab yes @tab yes
@item @w{ }@w{ }@w{ }@w{ }User- or system-missing values        @tab --- @tab yes @tab yes
@end multitable

@node CTABLES Scale Missing Values
@subsubsection Scale Missing Values

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

The @code{SMISSING} subcommand, which must precede the first
@code{TABLE} subcommand, controls treatment of missing values for
scalar variables in producing all the output tables.  @code{SMISSING}
is optional.

With @code{SMISSING=VARIABLE}, which is the default, missing values
are excluded on a variable-by-variable basis.  With
@code{SMISSING=LISTWISE}, when stacked scalar variables are nested
together with a categorical variable, a missing value for any of the
scalar variables causes the case to be excluded for all of them.

As an example, consider the following dataset, in which @samp{x} is a
categorical variable and @samp{y} and @samp{z} are scale:

@psppoutput{ctables18}

@noindent
With the default missing-value treatment, @samp{x}'s mean is 20, based
on the values 10, 20, and 30, and @samp{y}'s mean is 50, based on 40,
50, and 60:

@example
CTABLES /TABLE (y + z) > x.
@end example
@psppoutput{ctables19}

@noindent
By adding @code{SMISSING=LISTWISE}, only cases where @samp{y} and
@samp{z} are both non-missing are considered, so @samp{x}'s mean
becomes 15, as the average of 10 and 20, and @samp{y}'s mean becomes
55, the average of 50 and 60:

@example
CTABLES /SMISSING LISTWISE /TABLE (y + z) > x.
@end example
@psppoutput{ctables20}

@noindent
Even with @code{SMISSING=LISTWISE}, if @samp{y} and @samp{z} are
separately nested with @samp{x}, instead of using a single @samp{>}
operator, missing values revert to being considered on a
variable-by-variable basis:

@example
CTABLES /SMISSING LISTWISE /TABLE (y > x) + (z > x).
@end example
@psppoutput{ctables21}

@node CTABLES Computed Categories
@subsection Computed Categories

@display
@t{/PCOMPUTE} @t{&}@i{postcompute}@t{=EXPR(}@i{expression}@t{)}
@end display

@dfn{Computed categories}, also called @dfn{postcomputes}, are
categories created using arithmetic on categories obtained from the
data.  The @code{PCOMPUTE} subcommand defines computed categories,
which can then be used in two places: on @code{CATEGORIES} within an
explicit category list (@pxref{CTABLES Explicit Category List}), and on
the @code{PPROPERTIES} subcommand to define further properties for a
given postcompute.

@code{PCOMPUTE} must precede the first @code{TABLE} command.  It is
optional and it may be used any number of times to define multiple
postcomputes.

Each @code{PCOMPUTE} defines one postcompute.  Its syntax consists of
a name to identify the postcompute as a @pspp{} identifier prefixed by
@samp{&}, followed by @samp{=} and a postcompute expression enclosed
in @code{EXPR(@dots{})}.  A postcompute expression consists of:

@table @t
@item [@i{category}]
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.  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 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 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
@code{CATEGORIES} lists with any number of subtotals.

@item 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}
@itemx @i{a} * @i{b}
@itemx @i{a} / @i{b}
@itemx @i{a} ** @i{b}
These forms perform arithmetic on the values of postcompute
expressions @i{a} and @i{b}.  The usual operator precedence rules
apply.

@item @i{number}
Numeric constants may be used in postcompute expressions.

@item (@i{a})
Parentheses override operator precedence.
@end table

A postcompute is not associated with any particular variable.
Instead, it may be referenced within @code{CATEGORIES} for any
suitable variable (e.g.@: only a string variable is suitable for a
postcompute expression that refers to a string category, only a
variable with subtotals for an expression that refers to subtotals,
@dots{}).

Normally a named postcompute is defined only once, but if a later
@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

@display
@t{/PPROPERTIES} @t{&}@i{postcompute}@dots{}
    [@t{LABEL=}@i{string}]
    [@t{FORMAT=}[@i{summary} @i{format}]@dots{}]
    [@t{HIDESOURCECATS=}@{@t{NO} @math{|} @t{YES}@}
@end display

The @code{PPROPERTIES} subcommand, which must appear before
@code{TABLE}, sets properties for one or more postcomputes defined on
prior @code{PCOMPUTE} subcommands.  The subcommand syntax begins with
the list of postcomputes, each prefixed with @samp{&} as specified on
@code{PCOMPUTE}.

All of the settings on @code{PPROPERTIES} are optional.  Use
@code{LABEL} to set the label shown for the postcomputes in table
output.  The default label for a postcompute is the expression used to
define it.

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.

@c TODO example

@node CTABLES Effective Weight
@subsection Effective Weight

@display
@t{/WEIGHT VARIABLE=}@i{variable}
@end display

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 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 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

@display
@t{/HIDESMALLCOUNTS COUNT=@i{count}}
@end display

The @code{HIDESMALLCOUNTS} subcommand is optional.  If it specified,
then count values in output tables less than the value of @i{count}
are shown as @code{<@i{count}} instead of their true values.  The
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

@vindex FACTOR
@cindex factor analysis
@cindex principal components analysis
@cindex principal axis factoring
@cindex data reduction

@display
FACTOR  @{
         VARIABLES=@var{var_list},
         MATRIX IN (@{CORR,COV@}=@{*,@var{file_spec}@})
        @}

        [ /METHOD = @{CORRELATION, COVARIANCE@} ]

        [ /ANALYSIS=@var{var_list} ]

        [ /EXTRACTION=@{PC, PAF@}]

        [ /ROTATION=@{VARIMAX, EQUAMAX, QUARTIMAX, PROMAX[(@var{k})], NOROTATE@}]

        [ /PRINT=[INITIAL] [EXTRACTION] [ROTATION] [UNIVARIATE] [CORRELATION] [COVARIANCE] [DET] [KMO] [AIC] [SIG] [ALL] [DEFAULT] ]

        [ /PLOT=[EIGEN] ]

        [ /FORMAT=[SORT] [BLANK(@var{n})] [DEFAULT] ]

        [ /CRITERIA=[FACTORS(@var{n})] [MINEIGEN(@var{l})] [ITERATE(@var{m})] [ECONVERGE (@var{delta})] [DEFAULT] ]

        [ /MISSING=[@{LISTWISE, PAIRWISE@}] [@{INCLUDE, EXCLUDE@}] ]
@end display

The @cmd{FACTOR} command performs Factor Analysis or Principal Axis Factoring on a dataset.  It may be used to find
common factors in the data or for data reduction purposes.

The @subcmd{VARIABLES} subcommand is required (unless the @subcmd{MATRIX IN}
subcommand is used).
It lists the variables which are to partake in the analysis.  (The @subcmd{ANALYSIS}
subcommand may optionally further limit the variables that
participate; it is useful primarily in conjunction with @subcmd{MATRIX IN}.)

If @subcmd{MATRIX IN} instead of @subcmd{VARIABLES} is specified, then the analysis
is performed on a pre-prepared correlation or covariance matrix file instead of on
individual data cases.  Typically the matrix file will have been generated by
@cmd{MATRIX DATA} (@pxref{MATRIX DATA}) or provided by a third party.
If specified, @subcmd{MATRIX IN} must be followed by @samp{COV} or @samp{CORR},
then by @samp{=} and @var{file_spec} all in parentheses.
@var{file_spec} may either be an asterisk, which indicates the currently loaded
dataset, or it may be a file name to be loaded. @xref{MATRIX DATA}, for the expected
format of the file.

The @subcmd{/EXTRACTION} subcommand is used to specify the way in which factors
(components) are extracted from the data.
If @subcmd{PC} is specified, then Principal Components Analysis is used.
If @subcmd{PAF} is specified, then Principal Axis Factoring is
used. By default Principal Components Analysis is used.

The @subcmd{/ROTATION} subcommand is used to specify the method by which the
extracted solution is rotated.  Three orthogonal rotation methods are available:
@subcmd{VARIMAX} (which is the default), @subcmd{EQUAMAX}, and @subcmd{QUARTIMAX}.
There is one oblique rotation method, @i{viz}: @subcmd{PROMAX}.
Optionally you may enter the power of the promax rotation @var{k}, which must be enclosed in parentheses.
The default value of @var{k} is 5.
If you don't want any rotation to be performed, the word @subcmd{NOROTATE}
prevents the command from performing any rotation on the data.

The @subcmd{/METHOD} subcommand should be used to determine whether the
covariance matrix or the correlation matrix of the data is
to be analysed.  By default, the correlation matrix is analysed.

The @subcmd{/PRINT} subcommand may be used to select which features of the analysis are reported:

@itemize
@item @subcmd{UNIVARIATE}
      A table of mean values, standard deviations and total weights are printed.
@item @subcmd{INITIAL}
      Initial communalities and eigenvalues are printed.
@item @subcmd{EXTRACTION}
      Extracted communalities and eigenvalues are printed.
@item @subcmd{ROTATION}
      Rotated communalities and eigenvalues are printed.
@item @subcmd{CORRELATION}
      The correlation matrix is printed.
@item @subcmd{COVARIANCE}
      The covariance matrix is printed.
@item @subcmd{DET}
      The determinant of the correlation or covariance matrix is printed.
@item @subcmd{AIC}
      The anti-image covariance and anti-image correlation matrices are printed.
@item @subcmd{KMO}
      The Kaiser-Meyer-Olkin measure of sampling adequacy and the Bartlett test of sphericity is printed.
@item @subcmd{SIG}
      The significance of the elements of correlation matrix is printed.
@item @subcmd{ALL}
      All of the above are printed.
@item @subcmd{DEFAULT}
      Identical to @subcmd{INITIAL} and @subcmd{EXTRACTION}.
@end itemize

If @subcmd{/PLOT=EIGEN} is given, then a ``Scree'' plot of the eigenvalues is
printed.  This can be useful for visualizing the factors and deciding
which factors (components) should be retained.

The @subcmd{/FORMAT} subcommand determined how data are to be
displayed in loading matrices.  If @subcmd{SORT} is specified, then
the variables are sorted in descending order of significance.  If
@subcmd{BLANK(@var{n})} is specified, then coefficients whose absolute
value is less than @var{n} are not printed.  If the keyword
@subcmd{DEFAULT} is specified, or if no @subcmd{/FORMAT} subcommand is
specified, then no sorting is performed, and all coefficients are printed.

You can use the @subcmd{/CRITERIA} subcommand to specify how the number of
extracted factors (components) are chosen.  If @subcmd{FACTORS(@var{n})} is
specified, where @var{n} is an integer, then @var{n} factors are
extracted.  Otherwise, the @subcmd{MINEIGEN} setting is used.
@subcmd{MINEIGEN(@var{l})} requests that all factors whose eigenvalues
are greater than or equal to @var{l} are extracted. The default value
of @var{l} is 1. The @subcmd{ECONVERGE} setting has effect only when
using iterative algorithms for factor extraction (such as Principal Axis
Factoring).  @subcmd{ECONVERGE(@var{delta})} specifies that
iteration should cease when the maximum absolute value of the
communality estimate between one iteration and the previous is less
than @var{delta}. The default value of @var{delta} is 0.001.

The @subcmd{ITERATE(@var{m})} may appear any number of times and is
used for two different purposes. It is used to set the maximum number
of iterations (@var{m}) for convergence and also to set the maximum
number of iterations for rotation.
Whether it affects convergence or rotation depends upon which
subcommand follows the @subcmd{ITERATE} subcommand.
If @subcmd{EXTRACTION} follows, it affects convergence.
If @subcmd{ROTATION} follows, it affects rotation.
If neither @subcmd{ROTATION} nor @subcmd{EXTRACTION} follow a
@subcmd{ITERATE} subcommand, then the entire subcommand is ignored.
The default value of @var{m} is 25.

The @cmd{MISSING} subcommand determines the handling of missing
variables.  If @subcmd{INCLUDE} is set, then user-missing values are
included in the calculations, but system-missing values are not.
If @subcmd{EXCLUDE} is set, which is the default, user-missing
values are excluded as well as system-missing values.  This is the
default. If @subcmd{LISTWISE} is set, then the entire case is excluded
from analysis whenever any variable  specified in the @cmd{VARIABLES}
subcommand contains a missing value.

If @subcmd{PAIRWISE} is set, then a case is considered missing only if
either of the values  for the particular coefficient are missing.
The default is @subcmd{LISTWISE}.

@node GLM
@section GLM

@vindex GLM
@cindex univariate analysis of variance
@cindex fixed effects
@cindex factorial anova
@cindex analysis of variance
@cindex ANOVA


@display
GLM @var{dependent_vars} BY @var{fixed_factors}
     [/METHOD = SSTYPE(@var{type})]
     [/DESIGN = @var{interaction_0} [@var{interaction_1} [... @var{interaction_n}]]]
     [/INTERCEPT = @{INCLUDE|EXCLUDE@}]
     [/MISSING = @{INCLUDE|EXCLUDE@}]
@end display

The @cmd{GLM} procedure can be used for fixed effects factorial Anova.

The @var{dependent_vars} are the variables to be analysed.
You may analyse several variables in the same command in which case they should all
appear before the @code{BY} keyword.

The @var{fixed_factors} list must be one or more categorical variables.  Normally it
does not make sense to enter a scalar variable in the @var{fixed_factors} and doing
so may cause @pspp{} to do a lot of unnecessary processing.

The @subcmd{METHOD} subcommand is used to change the method for producing the sums of
squares.  Available values of @var{type} are 1, 2 and 3.  The default is type 3.

You may specify a custom design using the @subcmd{DESIGN} subcommand.
The design comprises a list of interactions where each interaction is a
list of variables separated by a @samp{*}.  For example the command
@display
GLM subject BY sex age_group race
    /DESIGN = age_group sex group age_group*sex age_group*race
@end display
@noindent specifies the model @math{subject = age_group + sex + race + age_group*sex + age_group*race}.
If no @subcmd{DESIGN} subcommand is specified, then the default is all possible combinations
of the fixed factors.  That is to say
@display
GLM subject BY sex age_group race
@end display
implies the model
@math{subject = age_group + sex + race + age_group*sex + age_group*race + sex*race + age_group*sex*race}.


The @subcmd{MISSING} subcommand determines the handling of missing
variables.
If @subcmd{INCLUDE} is set then, for the purposes of GLM analysis,
only system-missing values are considered
to be missing; user-missing values are not regarded as missing.
If @subcmd{EXCLUDE} is set, which is the default, then user-missing
values are considered to be missing as well as system-missing values.
A case for which any dependent variable or any factor
variable has a missing value is excluded from the analysis.

@node LOGISTIC REGRESSION
@section LOGISTIC REGRESSION

@vindex LOGISTIC REGRESSION
@cindex logistic regression
@cindex bivariate logistic regression

@display
LOGISTIC REGRESSION [VARIABLES =] @var{dependent_var} WITH @var{predictors}

     [/CATEGORICAL = @var{categorical_predictors}]

     [@{/NOCONST | /ORIGIN | /NOORIGIN @}]

     [/PRINT = [SUMMARY] [DEFAULT] [CI(@var{confidence})] [ALL]]

     [/CRITERIA = [BCON(@var{min_delta})] [ITERATE(@var{max_interations})]
                  [LCON(@var{min_likelihood_delta})] [EPS(@var{min_epsilon})]
                  [CUT(@var{cut_point})]]

     [/MISSING = @{INCLUDE|EXCLUDE@}]
@end display

Bivariate Logistic Regression is used when you want to explain a dichotomous dependent
variable in terms of one or more predictor variables.

The minimum command is
@example
LOGISTIC REGRESSION @var{y} WITH @var{x1} @var{x2} @dots{} @var{xn}.
@end example
Here, @var{y} is the dependent variable, which must be dichotomous and @var{x1} @dots{} @var{xn}
are the predictor variables whose coefficients the procedure estimates.

By default, a constant term is included in the model.
Hence, the full model is
@math{
{\bf y}
= b_0 + b_1 {\bf x_1}
+ b_2 {\bf x_2}
+ \dots
+ b_n {\bf x_n}
}

Predictor variables which are categorical in nature should be listed on the @subcmd{/CATEGORICAL} subcommand.
Simple variables as well as interactions between variables may be listed here.

If you want a model without the constant term @math{b_0}, use the keyword @subcmd{/ORIGIN}.
@subcmd{/NOCONST} is a synonym for @subcmd{/ORIGIN}.

An iterative Newton-Raphson procedure is used to fit the model.
The @subcmd{/CRITERIA} subcommand is used to specify the stopping criteria of the procedure,
and other parameters.
The value of @var{cut_point} is used in the classification table.  It is the
threshold above which predicted values are considered to be 1.  Values
of @var{cut_point} must lie in the range [0,1].
During iterations, if any one of the stopping criteria are satisfied, the procedure is
considered complete.
The stopping criteria are:
@itemize
@item The number of iterations exceeds @var{max_iterations}.
      The default value of @var{max_iterations} is 20.
@item The change in the all coefficient estimates are less than @var{min_delta}.
The default value of @var{min_delta} is 0.001.
@item The magnitude of change in the likelihood estimate is less than @var{min_likelihood_delta}.
The default value of @var{min_delta} is zero.
This means that this criterion is disabled.
@item The differential of the estimated probability for all cases is less than @var{min_epsilon}.
In other words, the probabilities are close to zero or one.
The default value of @var{min_epsilon} is 0.00000001.
@end itemize


The @subcmd{PRINT} subcommand controls the display of optional statistics.
Currently there is one such option, @subcmd{CI}, which indicates that the
confidence interval of the odds ratio should be displayed as well as its value.
@subcmd{CI} should be followed by an integer in parentheses, to indicate the
confidence level of the desired confidence interval.

The @subcmd{MISSING} subcommand determines the handling of missing
variables.
If @subcmd{INCLUDE} is set, then user-missing values are included in the
calculations, but system-missing values are not.
If @subcmd{EXCLUDE} is set, which is the default, user-missing
values are excluded as well as system-missing values.
This is the default.

@node MEANS
@section MEANS

@vindex MEANS
@cindex means

@display
MEANS [TABLES =]
      @{@var{var_list}@}
        [ BY @{@var{var_list}@} [BY @{@var{var_list}@} [BY @{@var{var_list}@} @dots{} ]]]

      [ /@{@var{var_list}@}
         [ BY @{@var{var_list}@} [BY @{@var{var_list}@} [BY @{@var{var_list}@} @dots{} ]]] ]

      [/CELLS = [MEAN] [COUNT] [STDDEV] [SEMEAN] [SUM] [MIN] [MAX] [RANGE]
        [VARIANCE] [KURT] [SEKURT]
        [SKEW] [SESKEW] [FIRST] [LAST]
        [HARMONIC] [GEOMETRIC]
        [DEFAULT]
        [ALL]
        [NONE] ]

      [/MISSING = [INCLUDE] [DEPENDENT]]
@end display

You can use the @cmd{MEANS} command to calculate the arithmetic mean and similar
statistics, either for the dataset as a whole or for categories of data.

The simplest form of the command is
@example
MEANS @var{v}.
@end example
@noindent which calculates the mean, count and standard deviation for @var{v}.
If you specify a grouping variable, for example
@example
MEANS @var{v} BY @var{g}.
@end example
@noindent then the means, counts and standard deviations for @var{v} after having
been grouped by @var{g} are calculated.
Instead of the mean, count and standard deviation, you could specify the statistics
in which you are interested:
@example
MEANS @var{x} @var{y} BY @var{g}
      /CELLS = HARMONIC SUM MIN.
@end example
This example calculates the harmonic mean, the sum and the minimum values of @var{x} and @var{y}
grouped by @var{g}.

The @subcmd{CELLS} subcommand specifies which statistics to calculate.  The available statistics
are:
@itemize
@item @subcmd{MEAN}
@cindex arithmetic mean
      The arithmetic mean.
@item @subcmd{COUNT}
      The count of the values.
@item @subcmd{STDDEV}
      The standard deviation.
@item @subcmd{SEMEAN}
      The standard error of the mean.
@item @subcmd{SUM}
      The sum of the values.
@item @subcmd{MIN}
      The minimum value.
@item @subcmd{MAX}
      The maximum value.
@item @subcmd{RANGE}
      The difference between the maximum and minimum values.
@item @subcmd{VARIANCE}
      The variance.
@item @subcmd{FIRST}
      The first value in the category.
@item @subcmd{LAST}
      The last value in the category.
@item @subcmd{SKEW}
      The skewness.
@item @subcmd{SESKEW}
      The standard error of the skewness.
@item @subcmd{KURT}
      The kurtosis
@item @subcmd{SEKURT}
      The standard error of the kurtosis.
@item @subcmd{HARMONIC}
@cindex harmonic mean
      The harmonic mean.
@item @subcmd{GEOMETRIC}
@cindex geometric mean
      The geometric mean.
@end itemize

In addition, three special keywords are recognized:
@itemize
@item @subcmd{DEFAULT}
      This is the same as @subcmd{MEAN} @subcmd{COUNT} @subcmd{STDDEV}.
@item @subcmd{ALL}
      All of the above statistics are calculated.
@item @subcmd{NONE}
      No statistics are calculated (only a summary is shown).
@end itemize


More than one @dfn{table} can be specified in a single command.
Each table is separated by a @samp{/}. For
example
@example
MEANS TABLES =
      @var{c} @var{d} @var{e} BY @var{x}
      /@var{a} @var{b} BY @var{x} @var{y}
      /@var{f} BY @var{y} BY @var{z}.
@end example
has three tables (the @samp{TABLE =} is optional).
The first table has three dependent variables @var{c}, @var{d} and @var{e}
and a single categorical variable @var{x}.
The second table has two dependent variables @var{a} and @var{b},
and two categorical variables @var{x} and @var{y}.
The third table has a single dependent variables @var{f}
and a categorical variable formed by the combination of @var{y} and @var{z}.


By default values are omitted from the analysis only if missing values
(either system missing or user missing)
for any of the variables directly involved in their calculation are
encountered.
This behaviour can be modified with the  @subcmd{/MISSING} subcommand.
Three options are possible: @subcmd{TABLE}, @subcmd{INCLUDE} and @subcmd{DEPENDENT}.

@subcmd{/MISSING = INCLUDE} says that user missing values, either in the dependent
variables or in the categorical variables should be taken at their face
value, and not excluded.

@subcmd{/MISSING = DEPENDENT} says that user missing values, in the dependent
variables should be taken at their face value, however cases which
have user missing values for the categorical variables should be omitted
from the calculation.

@subsection Example Means

The dataset in @file{repairs.sav} contains the mean time between failures (@exvar{mtbf})
for a sample of artifacts produced by different factories and trialed under
different operating conditions.
Since there are four combinations of categorical variables, by simply looking
at the list of data, it would be hard to how the scores vary for each category.
@ref{means:ex} shows one way of tabulating the @exvar{mtbf} in a way which is
easier to understand.

@float Example, means:ex
@psppsyntax {means.sps}
@caption {Running @cmd{MEANS} on the @exvar{mtbf} score with categories @exvar{factory} and @exvar{environment}}
@end float

The results are shown in @ref{means:res}.   The figures shown indicate the mean,
standard deviation and number of samples in each category.
These figures however do not indicate whether the results are statistically
significant.  For that, you would need to use the procedures @cmd{ONEWAY}, @cmd{GLM} or
@cmd{T-TEST} depending on the hypothesis being tested.

@float Result, means:res
@psppoutput {means}
@caption {The @exvar{mtbf} categorised by @exvar{factory} and @exvar{environment}}
@end float

Note that there is no limit to the number of variables for which you can calculate
statistics, nor to the number of categorical variables per layer, nor the number
of layers.
However, running @cmd{MEANS} on a large numbers of variables, or with categorical variables
containing a large number of distinct values may result in an extremely large output, which
will not be easy to interpret.
So you should consider carefully which variables to select for participation in the analysis.

@node NPAR TESTS
@section NPAR TESTS

@vindex NPAR TESTS
@cindex nonparametric tests

@display
NPAR TESTS

     nonparametric test subcommands
     .
     .
     .

     [ /STATISTICS=@{DESCRIPTIVES@} ]

     [ /MISSING=@{ANALYSIS, LISTWISE@} @{INCLUDE, EXCLUDE@} ]

     [ /METHOD=EXACT [ TIMER [(@var{n})] ] ]
@end display

@cmd{NPAR TESTS} performs nonparametric tests.
Non parametric tests make very few assumptions about the distribution of the
data.
One or more tests may be specified by using the corresponding subcommand.
If the @subcmd{/STATISTICS} subcommand is also specified, then summary statistics are
produces for each variable that is the subject of any test.

Certain tests may take a long time to execute, if an exact figure is required.
Therefore, by default asymptotic approximations are used unless the
subcommand @subcmd{/METHOD=EXACT} is specified.
Exact tests give more accurate results, but may take an unacceptably long
time to perform.  If the @subcmd{TIMER} keyword is used, it sets a maximum time,
after which the test is abandoned, and a warning message printed.
The time, in minutes, should be specified in parentheses after the @subcmd{TIMER} keyword.
If the @subcmd{TIMER} keyword is given without this figure, then a default value of 5 minutes
is used.


@menu
* BINOMIAL::                Binomial Test
* CHISQUARE::               Chi-square Test
* COCHRAN::                 Cochran Q Test
* FRIEDMAN::                Friedman Test
* KENDALL::                 Kendall's W Test
* KOLMOGOROV-SMIRNOV::      Kolmogorov Smirnov Test
* KRUSKAL-WALLIS::          Kruskal-Wallis Test
* MANN-WHITNEY::            Mann Whitney U Test
* MCNEMAR::                 McNemar Test
* MEDIAN::                  Median Test
* RUNS::                    Runs Test
* SIGN::                    The Sign Test
* WILCOXON::                Wilcoxon Signed Ranks Test
@end menu


@node    BINOMIAL
@subsection Binomial test
@vindex BINOMIAL
@cindex binomial test

@display
     [ /BINOMIAL[(@var{p})]=@var{var_list}[(@var{value1}[, @var{value2})] ] ]
@end display

The @subcmd{/BINOMIAL} subcommand compares the observed distribution of a dichotomous
variable with that of a binomial distribution.
The variable @var{p} specifies the test proportion of the binomial
distribution.
The default value of 0.5 is assumed if @var{p} is omitted.

If a single value appears after the variable list, then that value is
used as the threshold to partition the observed values. Values less
than or equal to the threshold value form the first category.  Values
greater than the threshold form the second category.

If two values appear after the variable list, then they are used
as the values which a variable must take to be in the respective
category.
Cases for which a variable takes a value equal to neither of the specified
values, take no part in the test for that variable.

If no values appear, then the variable must assume dichotomous
values.
If more than two distinct, non-missing values for a variable
under test are encountered then an error occurs.

If the test proportion is equal to 0.5, then a two tailed test is
reported.   For any other test proportion, a one tailed test is
reported.
For one tailed tests, if the test proportion is less than
or equal to the observed proportion, then the significance of
observing the observed proportion or more is reported.
If the test proportion is more than the observed proportion, then the
significance of observing the observed proportion or less is reported.
That is to say, the test is always performed in the observed
direction.

@pspp{} uses a very precise approximation to the gamma function to
compute the binomial significance.  Thus, exact results are reported
even for very large sample sizes.


@node    CHISQUARE
@subsection Chi-square Test
@vindex CHISQUARE
@cindex chi-square test


@display
     [ /CHISQUARE=@var{var_list}[(@var{lo},@var{hi})] [/EXPECTED=@{EQUAL|@var{f1}, @var{f2} @dots{} @var{fn}@}] ]
@end display


The @subcmd{/CHISQUARE} subcommand produces a chi-square statistic for the differences
between the expected and observed frequencies of the categories of a variable.
Optionally, a range of values may appear after the variable list.
If a range is given, then non integer values are truncated, and values
outside the  specified range are excluded from the analysis.

The @subcmd{/EXPECTED} subcommand specifies the expected values of each
category.
There must be exactly one non-zero expected value, for each observed
category, or the @subcmd{EQUAL} keyword must be specified.
You may use the notation @subcmd{@var{n}*@var{f}} to specify @var{n}
consecutive expected categories all taking a frequency of @var{f}.
The frequencies given are proportions, not absolute frequencies.  The
sum of the frequencies need not be 1.
If no @subcmd{/EXPECTED} subcommand is given, then equal frequencies
are expected.

@subsubsection Chi-square Example

A researcher wishes to investigate whether there are an equal number of
persons of each sex in a population.   The sample chosen for invesigation
is that from the @file {physiology.sav} dataset.   The null hypothesis for
the test is that the population comprises an equal number of males and females.
The analysis is performed as shown in @ref{chisquare:ex}.

@float Example, chisquare:ex
@psppsyntax {chisquare.sps}
@caption {Performing a chi-square test to check for equal distribution of sexes}
@end float

There is only one test variable, @i{viz:} @exvar{sex}.  The other variables in the dataset
are ignored.

@float Screenshot, chisquare:scr
@psppimage {chisquare}
@caption {Performing a chi-square test using the graphic user interface}
@end float

In @ref{chisquare:res} the summary box shows that in the sample, there are more males
than females.  However the significance of chi-square result is greater than 0.05
--- the most commonly accepted p-value --- and therefore
there is not enough evidence to reject the null hypothesis and one must conclude
that the evidence does not indicate that there is an imbalance of the sexes
in the population.

@float Result, chisquare:res
@psppoutput {chisquare}
@caption {The results of running a chi-square test on @exvar{sex}}
@end float


@node COCHRAN
@subsection Cochran Q Test
@vindex Cochran
@cindex Cochran Q test
@cindex Q, Cochran Q

@display
     [ /COCHRAN = @var{var_list} ]
@end display

The Cochran Q test is used to test for differences between three or more groups.
The data for @var{var_list} in all cases must assume exactly two
distinct values (other than missing values).

The value of Q is displayed along with its Asymptotic significance
based on a chi-square distribution.

@node FRIEDMAN
@subsection Friedman Test
@vindex FRIEDMAN
@cindex Friedman test

@display
     [ /FRIEDMAN = @var{var_list} ]
@end display

The Friedman test is used to test for differences between repeated measures when
there is no indication that the distributions are normally distributed.

A list of variables which contain the measured data must be given.  The procedure
prints the sum of ranks for each variable, the test statistic and its significance.

@node KENDALL
@subsection Kendall's W Test
@vindex KENDALL
@cindex Kendall's W test
@cindex coefficient of concordance

@display
     [ /KENDALL = @var{var_list} ]
@end display

The Kendall test investigates whether an arbitrary number of related samples come from the
same population.
It is identical to the Friedman test except that the additional statistic W, Kendall's Coefficient of Concordance is printed.
It has the range [0,1] --- a value of zero indicates no agreement between the samples whereas a value of
unity indicates complete agreement.


@node KOLMOGOROV-SMIRNOV
@subsection Kolmogorov-Smirnov Test
@vindex KOLMOGOROV-SMIRNOV
@vindex K-S
@cindex Kolmogorov-Smirnov test

@display
     [ /KOLMOGOROV-SMIRNOV (@{NORMAL [@var{mu}, @var{sigma}], UNIFORM [@var{min}, @var{max}], POISSON [@var{lambda}], EXPONENTIAL [@var{scale}] @}) = @var{var_list} ]
@end display

The one sample Kolmogorov-Smirnov subcommand is used to test whether or not a dataset is
drawn from a particular distribution.  Four distributions are supported, @i{viz:}
Normal, Uniform, Poisson and Exponential.

Ideally you should provide the parameters of the distribution against
which you wish to test the data. For example, with the normal
distribution  the mean (@var{mu})and standard deviation (@var{sigma})
should be given; with the uniform distribution, the minimum
(@var{min})and maximum (@var{max}) value should be provided.
However, if the parameters are omitted they are imputed from the
data.  Imputing the parameters reduces the power of the test so should
be avoided if possible.

In the following example, two variables @var{score} and @var{age} are
tested to see if they follow a normal distribution with a mean of 3.5
and a standard deviation of 2.0.
@example
  NPAR TESTS
        /KOLMOGOROV-SMIRNOV (normal 3.5 2.0) = @var{score} @var{age}.
@end example
If the variables need to be tested against different distributions, then a separate
subcommand must be used.  For example the following syntax tests @var{score} against
a normal distribution with mean of 3.5 and standard deviation of 2.0 whilst @var{age}
is tested against a normal distribution of mean 40 and standard deviation 1.5.
@example
  NPAR TESTS
        /KOLMOGOROV-SMIRNOV (normal 3.5 2.0) = @var{score}
        /KOLMOGOROV-SMIRNOV (normal 40 1.5) =  @var{age}.
@end example

The abbreviated subcommand  @subcmd{K-S} may be used in place of @subcmd{KOLMOGOROV-SMIRNOV}.

@node KRUSKAL-WALLIS
@subsection Kruskal-Wallis Test
@vindex KRUSKAL-WALLIS
@vindex K-W
@cindex Kruskal-Wallis test

@display
     [ /KRUSKAL-WALLIS = @var{var_list} BY var (@var{lower}, @var{upper}) ]
@end display

The Kruskal-Wallis test is used to compare data from an
arbitrary number of populations.  It does not assume normality.
The data to be compared are specified by @var{var_list}.
The categorical variable determining the groups to which the
data belongs is given by @var{var}. The limits @var{lower} and
@var{upper} specify the valid range of @var{var}.
If @var{upper} is smaller than @var{lower}, the PSPP will assume their values
to be reversed. Any cases for which @var{var} falls outside
[@var{lower}, @var{upper}] are ignored.

The mean rank of each group as well as the chi-squared value and
significance of the test are printed.
The abbreviated subcommand  @subcmd{K-W} may be used in place of
@subcmd{KRUSKAL-WALLIS}.


@node MANN-WHITNEY
@subsection Mann-Whitney U Test
@vindex MANN-WHITNEY
@vindex M-W
@cindex Mann-Whitney U test
@cindex U, Mann-Whitney U

@display
     [ /MANN-WHITNEY = @var{var_list} BY var (@var{group1}, @var{group2}) ]
@end display

The Mann-Whitney subcommand is used to test whether two groups of data
come from different populations. The variables to be tested should be
specified in @var{var_list} and the grouping variable, that determines
to which group the test variables belong, in @var{var}.
@var{Var} may be either a string or an alpha variable.
@var{Group1} and @var{group2} specify the
two values of @var{var} which determine the groups of the test data.
Cases for which the @var{var} value is neither @var{group1} or
@var{group2} are ignored.

The value of the Mann-Whitney U statistic, the Wilcoxon W, and the
significance are printed.
You may abbreviated the subcommand @subcmd{MANN-WHITNEY} to
@subcmd{M-W}.


@node MCNEMAR
@subsection McNemar Test
@vindex MCNEMAR
@cindex McNemar test

@display
     [ /MCNEMAR @var{var_list} [ WITH @var{var_list} [ (PAIRED) ]]]
@end display

Use McNemar's test to analyse the significance of the difference between
pairs of correlated proportions.

If the @code{WITH} keyword is omitted, then tests for all
combinations of the listed variables are performed.
If the @code{WITH} keyword is given, and the @code{(PAIRED)} keyword
is also given, then the number of variables preceding @code{WITH}
must be the same as the number following it.
In this case, tests for each respective pair of variables are
performed.
If the @code{WITH} keyword is given, but the
@code{(PAIRED)} keyword is omitted, then tests for each combination
of variable preceding @code{WITH} against variable following
@code{WITH} are performed.

The data in each variable must be dichotomous.  If there are more
than two distinct variables an error will occur and the test will
not be run.

@node MEDIAN
@subsection Median Test
@vindex MEDIAN
@cindex Median test

@display
     [ /MEDIAN [(@var{value})] = @var{var_list} BY @var{variable} (@var{value1}, @var{value2}) ]
@end display

The median test is used to test whether independent samples come from
populations with a common median.
The median of the populations against which the samples are to be tested
may be given in parentheses immediately after the
@subcmd{/MEDIAN} subcommand.  If it is not given, the median is imputed from the
union of all the samples.

The variables of the samples to be tested should immediately follow the @samp{=} sign. The
keyword @code{BY} must come next, and then the grouping variable.  Two values
in parentheses should follow.  If the first value is greater than the second,
then a 2 sample test is performed using these two values to determine the groups.
If however, the first variable is less than the second, then a @i{k} sample test is
conducted and the group values used are all values encountered which lie in the
range [@var{value1},@var{value2}].


@node RUNS
@subsection Runs Test
@vindex RUNS
@cindex runs test

@display
     [ /RUNS (@{MEAN, MEDIAN, MODE, @var{value}@})  = @var{var_list} ]
@end display

The @subcmd{/RUNS} subcommand tests whether a data sequence is randomly ordered.

It works by examining the number of times a variable's value crosses a given threshold.
The desired threshold must be specified within parentheses.
It may either be specified as a number or as one of @subcmd{MEAN}, @subcmd{MEDIAN} or @subcmd{MODE}.
Following the threshold specification comes the list of variables whose values are to be
tested.

The subcommand shows the number of runs, the asymptotic significance based on the
length of the data.

@node SIGN
@subsection Sign Test
@vindex SIGN
@cindex sign test

@display
     [ /SIGN @var{var_list} [ WITH @var{var_list} [ (PAIRED) ]]]
@end display

The @subcmd{/SIGN} subcommand tests for differences between medians of the
variables listed.
The test does not make any assumptions about the
distribution of the data.

If the @code{WITH} keyword is omitted, then tests for all
combinations of the listed variables are performed.
If the @code{WITH} keyword is given, and the @code{(PAIRED)} keyword
is also given, then the number of variables preceding @code{WITH}
must be the same as the number following it.
In this case, tests for each respective pair of variables are
performed.
If the @code{WITH} keyword is given, but the
@code{(PAIRED)} keyword is omitted, then tests for each combination
of variable preceding @code{WITH} against variable following
@code{WITH} are performed.

@node WILCOXON
@subsection Wilcoxon Matched Pairs Signed Ranks Test
@vindex WILCOXON
@cindex wilcoxon matched pairs signed ranks test

@display
     [ /WILCOXON @var{var_list} [ WITH @var{var_list} [ (PAIRED) ]]]
@end display

The @subcmd{/WILCOXON} subcommand tests for differences between medians of the
variables listed.
The test does not make any assumptions about the variances of the samples.
It does however assume that the distribution is symmetrical.

If the @subcmd{WITH} keyword is omitted, then tests for all
combinations of the listed variables are performed.
If the @subcmd{WITH} keyword is given, and the @subcmd{(PAIRED)} keyword
is also given, then the number of variables preceding @subcmd{WITH}
must be the same as the number following it.
In this case, tests for each respective pair of variables are
performed.
If the @subcmd{WITH} keyword is given, but the
@subcmd{(PAIRED)} keyword is omitted, then tests for each combination
of variable preceding @subcmd{WITH} against variable following
@subcmd{WITH} are performed.

@node T-TEST
@section T-TEST

@vindex T-TEST

@display
T-TEST
        /MISSING=@{ANALYSIS,LISTWISE@} @{EXCLUDE,INCLUDE@}
        /CRITERIA=CI(@var{confidence})


(One Sample mode.)
        TESTVAL=@var{test_value}
        /VARIABLES=@var{var_list}


(Independent Samples mode.)
        GROUPS=var(@var{value1} [, @var{value2}])
        /VARIABLES=@var{var_list}


(Paired Samples mode.)
        PAIRS=@var{var_list} [WITH @var{var_list} [(PAIRED)] ]

@end display


The @cmd{T-TEST} procedure outputs tables used in testing hypotheses about
means.
It operates in one of three modes:
@itemize
@item One Sample mode.
@item Independent Groups mode.
@item Paired mode.
@end itemize

@noindent
Each of these modes are described in more detail below.
There are two optional subcommands which are common to all modes.

The @cmd{/CRITERIA} subcommand tells @pspp{} the confidence interval used
in the tests.  The default value is 0.95.


The @cmd{MISSING} subcommand determines the handling of missing
variables.
If @subcmd{INCLUDE} is set, then user-missing values are included in the
calculations, but system-missing values are not.
If @subcmd{EXCLUDE} is set, which is the default, user-missing
values are excluded as well as system-missing values.
This is the default.

If @subcmd{LISTWISE} is set, then the entire case is excluded from analysis
whenever any variable  specified in the @subcmd{/VARIABLES}, @subcmd{/PAIRS} or
@subcmd{/GROUPS} subcommands contains a missing value.
If @subcmd{ANALYSIS} is set, then missing values are excluded only in the analysis for
which they would be needed. This is the default.


@menu
* One Sample Mode::             Testing against a hypothesized mean
* Independent Samples Mode::    Testing two independent groups for equal mean
* Paired Samples Mode::         Testing two interdependent groups for equal mean
@end menu

@node One Sample Mode
@subsection One Sample Mode

The @subcmd{TESTVAL} subcommand invokes the One Sample mode.
This mode is used to test a population mean against a hypothesized
mean.
The value given to the @subcmd{TESTVAL} subcommand is the value against
which you wish to test.
In this mode, you must also use the @subcmd{/VARIABLES} subcommand to
tell @pspp{} which variables you wish to test.

@subsubsection Example - One Sample T-test

A researcher wishes to know whether the weight of persons in a population
is different from the national average.
The samples are drawn from the population under investigation and recorded
in the file @file{physiology.sav}.
From the Department of Health, she
knows that the national average weight of healthy adults is 76.8kg.
Accordingly the @subcmd{TESTVAL} is set to 76.8.
The null hypothesis therefore is that the mean average weight of the
population from which the sample was drawn is 76.8kg.

As previously noted (@pxref{Identifying incorrect data}), one
sample in the dataset contains a weight value
which is clearly incorrect.  So this is excluded from the analysis
using the @cmd{SELECT} command.

@float Example, one-sample-t:ex
@psppsyntax {one-sample-t.sps}
@caption {Running a one sample T-Test after excluding all non-positive values}
@end float

@float Screenshot, one-sample-t:scr
@psppimage {one-sample-t}
@caption {Using the One Sample T-Test dialog box to test @exvar{weight} for a mean of 76.8kg}
@end float


@ref{one-sample-t:res} shows that the mean of our sample differs from the test value
by -1.40kg.  However the significance is very high (0.610).  So one cannot
reject the null hypothesis, and must conclude there is not enough evidence
to suggest that the mean weight of the persons in our population is different
from 76.8kg.

@float Results, one-sample-t:res
@psppoutput {one-sample-t}
@caption {The results of a one sample T-test of @exvar{weight} using a test value of 76.8kg}
@end float

@node Independent Samples Mode
@subsection Independent Samples Mode

The @subcmd{GROUPS} subcommand invokes Independent Samples mode or
`Groups' mode.
This mode is used to test whether two groups of values have the
same population mean.
In this mode, you must also use the @subcmd{/VARIABLES} subcommand to
tell @pspp{} the dependent variables you wish to test.

The variable given in the @subcmd{GROUPS} subcommand is the independent
variable which determines to which group the samples belong.
The values in parentheses are the specific values of the independent
variable for each group.
If the parentheses are omitted and no values are given, the default values
of 1.0 and 2.0 are assumed.

If the independent variable is numeric,
it is acceptable to specify only one value inside the parentheses.
If you do this, cases where the independent variable is
greater than or equal to this value belong to the first group, and cases
less than this value belong to the second group.
When using this form of the @subcmd{GROUPS} subcommand, missing values in
the independent variable are excluded on a listwise basis, regardless
of whether @subcmd{/MISSING=LISTWISE} was specified.

@subsubsection Example - Independent Samples T-test

A researcher wishes to know whether within a population, adult males
are taller than adult females.
The samples are drawn from the population under investigation and recorded
in the file @file{physiology.sav}.

As previously noted (@pxref{Identifying incorrect data}), one
sample in the dataset contains a height value
which is clearly incorrect.  So this is excluded from the analysis
using the @cmd{SELECT} command.


@float Example, indepdendent-samples-t:ex
@psppsyntax {independent-samples-t.sps}
@caption {Running a independent samples T-Test after excluding all observations less than 200kg}
@end float


The null hypothesis is that both males and females are on average
of equal height.

@float Screenshot, independent-samples-t:scr
@psppimage {independent-samples-t}
@caption {Using the Independent Sample T-test dialog, to test for differences of @exvar{height} between values of @exvar{sex}}
@end float


In this case, the grouping variable is @exvar{sex}, so this is entered
as the variable for the @subcmd{GROUP} subcommand.  The group values are  0 (male) and
1 (female).

If you are running the proceedure using syntax, then you need to enter
the values corresponding to each group within parentheses.
If you are using the graphic user interface, then you have to open
the ``Define Groups'' dialog box and enter the values corresponding
to each group as shown in @ref{define-groups-t:scr}.  If, as in this case, the dataset has defined value
labels for the group variable, then you can enter them by label
or by value.

@float Screenshot, define-groups-t:scr
@psppimage {define-groups-t}
@caption {Setting the values of the grouping variable for an Independent Samples T-test}
@end float

From @ref{independent-samples-t:res}, one can clearly see that the @emph{sample} mean height
is greater for males than for females.  However in order to see if this
is a significant result, one must consult the T-Test table.

The T-Test table contains two rows; one for use if the variance of the samples
in each group may be safely assumed to be equal, and the second row
if the variances in each group may not be safely assumed to be equal.

In this case however, both rows show a 2-tailed significance less than 0.001 and
one must therefore reject the null hypothesis and conclude that within
the population the mean height of males and of females are unequal.

@float Result, independent-samples-t:res
@psppoutput {independent-samples-t}
@caption {The results of an independent samples T-test of @exvar{height} by @exvar{sex}}
@end float

@node Paired Samples Mode
@subsection Paired Samples Mode

The @cmd{PAIRS} subcommand introduces Paired Samples mode.
Use this mode when repeated measures have been taken from the same
samples.
If the @subcmd{WITH} keyword is omitted, then tables for all
combinations of variables given in the @cmd{PAIRS} subcommand are
generated.
If the @subcmd{WITH} keyword is given, and the @subcmd{(PAIRED)} keyword
is also given, then the number of variables preceding @subcmd{WITH}
must be the same as the number following it.
In this case, tables for each respective pair of variables are
generated.
In the event that the @subcmd{WITH} keyword is given, but the
@subcmd{(PAIRED)} keyword is omitted, then tables for each combination
of variable preceding @subcmd{WITH} against variable following
@subcmd{WITH} are generated.


@node ONEWAY
@section ONEWAY

@vindex ONEWAY
@cindex analysis of variance
@cindex ANOVA

@display
ONEWAY
        [/VARIABLES = ] @var{var_list} BY @var{var}
        /MISSING=@{ANALYSIS,LISTWISE@} @{EXCLUDE,INCLUDE@}
        /CONTRAST= @var{value1} [, @var{value2}] ... [,@var{valueN}]
        /STATISTICS=@{DESCRIPTIVES,HOMOGENEITY@}
        /POSTHOC=@{BONFERRONI, GH, LSD, SCHEFFE, SIDAK, TUKEY, ALPHA ([@var{value}])@}
@end display

The @cmd{ONEWAY} procedure performs a one-way analysis of variance of
variables factored by a single independent variable.
It is used to compare the means of a population
divided into more than two groups.

The dependent variables to be analysed should be given in the @subcmd{VARIABLES}
subcommand.
The list of variables must be followed by the @subcmd{BY} keyword and
the name of the independent (or factor) variable.

You can use the @subcmd{STATISTICS} subcommand to tell @pspp{} to display
ancillary information.  The options accepted are:
@itemize
@item DESCRIPTIVES
Displays descriptive statistics about the groups factored by the independent
variable.
@item HOMOGENEITY
Displays the Levene test of Homogeneity of Variance for the
variables and their groups.
@end itemize

The @subcmd{CONTRAST} subcommand is used when you anticipate certain
differences between the groups.
The subcommand must be followed by a list of numerals which are the
coefficients of the groups to be tested.
The number of coefficients must correspond to the number of distinct
groups (or values of the independent variable).
If the total sum of the coefficients are not zero, then @pspp{} will
display a warning, but will proceed with the analysis.
The @subcmd{CONTRAST} subcommand may be given up to 10 times in order
to specify different contrast tests.
The @subcmd{MISSING} subcommand defines how missing values are handled.
If @subcmd{LISTWISE} is specified then cases which have missing values for
the independent variable or any dependent variable are ignored.
If @subcmd{ANALYSIS} is specified, then cases are ignored if the independent
variable is missing or if the dependent variable currently being
analysed is missing.  The default is @subcmd{ANALYSIS}.
A setting of @subcmd{EXCLUDE} means that variables whose values are
user-missing are to be excluded from the analysis. A setting of
@subcmd{INCLUDE} means they are to be included.  The default is @subcmd{EXCLUDE}.

Using the @code{POSTHOC} subcommand you can perform multiple
pairwise comparisons on the data. The following comparison methods
are available:
@itemize
@item @subcmd{LSD}
Least Significant Difference.
@item @subcmd{TUKEY}
Tukey Honestly Significant Difference.
@item @subcmd{BONFERRONI}
Bonferroni test.
@item @subcmd{SCHEFFE}
Scheff@'e's test.
@item @subcmd{SIDAK}
Sidak test.
@item @subcmd{GH}
The Games-Howell test.
@end itemize

@noindent
Use the optional syntax @code{ALPHA(@var{value})} to indicate that
@cmd{ONEWAY} should perform the posthoc tests at a confidence level of
@var{value}.  If @code{ALPHA(@var{value})} is not specified, then the
confidence level used is 0.05.

@node QUICK CLUSTER
@section QUICK CLUSTER
@vindex QUICK CLUSTER

@cindex K-means clustering
@cindex clustering

@display
QUICK CLUSTER @var{var_list}
      [/CRITERIA=CLUSTERS(@var{k}) [MXITER(@var{max_iter})] CONVERGE(@var{epsilon}) [NOINITIAL]]
      [/MISSING=@{EXCLUDE,INCLUDE@} @{LISTWISE, PAIRWISE@}]
      [/PRINT=@{INITIAL@} @{CLUSTER@}]
      [/SAVE[=[CLUSTER[(@var{membership_var})]] [DISTANCE[(@var{distance_var})]]]
@end display

The @cmd{QUICK CLUSTER} command performs k-means clustering on the
dataset.  This is useful when you wish to allocate cases into clusters
of similar values and you already know the number of clusters.

The minimum specification is @samp{QUICK CLUSTER} followed by the names
of the variables which contain the cluster data.  Normally you will also
want to specify @subcmd{/CRITERIA=CLUSTERS(@var{k})} where @var{k} is the
number of clusters.  If this is not specified, then @var{k} defaults to 2.

If you use @subcmd{/CRITERIA=NOINITIAL} then a naive algorithm to select
the initial clusters is used.   This will provide for faster execution but
less well separated initial clusters and hence possibly an inferior final
result.


@cmd{QUICK CLUSTER} uses an iterative algorithm to select the clusters centers.
The subcommand  @subcmd{/CRITERIA=MXITER(@var{max_iter})} sets the maximum number of iterations.
During classification, @pspp{} will continue iterating until until @var{max_iter}
iterations have been done or the convergence criterion (see below) is fulfilled.
The default value of @var{max_iter} is 2.

If however, you specify @subcmd{/CRITERIA=NOUPDATE} then after selecting the initial centers,
no further update to the cluster centers is done.  In this case, @var{max_iter}, if specified.
is ignored.

The subcommand  @subcmd{/CRITERIA=CONVERGE(@var{epsilon})} is used
to set the convergence criterion.  The value of convergence criterion is  @var{epsilon}
times the minimum distance between the @emph{initial} cluster centers.  Iteration stops when
the  mean cluster distance between  one iteration and the next
is less than the convergence criterion.  The default value of @var{epsilon} is zero.

The @subcmd{MISSING} subcommand determines the handling of missing variables.
If @subcmd{INCLUDE} is set, then user-missing values are considered at their face
value and not as missing values.
If @subcmd{EXCLUDE} is set, which is the default, user-missing
values are excluded as well as system-missing values.

If @subcmd{LISTWISE} is set, then the entire case is excluded from the analysis
whenever any of the clustering variables contains a missing value.
If @subcmd{PAIRWISE} is set, then a case is considered missing only if all the
clustering variables contain missing values.  Otherwise it is clustered
on the basis of the non-missing values.
The default is @subcmd{LISTWISE}.

The @subcmd{PRINT} subcommand requests additional output to be printed.
If @subcmd{INITIAL} is set, then the initial cluster memberships will
be printed.
If @subcmd{CLUSTER} is set, the cluster memberships of the individual
cases are displayed (potentially generating lengthy output).

You can specify the subcommand @subcmd{SAVE} to ask that each case's cluster membership
and the euclidean distance between the case and its cluster center be saved to
a new variable in the active dataset.   To save the cluster membership use the
@subcmd{CLUSTER} keyword and to save the distance use the @subcmd{DISTANCE} keyword.
Each keyword may optionally be followed by a variable name in parentheses to specify
the new variable which is to contain the saved parameter.  If no variable name is specified,
then PSPP will create one.

@node RANK
@section RANK

@vindex RANK
@display
RANK
        [VARIABLES=] @var{var_list} [@{A,D@}] [BY @var{var_list}]
        /TIES=@{MEAN,LOW,HIGH,CONDENSE@}
        /FRACTION=@{BLOM,TUKEY,VW,RANKIT@}
        /PRINT[=@{YES,NO@}
        /MISSING=@{EXCLUDE,INCLUDE@}

        /RANK [INTO @var{var_list}]
        /NTILES(k) [INTO @var{var_list}]
        /NORMAL [INTO @var{var_list}]
        /PERCENT [INTO @var{var_list}]
        /RFRACTION [INTO @var{var_list}]
        /PROPORTION [INTO @var{var_list}]
        /N [INTO @var{var_list}]
        /SAVAGE [INTO @var{var_list}]
@end display

The @cmd{RANK} command ranks variables and stores the results into new
variables.

The @subcmd{VARIABLES} subcommand, which is mandatory, specifies one or
more variables whose values are to be ranked.
After each variable, @samp{A} or @samp{D} may appear, indicating that
the variable is to be ranked in ascending or descending order.
Ascending is the default.
If a @subcmd{BY} keyword appears, it should be followed by a list of variables
which are to serve as group variables.
In this case, the cases are gathered into groups, and ranks calculated
for each group.

The @subcmd{TIES} subcommand specifies how tied values are to be treated.  The
default is to take the mean value of all the tied cases.

The @subcmd{FRACTION} subcommand specifies how proportional ranks are to be
calculated.  This only has any effect if @subcmd{NORMAL} or @subcmd{PROPORTIONAL} rank
functions are requested.

The @subcmd{PRINT} subcommand may be used to specify that a summary of the rank
variables created should appear in the output.

The function subcommands are @subcmd{RANK}, @subcmd{NTILES}, @subcmd{NORMAL}, @subcmd{PERCENT}, @subcmd{RFRACTION},
@subcmd{PROPORTION} and @subcmd{SAVAGE}.  Any number of function subcommands may appear.
If none are given, then the default is RANK.
The @subcmd{NTILES} subcommand must take an integer specifying the number of
partitions into which values should be ranked.
Each subcommand may be followed by the @subcmd{INTO} keyword and a list of
variables which are the variables to be created and receive the rank
scores.  There may be as many variables specified as there are
variables named on the @subcmd{VARIABLES} subcommand.  If fewer are specified,
then the variable names are automatically created.

The @subcmd{MISSING} subcommand determines how user missing values are to be
treated. A setting of @subcmd{EXCLUDE} means that variables whose values are
user-missing are to be excluded from the rank scores. A setting of
@subcmd{INCLUDE} means they are to be included.  The default is @subcmd{EXCLUDE}.

@include regression.texi


@node RELIABILITY
@section RELIABILITY

@vindex RELIABILITY
@display
RELIABILITY
        /VARIABLES=@var{var_list}
        /SCALE (@var{name}) = @{@var{var_list}, ALL@}
        /MODEL=@{ALPHA, SPLIT[(@var{n})]@}
        /SUMMARY=@{TOTAL,ALL@}
        /MISSING=@{EXCLUDE,INCLUDE@}
@end display

@cindex Cronbach's Alpha
The @cmd{RELIABILITY} command performs reliability analysis on the data.

The @subcmd{VARIABLES} subcommand is required. It determines the set of variables
upon which analysis is to be performed.

The @subcmd{SCALE} subcommand determines the  variables for which
reliability is to be calculated.  If @subcmd{SCALE} is omitted, then analysis for
all variables named in the @subcmd{VARIABLES} subcommand are used.
Optionally, the @var{name} parameter may be specified to set a string name
for the scale.

The @subcmd{MODEL} subcommand determines the type of analysis. If @subcmd{ALPHA} is specified,
then Cronbach's Alpha is calculated for the scale.  If the model is @subcmd{SPLIT},
then the variables  are divided into 2 subsets.  An optional parameter
@var{n} may be given, to specify how many variables to be in the first subset.
If @var{n} is omitted, then it defaults to one half of the variables in the
scale, or one half minus one if there are an odd number of variables.
The default model is @subcmd{ALPHA}.

By default, any cases with user missing, or system missing values for
any variables given in the @subcmd{VARIABLES} subcommand are omitted
from the analysis.  The @subcmd{MISSING} subcommand determines whether
user missing values are included or excluded in the analysis.

The @subcmd{SUMMARY} subcommand determines the type of summary analysis to be performed.
Currently there is only one type: @subcmd{SUMMARY=TOTAL}, which displays per-item
analysis tested against the totals.

@subsection Example - Reliability

Before analysing the results of a survey -- particularly for a multiple choice survey --
it is desireable to know whether the respondents have considered their answers
or simply provided random answers.

In the following example the survey results from the file @file{hotel.sav} are used.
All five survey questions are included in the reliability analysis.
However, before running the analysis, the data must be preprocessed.
An examination of the survey questions reveals that two questions, @i{viz:} v3 and v5
are negatively worded, whereas the others are positively worded.
All questions must be based upon the same scale for the analysis to be meaningful.
One could use the @cmd{RECODE} command (@pxref{RECODE}), however a simpler way is
to use @cmd{COMPUTE} (@pxref{COMPUTE}) and this is what is done in @ref{reliability:ex}.

@float Example, reliability:ex
@psppsyntax {reliability.sps}
@caption {Investigating the reliability of survey responses}
@end float

In this case, all variables in the data set are used.  So we can use the special
keyword @samp{ALL} (@pxref{BNF}).

@float Screenshot, reliability:src
@psppimage {reliability}
@caption {Reliability dialog box with all variables selected}
@end float

@ref{reliability:res} shows that Cronbach's Alpha is 0.11  which is a value normally considered too
low to indicate consistency within the data.  This is possibly due to the small number of
survey questions.  The survey should be redesigned before serious use of the results are
applied.

@float Result, reliability:res
@psppoutput {reliability}
@caption {The results of the reliability command on @file{hotel.sav}}
@end float


@node ROC
@section ROC

@vindex ROC
@cindex Receiver Operating Characteristic
@cindex Area under curve

@display
ROC     @var{var_list} BY @var{state_var} (@var{state_value})
        /PLOT = @{ CURVE [(REFERENCE)], NONE @}
        /PRINT = [ SE ] [ COORDINATES ]
        /CRITERIA = [ CUTOFF(@{INCLUDE,EXCLUDE@}) ]
          [ TESTPOS (@{LARGE,SMALL@}) ]
          [ CI (@var{confidence}) ]
          [ DISTRIBUTION (@{FREE, NEGEXPO @}) ]
        /MISSING=@{EXCLUDE,INCLUDE@}
@end display


The @cmd{ROC} command is used to plot the receiver operating characteristic curve
of a dataset, and to estimate the area under the curve.
This is useful for analysing the efficacy of a variable as a predictor of a state of nature.

The mandatory @var{var_list} is the list of predictor variables.
The variable @var{state_var} is the variable whose values represent the actual states,
and @var{state_value} is the value of this variable which represents the positive state.

The optional subcommand @subcmd{PLOT} is used to determine if and how the @subcmd{ROC} curve is drawn.
The keyword @subcmd{CURVE} means that the @subcmd{ROC} curve should be drawn, and the optional keyword @subcmd{REFERENCE},
which should be enclosed in parentheses, says that the diagonal reference line should be drawn.
If the keyword @subcmd{NONE} is given, then no @subcmd{ROC} curve is drawn.
By default, the curve is drawn with no reference line.

The optional subcommand @subcmd{PRINT} determines which additional
tables should be printed.  Two additional tables are available.  The
@subcmd{SE} keyword says that standard error of the area under the
curve should be printed as well as the area itself.  In addition, a
p-value for the null hypothesis that the area under the curve equals
0.5 is printed.   The @subcmd{COORDINATES} keyword says that a
table of coordinates of the @subcmd{ROC} curve should be printed.

The @subcmd{CRITERIA} subcommand has four optional parameters:
@itemize @bullet
@item The @subcmd{TESTPOS} parameter may be @subcmd{LARGE} or @subcmd{SMALL}.
@subcmd{LARGE} is the default, and says that larger values in the predictor variables are to be
considered positive.  @subcmd{SMALL} indicates that smaller values should be considered positive.

@item The @subcmd{CI} parameter specifies the confidence interval that should be printed.
It has no effect if the @subcmd{SE} keyword in the @subcmd{PRINT} subcommand has not been given.

@item The @subcmd{DISTRIBUTION} parameter determines the method to be used when estimating the area
under the curve.
There are two possibilities, @i{viz}: @subcmd{FREE} and @subcmd{NEGEXPO}.
The @subcmd{FREE} method uses a non-parametric estimate, and the @subcmd{NEGEXPO} method a bi-negative
exponential distribution estimate.
The @subcmd{NEGEXPO} method should only be used when the number of positive actual states is
equal to the number of negative actual states.
The default is @subcmd{FREE}.

@item The @subcmd{CUTOFF} parameter is for compatibility and is ignored.
@end itemize

The @subcmd{MISSING} subcommand determines whether user missing values are to
be included or excluded in the analysis.  The default behaviour is to
exclude them.
Cases are excluded on a listwise basis; if any of the variables in @var{var_list}
or if the variable @var{state_var} is missing, then the entire case is
excluded.

@c  LocalWords:  subcmd subcommand