pintos-os.org Git - pspp/blob - src/math/categoricals.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 2009, 2010, 2011, 2012 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 #ifndef _CATEGORICALS__
  19 #define _CATEGORICALS__
  20
  21 #include <stddef.h>
  22 #include "data/missing-values.h"
  23
  24 struct categoricals;
  25 struct variable;
  26 struct ccase;
  27 struct interaction;
  28
  29 union value ;
  30
  31 struct categoricals *categoricals_create (struct interaction *const*, size_t n_int,
  32                                           const struct variable *wv, enum mv_class dep_excl,
  33                                           enum mv_class fctr_excl);
  34
  35 void categoricals_destroy (struct categoricals *);
  36
  37 void categoricals_update (struct categoricals *cat, const struct ccase *c);
  38
  39
  40 /* Return the number of categories (distinct values) for variable N */
  41 size_t categoricals_n_count (const struct categoricals *cat, size_t n);
  42
  43 size_t categoricals_df (const struct categoricals *cat, size_t n);
  44
  45 /* Return the total number of categories */
  46 size_t categoricals_n_total (const struct categoricals *cat);
  47
  48 /* Return the total degrees of freedom */
  49 size_t categoricals_df_total (const struct categoricals *cat);
  50
  51
  52 /*
  53   Return the total number of variables which participated in these categoricals.
  54   Due to the possibility of missing values, this is NOT necessarily
  55   equal to the number of variables passed in when the object was
  56   created.
  57 */
  58 size_t categoricals_get_n_variables (const struct categoricals *cat);
  59
  60 bool categoricals_is_complete (const struct categoricals *cat);
  61
  62
  63 /*
  64   Must be called (once) before any call to the *_by_subscript or *_by_category
  65   functions, but AFTER any calls to categoricals_update.
  66   If this function returns false, then no calls to _by_subscript or *_by_category
  67   are allowed.
  68 */
  69 void categoricals_done (const struct categoricals *cat);
  70
  71 bool categoricals_sane (const struct categoricals *cat);
  72
  73
  74 /*
  75   The *_by_subscript functions use the short map.
  76   Their intended use is by covariance matrix routines, where normally 1 less than
  77   the total number of distinct values of each categorical variable should
  78   be considered.
  79  */
  80 double categoricals_get_weight_by_subscript (const struct categoricals *cat, int subscript);
  81 const struct interaction *categoricals_get_interaction_by_subscript (const struct categoricals *cat, int subscript);
  82
  83 double categoricals_get_sum_by_subscript (const struct categoricals *cat, int subscript);
  84
  85 /* Returns unity if the value in case C at SUBSCRIPT is equal to the category
  86    for that subscript */
  87 double
  88 categoricals_get_dummy_code_for_case (const struct categoricals *cat, int subscript,
  89                                      const struct ccase *c);
  90
  91 /* Returns unity if the value in case C at SUBSCRIPT is equal to the category
  92    for that subscript.
  93    Else if it is the last category, return -1.
  94    Otherwise return 0.
  95  */
  96 double
  97 categoricals_get_effects_code_for_case (const struct categoricals *cat, int subscript,
  98                                         const struct ccase *c);
  99
 100
 101 /* These use the long map.  Useful for descriptive statistics. */
 102
 103
 104 const struct ccase *
 105 categoricals_get_case_by_category_real (const struct categoricals *cat, int iact, int n);
 106
 107 void *
 108 categoricals_get_user_data_by_category_real (const struct categoricals *cat, int iact, int n);
 109
 110
 111 void * categoricals_get_user_data_by_category (const struct categoricals *cat, int category);
 112
 113 const struct ccase * categoricals_get_case_by_category (const struct categoricals *cat, int subscript);
 114
 115
 116 struct payload
 117 {
 118   void* (*create)  (const void *aux1, void *aux2);
 119   void (*update)  (const void *aux1, void *aux2, void *user_data, const struct ccase *, double weight);
 120   void (*calculate) (const void *aux1, void *aux2, void *user_data);
 121   void (*destroy) (const void *aux1, void *aux2, void *user_data);
 122 };
 123
 124
 125 void  categoricals_set_payload (struct categoricals *cats, const struct payload *p, const void *aux1, void *aux2);
 126
 127 bool categoricals_isbalanced (const struct categoricals *cat);
 128
 129 #endif