f2831d27680d26033965a756c0aebf5c808fd177
[pspp-builds.git] / src / math / interaction.c
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2009 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   An interaction is a gsl_vector containing a "product" of other
19   variables. The variables can be either categorical or numeric.
20   If the variables are all numeric, the interaction is just the
21   scalar product. If any of the variables are categorical, their
22   product is a vector containing 0's in all but one entry. This entry
23   is found by combining the vectors corresponding to the variables'
24   OBS_VALS member. If there are K categorical variables, each with
25   N_1, N_2, ..., N_K categories, then the interaction will have
26   N_1 * N_2 * N_3 *...* N_K - 1 entries.
27
28   When using these functions, make sure the orders of variables and
29   values match when appropriate.
30  */
31
32 #include <config.h>
33 #include <assert.h>
34 #include <gsl/gsl_math.h>
35 #include <gsl/gsl_vector.h>
36 #include <data/value.h>
37 #include <data/variable.h>
38 #include <math/interaction.h>
39 #include <string.h>
40 #include <xalloc.h>
41
42 struct interaction_variable
43 {
44   int n_vars;
45   const struct variable **members;
46   struct variable *intr;
47   size_t n_alpha;
48 };
49
50 struct interaction_value
51 {
52   const struct interaction_variable *intr;
53   union value val; /* Concatenation of the string values in this
54                       interaction's value, or the product of a bunch
55                       of numeric values for a purely numeric
56                       interaction.
57                     */
58   double f; /* Product of the numerical values in this interaction's value. */
59 };
60
61 /*
62   An interaction_variable has type alpha if any of members have type
63   alpha. Otherwise, its type is numeric.
64  */
65 struct interaction_variable *
66 interaction_variable_create (const struct variable **vars, int n_vars)
67 {
68   struct interaction_variable *result = NULL;
69   size_t i;
70
71   if (n_vars > 0)
72     {
73       int width = 0;
74
75       result = xmalloc (sizeof (*result));
76       result->n_alpha = 0;
77       result->members = xnmalloc (n_vars, sizeof (*result->members));
78       result->n_vars = n_vars;
79       for (i = 0; i < n_vars; i++)
80         {
81           result->members[i] = vars[i];
82           if (var_is_alpha (vars[i]))
83             {
84               result->n_alpha++;
85               width += var_get_width (vars[i]);
86             }
87         }
88       result->intr = var_create_internal (0, width);
89     }
90
91   return result;
92 }
93 void interaction_variable_destroy (struct interaction_variable *iv)
94 {
95   var_destroy (iv->intr);
96   free (iv->members);
97   free (iv);
98 }
99
100 /*
101   Get one of the member variables.
102  */
103 const struct variable *
104 interaction_get_member (const struct interaction_variable *iv, size_t i)
105 {
106   return iv->members[i];
107 }
108
109 size_t
110 interaction_get_n_vars (const struct interaction_variable *iv)
111 {
112   return (iv == NULL) ? 0 : iv->n_vars;
113 }
114
115 size_t
116 interaction_get_n_alpha (const struct interaction_variable *iv)
117 {
118   return iv->n_alpha;
119 }
120
121 size_t
122 interaction_get_n_numeric (const struct interaction_variable *iv)
123 {
124   return (interaction_get_n_vars (iv) - interaction_get_n_alpha (iv));
125 }
126
127 /*
128   Get the interaction variable itself.
129  */
130 const struct variable *
131 interaction_get_variable (const struct interaction_variable *iv)
132 {
133   return iv->intr;
134 }
135 /*
136   Given list of values, compute the value of the corresponding
137   interaction.  This "value" is not stored as the typical vector of
138   0's and one double, but rather the string values are concatenated to
139   make one big string value, and the numerical values are multiplied
140   together to give the non-zero entry of the corresponding vector.
141  */
142 struct interaction_value *
143 interaction_value_create (const struct interaction_variable *var, const union value **vals)
144 {
145   struct interaction_value *result = NULL;
146   
147   if (var != NULL)
148     {
149       size_t i;
150       int val_width = var_get_width (interaction_get_variable (var));
151       int offset = 0;
152       size_t n_vars = interaction_get_n_vars (var);
153
154       result = xmalloc (sizeof (*result));
155       result->intr = var;
156
157       value_init (&result->val, val_width);
158
159       result->f = 1.0;
160       for (i = 0; i < n_vars; i++)
161         {
162           const struct variable *member = interaction_get_member (var, i);
163
164           if (var_is_value_missing (member, vals[i], MV_ANY))
165             {
166               value_set_missing (&result->val, val_width);
167               result->f = SYSMIS;
168               break;
169             }
170           else
171             {
172               if (var_is_alpha (var->members[i]))
173                 {
174                   uint8_t *val = value_str_rw (&result->val, val_width);
175                   int w = var_get_width (var->members[i]);
176                   u8_cpy (val + offset, value_str (vals[i], w), w);
177                   offset += w;
178                 }
179               else if (var_is_numeric (var->members[i]))
180                 {
181                   result->f *= vals[i]->f;
182                 }
183             }
184         }
185       if (interaction_get_n_alpha (var) == 0)
186         {
187           /*
188             If there are no categorical variables, then the
189             interaction consists of only numeric data. In this case,
190             code that uses this interaction_value will see the union
191             member as the numeric value. If we were to store that
192             numeric value in result->f as well, the calling code may
193             inadvertently square this value by multiplying by
194             result->val->f. Such multiplication would be correct for an
195             interaction consisting of both categorical and numeric
196             data, but a mistake for purely numerical interactions. To
197             avoid the error, we set result->f to 1.0 for numeric
198             interactions.
199            */
200           result->val.f = result->f;
201           result->f = 1.0;
202         }
203     }
204   return result;
205 }
206
207 const union value *
208 interaction_value_get (const struct interaction_value *val)
209 {
210   return &val->val;
211 }
212
213 /*
214   Returns the numeric value of the non-zero entry for the vector
215   corresponding to this interaction.  Do not use this function to get
216   the numeric value of a purely numeric interaction. Instead, use the
217   union value * returned by interaction_value_get.
218  */
219 double 
220 interaction_value_get_nonzero_entry (const struct interaction_value *val)
221 {
222   if (val != NULL)
223     return val->f;
224   return 1.0;
225 }
226
227 void 
228 interaction_value_destroy (struct interaction_value *val)
229 {
230   if (val != NULL)
231     {
232       int val_width = var_get_width (interaction_get_variable (val->intr));
233
234       value_destroy (&val->val, val_width);
235       free (val);
236     }
237 }
238
239 /*
240   Return a value from a variable that is an interaction. 
241  */
242 struct interaction_value *
243 interaction_case_data (const struct ccase *ccase, const struct interaction_variable *iv)
244 {
245   size_t i;
246   size_t n_vars;
247   const struct variable *member;
248   const union value **vals = NULL;
249
250   n_vars = interaction_get_n_vars (iv);
251   vals = xnmalloc (n_vars, sizeof (*vals));
252
253   for (i = 0; i < n_vars; i++)
254         {
255           member = interaction_get_member (iv, i);
256           vals[i] = case_data (ccase, member);
257         }
258
259   return interaction_value_create (iv, vals);
260 }
261
262 bool
263 is_interaction (const struct variable *var, const struct interaction_variable **iv, size_t n_intr)
264 {
265   size_t i;
266   const struct variable *intr;
267   
268   for (i = 0; i < n_intr; i++)
269     {
270       intr = interaction_get_variable (iv[i]);
271       if (var_get_dict_index (intr) == var_get_dict_index (var))
272         {
273           return true;
274         }
275     }
276   return false;
277 }
278