Update documentation regarding missing values.

[pspp-builds.git] / doc / statistics.texi

diff --git a/doc/statistics.texi b/doc/statistics.texi
index 985560604b02b52b02440dcd39a36bd1b773c118..632c1a3754492fb0eb5aa4c59ff31e810342e272 100644 (file)
--- a/doc/statistics.texi
+++ b/doc/statistics.texi
@@ -15,6 +15,7 @@ far.
 * RANK::                        Compute rank scores.
 * REGRESSION::                  Linear regression.
 * RELIABILITY::                 Reliability analysis.
 * RANK::                        Compute rank scores.
 * REGRESSION::                  Linear regression.
 * RELIABILITY::                 Reliability analysis.

+* ROC::                         Receiver Operating Characteristic.

 @end menu
 
 @node DESCRIPTIVES
 @end menu
 
 @node DESCRIPTIVES


@@ -205,12 +206,13 @@ boundaries of the data set divided into the specified number of ranges.
 For instance, @code{/NTILES=4} would cause quartiles to be reported.
 
 The HISTOGRAM subcommand causes the output to include a histogram for
 For instance, @code{/NTILES=4} would cause quartiles to be reported.
 
 The HISTOGRAM subcommand causes the output to include a histogram for

-each specified variable.  The X axis by default ranges from the
+each specified numeric variable.  The X axis by default ranges from the

 minimum to the maximum value observed in the data, but the MINIMUM and
 MAXIMUM keywords can set an explicit range.  The Y axis by default is
 labeled in frequencies; use the PERCENT keyword to causes it to be
 labeled in percent of the total observed count.  Specify NORMAL to
 superimpose a normal curve on the histogram.
 minimum to the maximum value observed in the data, but the MINIMUM and
 MAXIMUM keywords can set an explicit range.  The Y axis by default is
 labeled in frequencies; use the PERCENT keyword to causes it to be
 labeled in percent of the total observed count.  Specify NORMAL to
 superimpose a normal curve on the histogram.

+Histograms are not created for string variables.

 
 The PIECHART adds a pie chart for each variable to the data.  Each
 slice represents one value, with the size of the slice proportional to
 
 The PIECHART adds a pie chart for each variable to the data.  Each
 slice represents one value, with the size of the slice proportional to


@@ -347,9 +349,7 @@ is present, the VARIABLES subcommand must precede the TABLES
 subcommand.
 
 In general mode, numeric and string variables may be specified on
 subcommand.
 
 In general mode, numeric and string variables may be specified on

-TABLES.  Although long string variables are allowed, only their
-initial short-string parts are used.  In integer mode, only numeric
-variables are allowed.
+TABLES.  In integer mode, only numeric variables are allowed.

 
 The MISSING subcommand determines the handling of user-missing values.
 When set to TABLE, the default, missing values are dropped on a table by
 
 The MISSING subcommand determines the handling of user-missing values.
 When set to TABLE, the default, missing values are dropped on a table by


@@ -532,6 +532,7 @@ is used.
 * BINOMIAL::                Binomial Test
 * CHISQUARE::               Chisquare Test
 * WILCOXON::                Wilcoxon Signed Ranks Test
 * BINOMIAL::                Binomial Test
 * CHISQUARE::               Chisquare Test
 * WILCOXON::                Wilcoxon Signed Ranks Test

+* SIGN::                    The Sign Test

 @end menu
 
 
 @end menu
 
 


@@ -544,7 +545,7 @@ is used.
      [ /BINOMIAL[(p)]=var_list[(value1[, value2)] ] ]
 @end display 
 
      [ /BINOMIAL[(p)]=var_list[(value1[, value2)] ] ]
 @end display 
 

-The binomial test compares the observed distribution of a dichotomous 
+The /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.  
 variable with that of a binomial distribution.
 The variable @var{p} specifies the test proportion of the binomial 
 distribution.  


@@ -584,7 +585,7 @@ even for very large sample sizes.
 
 
 @node    CHISQUARE
 
 
 @node    CHISQUARE

