Merge commit 'origin/stable'
[pspp-builds.git] / doc / statistics.texi
index 69576e55cbbc025d23887d0435708c6e09ac266f..985560604b02b52b02440dcd39a36bd1b773c118 100644 (file)
@@ -1,4 +1,4 @@
-@node Statistics, Utilities, Conditionals and Looping, Top
+@node Statistics
 @chapter Statistics
 
 This chapter documents the statistical procedures that PSPP supports so
@@ -14,9 +14,10 @@ far.
 * ONEWAY::                      One way analysis of variance.
 * RANK::                        Compute rank scores.
 * REGRESSION::                  Linear regression.
+* RELIABILITY::                 Reliability analysis.
 @end menu
 
-@node DESCRIPTIVES, FREQUENCIES, Statistics, Statistics
+@node DESCRIPTIVES
 @section DESCRIPTIVES
 
 @vindex DESCRIPTIVES
@@ -106,7 +107,7 @@ in the order that they are specified on the VARIABLES subcommand.  The A
 and D settings request an ascending or descending sort order,
 respectively.
 
-@node FREQUENCIES, EXAMINE, DESCRIPTIVES, Statistics
+@node FREQUENCIES
 @section FREQUENCIES
 
 @vindex FREQUENCIES
@@ -133,9 +134,6 @@ FREQUENCIES
         /BARCHART=@dots{}
         /HBAR=@dots{}
         /GROUPED=@dots{}
-
-(Integer mode.)
-        /VARIABLES=var_list (low,high)@dots{}
 @end display
 
 The @cmd{FREQUENCIES} procedure outputs frequency tables for specified
@@ -148,16 +146,7 @@ histograms and pie charts.  In the future, it will be able to produce
 bar charts and output percentiles for grouped data.
 
 The VARIABLES subcommand is the only required subcommand.  Specify the
-variables to be analyzed.  In most cases, this is all that is required.
-This is known as @dfn{general mode}.
-
-Occasionally, one may want to invoke a special mode called @dfn{integer
-mode}.  Normally, in general mode, PSPP will automatically determine
-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 a
-range of data values in parentheses, separated by a comma.  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.
+variables to be analyzed.
 
 The FORMAT subcommand controls the output format.  It has several
 possible settings:  
@@ -230,7 +219,7 @@ slices.  The MINIMUM and MAXIMUM keywords can be used to limit the
 displayed slices to a given range of values.  The MISSING keyword adds
 slices for missing values.
 
-@node EXAMINE, CROSSTABS, FREQUENCIES, Statistics
+@node EXAMINE
 @comment  node-name,  next,  previous,  up
 @section EXAMINE
 @vindex EXAMINE
@@ -244,7 +233,7 @@ EXAMINE
         /PLOT=@{BOXPLOT, NPPLOT, HISTOGRAM, ALL, NONE@}
         /CINTERVAL n
         /COMPARE=@{GROUPS,VARIABLES@}
-        /ID=@{case_number, var_name@}
+        /ID=var_name
         /@{TOTAL,NOTOTAL@}
         /PERCENTILE=[value_list]=@{HAVERAGE, WAVERAGE, ROUND, AEMPIRICAL, EMPIRICAL @}
         /MISSING=@{LISTWISE, PAIRWISE@} [@{EXCLUDE, INCLUDE@}] 
@@ -283,6 +272,12 @@ If /COMPARE=VARIABLES is specified, then one plot per factor is produced, each
 each containing one boxplot per dependent variable.
 If the /COMPARE subcommand is ommitted, then PSPP uses the default value of 
 /COMPARE=GROUPS.
+The ID subcommand also pertains to boxplots.  If given, it must
+specify a variable name.   Outliers and extreme cases plotted in
+boxplots will be labelled with the case from that variable.  Numeric or
+string variables are permissible.  If the ID subcommand is not given,
+then the casenumber will be used for labelling.
 
 The CINTERVAL subcommand specifies the confidence interval to use in
 calculation of the descriptives command.  The default it 95%.
@@ -305,7 +300,7 @@ there are many distinct values, then @cmd{EXAMINE} will produce a very
 large quantity of output.
 
 
-@node CROSSTABS, NPAR TESTS, EXAMINE, Statistics
+@node CROSSTABS
 @section CROSSTABS
 
 @vindex CROSSTABS
@@ -494,7 +489,7 @@ Approximate T of uncertainty coefficient is wrong.
 
 Fixes for any of these deficiencies would be welcomed.
 
-@node NPAR TESTS, T-TEST, CROSSTABS, Statistics
+@node NPAR TESTS
 @section NPAR TESTS
 
 @vindex NPAR TESTS
@@ -511,6 +506,8 @@ NPAR TESTS
      [ /STATISTICS=@{DESCRIPTIVES@} ]
 
      [ /MISSING=@{ANALYSIS, LISTWISE@} @{INCLUDE, EXCLUDE@} ]
+
+     [ /METHOD=EXACT [ TIMER [(n)] ] ]
 @end display
 
 NPAR TESTS performs nonparametric tests. 
@@ -520,14 +517,25 @@ One or more tests may be specified by using the corresponding subcommand.
 If the /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 /METHOD=EXACT is specified.  
+Exact tests give more accurate results, but may take an unacceptably long 
+time to perform.  If the 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 TIMER keyword.
+If the TIMER keyword is given without this figure, then a default value of 5 minutes 
+is used.
+
 
 @menu
 * BINOMIAL::                Binomial Test
 * CHISQUARE::               Chisquare Test
+* WILCOXON::                Wilcoxon Signed Ranks Test
 @end menu
 
 
-@node    BINOMIAL,  CHISQUARE, NPAR TESTS, NPAR TESTS
+@node    BINOMIAL
 @subsection Binomial test
 @vindex BINOMIAL
 @cindex binomial test
