Patch #6262. New developers guide and resulting fixes and cleanups.
[pspp-builds.git] / doc / regression.texi
1 @node REGRESSION
2 @comment  node-name,  next,  previous,  up
3 @section REGRESSION
4
5 @cindex regression
6 @cindex linear regression
7 The REGRESSION procedure fits linear models to data via least-squares
8 estimation. The procedure is appropriate for data which satisfy those
9 assumptions typical in linear regression:
10
11 @itemize @bullet
12 @item The data set contains n observations of a dependent variable, say
13 Y_1,...,Y_n, and n observations of one or more explanatory
14 variables. Let X_11, X_12, ..., X_1n denote the n observations of the
15 first explanatory variable; X_21,...,X_2n denote the n observations of the
16 second explanatory variable; X_k1,...,X_kn denote the n observations of the kth
17 explanatory variable.
18
19 @item The dependent variable Y has the following relationship to the 
20 explanatory variables:
21 @math{Y_i = b_0 + b_1 X_1i + ... + b_k X_ki + Z_i} 
22 where @math{b_0, b_1, ..., b_k} are unknown
23 coefficients, and @math{Z_1,...,Z_n} are independent, normally
24 distributed ``noise'' terms with common variance. The noise, or
25 ``error'' terms are unobserved. This relationship is called the
26 ``linear model.''
27 @end itemize
28
29 The REGRESSION procedure estimates the coefficients
30 @math{b_0,...,b_k} and produces output relevant to inferences for the
31 linear model. 
32
33 @c If you add any new commands, then don't forget to remove the entry in 
34 @c not-implemented.texi
35
36 @menu
37 * Syntax::                      Syntax definition.
38 * Examples::                    Using the REGRESSION procedure.
39 @end menu
40
41 @node Syntax
42 @subsection Syntax
43
44 @vindex REGRESSION
45 @display
46 REGRESSION
47         /VARIABLES=var_list
48         /DEPENDENT=var_list
49         /STATISTICS=@{ALL, DEFAULTS, R, COEFF, ANOVA, BCOV@}
50         /EXPORT ('file-name')
51         /SAVE=@{PRED, RESID@}
52 @end display
53
54 The @cmd{REGRESSION} procedure reads the active file and outputs
55 statistics relevant to the linear model specified by the user.
56
57 The VARIABLES subcommand, which is required, specifies the list of
58 variables to be analyzed.  Keyword VARIABLES is required. The
59 DEPENDENT subcommand specifies the dependent variable of the linear
60 model. The DEPENDENT subcommand is required. All variables listed in
61 the VARIABLES subcommand, but not listed in the DEPENDENT subcommand,
62 are treated as explanatory variables in the linear model.
63
64 All other subcommands are optional:
65
66 The STATISTICS subcommand specifies the statistics to be displayed:
67
68 @table @code
69 @item ALL
70 All of the statistics below.
71 @item R
72 The ratio of the sums of squares due to the model to the total sums of
73 squares for the dependent variable.
74 @item COEFF
75 A table containing the estimated model coefficients and their standard errors.
76 @item ANOVA
77 Analysis of variance table for the model.
78 @item BCOV
79 The covariance matrix for the estimated model coefficients.
80 @end table
81
82 The SAVE subcommand causes PSPP to save the residuals or predicted
83 values from the fitted
84 model to the active file. PSPP will store the residuals in a variable
85 called RES1 if no such variable exists, RES2 if RES1 already exists,
86 RES3 if RES1 and RES2 already exist, etc. It will choose the name of
87 the variable for the predicted values similarly, but with PRED as a
88 prefix.
89
90 The EXPORT subcommand causes PSPP to write a C program containing
91 functions related to the model. One such function accepts values of
92 explanatory variables as arguments, and returns an estimate of the
93 corresponding new
94 value of the dependent variable. The generated program will also contain
95 functions that return prediction and confidence intervals related to
96 those new estimates. PSPP will write the program to the
97 'file-name' given by the user, and write declarations of functions
98 to a file called pspp_model_reg.h. The user can then compile the C
99 program and use it as part of another program. This subcommand is a
100 PSPP extension.
101
102 @node Examples
103 @subsection Examples
104 The following PSPP syntax will generate the default output, save the
105 predicted values and residuals to the active file, and save the
106 linear model in a program called ``model.c.''
107
108 @example
109 title 'Demonstrate REGRESSION procedure'.
110 data list / v0 1-2 (A) v1 v2 3-22 (10).
111 begin data.
112 b  7.735648 -23.97588
113 b  6.142625 -19.63854
114 a  7.651430 -25.26557
115 c  6.125125 -16.57090
116 a  8.245789 -25.80001
117 c  6.031540 -17.56743
118 a  9.832291 -28.35977
119 c  5.343832 -16.79548
120 a  8.838262 -29.25689
121 b  6.200189 -18.58219
122 end data.
123 list.
124 regression /variables=v0 v1 v2 /statistics defaults /dependent=v2 
125            /export (model.c) /save pred resid /method=enter.
126 @end example
127
128 The file pspp_model_reg.h contains these declarations:
129
130 @example
131 double pspp_reg_estimate (const double *, const char *[]);
132 double pspp_reg_variance (const double *var_vals, const char *[]);
133 double pspp_reg_confidence_interval_U (const double *var_vals, const char *var_names[], double p);
134 double pspp_reg_confidence_interval_L (const double *var_vals, const char *var_names[], double p);
135 double pspp_reg_prediction_interval_U (const double *var_vals, const char *var_names[], double p);
136 double pspp_reg_prediction_interval_L (const double *var_vals, const char *var_names[], double p);
137 @end example
138
139 The file model.c contains the definitions of the functions. 
140 @setfilename ignored