src/data/category.c

   1 /* PSPP - binary encodings for categorical variables.
   2    Copyright (C) 2005 Free Software Foundation, Inc.
   3    Written by Jason H Stover <jason@sakla.net>.
   4
   5    This program is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU General Public License as
   7    published by the Free Software Foundation; either version 2 of the
   8    License, or (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful, but
  11    WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program; if not, write to the Free Software
  17    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  18    02110-1301, USA. */
  19
  20 /*
  21   Functions and data structures to store values of a categorical
  22   variable, and to recode those values into binary vectors.
  23
  24   For some statistical models, it is necessary to change each value
  25   of a categorical variable to a vector with binary entries. These
  26   vectors are then stored as sub-rows within a matrix during
  27   model-fitting. For example, we need functions and data strucutres to map a
  28   value, say 'a', of a variable named 'cat_var', to a vector, say (0
  29   1 0 0 0), and vice versa.  We also need to be able to map the
  30   vector back to the value 'a', and if the vector is a sub-row of a
  31   matrix, we need to know which sub-row corresponds to the variable
  32   'cat_var'.
  33 */
  34 #include <config.h>
  35 #include <stdlib.h>
  36 #include <message.h>
  37 #include "alloc.h"
  38 #include "message.h"
  39 #include "category.h"
  40 #include "cat-routines.h"
  41 #include <string.h>
  42 #include "variable.h"
  43
  44 #define N_INITIAL_CATEGORIES 1
  45
  46 void
  47 cat_stored_values_create (struct variable *v)
  48 {
  49   if (v->obs_vals == NULL)
  50     {
  51       v->obs_vals = xmalloc (sizeof (*v->obs_vals));
  52       v->obs_vals->n_categories = 0;
  53       v->obs_vals->n_allocated_categories = N_INITIAL_CATEGORIES;
  54       v->obs_vals->vals =
  55         xnmalloc (N_INITIAL_CATEGORIES, sizeof *v->obs_vals->vals);
  56     }
  57 }
  58
  59 void
  60 cat_stored_values_destroy (struct variable *v)
  61 {
  62   assert (v != NULL);
  63   if (v->obs_vals != NULL)
  64     {
  65       free (v->obs_vals);
  66     }
  67 }
  68
  69 /*
  70   Which subscript corresponds to val?
  71  */
  72 size_t
  73 cat_value_find (const struct variable *v, const union value *val)
  74 {
  75   size_t i;
  76   const union value *candidate;
  77
  78   assert (val != NULL);
  79   assert (v != NULL);
  80   assert (v->obs_vals != NULL);
  81   for (i = 0; i < v->obs_vals->n_categories; i++)
  82     {
  83       candidate = v->obs_vals->vals + i;
  84       assert (candidate != NULL);
  85       if (!compare_values (candidate, val, v->width))
  86         {
  87           return i;
  88         }
  89     }
  90   return CAT_VALUE_NOT_FOUND;
  91 }
  92
  93 /*
  94    Add the new value unless it is already present.
  95  */
  96 void
  97 cat_value_update (struct variable *v, const union value *val)
  98 {
  99   struct cat_vals *cv;
 100
 101   if (v->type == ALPHA)
 102     {
 103       assert (val != NULL);
 104       assert (v != NULL);
 105       cv = v->obs_vals;
 106       if (cat_value_find (v, val) == CAT_VALUE_NOT_FOUND)
 107         {
 108           if (cv->n_categories >= cv->n_allocated_categories)
 109             {
 110               cv->n_allocated_categories *= 2;
 111               cv->vals = xnrealloc (cv->vals,
 112                                     cv->n_allocated_categories,
 113                                     sizeof *cv->vals);
 114             }
 115           cv->vals[cv->n_categories] = *val;
 116           cv->n_categories++;
 117         }
 118     }
 119 }
 120
 121 union value *
 122 cat_subscript_to_value (const size_t s, struct variable *v)
 123 {
 124   assert (v->obs_vals != NULL);
 125   if (s < v->obs_vals->n_categories)
 126     {
 127       return (v->obs_vals->vals + s);
 128     }
 129   else
 130     {
 131       return NULL;
 132     }
 133 }
 134
 135 /*
 136   Return the number of categories of a categorical variable.
 137  */
 138 size_t
 139 cat_get_n_categories (const struct variable *v)
 140 {
 141   return v->obs_vals->n_categories;
 142 }
 143