@@ -553,12 +561,12 @@ 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 the variable must assume dichotomous
+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 one tailed test is
+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
@@ -575,7 +583,7 @@ even for very large sample sizes.
 
 
 
-@node    CHISQUARE, , BINOMIAL, NPAR TESTS
+@node    CHISQUARE
 @subsection Chisquare test
 @vindex CHISQUARE
 @cindex chisquare test
@@ -603,8 +611,36 @@ sum of the frequencies need not be 1.
 If no /EXPECTED subcommand is given, then then equal frequencies 
 are expected.
 
+@node WILCOXON
+@subsection Wilcoxon
+@comment  node-name,  next,  previous,  up
+@vindex WILCOXON
+@cindex wilcoxon matched pairs signed ranks test
+
+@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.
+
+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, ONEWAY, NPAR TESTS, Statistics
+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 T-TEST
 @comment  node-name,  next,  previous,  up
 @section T-TEST
 
@@ -670,7 +706,7 @@ which they would be needed. This is the default.
 * Paired Samples Mode::         Testing two interdependent groups for equal mean
 @end menu
 
-@node One Sample Mode, Independent Samples Mode, T-TEST, T-TEST
+@node One Sample Mode
 @subsection One Sample Mode
 
 The @cmd{TESTVAL} subcommand invokes the One Sample mode.
@@ -681,7 +717,7 @@ which you wish to test.
 In this mode, you must also use the @cmd{/VARIABLES} subcommand to
 tell PSPP which variables you wish to test.
 
-@node Independent Samples Mode, Paired Samples Mode, One Sample Mode, T-TEST
+@node Independent Samples Mode
 @comment  node-name,  next,  previous,  up
 @subsection Independent Samples Mode
 
@@ -702,21 +738,21 @@ 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
-less than  or equal to this value belong to the first group, and cases
-greater than this value belong to the second group.
+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 @cmd{GROUPS} subcommand, missing values in
 the independent variable are excluded on a listwise basis, regardless
 of whether @cmd{/MISSING=LISTWISE} was specified.
 
 
-@node Paired Samples Mode,  , Independent Samples Mode, T-TEST
+@node Paired Samples Mode
 @comment  node-name,  next,  previous,  up
 @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 the @code{WITH} keyword is omitted, then tables for all
+If the @code{WITH} keyword is omitted, then tables for all
 combinations of variables given in the @cmd{PAIRS} subcommand are
 generated. 
 If the @code{WITH} keyword is given, and the @code{(PAIRED)} keyword
@@ -730,7 +766,7 @@ of variable preceding @code{WITH} against variable following
 @code{WITH} are generated.
 
 
-@node ONEWAY, RANK, T-TEST, Statistics
+@node ONEWAY
 @comment  node-name,  next,  previous,  up
 @section ONEWAY
 
@@ -742,7 +778,7 @@ of variable preceding @code{WITH} against variable following
 ONEWAY
         [/VARIABLES = ] var_list BY var
         /MISSING=@{ANALYSIS,LISTWISE@} @{EXCLUDE,INCLUDE@}
-        /CONTRASTS= value1 [, value2] ... [,valueN]
+        /CONTRAST= value1 [, value2] ... [,valueN]
         /STATISTICS=@{DESCRIPTIVES,HOMOGENEITY@}
 
 @end display
@@ -768,7 +804,7 @@ Displays the Levene test of Homogeneity of Variance for the
 variables and their groups.
 @end itemize
 
-The @code{CONTRASTS} subcommand is used when you anticipate certain
+The @code{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.
@@ -776,11 +812,10 @@ 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 @code{CONTRASTS} subcommand may be given up to 10 times in order
+The @code{CONTRAST} subcommand may be given up to 10 times in order
 to specify different contrast tests.
-@setfilename ignored
 
-@node RANK, REGRESSION, ONEWAY, Statistics
+@node RANK
 @comment  node-name,  next,  previous,  up
 @section RANK
 
@@ -843,3 +878,50 @@ user-missing are to be excluded from the rank scores. A setting of
 INCLUDE means they are to be included.  The default is EXCLUDE.
 
 @include regression.texi
+
+
+@node RELIABILITY
+@section RELIABILITY
+
+@vindex RELIABILITY
+@display
+RELIABILITY
+        /VARIABLES=var_list
+        /SCALE (@var{name}) = @{var_list, ALL@}
+        /MODEL=@{ALPHA, SPLIT[(N)]@}
+        /SUMMARY=@{TOTAL,ALL@}
+        /MISSING=@{EXCLUDE,INCLUDE@}
+@end display
+
+@cindex Cronbach's Alpha
+The @cmd{RELIABILTY} command performs reliablity analysis on the data.
+
+The VARIABLES subcommand is required. It determines the set of variables 
+upon which analysis is to be performed.
+
+The SCALE subcommand determines which variables reliability is to be 
+calculated for.  If it is omitted, then analysis for all variables named
+in the VARIABLES subcommand will be used.
+Optionally, the @var{name} parameter may be specified to set a string name 
+for the scale.
+
+The MODEL subcommand determines the type of analysis. If ALPHA is specified, 
+then Cronbach's Alpha is calculated for the scale.  If the model is 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 ALPHA.
+
+By default, any cases with user missing, or system missing values for 
+any variables given 
+in the VARIABLES subcommand will be omitted from analysis.
+The MISSING subcommand determines whether user missing values are to 
+be included or excluded in the analysis.
+
+The SUMMARY subcommand determines the type of summary analysis to be performed.
+Currently there is only one type: SUMMARY=TOTAL, which displays per-item
+analysis tested against the totals.
+
+
+