work on pivot table and FREQUENCIES usage
[pspp] / doc / statistics.texi
index 76925d7e954d865d76217b97e79c86fa3a0ca272..fd1f7214668d91603c747f94d6f3da2d9c9ffab7 100644 (file)
@@ -8,7 +8,9 @@ far.
 * DESCRIPTIVES::                Descriptive statistics.
 * FREQUENCIES::                 Frequency tables.
 * EXAMINE::                     Testing data for normality.
+* CORRELATIONS::                Correlation tables.
 * CROSSTABS::                   Crosstabulation tables.
+* FACTOR::                      Factor analysis and Principal Components analysis
 * NPAR TESTS::                  Nonparametric tests.
 * T-TEST::                      Test hypotheses about means.
 * ONEWAY::                      One way analysis of variance.
@@ -116,11 +118,7 @@ respectively.
 FREQUENCIES
         /VARIABLES=var_list
         /FORMAT=@{TABLE,NOTABLE,LIMIT(limit)@}
-                @{STANDARD,CONDENSE,ONEPAGE[(onepage_limit)]@}
-                @{LABELS,NOLABELS@}
                 @{AVALUE,DVALUE,AFREQ,DFREQ@}
-                @{SINGLE,DOUBLE@}
-                @{OLDPAGE,NEWPAGE@}
         /MISSING=@{EXCLUDE,INCLUDE@}
         /STATISTICS=@{DEFAULT,MEAN,SEMEAN,MEDIAN,MODE,STDDEV,VARIANCE,
                      KURTOSIS,SKEWNESS,RANGE,MINIMUM,MAXIMUM,SUM,
@@ -128,8 +126,9 @@ FREQUENCIES
         /NTILES=ntiles
         /PERCENTILES=percent@dots{}
         /HISTOGRAM=[MINIMUM(x_min)] [MAXIMUM(x_max)] 
-                   [@{FREQ,PCNT@}] [@{NONORMAL,NORMAL@}]
-        /PIECHART=[MINIMUM(x_min)] [MAXIMUM(x_max)] @{NOMISSING,MISSING@}
+                   [@{FREQ[(y_max)],PERCENT[(y_max)]@}] [@{NONORMAL,NORMAL@}]
+        /PIECHART=[MINIMUM(x_min)] [MAXIMUM(x_max)]
+                  [@{FREQ,PERCENT@}] [@{NOMISSING,MISSING@}]
 
 (These options are not currently implemented.)
         /BARCHART=@dots{}
@@ -140,11 +139,9 @@ FREQUENCIES
 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.
-
-@cmd{FREQUENCIES} also support graphical output in the form of
-histograms and pie charts.  In the future, it will be able to produce
-bar charts and output percentiles for grouped data.
+(including median and mode) and percentiles,
+@cmd{FREQUENCIES} can also output
+histograms and pie charts.  
 
 The VARIABLES subcommand is the only required subcommand.  Specify the
 variables to be analyzed.
@@ -159,30 +156,11 @@ variable specified.  NOTABLE prevents them from being output.  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
-STANDARD frequency tables contain more complete information, but also to
-take up more space on the printed page.  CONDENSE frequency tables are
-less informative but take up less space.  ONEPAGE with a numeric
-argument will output standard frequency tables if there are the
-specified number of values or less, condensed tables otherwise.  ONEPAGE
-without an argument defaults to a threshold of 50 values.
-
-@item
-LABELS causes value labels to be displayed in STANDARD frequency
-tables.  NOLABLES prevents this.
-
 @item
 Normally frequency tables are sorted in ascending order by value.  This
 is AVALUE.  DVALUE tables are sorted in descending order by value.
 AFREQ and DFREQ tables are sorted in ascending and descending order,
 respectively, by frequency count.
-
-@item
-SINGLE spaced frequency tables are closely spaced.  DOUBLE spaced
-frequency tables have wider spacing.
-
-@item
-OLDPAGE and NEWPAGE are not currently used.
 @end itemize
 
 The MISSING subcommand controls the handling of user-missing values.
@@ -206,13 +184,11 @@ 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
-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.
-Histograms are not created for string variables.
+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.  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
@@ -221,6 +197,9 @@ 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.
 
+The FREQ and PERCENT options on HISTOGRAM and PIECHART are accepted
+but not currently honored.
+
 @node EXAMINE
 @comment  node-name,  next,  previous,  up
 @section EXAMINE
@@ -301,6 +280,69 @@ If many dependent variable are given, or factors are given for which
 there are many distinct values, then @cmd{EXAMINE} will produce a very
 large quantity of output.
 
+@node CORRELATIONS
+@section CORRELATIONS
+
+@vindex CORRELATIONS
+@display
+CORRELATIONS
+     /VARIABLES = varlist [ WITH varlist ]
+     [
+      .
+      .
+      .
+      /VARIABLES = varlist [ WITH varlist ]
+      /VARIABLES = varlist [ WITH varlist ]
+     ]
+
+     [ /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 VARIABLES subcommand is required. If the WITH keyword is used, then a non-square
+correlation table will be produced.
+The variables preceding WITH, will be used as the rows of the table, and the variables following
+will be the columns of the table.
+If no 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 INCLUDE is set, then user-missing values are included in the
+calculations, but system-missing values are not.
+If EXCLUDE is set, which is the default, user-missing
+values are excluded as well as system-missing values. 
+This is the default.
+
+If 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 PAIRWISE is set, then a case is considered missing only if either of the
+values  for the particular coefficient are missing.
+The default is PAIRWISE.
+
+The PRINT subcommand is used to control how the reported significance values are printed.
+If the TWOTAIL option is used, then a two-tailed test of significance is 
+printed.  If the ONETAIL option is given, then a one-tailed test is used.
+The default is TWOTAIL.
+
+If the NOSIG option is specified, then correlation coefficients with significance less than
+0.05 are highlighted.
+If SIG is specified, then no highlighting is performed.  This is the default.
+
+@cindex covariance
+The STATISTICS subcommand requests additional statistics to be displayed.  The keyword 
+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 /VARIABLES subcommand.
+The XPROD keyword requests cross-product deviations and covariance estimators to 
+be displayed for each pair of variables.
+The keyword ALL is the union of DESCRIPTIVES and XPROD.
 
 @node CROSSTABS
 @section CROSSTABS
@@ -489,6 +531,99 @@ Approximate T of uncertainty coefficient is wrong.
 
 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_list
+
+        [ /METHOD = @{CORRELATION, COVARIANCE@} ]
+
+        [ /EXTRACTION=@{PC, PAF@}] 
+
+        [ /PRINT=[INITIAL] [EXTRACTION] [UNIVARIATE] [CORRELATION] [COVARIANCE] [DET] [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 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 VARIABLES subcommand is required.  It lists the variables which are to partake in the analysis.
+
+The /EXTRACTION subcommand is used to specify the way in which factors (components) are extracted from the data.
+If PC is specified, then Principal Components Analysis is used.  If PAF is specified, then Principal Axis Factoring is
+used. By default Principal Components Analysis will be used.
+
+The /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 /PRINT subcommand may be used to select which features of the analysis are reported:
+
+@itemize
+@item UNIVARIATE
+      A table of mean values, standard deviations and total weights are printed.
+@item INITIAL
+      Initial communalities and eigenvalues are printed.
+@item EXTRACTION
+      Extracted communalities and eigenvalues are printed.
+@item CORRELATION
+      The correlation matrix is printed.
+@item COVARIANCE
+      The covariance matrix is printed.
+@item DET
+      The determinant of the correlation or covariance matrix is printed.
+@item SIG
+      The significance of the elements of correlation matrix is printed.
+@item ALL
+      All of the above are printed.
+@item DEFAULT
+      Identical to INITIAL and EXTRACTION.
+@end itemize
+
+If /PLOT=EIGEN is given, then a ``Scree'' plot of the eigenvalues will be printed.  This can be useful for visualising
+which factors (components) should be retained.
+
+The /FORMAT subcommand determined how data are to be displayed in loading matrices.  If SORT is specified, then the variables
+are sorted in descending order of significance.  If BLANK(@var{n}) is specified, then coefficients whose absolute value is less
+than @var{n} will not be printed.  If the keyword DEFAULT is given, or if no /FORMAT subcommand is given, then no sorting is 
+performed, and all coefficients will be printed.
+
+The /CRITERIA subcommand is used to specify how the number of extracted factors (components) are chosen.  If FACTORS(@var{n}) is
+specified, where @var{n} is an integer, then @var{n} factors will be extracted.  Otherwise, the MINEIGEN setting will
+be used.  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 ECONVERGE and ITERATE settings have effect only when iterative algorithms for factor
+extraction (such as Principal Axis Factoring) are used.   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 ITERATE(@var{m}) setting sets the maximum number of iterations to @var{m}.  The default value of @var{m} is 25.
+
+The @cmd{MISSING} subcommand determines the handling of missing variables.  
+If INCLUDE is set, then user-missing values are included in the
+calculations, but system-missing values are not.
+If EXCLUDE is set, which is the default, user-missing
+values are excluded as well as system-missing values. 
+This is the default.
+If 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 PAIRWISE is set, then a case is considered missing only if either of the
+values  for the particular coefficient are missing.
+The default is LISTWISE.
+
 @node NPAR TESTS
 @section NPAR TESTS