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