src/data/category.c

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 2005 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 /*
  18   Functions and data structures to store values of a categorical
  19   variable, and to recode those values into binary vectors.
  20
  21   For some statistical models, it is necessary to change each value
  22   of a categorical variable to a vector with binary entries. These
  23   vectors are then stored as sub-rows within a matrix during
  24   model-fitting. For example, we need functions and data strucutres to map a
  25   value, say 'a', of a variable named 'cat_var', to a vector, say (0
  26   1 0 0 0), and vice versa.  We also need to be able to map the
  27   vector back to the value 'a', and if the vector is a sub-row of a
  28   matrix, we need to know which sub-row corresponds to the variable
  29   'cat_var'.
  30 */
  31 #include <config.h>
  32
  33 #include <assert.h>
  34 #include <stdlib.h>
  35 #include <string.h>
  36
  37 #include <libpspp/message.h>
  38 #include "category.h"
  39 #include "value.h"
  40 #include "variable.h"
  41
  42 #include "xalloc.h"
  43
  44 #define CAT_VALUE_NOT_FOUND -1
  45
  46 #define N_INITIAL_CATEGORIES 1
  47
  48 /*
  49   This structure contains the observed values of a
  50   categorical variable.
  51  */
  52 struct cat_vals
  53 {
  54   union value *vals;
  55   size_t n_categories;
  56   size_t n_allocated_categories;        /* This is used only during
  57                                            initialization to keep
  58                                            track of the number of
  59                                            values stored.
  60                                          */
  61   size_t *value_counts; /* Element i stores the number of cases for which
  62                            the categorical variable has that corresponding
  63                            value. This is necessary for computing covariance
  64                            matrices.
  65                          */
  66 };
  67
  68 void
  69 cat_stored_values_create (const struct variable *v)
  70 {
  71   if (!var_has_obs_vals (v))
  72     {
  73       struct cat_vals *obs_vals = xmalloc (sizeof *obs_vals);
  74
  75       obs_vals->n_categories = 0;
  76       obs_vals->n_allocated_categories = N_INITIAL_CATEGORIES;
  77       obs_vals->vals = xnmalloc (N_INITIAL_CATEGORIES, sizeof *obs_vals->vals);
  78       obs_vals->value_counts = xnmalloc (N_INITIAL_CATEGORIES, sizeof *obs_vals->value_counts);
  79       var_set_obs_vals (v, obs_vals);
  80     }
  81 }
  82
  83 void
  84 cat_stored_values_destroy (struct cat_vals *obs_vals)
  85 {
  86   if (obs_vals != NULL)
  87     {
  88       if (obs_vals->n_allocated_categories > 0)
  89         {
  90           free (obs_vals->vals);
  91           free (obs_vals->value_counts);
  92         }
  93       free (obs_vals);
  94     }
  95 }
  96
  97 /*
  98   Which subscript corresponds to val?
  99  */
 100 size_t
 101 cat_value_find (const struct variable *v, const union value *val)
 102 {
 103   struct cat_vals *obs_vals = var_get_obs_vals (v);
 104   size_t i;
 105   const union value *candidate;
 106
 107   for (i = 0; i < obs_vals->n_categories; i++)
 108     {
 109       candidate = obs_vals->vals + i;
 110       assert (candidate != NULL);
 111       if (!compare_values_short (candidate, val, v))
 112         {
 113           return i;
 114         }
 115     }
 116   return CAT_VALUE_NOT_FOUND;
 117 }
 118
 119 /*
 120    Add the new value unless it is already present. Increment the count.
 121  */
 122 void
 123 cat_value_update (const struct variable *v, const union value *val)
 124 {
 125   if (var_is_alpha (v))
 126     {
 127       size_t i;
 128       struct cat_vals *cv = var_get_obs_vals (v);
 129       i = cat_value_find (v, val);
 130       if (i == CAT_VALUE_NOT_FOUND)
 131         {
 132           if (cv->n_categories >= cv->n_allocated_categories)
 133             {
 134               cv->n_allocated_categories *= 2;
 135               cv->vals = xnrealloc (cv->vals,
 136                                     cv->n_allocated_categories,
 137                                     sizeof *cv->vals);
 138               cv->value_counts = xnrealloc (cv->value_counts, cv->n_allocated_categories,
 139                                             sizeof *cv->value_counts);
 140             }
 141           cv->vals[cv->n_categories] = *val;
 142           cv->value_counts[cv->n_categories] = 1;
 143           cv->n_categories++;
 144         }
 145       else
 146         {
 147           cv->value_counts[i]++;
 148         }
 149     }
 150 }
 151 /*
 152   Return the count for the sth category.
 153  */
 154 size_t
 155 cat_get_category_count (const size_t s, const struct variable *v)
 156 {
 157   struct cat_vals *tmp;
 158   size_t n_categories;
 159
 160   tmp = var_get_obs_vals (v);
 161   n_categories = cat_get_n_categories (v);
 162   if (s < n_categories)
 163     {
 164       return tmp->value_counts[s];
 165     }
 166   return CAT_VALUE_NOT_FOUND;
 167 }
 168
 169 const union value *
 170 cat_subscript_to_value (const size_t s, const struct variable *v)
 171 {
 172   struct cat_vals *obs_vals = var_get_obs_vals (v);
 173   return s < obs_vals->n_categories ? obs_vals->vals + s : NULL;
 174 }
 175
 176 /*
 177   Return the number of categories of a categorical variable.
 178  */
 179 size_t
 180 cat_get_n_categories (const struct variable *v)
 181 {
 182   return var_get_obs_vals (v)->n_categories;
 183 }
 184