Replace checkbox-treeview functions with a object PsppireCheckboxTreeview
[pspp] / src / math / categoricals.c
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 2009, 2010, 2011, 2012 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 #include <config.h>
18
19 #include "math/categoricals.h"
20 #include "math/interaction.h"
21
22 #include <stdio.h>
23
24 #include "data/case.h"
25 #include "data/value.h"
26 #include "data/variable.h"
27 #include "libpspp/array.h"
28 #include "libpspp/hmap.h"
29 #include "libpspp/pool.h"
30 #include "libpspp/str.h"
31 #include "libpspp/hash-functions.h"
32
33 #include "gl/xalloc.h"
34
35 #define CATEGORICALS_DEBUG 0
36
37 struct value_node
38 {
39   struct hmap_node node;      /* Node in hash map. */
40
41   union value val;            /* The value */
42
43   int index;                  /* A zero based unique index for this value */
44 };
45
46
47 struct interaction_value
48 {
49   struct hmap_node node;      /* Node in hash map */
50
51   struct ccase *ccase;        /* A case (probably the first in the dataset) which matches
52                                  this value */
53
54   double cc;                  /* Total of the weights of cases matching this interaction */
55
56   void *user_data;            /* A pointer to data which the caller can store stuff */
57 };
58
59 static struct value_node *
60 lookup_value (const struct hmap *map, const union value *val, unsigned int hash, int width)
61 {
62   struct value_node *vn = NULL;
63   HMAP_FOR_EACH_WITH_HASH (vn, struct value_node, node, hash, map)
64     {
65       if (value_equal (&vn->val, val, width))
66         break;
67     }
68   
69   return vn;
70 }
71
72 struct variable_node
73 {
74   struct hmap_node node;      /* Node in hash map. */
75   const struct variable *var; /* The variable */
76
77   struct hmap valmap;         /* A map of value nodes */
78   int n_vals;                 /* Number of values for this variable */
79 };
80
81
82 /* Comparison function to sort value_nodes in ascending order */
83 static int
84 compare_value_node_3way (const void *vn1_, const void *vn2_, const void *aux)
85 {
86   const struct value_node *const *vn1p = vn1_;
87   const struct value_node *const *vn2p = vn2_;
88
89   const struct variable_node *vn = aux;
90
91
92   return value_compare_3way (&(*vn1p)->val, &(*vn2p)->val, var_get_width (vn->var));
93 }
94
95
96
97 static struct variable_node *
98 lookup_variable (const struct hmap *map, const struct variable *var, unsigned int hash)
99 {
100   struct variable_node *vn = NULL;
101   HMAP_FOR_EACH_WITH_HASH (vn, struct variable_node, node, hash, map)
102     {
103       if (vn->var == var)
104         break;
105       
106       fprintf (stderr, "%s:%d Warning: Hash table collision\n", __FILE__, __LINE__);
107     }
108   
109   return vn;
110 }
111
112
113 struct interact_params
114 {
115   /* A map of cases indexed by a interaction_value */
116   struct hmap ivmap;
117
118   const struct interaction *iact;
119
120   int base_subscript_short;
121   int base_subscript_long;
122
123   /* The number of distinct values of this interaction */
124   int n_cats;
125
126   /* An array of integers df_n * df_{n-1} * df_{n-2} ...
127      These are the products of the degrees of freedom for the current 
128      variable and all preceeding variables */
129   int *df_prod; 
130
131   double *enc_sum;
132
133   /* A map of interaction_values indexed by subscript */
134   struct interaction_value **reverse_interaction_value_map;
135
136   double cc;
137 };
138
139
140 /* Comparison function to sort the reverse_value_map in ascending order */
141 static int
142 compare_interaction_value_3way (const void *vn1_, const void *vn2_, const void *aux)
143 {
144   const struct interaction_value *const *vn1p = vn1_;
145   const struct interaction_value *const *vn2p = vn2_;
146
147   const struct interact_params *iap = aux;
148
149   return interaction_case_cmp_3way (iap->iact, (*vn1p)->ccase, (*vn2p)->ccase);
150 }
151
152 struct categoricals
153 {
154   /* The weight variable */
155   const struct variable *wv;
156
157   /* An array of interact_params */
158   struct interact_params *iap;
159
160   /* Map whose members are the union of the variables which comprise IAP */
161   struct hmap varmap;
162
163   /* The size of IAP. (ie, the number of interactions involved.) */
164   size_t n_iap;
165
166   /* The number of categorical variables which contain entries.
167      In the absence of missing values, this will be equal to N_IAP */
168   size_t n_vars;
169
170   size_t df_sum;
171
172   /* A map to enable the lookup of variables indexed by subscript.
173      This map considers only the N - 1 of the N variables.
174   */
175   int *reverse_variable_map_short;
176
177   /* Like the above, but uses all N variables */
178   int *reverse_variable_map_long;
179
180   size_t n_cats_total;
181
182   struct pool *pool;
183
184   /* Missing values in the dependent varirable to be excluded */
185   enum mv_class dep_excl;
186
187   /* Missing values in the factor variables to be excluded */
188   enum mv_class fctr_excl;
189
190   const void *aux1;
191   void *aux2;
192
193   bool sane;
194
195   const struct payload *payload;
196 };
197
198 static void
199 categoricals_dump (const struct categoricals *cat)
200 {
201   if (CATEGORICALS_DEBUG)
202     {
203       int i;
204
205       printf ("Reverse Variable Map (short):\n");
206       for (i = 0; i < cat->df_sum; ++i)
207         {
208           printf (" %d", cat->reverse_variable_map_short[i]);
209         }
210       printf ("\n");
211
212       printf ("Reverse Variable Map (long):\n");
213       for (i = 0; i < cat->n_cats_total; ++i)
214         {
215           printf (" %d", cat->reverse_variable_map_long[i]);
216         }
217       printf ("\n");
218
219       printf ("Number of interactions %d\n", cat->n_iap);
220       for (i = 0 ; i < cat->n_iap; ++i)
221         {
222           int v;
223           struct string str;
224           const struct interact_params *iap = &cat->iap[i];
225           const struct interaction *iact = iap->iact;
226
227           ds_init_empty (&str);
228           interaction_to_string (iact, &str);
229
230           printf ("\nInteraction: \"%s\" (number of categories: %d); ", ds_cstr (&str), iap->n_cats);
231           ds_destroy (&str);
232           printf ("Base index (short/long): %d/%d\n", iap->base_subscript_short, iap->base_subscript_long);
233
234           printf ("\t(");
235           for (v = 0; v < hmap_count (&iap->ivmap); ++v)
236             {
237               int vv;
238               const struct interaction_value *iv = iap->reverse_interaction_value_map[v];
239
240               if (v > 0)  printf ("   ");
241               printf ("{");
242               for (vv = 0; vv < iact->n_vars; ++vv)
243                 {
244                   const struct variable *var = iact->vars[vv];
245                   const union value *val = case_data (iv->ccase, var);
246                   unsigned int varhash = hash_pointer (var, 0);
247                   struct variable_node *vn = lookup_variable (&cat->varmap, var, varhash);
248
249                   const int width = var_get_width (var);
250                   unsigned int valhash = value_hash (val, width, 0);
251                   struct value_node *valn = lookup_value (&vn->valmap, val, valhash, width);
252
253                   assert (vn->var == var);
254
255                   printf ("%g(%d)", val->f, valn->index);
256                   if (vv < iact->n_vars - 1)
257                     printf (", ");
258                 }
259               printf ("}");
260             }
261           printf (")\n");
262         }
263     }
264 }
265
266 void
267 categoricals_destroy (struct categoricals *cat)
268 {
269   struct variable_node *vn = NULL;
270   int i;
271   if (NULL == cat)
272     return;
273
274   for (i = 0; i < cat->n_iap; ++i)
275     {
276       struct interaction_value *iv = NULL;
277       /* Interate over each interaction value, and unref any cases that we reffed */
278       HMAP_FOR_EACH (iv, struct interaction_value, node, &cat->iap[i].ivmap)
279         {
280           if (cat->payload && cat->payload->destroy)
281             cat->payload->destroy (cat->aux1, cat->aux2, iv->user_data);
282           case_unref (iv->ccase);
283         }
284
285       free (cat->iap[i].enc_sum);
286       free (cat->iap[i].df_prod);
287       hmap_destroy (&cat->iap[i].ivmap);
288     }
289
290   /* Interate over each variable and delete its value map */
291   HMAP_FOR_EACH (vn, struct variable_node, node, &cat->varmap)
292     {
293       hmap_destroy (&vn->valmap);
294     }
295
296   hmap_destroy (&cat->varmap);
297
298   pool_destroy (cat->pool);
299
300   free (cat);
301 }
302
303
304
305 static struct interaction_value *
306 lookup_case (const struct hmap *map, const struct interaction *iact, const struct ccase *c)
307 {
308   struct interaction_value *iv = NULL;
309   size_t hash = interaction_case_hash (iact, c, 0);
310
311   HMAP_FOR_EACH_WITH_HASH (iv, struct interaction_value, node, hash, map)
312     {
313       if (interaction_case_equal (iact, c, iv->ccase))
314         break;
315
316       fprintf (stderr, "Warning: Hash table collision\n");
317     }
318
319   return iv;
320 }
321
322 bool 
323 categoricals_sane (const struct categoricals *cat)
324 {
325   return cat->sane;
326 }
327
328 struct categoricals *
329 categoricals_create (struct interaction *const*inter, size_t n_inter,
330                      const struct variable *wv, enum mv_class dep_excl, enum mv_class fctr_excl)
331 {
332   size_t i;
333   struct categoricals *cat = xmalloc (sizeof *cat);
334   
335   cat->n_iap = n_inter;
336   cat->wv = wv;
337   cat->n_cats_total = 0;
338   cat->n_vars = 0;
339   cat->reverse_variable_map_short = NULL;
340   cat->reverse_variable_map_long = NULL;
341   cat->pool = pool_create ();
342   cat->dep_excl = dep_excl;
343   cat->fctr_excl = fctr_excl;
344   cat->payload = NULL;
345   cat->aux2 = NULL;
346   cat->sane = false;
347
348   cat->iap = pool_calloc (cat->pool, cat->n_iap, sizeof *cat->iap);
349
350   hmap_init (&cat->varmap);
351   for (i = 0 ; i < cat->n_iap; ++i)
352     {
353       int v;
354       hmap_init (&cat->iap[i].ivmap);
355       cat->iap[i].iact = inter[i];
356       cat->iap[i].cc = 0.0;
357       for (v = 0; v < inter[i]->n_vars; ++v)
358         {
359           const struct variable *var = inter[i]->vars[v];
360           unsigned int hash = hash_pointer (var, 0);
361           struct variable_node *vn = lookup_variable (&cat->varmap, var, hash);
362           if (vn == NULL)
363             {
364               vn = pool_malloc (cat->pool, sizeof *vn);
365               vn->var = var;
366               vn->n_vals = 0;
367               hmap_init (&vn->valmap);
368
369               hmap_insert (&cat->varmap, &vn->node,  hash);
370             }
371         }
372     }
373
374   return cat;
375 }
376
377
378
379 void
380 categoricals_update (struct categoricals *cat, const struct ccase *c)
381 {
382   int i;
383   struct variable_node *vn = NULL;
384   double weight;
385
386   if (NULL == cat)
387     return;
388
389   weight = cat->wv ? case_data (c, cat->wv)->f : 1.0;
390
391   assert (NULL == cat->reverse_variable_map_short);
392   assert (NULL == cat->reverse_variable_map_long);
393
394   /* Interate over each variable, and add the value of that variable
395      to the appropriate map, if it's not already present. */
396   HMAP_FOR_EACH (vn, struct variable_node, node, &cat->varmap)
397     {
398       const int width = var_get_width (vn->var);
399       const union value *val = case_data (c, vn->var);
400       unsigned int hash = value_hash (val, width, 0);
401
402       struct value_node *valn = lookup_value (&vn->valmap, val, hash, width);
403       if (valn == NULL)
404         {
405           valn = pool_malloc (cat->pool, sizeof *valn);
406           valn->index = -1; 
407           vn->n_vals++;
408           value_init (&valn->val, width);
409           value_copy (&valn->val, val, width);
410           hmap_insert (&vn->valmap, &valn->node, hash);
411         }
412     }
413   
414   for (i = 0 ; i < cat->n_iap; ++i)
415     {
416       const struct interaction *iact = cat->iap[i].iact;
417
418       size_t hash;
419       struct interaction_value *node;
420
421       if ( interaction_case_is_missing (iact, c, cat->fctr_excl))
422         continue;
423
424       hash = interaction_case_hash (iact, c, 0);
425       node = lookup_case (&cat->iap[i].ivmap, iact, c);
426
427       if ( NULL == node)
428         {
429           node = pool_malloc (cat->pool, sizeof *node);
430           node->ccase = case_ref (c);
431           node->cc = weight;
432
433           hmap_insert (&cat->iap[i].ivmap, &node->node, hash);
434
435           if (cat->payload) 
436             {
437               node->user_data = cat->payload->create (cat->aux1, cat->aux2);
438             }
439         }
440       else
441         {
442           node->cc += weight;
443         }
444       cat->iap[i].cc += weight;
445
446       if (cat->payload)
447         {
448           double weight = cat->wv ? case_data (c, cat->wv)->f : 1.0;
449           cat->payload->update (cat->aux1, cat->aux2, node->user_data, c, weight);
450         }
451
452     }
453 }
454
455 /* Return the number of categories (distinct values) for interction N */
456 size_t
457 categoricals_n_count (const struct categoricals *cat, size_t n)
458 {
459   return hmap_count (&cat->iap[n].ivmap);
460 }
461
462
463 size_t
464 categoricals_df (const struct categoricals *cat, size_t n)
465 {
466   const struct interact_params *iap = &cat->iap[n];
467   return iap->df_prod[iap->iact->n_vars - 1];
468 }
469
470
471 /* Return the total number of categories */
472 size_t
473 categoricals_n_total (const struct categoricals *cat)
474 {
475   if (!categoricals_is_complete (cat))
476     return 0;
477
478   return cat->n_cats_total;
479 }
480
481 size_t
482 categoricals_df_total (const struct categoricals *cat)
483 {
484   if (NULL == cat)
485     return 0;
486
487   return cat->df_sum;
488 }
489
490 bool
491 categoricals_is_complete (const struct categoricals *cat)
492 {
493   return (NULL != cat->reverse_variable_map_short);
494 }
495
496
497 /* This function must be called *before* any call to categoricals_get_*_by subscript and
498  *after* all calls to categoricals_update */
499 void
500 categoricals_done (const struct categoricals *cat_)
501 {
502   /* Implementation Note: Whilst this function is O(n) in cat->n_cats_total, in most
503      uses it will be more efficient that using a tree based structure, since it
504      is called only once, and means that subsequent lookups will be O(1).
505
506      1 call of O(n) + 10^9 calls of O(1) is better than 10^9 calls of O(log n).
507   */
508   struct categoricals *cat = CONST_CAST (struct categoricals *, cat_);
509   int v;
510   int i;
511   int idx_short = 0;
512   int idx_long = 0;
513
514   if (NULL == cat)
515     return;
516
517   cat->df_sum = 0;
518   cat->n_cats_total = 0;
519
520   /* Calculate the degrees of freedom, and the number of categories */
521   for (i = 0 ; i < cat->n_iap; ++i)
522     {
523       int df = 1;
524       const struct interaction *iact = cat->iap[i].iact;
525
526       cat->iap[i].df_prod = iact->n_vars ? xcalloc (iact->n_vars, sizeof (int)) : NULL;
527
528       cat->iap[i].n_cats = 1;
529       
530       for (v = 0 ; v < iact->n_vars; ++v)
531         {
532           int x;
533           const struct variable *var = iact->vars[v];
534
535           struct variable_node *vn = lookup_variable (&cat->varmap, var, hash_pointer (var, 0));
536
537           struct value_node *valnd = NULL;
538           struct value_node **array ;
539
540           assert (vn->n_vals == hmap_count (&vn->valmap));
541
542           if  (vn->n_vals == 0)
543             {
544               cat->sane = false;
545               return;
546             }
547
548           /* Sort the VALMAP here */
549           array = xcalloc (sizeof *array, vn->n_vals);
550           x = 0;
551           HMAP_FOR_EACH (valnd, struct value_node, node, &vn->valmap)
552             {
553               /* Note: This loop is probably superfluous, it could be done in the 
554                update stage (at the expense of a realloc) */
555               array[x++] = valnd;
556             }
557
558           sort (array, vn->n_vals, sizeof (*array), 
559                 compare_value_node_3way, vn);
560
561           for (x = 0; x <  vn->n_vals; ++x)
562             {
563               struct value_node *vvv = array[x];
564               vvv->index = x;
565             }
566           free (array);
567
568           cat->iap[i].df_prod[v] = df * (vn->n_vals - 1);
569           df = cat->iap[i].df_prod[v];
570
571           cat->iap[i].n_cats *= vn->n_vals;
572         }
573
574       if (v > 0)
575         cat->df_sum += cat->iap[i].df_prod [v - 1];
576
577       cat->n_cats_total += cat->iap[i].n_cats;
578     }
579
580
581   cat->reverse_variable_map_short = pool_calloc (cat->pool,
582                                                  cat->df_sum,
583                                                  sizeof *cat->reverse_variable_map_short);
584
585   cat->reverse_variable_map_long = pool_calloc (cat->pool,
586                                                 cat->n_cats_total,
587                                                 sizeof *cat->reverse_variable_map_long);
588
589   for (i = 0 ; i < cat->n_iap; ++i)
590     {
591       struct interaction_value *ivn = NULL;
592       int x = 0;
593       int ii;
594       struct interact_params *iap = &cat->iap[i];
595
596       iap->base_subscript_short = idx_short;
597       iap->base_subscript_long = idx_long;
598
599       iap->reverse_interaction_value_map = pool_calloc (cat->pool, iap->n_cats,
600                                                         sizeof *iap->reverse_interaction_value_map);
601
602       HMAP_FOR_EACH (ivn, struct interaction_value, node, &iap->ivmap)
603         {
604           iap->reverse_interaction_value_map[x++] = ivn;
605         }
606
607       assert (x <= iap->n_cats);
608
609       /* For some purposes (eg CONTRASTS in ONEWAY) the values need to be sorted */
610       sort (iap->reverse_interaction_value_map, x, sizeof (*iap->reverse_interaction_value_map),
611             compare_interaction_value_3way, iap);
612
613       /* Fill the remaining values with null */
614       for (ii = x ; ii < iap->n_cats; ++ii)
615         iap->reverse_interaction_value_map[ii] = NULL;
616
617       /* Populate the reverse variable maps. */
618       if (iap->df_prod)
619         {
620           for (ii = 0; ii < iap->df_prod [iap->iact->n_vars - 1]; ++ii)
621             cat->reverse_variable_map_short[idx_short++] = i;
622         }
623
624       for (ii = 0; ii < iap->n_cats; ++ii)
625         cat->reverse_variable_map_long[idx_long++] = i;
626     }
627
628   assert (cat->n_vars <= cat->n_iap);
629
630   categoricals_dump (cat);
631
632   /* Tally up the sums for all the encodings */
633   for (i = 0 ; i < cat->n_iap; ++i)
634     {
635       int x, y;
636       struct interact_params *iap = &cat->iap[i];
637       const struct interaction *iact = iap->iact;
638
639       const int df = iap->df_prod ? iap->df_prod [iact->n_vars - 1] : 0;
640
641       iap->enc_sum = xcalloc (df, sizeof (*(iap->enc_sum)));
642
643       for (y = 0; y < hmap_count (&iap->ivmap); ++y)
644         {
645           struct interaction_value *iv = iap->reverse_interaction_value_map[y];
646           for (x = iap->base_subscript_short; x < iap->base_subscript_short + df ;++x)
647             {
648               const double bin = categoricals_get_effects_code_for_case (cat, x, iv->ccase);
649               iap->enc_sum [x - iap->base_subscript_short] += bin * iv->cc;
650             }
651           if (cat->payload && cat->payload->calculate)
652             cat->payload->calculate (cat->aux1, cat->aux2, iv->user_data);
653         }
654     }
655
656   cat->sane = true;
657 }
658
659
660 static int
661 reverse_variable_lookup_short (const struct categoricals *cat, int subscript)
662 {
663   assert (cat->reverse_variable_map_short);
664   assert (subscript >= 0);
665   assert (subscript < cat->df_sum);
666
667   return cat->reverse_variable_map_short[subscript];
668 }
669
670 static int
671 reverse_variable_lookup_long (const struct categoricals *cat, int subscript)
672 {
673   assert (cat->reverse_variable_map_long);
674   assert (subscript >= 0);
675   assert (subscript < cat->n_cats_total);
676
677   return cat->reverse_variable_map_long[subscript];
678 }
679
680
681 /* Return the interaction corresponding to SUBSCRIPT */
682 const struct interaction *
683 categoricals_get_interaction_by_subscript (const struct categoricals *cat, int subscript)
684 {
685   int index = reverse_variable_lookup_short (cat, subscript);
686
687   return cat->iap[index].iact;
688 }
689
690 double
691 categoricals_get_weight_by_subscript (const struct categoricals *cat, int subscript)
692 {
693   int vindex = reverse_variable_lookup_short (cat, subscript);
694   const struct interact_params *vp = &cat->iap[vindex];
695
696   return vp->cc;
697 }
698
699 double
700 categoricals_get_sum_by_subscript (const struct categoricals *cat, int subscript)
701 {
702   int vindex = reverse_variable_lookup_short (cat, subscript);
703   const struct interact_params *vp = &cat->iap[vindex];
704
705   return   vp->enc_sum[subscript - vp->base_subscript_short];
706 }
707
708
709 /* Returns unity if the value in case C at SUBSCRIPT is equal to the category
710    for that subscript */
711 static double
712 categoricals_get_code_for_case (const struct categoricals *cat, int subscript,
713                                 const struct ccase *c,
714                                 bool effects_coding)
715 {
716   const struct interaction *iact = categoricals_get_interaction_by_subscript (cat, subscript);
717
718   const int i = reverse_variable_lookup_short (cat, subscript);
719
720   const int base_index = cat->iap[i].base_subscript_short;
721
722   int v;
723   double result = 1.0;
724
725   const struct interact_params *iap = &cat->iap[i];
726
727   double dfp = 1.0;
728   for (v = 0; v < iact->n_vars; ++v)
729     {
730       const struct variable *var = iact->vars[v];
731
732       const union value *val = case_data (c, var);
733       const int width = var_get_width (var);
734       const struct variable_node *vn = lookup_variable (&cat->varmap, var, hash_pointer (var, 0));
735
736       const unsigned int hash = value_hash (val, width, 0);
737       const struct value_node *valn = lookup_value (&vn->valmap, val, hash, width);
738
739       double bin = 1.0;
740
741       const double df = iap->df_prod[v] / dfp;
742
743       /* Translate the subscript into an index for the individual variable */
744       const int index = ((subscript - base_index) % iap->df_prod[v] ) / dfp;
745       dfp = iap->df_prod [v];
746
747       if (effects_coding && valn->index == df )
748         bin = -1.0;
749       else if ( valn->index != index )
750         bin = 0;
751     
752       result *= bin;
753     }
754
755   return result;
756 }
757
758
759 /* Returns unity if the value in case C at SUBSCRIPT is equal to the category
760    for that subscript */
761 double
762 categoricals_get_dummy_code_for_case (const struct categoricals *cat, int subscript,
763                                      const struct ccase *c)
764 {
765   return categoricals_get_code_for_case (cat, subscript, c, false);
766 }
767
768 /* Returns unity if the value in case C at SUBSCRIPT is equal to the category
769    for that subscript. 
770    Else if it is the last category, return -1.
771    Otherwise return 0.
772  */
773 double
774 categoricals_get_effects_code_for_case (const struct categoricals *cat, int subscript,
775                                         const struct ccase *c)
776 {
777   return categoricals_get_code_for_case (cat, subscript, c, true);
778 }
779
780
781 size_t
782 categoricals_get_n_variables (const struct categoricals *cat)
783 {
784   printf ("%s\n", __FUNCTION__);
785   return cat->n_vars;
786 }
787
788
789 /* Return a case containing the set of values corresponding to 
790    the Nth Category of the IACTth interaction */
791 const struct ccase *
792 categoricals_get_case_by_category_real (const struct categoricals *cat, int iact, int n)
793 {
794   const struct interaction_value *vn;
795
796   const struct interact_params *vp = &cat->iap[iact];
797
798   if ( n >= hmap_count (&vp->ivmap))
799     return NULL;
800
801   vn = vp->reverse_interaction_value_map [n];
802
803   return vn->ccase;
804 }
805
806 /* Return a the user data corresponding to the Nth Category of the IACTth interaction. */
807 void *
808 categoricals_get_user_data_by_category_real (const struct categoricals *cat, int iact, int n)
809 {
810   const struct interact_params *vp = &cat->iap[iact];
811   const struct interaction_value *iv ;
812
813   if ( n >= hmap_count (&vp->ivmap))
814     return NULL;
815
816   iv = vp->reverse_interaction_value_map [n];
817
818   return iv->user_data;
819 }
820
821
822
823 /* Return a case containing the set of values corresponding to SUBSCRIPT */
824 const struct ccase *
825 categoricals_get_case_by_category (const struct categoricals *cat, int subscript)
826 {
827   int vindex = reverse_variable_lookup_long (cat, subscript);
828   const struct interact_params *vp = &cat->iap[vindex];
829   const struct interaction_value *vn = vp->reverse_interaction_value_map [subscript - vp->base_subscript_long];
830
831   return vn->ccase;
832 }
833
834 void *
835 categoricals_get_user_data_by_category (const struct categoricals *cat, int subscript)
836 {
837   int vindex = reverse_variable_lookup_long (cat, subscript);
838   const struct interact_params *vp = &cat->iap[vindex];
839
840   const struct interaction_value *iv = vp->reverse_interaction_value_map [subscript - vp->base_subscript_long];
841   return iv->user_data;
842 }
843
844
845 \f
846
847 void
848 categoricals_set_payload (struct categoricals *cat, const struct payload *p,
849                           const void *aux1, void *aux2)
850 {
851   cat->payload = p;
852   cat->aux1 = aux1;
853   cat->aux2 = aux2;
854 }