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