fbuf: New data structure for buffered file I/O.

[pspp] / doc / statistics.texi

@c PSPP - a program for statistical analysis.
@c Copyright (C) 2017 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.
* 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.
* REGRESSION::                  Linear regression.
* RELIABILITY::                 Reliability analysis.
* ROC::                         Receiver Operating Characteristic.
@end menu

@node DESCRIPTIVES
@section DESCRIPTIVES

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

The @cmd{DESCRIPTIVES} procedure reads the active dataset and outputs
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 affects the output format.  Currently the
@subcmd{LABELS/NOLABELS} and @subcmd{NOINDEX/INDEX} settings are not used.
When @subcmd{SERIAL} is
set, both valid and missing number of cases are listed in the output;
when @subcmd{NOSERIAL} is set, only valid cases are listed.

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.

@node FREQUENCIES
@section FREQUENCIES

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


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

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

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

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

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

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

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

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

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

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

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

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

@node EXAMINE
@section EXAMINE

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

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

@end display

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

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

Following the dependent variables, factors may be specified.
The factors (if desired) should be preceded by a single @subcmd{BY} keyword.
The format for each factor is 
@display
@var{factorvar} [BY @var{subfactorvar}].
@end display
Each unique combination of the values of  @var{factorvar} and
@var{subfactorvar} divide the dataset into @dfn{cells}.
Statistics will be 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} will produce 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 will be produced for the entire dataset
as well as for each cell.
If @subcmd{NOTOTAL} appears, then statistics will be 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 of differs between factors.
Boxplots will also 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 is raised.  For example, if
@var{t} is given as 2, then the data will be squared.
Zero, however is a special value.  If @var{t} is 0 or 
is omitted, then data will be transformed by taking its natural logarithm instead of
raising to the power of @var{t}.

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 will be 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 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 will generate 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 will be 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 @var{height} and 
@var{weight} for each gender, and for the whole dataset will be shown.
Boxplots will also be produced.
Because @subcmd{/COMPARE = GROUPS} was given, boxplots for male and female will be
shown 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, this will be
used to label the extreme values.

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

@node GRAPH
@section GRAPH

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

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

@end display

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

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

@node SCATTERPLOT
@subsection Scatterplot
@cindex scatterplot

The subcommand @subcmd{SCATTERPLOT} produces an xy plot of the
data. The different values of the optional third variable @var{var3}
will result in different 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 will produce 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} vs.@: @var{weight} relation.

@node HISTOGRAM
@subsection Histogram
@cindex histogram

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

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

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

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

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

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

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

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

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

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

@node CORRELATIONS
@section CORRELATIONS

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

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

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

At least one @subcmd{VARIABLES} subcommand is required. If the @subcmd{WITH} 
keyword is used, then a non-square correlation table will be produced.
The variables preceding @subcmd{WITH}, will be used as the rows of the table,
and the variables following will be the columns of the table.
If no @subcmd{WITH} subcommand is given, then a square, symmetrical table using all variables is produced.


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 will be displayed in a separated table, for all the variables listed
in any @subcmd{/VARIABLES} subcommand.
The @subcmd{XPROD} keyword requests cross-product deviations and covariance estimators to 
be displayed for each pair of variables.
The keyword @subcmd{ALL} is the union of @subcmd{DESCRIPTIVES} and @subcmd{XPROD}.

@node CROSSTABS
@section CROSSTABS

@vindex CROSSTABS
@display
CROSSTABS
        /TABLES=@var{var_list} BY @var{var_list} [BY @var{var_list}]@dots{}
        /MISSING=@{TABLE,INCLUDE,REPORT@}
        /WRITE=@{NONE,CELLS,ALL@}
        /FORMAT=@{TABLES,NOTABLES@}
                @{PIVOT,NOPIVOT@}
                @{AVALUE,DVALUE@}
                @{NOINDEX,INDEX@}
                @{BOX,NOBOX@}
        /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
an @samp{M} (for ``missing'') and excluded from statistical
calculations.

Currently the @subcmd{WRITE} subcommand is ignored.

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} suppresses them.

@item
@subcmd{PIVOT}, the default, causes each @subcmd{TABLES} subcommand to be displayed in a
pivot table format.  @subcmd{NOPIVOT} causes the old-style crosstabulation format
to be used.

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

@item
@subcmd{INDEX} and @subcmd{NOINDEX} are currently ignored.

@item
@subcmd{BOX} and @subcmd{NOBOX} is currently ignored.
@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}
will be 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 chisquare
@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 
will be aggregated and the chart will be produces 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.

@node FACTOR
@section FACTOR

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

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

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

        [ /ANALYSIS=@var{var_list} ]

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

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

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

        [ /PLOT=[EIGEN] ]

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

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

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

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

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

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

The @subcmd{/ROTATION} subcommand is used to specify the method by which the extracted solution will be 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} will prevent 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 will be printed.  This can be useful for visualizing
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} will not be printed.  If the keyword @subcmd{DEFAULT} is given, or if no @subcmd{/FORMAT} subcommand is given, then no sorting is 
performed, and all coefficients will be printed.

The @subcmd{/CRITERIA} subcommand is used 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 will be extracted.  Otherwise, the @subcmd{MINEIGEN} setting will
be 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 iterative algorithms for factor
extraction (such as Principal Axis Factoring) are used.   
@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 it will be ignored.
The default value of @var{m} is 25.

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

