pspp_coeff_var_to_coeff: Guard against a null pointer in coefs[i]->v_info.
[pspp-builds.git] / src / math / coefficient.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2005 Free Software Foundation, Inc.
3
4    This program is free software: you can redistribute it and/or modify
5    it under the terms of the GNU General Public License as published by
6    the Free Software Foundation, either version 3 of the License, or
7    (at your option) any later version.
8
9    This program is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    GNU General Public License for more details.
13
14    You should have received a copy of the GNU General Public License
15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
16
17
18 #ifndef COEFFICIENT_H
19 #define COEFFICIENT_H
20
21 #include <assert.h>
22 #include <src/data/variable.h>
23 #include <src/data/value.h>
24
25 /*
26   This file contains definitions of data structures for storing
27   coefficients of a statistical model. The coefficients are the point
28   in the model where the theoretical aspects of the model meet the
29   data. As such, the coefficients are the interface where users need
30   to match variable names and values with any information about the
31   model itself. This file and coefficient.c provide this interface
32   between data and model structures.
33  */
34
35 struct design_matrix;
36
37 /*
38   Cache for the relevant data from the model. There are several
39   members which the caller might not use, and which could use a lot of
40   storage. Therefore non-essential members of the struct will be
41   allocated only when requested.
42  */
43 struct pspp_coeff
44 {
45   double estimate;              /* Estimated coefficient. */
46   double std_err;               /* Standard error of the estimate. */
47   struct varinfo *v_info;       /* Information pertaining to the variable(s)
48                                    associated with this coefficient.  The
49                                    calling function should initialize this
50                                    value with the functions in coefficient.c.
51                                    The estimation procedure ignores this
52                                    member. It is here so the caller can match
53                                    parameters with relevant variables and
54                                    values. If the coefficient is associated
55                                    with an interaction, then v_info contains
56                                    information for multiple variables. */
57   int n_vars;                   /* Number of variables associated with this
58                                    coefficient. Coefficients corresponding to
59                                    interaction terms will have more than one
60                                    variable. */
61 };
62 typedef struct pspp_coeff coefficient;
63
64 void pspp_coeff_free (struct pspp_coeff *);
65
66 /*
67   Initialize the variable and value pointers inside the
68   coefficient structures for the linear model.
69  */
70 void pspp_coeff_init (struct pspp_coeff **, const struct design_matrix *);
71
72
73 void
74 pspp_coeff_set_estimate (struct pspp_coeff *, double estimate);
75
76 void
77 pspp_coeff_set_std_err (struct pspp_coeff *, double std_err);
78
79 /*
80   Accessor functions for matching coefficients and variables.
81  */
82
83 /*
84   Return the estimated value of the coefficient.
85  */
86 double pspp_coeff_get_est (const struct pspp_coeff *);
87
88 /*
89   Return the standard error of the estimated coefficient.
90 */
91 double pspp_coeff_get_std_err (const struct pspp_coeff *);
92
93 /*
94   How many variables are associated with this coefficient?
95  */
96 int pspp_coeff_get_n_vars (struct pspp_coeff *);
97
98 /*
99   Which coefficient does this variable match? If the variable is
100   categorical, and has more than one coefficient, report the first
101   coefficient found. Note that in this case, the result will depend on
102   the order of COEFS.
103  */
104 struct pspp_coeff *
105 pspp_coeff_var_to_coeff (const struct variable *, struct pspp_coeff **, size_t, const union value *);
106
107 /*
108   Which variable does this coefficient match? The int argument is usually
109   0, unless the coefficient refers to an interaction.
110  */
111 const struct variable *pspp_coeff_get_var (struct pspp_coeff *,
112                                                   int);
113 /*
114   Which value is associated with this coefficient/variable comination?
115  */
116 const union value *pspp_coeff_get_value (struct pspp_coeff *,
117                                                 const struct variable *);
118
119 /*
120   Get or set the standard deviation of the variable associated with this coefficient.
121  */
122 double pspp_coeff_get_sd (const struct pspp_coeff *);
123 void pspp_coeff_set_sd (struct pspp_coeff *, double);
124
125 /*
126   Get or set the mean for the variable associated with this coefficient.
127 */
128 double pspp_coeff_get_mean (const struct pspp_coeff *);
129 void pspp_coeff_set_mean (struct pspp_coeff *, double);
130 #endif