src/data/category.h

   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 recode categorical variables into
  19   vectors and sub-rows of matrices.
  20
  21   To fit many types of statistical models, it is necessary
  22   to change each value of a categorical variable to a vector with binary
  23   entries. These vectors are then stored as sub-rows within a matrix
  24   during model-fitting. We need functions and data strucutres to,
  25   e.g., map a value, say 'a', of a variable named 'cat_var', to a
  26   vector, say (0 1 0 0 0), and vice versa.  We also need to be able
  27   to map the vector back to the value 'a', and if the vector is a
  28   sub-row of a matrix, we need to know which sub-row corresponds to
  29   the variable 'cat_var'.
  30
  31  */
  32
  33 #ifndef CATEGORY_H
  34 #define CATEGORY_H
  35 #include <stdbool.h>
  36 #include <stddef.h>
  37
  38 struct cat_vals;
  39 struct variable ;
  40 union value;
  41
  42 void cat_stored_values_create (const struct variable *);
  43 void cat_stored_values_destroy (struct cat_vals *);
  44
  45 size_t cat_value_find (const struct variable *, const union value *);
  46
  47 const union value *cat_subscript_to_value (const size_t,
  48                                            const struct variable *);
  49
  50
  51 void cat_value_update (const struct variable *, const union value *);
  52
  53 /*
  54   Return the count for the sth category.
  55 */
  56 size_t
  57 cat_get_category_count (const size_t, const struct variable *);
  58
  59 /*
  60   Return the number of categories of a categorical variable.
  61  */
  62 size_t  cat_get_n_categories (const struct variable *v);
  63
  64 /*
  65   If VAR is categorical with d categories, its first category should
  66   correspond to the origin in d-dimensional Euclidean space.
  67  */
  68 bool cat_is_origin (const struct variable *, const union value *);
  69 #endif