src/var.h

   1 /* PSPP - computes sample statistics.
   2    Copyright (C) 1997-9, 2000 Free Software Foundation, Inc.
   3    Written by Ben Pfaff <blp@gnu.org>.
   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., 59 Temple Place - Suite 330, Boston, MA
  18    02111-1307, USA. */
  19
  20 #if !var_h
  21 #define var_h 1
  22
  23 #include <stddef.h>
  24 #include "format.h"
  25 #include "t-test.h"
  26 #include "oneway.h"
  27 #include "val.h"
  28
  29 /* Frequency tables. */
  30
  31 /* Frequency table entry. */
  32 struct freq
  33   {
  34     union value v;              /* The value. */
  35     double c;                   /* The number of occurrences of the value. */
  36   };
  37
  38 /* Types of frequency tables. */
  39 enum
  40   {
  41     FRQM_GENERAL,
  42     FRQM_INTEGER
  43   };
  44
  45 /* Entire frequency table. */
  46 struct freq_tab
  47   {
  48     int mode;                   /* FRQM_GENERAL or FRQM_INTEGER. */
  49
  50     /* General mode. */
  51     struct hsh_table *data;     /* Undifferentiated data. */
  52
  53     /* Integer mode. */
  54     double *vector;             /* Frequencies proper. */
  55     int min, max;               /* The boundaries of the table. */
  56     double out_of_range;        /* Sum of weights of out-of-range values. */
  57     double sysmis;              /* Sum of weights of SYSMIS values. */
  58
  59     /* All modes. */
  60     struct freq *valid;         /* Valid freqs. */
  61     int n_valid;                /* Number of total freqs. */
  62
  63     struct freq *missing;       /* Missing freqs. */
  64     int n_missing;              /* Number of missing freqs. */
  65
  66     /* Statistics. */
  67     double total_cases;         /* Sum of weights of all cases. */
  68     double valid_cases;         /* Sum of weights of valid cases. */
  69   };
  70 \f
  71 /* Procedures' private per-variable data. */
  72
  73 /* Structure name suffixes for private data:
  74    _proc: for a procedure (i.e., LIST -> list_proc).
  75    _trns: for a transformation (i.e., COMPUTE -> compute_trns.
  76    _pgm: for an input program (i.e., DATA LIST -> data_list_pgm). */
  77
  78 /* CROSSTABS private data. */
  79 struct crosstab_proc
  80   {
  81     /* Integer mode only. */
  82     int min;                    /* Minimum value. */
  83     int max;                    /* Maximum value + 1. */
  84     int count;                  /* max - min. */
  85   };
  86
  87
  88 /* FREQUENCIES private data. */
  89 enum
  90   {
  91     frq_mean = 0, frq_semean, frq_median, frq_mode, frq_stddev, frq_variance,
  92     frq_kurt, frq_sekurt, frq_skew, frq_seskew, frq_range, frq_min, frq_max,
  93     frq_sum, frq_n_stats
  94   };
  95
  96 struct frequencies_proc
  97   {
  98     int used;                   /* 1=This variable already used. */
  99
 100     /* Freqency table. */
 101     struct freq_tab tab;        /* Frequencies table to use. */
 102
 103     /* Percentiles. */
 104     int n_groups;               /* Number of groups. */
 105     double *groups;             /* Groups. */
 106
 107     /* Statistics. */
 108     double stat[frq_n_stats];
 109   };
 110
 111 /* LIST private data. */
 112 struct list_proc
 113   {
 114     int newline;                /* Whether a new line begins here. */
 115     int width;                  /* Field width. */
 116     int vert;                   /* Whether to print the varname vertically. */
 117   };
 118
 119 /* GET private data. */
 120 struct get_proc
 121   {
 122     int fv, nv;                 /* First, # of values. */
 123   };
 124
 125 /* MEANS private data. */
 126 struct means_proc
 127   {
 128     double min, max;            /* Range for integer mode. */
 129   };
 130
 131 /* Different types of variables for MATRIX DATA procedure.  Order is
 132    important: these are used for sort keys. */
 133 enum
 134   {
 135     MXD_SPLIT,                  /* SPLIT FILE variables. */
 136     MXD_ROWTYPE,                /* ROWTYPE_. */
 137     MXD_FACTOR,                 /* Factor variables. */
 138     MXD_VARNAME,                /* VARNAME_. */
 139     MXD_CONTINUOUS,             /* Continuous variables. */
 140
 141     MXD_COUNT
 142   };
 143
 144 /* MATRIX DATA private data. */
 145 struct matrix_data_proc
 146   {
 147     int vartype;                /* Variable type. */
 148     int subtype;                /* Subtype. */
 149   };
 150
 151 /* MATCH FILES private data. */
 152 struct match_files_proc
 153   {
 154     struct variable *master;    /* Corresponding master file variable. */
 155   };
 156
 157 \f
 158 /* Script variables. */
 159
 160 /* Variable type. */
 161 enum
 162   {
 163     NUMERIC,                    /* A numeric variable. */
 164     ALPHA                       /* A string variable.  (STRING is pre-empted by lexer.h) */
 165   };
 166
 167 /* Types of missing values.  Order is significant, see
 168    mis-val.c:parse_numeric(), sfm-read.c:sfm_read_dictionary()
 169    sfm-write.c:sfm_write_dictionary(),
 170    sysfile-info.c:cmd_sysfile_info(), mis-val.c:copy_missing_values(),
 171    pfm-read.c:read_variables(), pfm-write.c:write_variables(),
 172    apply-dict.c:cmd_apply_dictionary(), and more (?). */
 173 enum
 174   {
 175     MISSING_NONE,               /* No user-missing values. */
 176     MISSING_1,                  /* One user-missing value. */
 177     MISSING_2,                  /* Two user-missing values. */
 178     MISSING_3,                  /* Three user-missing values. */
 179     MISSING_RANGE,              /* [a,b]. */
 180     MISSING_LOW,                /* (-inf,a]. */
 181     MISSING_HIGH,               /* (a,+inf]. */
 182     MISSING_RANGE_1,            /* [a,b], c. */
 183     MISSING_LOW_1,              /* (-inf,a], b. */
 184     MISSING_HIGH_1,             /* (a,+inf), b. */
 185     MISSING_COUNT
 186   };
 187
 188 /* A variable's dictionary entry.  */
 189 struct variable
 190   {
 191     char name[9];               /* As a string. */
 192     int index;                  /* Index into its dictionary's var[]. */
 193     int type;                   /* NUMERIC or ALPHA. */
 194
 195     int width;                  /* Size of string variables in chars. */
 196     int fv, nv;                 /* Index into `value's, number of values. */
 197     unsigned init : 1;          /* 1=VFM must init and possibly reinit. */
 198     unsigned reinit : 1;        /* Cases are: 1=reinitialized; 0=left. */
 199
 200     /* Missing values. */
 201     int miss_type;              /* One of the MISSING_* constants. */
 202     union value missing[3];     /* User-missing value. */
 203
 204     /* Display formats. */
 205     struct fmt_spec print;      /* Default format for PRINT. */
 206     struct fmt_spec write;      /* Default format for WRITE. */
 207
 208     /* Labels. */
 209     struct val_labs *val_labs;
 210     char *label;                /* Variable label. */
 211
 212     /* Per-procedure info. */
 213     void *aux;
 214     struct get_proc get;
 215     union
 216       {
 217         struct crosstab_proc crs;
 218         struct frequencies_proc frq;
 219         struct list_proc lst;
 220         struct means_proc mns;
 221         struct matrix_data_proc mxd;
 222         struct match_files_proc mtf;
 223         struct t_test_proc t_t;
 224         struct oneway_proc ww;
 225       }
 226     p;
 227   };
 228
 229 int compare_variables (const void *, const void *, void *);
 230 unsigned hash_variable (const void *, void *);
 231
 232 /* Classes of variables. */
 233 enum dict_class
 234   {
 235     DC_ORDINARY,                /* Ordinary identifier. */
 236     DC_SYSTEM,                  /* System variable. */
 237     DC_SCRATCH                  /* Scratch variable. */
 238   };
 239
 240 enum dict_class dict_class_from_id (const char *name);
 241 const char *dict_class_to_name (enum dict_class dict_class);
 242 \f
 243 /* Vector of variables. */
 244 struct vector
 245   {
 246     int idx;                    /* Index for dict_get_vector(). */
 247     char name[9];               /* Name. */
 248     struct variable **var;      /* Vector of variables. */
 249     int cnt;                    /* Number of variables. */
 250   };
 251 \f
 252 /* Dictionary. */
 253
 254 /* Complete dictionary state. */
 255 struct dictionary;
 256
 257 struct dictionary *dict_create (void);
 258 struct dictionary *dict_clone (const struct dictionary *);
 259 void dict_clear (struct dictionary *);
 260 void dict_destroy (struct dictionary *);
 261
 262 size_t dict_get_var_cnt (const struct dictionary *);
 263 struct variable *dict_get_var (const struct dictionary *, size_t idx);
 264 void dict_get_vars (const struct dictionary *,
 265                     struct variable ***vars, size_t *cnt,
 266                     unsigned exclude_classes);
 267
 268 struct variable *dict_create_var (struct dictionary *, const char *,
 269                                   int width);
 270 struct variable *dict_create_var_assert (struct dictionary *, const char *,
 271                                   int width);
 272 struct variable *dict_clone_var (struct dictionary *, const struct variable *,
 273                                  const char *);
 274 void dict_rename_var (struct dictionary *, struct variable *, const char *);
 275
 276 struct variable *dict_lookup_var (const struct dictionary *, const char *);
 277 struct variable *dict_lookup_var_assert (const struct dictionary *,
 278                                          const char *);
 279 int dict_contains_var (const struct dictionary *, const struct variable *);
 280 void dict_delete_var (struct dictionary *, struct variable *);
 281 void dict_delete_vars (struct dictionary *,
 282                        struct variable *const *, size_t count);
 283 void dict_reorder_vars (struct dictionary *,
 284                         struct variable *const *, size_t count);
 285 int dict_rename_vars (struct dictionary *,
 286                       struct variable **, char **new_names,
 287                       size_t count, char **err_name);
 288
 289 struct ccase;
 290 struct variable *dict_get_weight (const struct dictionary *);
 291 double dict_get_case_weight (const struct dictionary *,
 292                              const struct ccase *, int *);
 293 void dict_set_weight (struct dictionary *, struct variable *);
 294
 295 struct variable *dict_get_filter (const struct dictionary *);
 296 void dict_set_filter (struct dictionary *, struct variable *);
 297
 298 int dict_get_case_limit (const struct dictionary *);
 299 void dict_set_case_limit (struct dictionary *, int);
 300
 301 int dict_get_next_value_idx (const struct dictionary *);
 302 size_t dict_get_case_size (const struct dictionary *);
 303
 304 void dict_compact_values (struct dictionary *);
 305 size_t dict_get_compacted_value_cnt (const struct dictionary *);
 306 int *dict_get_compacted_idx_to_fv (const struct dictionary *);
 307
 308 struct variable *const *dict_get_split_vars (const struct dictionary *);
 309 size_t dict_get_split_cnt (const struct dictionary *);
 310 void dict_set_split_vars (struct dictionary *,
 311                           struct variable *const *, size_t cnt);
 312
 313 const char *dict_get_label (const struct dictionary *);
 314 void dict_set_label (struct dictionary *, const char *);
 315
 316 const char *dict_get_documents (const struct dictionary *);
 317 void dict_set_documents (struct dictionary *, const char *);
 318
 319 int dict_create_vector (struct dictionary *,
 320                         const char *name,
 321                         struct variable **, size_t cnt);
 322 const struct vector *dict_get_vector (const struct dictionary *,
 323                                       size_t idx);
 324 size_t dict_get_vector_cnt (const struct dictionary *);
 325 const struct vector *dict_lookup_vector (const struct dictionary *,
 326                                          const char *name);
 327 void dict_clear_vectors (struct dictionary *);
 328 \f
 329 void discard_variables (void);
 330
 331 /* This is the active file dictionary. */
 332 extern struct dictionary *default_dict;
 333 \f
 334 /* Transformation state. */
 335
 336 /* Default file handle for DATA LIST, REREAD, REPEATING DATA
 337    commands. */
 338 extern struct file_handle *default_handle;
 339
 340 /* PROCESS IF expression. */
 341 extern struct expression *process_if_expr;
 342 \f
 343 /* TEMPORARY support. */
 344
 345 /* 1=TEMPORARY has been executed at some point. */
 346 extern int temporary;
 347
 348 /* If temporary!=0, the saved dictionary. */
 349 extern struct dictionary *temp_dict;
 350
 351 /* If temporary!=0, index into t_trns[] (declared far below) that
 352    gives the point at which data should be written out.  -1 means that
 353    the data shouldn't be changed since all transformations are
 354    temporary. */
 355 extern int temp_trns;
 356
 357 /* If FILTER is active, whether it was executed before or after
 358    TEMPORARY. */
 359 extern int FILTER_before_TEMPORARY;
 360
 361 void cancel_temporary (void);
 362 \f
 363 /* Functions. */
 364
 365 void dump_split_vars (const struct ccase *);
 366 typedef int (* is_missing_func )(const union value *, const struct variable *);
 367
 368 int is_num_user_missing (double, const struct variable *);
 369 int is_str_user_missing (const unsigned char[], const struct variable *);
 370 int is_missing (const union value *, const struct variable *);
 371 int is_system_missing (const union value *, const struct variable *);
 372 int is_user_missing (const union value *, const struct variable *);
 373 void copy_missing_values (struct variable *dest, const struct variable *src);
 374 \f
 375 /* Transformations. */
 376
 377 struct trns_header;
 378 typedef int trns_proc_func (struct trns_header *, struct ccase *, int);
 379 typedef void trns_free_func (struct trns_header *);
 380
 381 /* Header for all transformations. */
 382 struct trns_header
 383   {
 384     int index;                  /* Index into t_trns[]. */
 385     trns_proc_func *proc;       /* Transformation proc. */
 386     trns_free_func *free;       /* Garbage collector proc. */
 387   };
 388
 389 /* Array of transformations */
 390 extern struct trns_header **t_trns;
 391
 392 /* Number of transformations, maximum number in array currently. */
 393 extern int n_trns, m_trns;
 394
 395 /* Index of first transformation that is really a transformation.  Any
 396    transformations before this belong to INPUT PROGRAM. */
 397 extern int f_trns;
 398
 399 void add_transformation (struct trns_header *trns);
 400 void cancel_transformations (void);
 401 \f
 402 struct var_set;
 403
 404 struct var_set *var_set_create_from_dict (const struct dictionary *d);
 405 struct var_set *var_set_create_from_array (struct variable *const *var,
 406                                            size_t);
 407
 408 size_t var_set_get_cnt (const struct var_set *vs);
 409 struct variable *var_set_get_var (const struct var_set *vs, size_t idx);
 410 struct variable *var_set_lookup_var (const struct var_set *vs,
 411                                      const char *name);
 412 void var_set_destroy (struct var_set *vs);
 413 \f
 414 /* Variable parsers. */
 415
 416 enum
 417   {
 418     PV_NONE = 0,                /* No options. */
 419     PV_SINGLE = 0001,           /* Restrict to a single name or TO use. */
 420     PV_DUPLICATE = 0002,        /* Don't merge duplicates. */
 421     PV_APPEND = 0004,           /* Append to existing list. */
 422     PV_NO_DUPLICATE = 0010,     /* Error on duplicates. */
 423     PV_NUMERIC = 0020,          /* Vars must be numeric. */
 424     PV_STRING = 0040,           /* Vars must be string. */
 425     PV_SAME_TYPE = 00100,       /* All vars must be the same type. */
 426     PV_NO_SCRATCH = 00200       /* Disallow scratch variables. */
 427   };
 428
 429 struct variable *parse_variable (void);
 430 struct variable *parse_dict_variable (const struct dictionary *);
 431 int parse_variables (const struct dictionary *, struct variable ***, int *,
 432                      int opts);
 433 int parse_var_set_vars (const struct var_set *, struct variable ***, int *,
 434                         int opts);
 435 int parse_DATA_LIST_vars (char ***names, int *cnt, int opts);
 436 int parse_mixed_vars (char ***names, int *cnt, int opts);
 437
 438 #endif /* !var_h */