work on documentation

[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, FREQUENCIES, Statistics, Statistics
@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, EXAMINE, DESCRIPTIVES, Statistics
@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, GRAPH, FREQUENCIES, Statistics
@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, CORRELATIONS, EXAMINE, Statistics
@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, HISTOGRAM, GRAPH, GRAPH
@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, BAR CHART, SCATTERPLOT, GRAPH
@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,  , HISTOGRAM, GRAPH
@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, CROSSTABS, GRAPH, Statistics
@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, CTABLES, CORRELATIONS, Statistics
@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, FACTOR, CROSSTABS, Statistics
@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}@}
@t{/MRSETS COUNTDUPLICATES=}@{@t{YES} @math{|} @t{NO}@}
@t{/SMISSING} @{@t{VARIABLE} @math{|} @t{LISTWISE}@}
@t{/PCOMPUTE} @t{&}@i{category}@t{=EXPR(}@i{expression}@t{)}
@t{/PPROPERTIES} @t{&}@i{category}@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{/CRITERIA CILEVEL=}@i{percentage}
@t{/CATEGORIES} @t{VARIABLES=}@i{variables}
    @{@t{[}@i{value}@t{,} @i{value}@dots{}@t{]}
   @math{|} [@t{ORDER=}@{@t{A} @math{|} @t{D}@}]
     [@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{}]
@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 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}.

@menu
* CTABLES Basics::
* CTABLES Data Summarization::
@end menu

@node CTABLES Basics, CTABLES Data Summarization, CTABLES, CTABLES
@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.

@menu
* CTABLES Categorical Variable Basics::
* CTABLES Scalar Variable Basics::
* CTABLES Overriding Measurement Level::
* CTABLES Multiple Response Sets::
@end menu

@node CTABLES Categorical Variable Basics, CTABLES Scalar Variable Basics, CTABLES Basics, CTABLES 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:

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

@noindent
Specifying a row and a column categorical variable yields a
crosstabulation:

@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
If @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, CTABLES Overriding Measurement Level, CTABLES Categorical Variable Basics, CTABLES Basics
@subsubsection Scalar Variables

Categorical variables make @code{CTABLES} divide tables into cells.
With scalar variables, @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, CTABLES Multiple Response Sets, CTABLES Scalar Variable Basics, CTABLES Basics
@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.

Use the @code{VARIABLE LEVEL} command to change a variable's
measurement level.  To treat a variable as categorical or scalar only
for one use on @code{CTABLES}, add @samp{[C]} or @samp{[S]},
respectively, after the variable name.  The following example shows
how to analyze the scalar variable @code{qn20} as categorical:

@example
CTABLES /TABLE qn20 [C] BY qns3a.
@end example
@psppoutput {ctables9}

@node CTABLES Multiple Response Sets,  , CTABLES Overriding Measurement Level, CTABLES Basics
@subsubheading Multiple Response Sets

The @code{CTABLES} command does not yet support multiple response
sets.

@node CTABLES Data Summarization,  , CTABLES Basics, CTABLES
@subsection Data Summarization

The @code{CTABLES} command allows the user to control how the data are
summarized with summary specifications, which are enclosed in square
brackets following a variable name on the @code{TABLE} subcommand.
When all the variables are categorical, summary specifications can be
given for the innermost nested variables on any one axis.  When a
scalar variable is present, only the scalar variable may have summary
specifications.  The following example includes a summary
specification for column and row percentages for categorical
variables, and mean and median for a scalar variable:

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

Parentheses are 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.

@menu
* CTABLES Summary Functions for Categorical and Scale Variables::
@end menu

@node CTABLES Summary Functions for Categorical and Scale Variables,  , CTABLES Data Summarization, CTABLES Data Summarization
@subsubsection Summary Functions for Categorical and Scale Variables

This section lists the summary functions that can be applied to cells
in @code{CTABLES}.  Many of these functions have an @var{area} in
their names.  Some @var{area}s correspond to parts of @dfn{subtables},
whose contents are the cells that pair an innermost row variable and
an innermost column variable:

@table @code
@item ROW
A row within a subtable.