-@subsection Chisquare test
+@subsection Chisquare Test

 @vindex CHISQUARE
 @cindex chisquare test
 
 @vindex CHISQUARE
 @cindex chisquare test
 


@@ -594,7 +595,7 @@ even for very large sample sizes.
 @end display 
 
 
 @end display 
 
 

-The chisquare test produces a chi-square statistic for the differences 
+The /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
 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


@@ -612,7 +613,7 @@ If no /EXPECTED subcommand is given, then then equal frequencies
 are expected.
 
 @node WILCOXON
 are expected.
 
 @node WILCOXON

-@subsection Wilcoxon
+@subsection Wilcoxon Matched Pairs Signed Ranks Test

 @comment  node-name,  next,  previous,  up
 @vindex WILCOXON
 @cindex wilcoxon matched pairs signed ranks test
 @comment  node-name,  next,  previous,  up
 @vindex WILCOXON
 @cindex wilcoxon matched pairs signed ranks test


@@ -621,9 +622,10 @@ are expected.
      [ /WILCOXON varlist [ WITH varlist [ (PAIRED) ]]]
 @end display
 
      [ /WILCOXON varlist [ WITH varlist [ (PAIRED) ]]]
 @end display
 

-The wilcoxon subcommand tests for differences between means of the 
-variables listed.  The test does not make any assumptions about the
-variances of the samples.
+The /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 symetrical.

 
 If the @code{WITH} keyword is omitted, then tests for all
 combinations of the listed variables are performed.
 
 If the @code{WITH} keyword is omitted, then tests for all
 combinations of the listed variables are performed.


@@ -637,8 +639,32 @@ If the @code{WITH} keyword is given, but the
 of variable preceding @code{WITH} against variable following
 @code{WITH} are performed.
 
 of variable preceding @code{WITH} against variable following
 @code{WITH} are performed.
 

-If the number of observations is large, and exact tests have been
-requested. then the test may take a very long time to complete.
+
+@node SIGN
+@subsection Sign Test
+@vindex SIGN
+@cindex sign test
+
+@display
+     [ /SIGN varlist [ WITH varlist [ (PAIRED) ]]]
+@end display
+
+The /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 T-TEST
 @comment  node-name,  next,  previous,  up
 
 @node T-TEST
 @comment  node-name,  next,  previous,  up


@@ -925,3 +951,73 @@ analysis tested against the totals.
 
 
 
 
 
 

+@node ROC
+@section ROC
+
+@vindex ROC
+@cindex Receiver Operating Characterstic
+@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 PLOT is used to determine if and how the ROC curve is drawn.
+The keyword CURVE means that the ROC curve should be drawn, and the optional keyword REFERENCE,
+which should be enclosed in parentheses, says that the diagonal reference line should be drawn.
+If the keyword NONE is given, then no ROC curve is drawn.
+By default, the curve is drawn with no reference line.
+
+The optional subcommand PRINT determines which additional tables should be printed.
+Two additional tables are available. 
+The 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 COORDINATES keyword says that a table of coordinates of the ROC curve should be printed.
+
+The CRITERIA subcommand has four optional parameters:
+@itemize @bullet
+@item The TESTPOS parameter may be LARGE or SMALL.
+LARGE is the default, and says that larger values in the predictor variables are to be 
+considered positive.  SMALL indicates that smaller values should be considered positive.
+
+@item The CI parameter specifies the confidence interval that should be printed.
+It has no effect if the SE keyword in the PRINT subcommand has not been given.
+
+@item The DISTRIBUTION parameter determines the method to be used when estimating the area
+under the curve.  
+There are two possibilities, @i{viz}: FREE and NEGEXPO.
+The FREE method uses a non-parametric estimate, and the NEGEXPO method a bi-negative 
+exponential distribution estimate.
+The 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 FREE.
+
+@item The CUTOFF parameter is for compatibility and is ignored.
+@end itemize
+
+The 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.
+
+