src/data/category.c

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