@item COL
A column within a subtable.

@item SUBTABLE
All the cells in a subtable
@end table

Other areas correspond to parts of @dfn{sections}, where stacked
variables divide each section from another:

@table @code
@item TABLE
An entire section.

@item LAYER
A layer within a section.

@item LAYERROW
A row in one layer within a section.

@item LAYERCOL
A column in one layer within a section.
@end table

The following summary functions may be applied to any variable
regardless of whether it is categorical or scalar.

@table @asis
@item @code{COUNT}
@itemx @code{ECOUNT}
The sum of weights in a cell (the number of cases, for an unweighted
dataset).  For @code{ECOUNT}, if the @code{WEIGHT} subcommand
specified an adjustment weight variable, its sum is used.

@item @i{area}@code{PCT} or @i{area}@code{PCT.COUNT}
A percentage within the specified @var{area}.

@item @i{area}@code{PCT.VALIDN}
A percentage of valid values within the specified @var{area}.

@item @i{area}@code{PCT.TOTALN}
A percentage of total values within the specified @var{area}.
@end table

The following summary functions apply only to scale variables:

@table @asis
@item @code{MAXIMUM}
The largest value.

@item @code{MEAN}
The mean.

@item @code{MEDIAN}
The median value.

@item @code{MINIMUM}
The smallest value.

@item @code{MISSING}
Sum of weights of user- and system-missing values.

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

@item @i{area}@code{PCT.SUM}
Percentage of the sum of the values across @var{area}.

@item @code{PTILE} @i{n}
The @var{n}th percentile, where @math{0 @leq{} @var{n} @leq{} 100}.

@item @code{RANGE}
The maximum minus the minimum.

@item @code{SEMEAN}
The standard error of the mean.

@item @code{STDDEV}
The standard deviation.

@item @code{SUM}
The sum.

@item @code{TOTALN}
@itemx @code{ETOTALN}
The sum of total count weights.  For @code{ETOTALN}, if the
@code{WEIGHT} subcommand specified an adjustment weight variable, its
sum is used.

@item @code{VALIDN}
@itemx @code{EVALIDN}
The sum of valid count weights.  For @code{ETOTALN}, if the
@code{WEIGHT} subcommand specified an adjustment weight variable, its
sum is used.

@item @code{VARIANCE}
The variance.
@end table


@node FACTOR, GLM, CTABLES, Statistics
@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, LOGISTIC REGRESSION, FACTOR, Statistics
@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, MEANS, GLM, Statistics
@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, NPAR TESTS, LOGISTIC REGRESSION, Statistics
@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, T-TEST, MEANS, Statistics
@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, CHISQUARE, NPAR TESTS, NPAR TESTS
@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, COCHRAN, BINOMIAL, NPAR TESTS
@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, FRIEDMAN, CHISQUARE, NPAR TESTS
@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, KENDALL, COCHRAN, NPAR TESTS
@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, KOLMOGOROV-SMIRNOV, FRIEDMAN, NPAR TESTS
@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, KRUSKAL-WALLIS, KENDALL, NPAR TESTS
@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, MANN-WHITNEY, KOLMOGOROV-SMIRNOV, NPAR TESTS
@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, MCNEMAR, KRUSKAL-WALLIS, NPAR TESTS
@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, MEDIAN, MANN-WHITNEY, NPAR TESTS
@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, RUNS, MCNEMAR, NPAR TESTS
@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, SIGN, MEDIAN, NPAR TESTS
@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, WILCOXON, RUNS, NPAR TESTS
@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,  , SIGN, NPAR TESTS
@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, ONEWAY, NPAR TESTS, Statistics
@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, Independent Samples Mode, T-TEST, T-TEST
@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, Paired Samples Mode, One Sample Mode, T-TEST
@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,  , Independent Samples Mode, T-TEST
@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, QUICK CLUSTER, T-TEST, Statistics
@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, RANK, ONEWAY, Statistics
@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, RELIABILITY, QUICK CLUSTER, Statistics
@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, ROC, RANK, Statistics
@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,  , RELIABILITY, Statistics
@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