Add documentation for GLM
[pspp] / doc / statistics.texi
index 85217cd636fef532832114c5182e1aac4d30fee9..9774c514aa7435081336084ae32e4f196fe8b8e6 100644 (file)
@@ -12,6 +12,7 @@ far.
 * 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.
@@ -411,8 +412,9 @@ large quantity of output.
 
 @display
 GRAPH
-        /HISTOGRAM = @var{var}
-        /SCATTERPLOT [(BIVARIATE)] = @var{var1} WITH @var{var2} [BY @var{var3}] 
+        /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@}]
 
@@ -422,11 +424,20 @@ 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.
+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   
@@ -437,10 +448,14 @@ This example will produce a scatterplot where @var{height} is plotted versus @va
 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}.
 
@@ -449,6 +464,60 @@ 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
 
@@ -820,6 +889,64 @@ If @subcmd{PAIRWISE} is set, then a case is considered missing only if either of
 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 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 LOGISTIC REGRESSION
 @section LOGISTIC REGRESSION
 
@@ -1649,7 +1776,7 @@ The default is 0.05.
 QUICK CLUSTER @var{var_list}
       [/CRITERIA=CLUSTERS(@var{k}) [MXITER(@var{max_iter})] CONVERGE(@var{epsilon}) [NOINITIAL]]
       [/MISSING=@{EXCLUDE,INCLUDE@} @{LISTWISE, PAIRWISE@}]
-      [/PRINT=@{INITIAL@} @{CLUSTERS@}]
+      [/PRINT=@{INITIAL@} @{CLUSTER@}]
 @end display
 
 The @cmd{QUICK CLUSTER} command performs k-means clustering on the
@@ -1699,7 +1826,7 @@ 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{CLUSTERS} is set, the cluster memberships of the individual
+If @subcmd{CLUSTER} is set, the cluster memberships of the individual
 cases will be displayed (potentially generating lengthy output).
 
 
@@ -1880,3 +2007,5 @@ 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