@node GLM
@section GLM

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


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

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

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

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

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

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


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

@node LOGISTIC REGRESSION
@section LOGISTIC REGRESSION

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

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

     [/CATEGORICAL = @var{categorical_predictors}]

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

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

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

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

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

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

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

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

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

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


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

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

@node MEANS
@section MEANS

@vindex MEANS
@cindex means

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

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

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

      [/MISSING = [TABLE] [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} will be 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 will be calculated.
@item @subcmd{NONE}
      No statistics will be calculated (only a summary will be 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 = TABLE} causes cases to be dropped if any variable is missing 
in the table specification currently being processed, regardless of 
whether it is needed to calculate the statistic.

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

@node NPAR TESTS
@section NPAR TESTS

@vindex NPAR TESTS
@cindex nonparametric tests

@display 
NPAR TESTS
     
     nonparametric test subcommands
     .
     .
     .
     
     [ /STATISTICS=@{DESCRIPTIVES@} ]

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

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

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

Certain tests may take a long time to execute, if an exact figure is required.
Therefore, by default asymptotic approximations are used unless the
subcommand @subcmd{/METHOD=EXACT} is specified.  
Exact tests give more accurate results, but may take an unacceptably long 
time to perform.  If the @subcmd{TIMER} keyword is used, it sets a maximum time,
after which the test will be 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::               Chisquare Test
* COCHRAN::                 Cochran Q Test
* FRIEDMAN::                Friedman Test
* KENDALL::                 Kendall's W Test
* KOLMOGOROV-SMIRNOV::      Kolmogorov Smirnov Test
* KRUSKAL-WALLIS::          Kruskal-Wallis Test
* MANN-WHITNEY::            Mann Whitney U Test
* MCNEMAR::                 McNemar Test
* MEDIAN::                  Median Test
* RUNS::                    Runs Test
* SIGN::                    The Sign Test
* WILCOXON::                Wilcoxon Signed Ranks Test
@end menu


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

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

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

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

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

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

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

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



@node    CHISQUARE
@subsection Chisquare Test
@vindex CHISQUARE
@cindex chisquare 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 then equal frequencies 
are expected.


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

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

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

The value of Q will be displayed and its Asymptotic significance based on a chi-square distribution.

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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


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

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

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

The value of the Mann-Whitney U statistic, the Wilcoxon W, and the significance will be printed.
The abbreviated subcommand  @subcmd{M-W} may be used in place of @subcmd{MANN-WHITNEY}.

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

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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

@node T-TEST
@section T-TEST

@vindex T-TEST

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


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


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


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

@end display


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

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

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


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

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


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

@node One Sample Mode
@subsection One Sample Mode

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

@node Independent Samples Mode
@subsection Independent Samples Mode

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

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

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


@node Paired Samples Mode
@subsection Paired Samples Mode

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


@node ONEWAY
@section ONEWAY

@vindex ONEWAY
@cindex analysis of variance
@cindex ANOVA

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

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

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

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

The @subcmd{CONTRAST} subcommand is used when you anticipate certain
differences between the groups.
The subcommand must be followed by a list of numerals which are the
coefficients of the groups to be tested.
The number of coefficients must correspond to the number of distinct
groups (or values of the independent variable).
If the total sum of the coefficients are not zero, then @pspp{} will
display a warning, but will proceed with the analysis.
The @subcmd{CONTRAST} subcommand may be given up to 10 times in order
to specify different contrast tests.
The @subcmd{MISSING} subcommand defines how missing values are handled.
If @subcmd{LISTWISE} is specified then cases which have missing values for 
the independent variable or any dependent variable will be ignored.
If @subcmd{ANALYSIS} is specified, then cases will be 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
The optional syntax @code{ALPHA(@var{value})} is used to indicate
that @var{value} should be used as the
confidence level for which the posthoc tests will be performed.
The default is 0.05.

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

@cindex K-means clustering
@cindex clustering

@display
QUICK CLUSTER @var{var_list}
      [/CRITERIA=CLUSTERS(@var{k}) [MXITER(@var{max_iter})] CONVERGE(@var{epsilon}) [NOINITIAL]]
      [/MISSING=@{EXCLUDE,INCLUDE@} @{LISTWISE, PAIRWISE@}]
      [/PRINT=@{INITIAL@} @{CLUSTER@}]
@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 will be displayed (potentially generating lengthy output).


@node RANK
@section RANK

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

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

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

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

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

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

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

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

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

@include regression.texi


@node RELIABILITY
@section RELIABILITY

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

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

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

The @subcmd{SCALE} subcommand determines which variables reliability is to be 
calculated for.  If it is omitted, then analysis for all variables named
in the @subcmd{VARIABLES} subcommand will be 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 will be omitted from analysis.
The @subcmd{MISSING} subcommand determines whether user missing values are to 
be 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.



@node ROC
@section ROC

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

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


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

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

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

The optional subcommand @subcmd{PRINT} determines which additional tables should be printed.
Two additional tables are available. 
The @subcmd{SE} keyword says that standard error of the area under the curve should be printed as well as
the area itself.
In addition, a p-value under the null hypothesis that the area under the curve equals 0.5 will be
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 will be 
excluded.

@c  LocalWords:  subcmd subcommand