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
  36 #include "category.h"
  37
  38 #include <assert.h>
  39 #include <stdlib.h>
  40 #include <string.h>
  41
  42 #include <libpspp/alloc.h>
  43 #include <libpspp/message.h>
  44 #include "category.h"
  45 #include "value.h"
  46 #include "variable.h"
  47
  48 #define CAT_VALUE_NOT_FOUND -2
  49
  50 #define N_INITIAL_CATEGORIES 1
  51
  52 /*
  53   This structure contains the observed values of a
  54   categorical variable.
  55  */
  56 struct cat_vals
  57 {
  58   union value *vals;
  59   size_t n_categories;
  60   size_t n_allocated_categories;        /* This is used only during
  61                                            initialization to keep
  62                                            track of the number of
  63                                            values stored.
  64                                          */
  65 };
  66
  67 void
  68 cat_stored_values_create (const struct variable *v)
  69 {
  70   if (!var_has_obs_vals (v))
  71     {
  72       struct cat_vals *obs_vals = xmalloc (sizeof *obs_vals);
  73
  74       obs_vals->n_categories = 0;
  75       obs_vals->n_allocated_categories = N_INITIAL_CATEGORIES;
  76       obs_vals->vals = xnmalloc (N_INITIAL_CATEGORIES, sizeof *obs_vals->vals);
  77       var_set_obs_vals (v, obs_vals);
  78     }
  79 }
  80
  81 void
  82 cat_stored_values_destroy (struct cat_vals *obs_vals)
  83 {
  84   if (obs_vals != NULL)
  85     {
  86       if (obs_vals->n_allocated_categories > 0)
  87         free (obs_vals->vals);
  88       free (obs_vals);
  89     }
  90 }
  91
  92 /*
  93   Which subscript corresponds to val?
  94  */
  95 size_t
  96 cat_value_find (const struct variable *v, const union value *val)
  97 {
  98   struct cat_vals *obs_vals = var_get_obs_vals (v);
  99   size_t i;
 100   const union value *candidate;
 101
 102   for (i = 0; i < obs_vals->n_categories; i++)
 103     {
 104       candidate = obs_vals->vals + i;
 105       assert (candidate != NULL);
 106       if (!compare_values (candidate, val, var_get_width (v)))
 107         {
 108           return i;
 109         }
 110     }
 111   return CAT_VALUE_NOT_FOUND;
 112 }
 113
 114 /*
 115    Add the new value unless it is already present.
 116  */
 117 void
 118 cat_value_update (const struct variable *v, const union value *val)
 119 {
 120   if (var_is_alpha (v))
 121     {
 122       struct cat_vals *cv = var_get_obs_vals (v);
 123       if (cat_value_find (v, val) == CAT_VALUE_NOT_FOUND)
 124         {
 125           if (cv->n_categories >= cv->n_allocated_categories)
 126             {
 127               cv->n_allocated_categories *= 2;
 128               cv->vals = xnrealloc (cv->vals,
 129                                     cv->n_allocated_categories,
 130                                     sizeof *cv->vals);
 131             }
 132           cv->vals[cv->n_categories] = *val;
 133           cv->n_categories++;
 134         }
 135     }
 136 }
 137
 138 const union value *
 139 cat_subscript_to_value (const size_t s, const struct variable *v)
 140 {
 141   struct cat_vals *obs_vals = var_get_obs_vals (v);
 142   return s < obs_vals->n_categories ? obs_vals->vals + s : NULL;
 143 }
 144
 145 /*
 146   Return the number of categories of a categorical variable.
 147  */
 148 size_t
 149 cat_get_n_categories (const struct variable *v)
 150 {
 151   return var_get_obs_vals (v)->n_categories;
 152 }
 153