Added (some of the) calculations for the examine command.
[pspp] / TODO
1 Time-stamp: <2004-05-31 13:14:29 blp>
2
3 What Ben's working on now.
4 --------------------------
5
6 Workspace exhaustion heuristics.
7
8 Does SET work correctly?
9
10 Update q2c input format description.
11
12 Rewrite output subsystem, break into multiple processes.
13
14 CROSSTABS needs to be re-examined.
15
16 RANK, which is needed for the Wilcoxon signed-rank statistic, Mann-Whitney U,
17 Kruskal-Wallis on NPAR TESTS and for Spearman and the Johnkheere trend test (in
18 other procedures).
19
20 TODO
21 ----
22
23 Make valgrind --leak-check=yes --show-reachable=yes work.
24
25 Add Boolean type.
26
27 Add NOT_REACHED() macro.
28
29 Add compression to casefiles.
30
31 Expressions need to be able to abbreviate function names.  XDATE.QUARTER
32 abbreviates to XDA.QUA, etc.
33
34 The expression tests need tests for XDATE and a few others, see
35 tests/xforms/expressions.sh comments for details.
36
37 Expressions need random distribution functions.
38
39 There needs to be another layer onto the lexer, which should probably be
40 entirely rewritten anyway.  The lexer needs to read entire *commands* at a
41 time, not just a *line* at a time.  It also needs to support arbitrary putback,
42 probably by just backing up the "current position" in the command buffer.
43
44 Scratch variables should not be available for use following TEMPORARY.
45
46 Details of N OF CASES, SAMPLE, FILTER, PROCESS IF, TEMPORARY, etc., need to be
47 checked against the documentation.  See notes on these at end of file for a
48 start.
49
50 Check our results against the NIST StRD benchmark results at
51 strd.itl.nist.gov/div898/strd
52
53 In debug mode hash table code should verify that collisions are reasonably low.
54
55 Use AFM files instead of Groff font files, and include AFMs for our default
56 fonts with the distribution.
57
58 Add libplot output driver.  Suggested by Robert S. Maier
59 <rsm@math.arizona.edu>: "it produces output in idraw-editable PS format, PCL5
60 format, xfig-editable format, Illustrator format,..., and can draw vector
61 graphics on X11 displays also".
62
63 Storage of value labels on disk is inefficient.  Invent new data structure.
64
65 Add an output flag which would cause a page break if a table segment could fit
66 vertically on a page but it just happens to be positioned such that it won't.
67
68 Fix spanned joint cells, i.e., EDLEVEL on crosstabs.stat.
69
70 Cell footnotes.
71
72 PostScript driver should emit thin lines, then thick lines, to optimize time
73 and space.
74
75 New functions?  var_name_or_label(), tab_value_or_label()
76
77 Should be able to bottom-justify cells.  It'll be expensive, though, by
78 requiring an extra metrics call.
79
80 Perhaps instead of the current lines we should define the following line types:
81 null, thin, thick, double.  It might look pretty classy.
82
83 Perhaps thick table borders that are cut off by a page break should decay to
84 thin borders.  (i.e., on a thick bordered table that's longer than one page,
85 but narrow, the bottom border would be thin on the first page, and the top and
86 bottom borders on middle pages.)
87
88 Support multi-line titles on tables. (For the first page only, presumably.)
89
90 Rewrite the convert_F() function in data-out.c to be nicer code.
91
92 In addition to searching the source directory, we should search the current
93 directory (for data files).  (Yuck!)
94
95 Fix line-too-long problems in PostScript code, instead of covering them up.
96 setlinecap is *not* a proper solution.
97
98 Need a better way than MAX_WORKSPACE to detect low-memory conditions.
99
100 When malloc() returns 0, page to disk and free() unnecessary data.
101
102 Remove ccase * argument from procfunc argument to procedure().
103
104 See if process_active_file() has wider applicability.
105
106 Eliminate private data in struct variable through use of pointers.
107
108 Fix som_columns().
109
110 Has glob.c been pared down enough?
111
112 Improve interactivity of output by allowing a `commit' function for a page.
113 This will also allow for infinite-length pages.
114
115 All the tests need to be looked over.  Some of the SET calls don't make sense
116 any more.
117
118 Implement thin single lines, should be pretty easy now.
119
120 SELECT IF should be moved before other transformations whenever possible.  It
121 should only be impossible when one of the variables referred to in SELECT IF is
122 created or modified by a previous transformation.
123
124 The manual: add text, add index entries, add examples.
125
126 The inline file should be improved: There should be *real* detection of whether
127 it is used (in dfm.c:cmd_begin_data), not after-the-fact detection.
128
129 Figure out a stylesheet for messages displayed by PSPP: i.e., what quotation
130 marks around filenames, etc.
131
132 Data input and data output are currently arranged in reciprocal pairs: input is
133 done directly, with write_record() or whatever; output is done on a callback
134 event-driven basis.  It would definitely be easier if both could be done on a
135 direct basis, with read_record() and write_record() routines, with a coroutine
136 implementation (see Knuth).  But I'm not sure that coroutines can be
137 implemented in ANSI C.  This will require some thought.  Perhaps 0.4.0 can do
138 this.
139
140 New SET subcommand: OUTPUT.  i.e., SET OUTPUT="filename" to send output to that
141 file; SET OUTPUT="filename"(APPEND) to append to that file; SET OUTPUT=DEFAULT
142 to reset everything.  There might be a better approach, though--think about it.
143
144 HDF export capabilities (http://hdf.ncsa.uiuc.edu).  Suggested by Marcus
145 G. Daniels <mgd@santafe.edu>.
146
147 From Zvi Grauer <z.grauer@csuohio.edu> and <zvi@mail.ohio.net>:
148
149    1. design of experiments software, specifically Factorial, response surface
150    methodology and mixrture design.
151
152    These would be EXTREMELY USEFUL for chemists, engineeris, and anyone
153    involved in the production of chemicals or formulations.
154
155    2. Multidimensional Scaling analysis (for market analysis) -
156
157    3. Preference mapping software for market analysis
158
159    4. Hierarchical clustering (as well as partition clustering)
160
161    5. Conjoint analysis
162
163    6. Categorical data analsys ?
164
165 IDEAS
166 -----
167
168 In addition to an "infinite journal", we should keep a number of
169 individual-session journals, pspp.jnl-1 through pspp.jnl-X, renaming and
170 deleting as needed.  All of the journals should have date/time comments.
171
172 Qualifiers for variables giving type--categorical, ordinal, ...
173
174 Analysis Wizard
175
176 Consider consequences of xmalloc(), fail(), hcf() in interactive
177 use:
178 a. Can we safely just use setjmp()/longjmp()?
179 b. Will that leak memory?
180 i. I don't think so: all procedure-created memory is either
181 garbage-collected or globally-accessible.
182 ii. But you never know... esp. w/o Checker.
183 c. Is this too early to worry? too late?
184
185 Need to implement a shared buffer for funny functions that require relatively
186 large permanent transient buffers (1024 bytes or so), that is, buffers that are
187 permanent in the sense that they probably shouldn't be deallocated but are only
188 used from time to time, buffers that can't be allocated on the stack because
189 they are of variable and unpredictable but usually relatively small (usually
190 line buffers).  There are too many of these lurking around; can save a sizeable
191 amount of space at very little overhead and with very little effort by merging
192 them.
193
194 Clever multiplatform GUI idea (due partly to John Williams): write a GUI in
195 Java where each statistical procedure dialog box could be downloaded from the
196 server independently.  The statistical procedures would run on (the/a) server
197 and results would be reported through HTML tables viewed with the user's choice
198 of web browsers.  Help could be implemented through the browser as well.
199
200 Design a plotting API, with scatterplots, line plots, pie charts, barcharts,
201 Pareto plots, etc., as subclasses of the plot superclass.
202
203 HOWTOs
204 ------
205
206 1. How to add an operator for use in PSPP expressions:
207
208 a. Add the operator to the enumerated type at the top of expr.h.  If the
209 operator has arguments (i.e., it's not a terminal) then add it *before*
210 OP_TERMINAL; otherwise, add it *after* OP_TERMINAL.  All these begin with OP_.
211
212 b. If the operator's a terminal then you'll want to design a structure to hold
213 its content.  Add the structure to the union any_node.  (You can also reuse one
214 of the prefab structures, of course.)
215
216 c. Now switch to expr-prs.c--the module for expression parsing.  Insert the
217 operator somewhere in the precedence hierarchy.
218
219 (1) If you're adding a operator that is a function (like ACOS, ABS, etc.) then
220 add the function to functab in `void init_functab(void)'.  Order is not
221 important here.  The first element is the function name, like "ACOS".  The
222 second is the operator enumerator you added in expr.h, like OP_ARCOS.  The
223 third element is the C function to parse the PSPP function.  The predefined
224 functions will probably suit your needs, but if not, you can write your own.
225 The fourth element is an argument to the parsing function; it's only used
226 currently by generic_str_func(), which handles a rather general syntax for
227 functions that return strings; see the comment at the beginning of its code for
228 details.
229
230 (2) If you're adding an actual operator you'll have to put a function in
231 between two of the operators there already in functions `exprtype
232 parse_*(any_node **n)'.  Each of these stores the tree for its result into *n,
233 and returns the result type, or EX_ERROR on error.  Be sure to delete all the
234 allocated memory on error before returning.
235
236 d. Add the operator to the table `op_desc ops[OP_SENTINEL+1]' in expr-prs.c,
237 which has an entry for every operator.  These entries *must* be in the same
238 order as they are in expr.h.  The entries have the form `op(A,B,C,D)'.  A is
239 the name of the operator as it should be printed in a postfix output format.
240 For example, the addition operator is printed as `plus'.  B is a bitmapped set
241 of flags:
242
243 * Set the 001 bit (OP_VAR_ARGS) if the operator takes a variable number of
244 arguments.  If a function can take, say, two args or three args, but no other
245 numbers of args, this is a poor way to do it--instead implement the operator as
246 two separate operators, one with two args, the other with three.  (The main
247 effect of this bit is to cause the number of arguments to be output to the
248 postfix form so that the expression evaluator can know how many args the
249 operator takes.  It also causes the expression optimizer to calculate the
250 needed stack height differently, without referencing C.)
251
252 * Set the 002 bit (OP_MIN_ARGS) if the operator can take an optional `dotted
253 argument' that specified the minimum number of non-SYSMIS arguments in order to
254 have a non-SYSMIS result.  For instance, MIN.3(e1,e2,e3,e4,e5) returns a
255 non-SYSMIS result only if at least 3 out of 5 of the expressions e1 to e5 are
256 not missing.
257
258 Minargs are passed in the nonterm_node structure in `arg[]''s elements past
259 `n'--search expr-prs.c for the words `terrible crock' for an example of this.
260
261 Minargs are output to the postfix form.  A default value is output if none was
262 specified by the user.
263
264 You can use minargs for anything you want--they're not limited to actually
265 describing a minimum number of valid arguments; that's just what they're most
266 *commonly* used for.
267
268 * Set the 004 bit (OP_FMT_SPEC) if the operator has an argument that is a
269 format specifier.  (This causes the format specifier to be output to the
270 postfix representation.)
271
272 Format specs are passed in the nonterm_node structure in the same way as
273 minargs, except that there are three args, in this order: type, width, # of
274 decimals--search expr-prs.c for the words `is a crock' for an example of this.
275
276 * Set the 010 bit (OP_ABSORB_MISS) if the operator can *ever* have a result of
277 other than SYSMIS when given one or more arguments of SYSMIS.  Operators
278 lacking this bit and known to have a SYSMIS argument are short-circuited to
279 SYSMIS by the expression optimizer.
280
281 * If your operator doesn't fit easily into the existing categories,
282 congratulations, you get to write lots of code to adjust everything to cope
283 with this new operator.  Are you really sure you want to do that?
284
285 C is the effect the operator has on stack height.  Set this to `varies' if the
286 operator has a variable number of arguments.  Otherwise this 1, minus the
287 number of arguments the operator has.  (Since terminals have no arguments, they
288 have a value of +1 for this; other operators have a value of 0 or less.)
289
290 D is the number of items output to the postfix form after the operator proper.
291 This is 0, plus 1 if the operator has varargs, plus 1 if the operator has
292 minargs, plus 3 if the operator has a format spec.  Note that minargs/varargs
293 can't coexist with a format spec on the same operator as currently coded.  Some
294 terminals also have a nonzero value for this but don't fit into the above
295 categories.
296
297 e. Switch to expr-opt.c.  Add code to evaluate_tree() to evaluate the
298 expression when all arguments are known to be constants.  Pseudo-random
299 functions can't be evaluated even if their arguments are constants.  If the
300 function can be optimized even if its arguments aren't all known constants, add
301 code to optimize_tree() to do it.
302
303 f. Switch to expr-evl.c.  Add code to evaluate_expression() to evaluate the
304 expression.  You must be absolutely certain that the code in evaluate_tree(),
305 optimize_tree(), and evaluate_expression() will always return the same results,
306 otherwise users will get inconsistent results, a Bad Thing.  You must be
307 certain that even on boundary conditions users will get identical results, for
308 instance for the values 0, 1, -1, SYSMIS, or, for string functions, the null
309 string, 1-char strings, and 255-char strings.
310
311 g. Test the code.  Write some test syntax files.  Examine the output carefully.
312
313 NOTES ON SEARCH ALGORITHMS
314 --------------------------
315
316 1. Trees are nicer when you want a sorted table.  However, you can always
317 sort a hash table after you're done adding values.
318
319 2. Brent's variation of Algorithm D is best when the table is fixed: it's
320 memory-efficient, having small, fixed overhead.  It's easier to use
321 when you know in advance how many entries the table will contain.
322
323 3. Algorithm L is rather slow for a hash algorithm, however it's easy.
324
325 4. Chaining is best in terms of speed; ordered/self-ordering is even
326 better.
327
328 5. Rehashing is slow.
329
330 6. Might want to decide on an algorithm empirically since there are no
331 clear mathematical winners in some cases.
332
333 7. gprof?  Hey, it works!
334
335 MORE NOTES/IDEAS/BUGS
336 ---------------------
337
338 The behavior of converting a floating point to an integer when the value of the
339 float is out of range of the integer type is UNDEFINED!  See ANSI 6.2.1.3.
340
341 What should we do for *negative* times in expressions?
342
343 Sometimes very wide (or very tall) columns can occur in tables.  What is a good
344 way to truncate them?  It doesn't seem to cause problems for the ascii or
345 postscript drivers, but it's not good in the general case.  Should they be
346 split somehow?  (One way that wide columns can occur is through user request,
347 for instance through a wide PRINT request--try time-date.stat with a narrow
348 ascii page or with the postscript driver on letter size paper.)
349
350 NULs in input files break the products we're replacing: although it will input
351 them properly and display them properly as AHEX format, it truncates them in A
352 format.  Also, string-manipulation functions such as CONCAT truncate their
353 results after the first NUL.  This should simplify the result of PSPP design.
354 Perhaps those ugly a_string, b_string, ..., can all be eliminated.
355
356 From Moshe Braner <mbraner@nessie.vdh.state.vt.us>: An idea regarding MATCH
357 FILES, again getting BEYOND the state of SPSS: it always bothered me that if I
358 have a large data file and I want to match it to a small lookup table, via
359 MATCH FILES FILE= /TABLE= /BY key, I need to SORT the large file on key, do the
360 match, then (usually) re-sort back into the order I really want it.  There is
361 no reason to do this, when the lookup table is small.  Even a dumb sequential
362 search through the table, for every case in the big file, is better, in some
363 cases, than the sort.  So here's my idea: first look at the /TABLE file, if it
364 is "small enough", read it into memory, and create an index (or hash table,
365 whatever) for it.  Then read the /FILE and use the index to match to each case.
366 OTOH, if the /TABLE is too large, then do it the old way, complaining if either
367 file is not sorted on key.
368
369 ----------------------------------------------------------------------
370 Statistical procedures:
371
372 For each case we read from the input program:
373
374 1. Execute permanent transformations.  If these drop the case, stop.
375 2. N OF CASES.  If we have already written N cases, stop.
376 3. Write case to replacement active file.
377 4. Execute temporary transformations.  If these drop the case, stop.
378 5. Post-TEMPORARY N OF CASES.  If we have already analyzed N cases, stop.
379 6. FILTER, PROCESS IF.  If these drop the case, stop.
380 7. Pass case to procedure.
381
382 Ugly cases:
383
384 LAG records cases in step 3.
385
386 AGGREGATE: When output goes to an external file, this is just an ordinary
387 procedure.  When output goes to the active file, step 3 should be skipped,
388 because AGGREGATE creates its own case sink and writes to it in step 7.  Also,
389 TEMPORARY has no effect and we just cancel it.  Regardless of direction of
390 output, we should not implement AGGREGATE through a transformation because that
391 will fail to honor FILTER, PROCESS IF, N OF CASES.
392
393 ADD FILES: Essentially an input program.  It silently cancels unclosed LOOPs
394 and DO IFs.  If the active file is used for input, then runs EXECUTE (if there
395 are any transformations) and then steals vfm_source and encapsulates it.  If
396 the active file is not used for input, then it cancels all the transformations
397 and deletes the original active file.
398
399 CASESTOVARS: ???
400
401 FLIP:
402
403 MATCH FILES: Similar to AGGREGATE.  This is a procedure.  When the active file
404 is used for input, it reads the active file; otherwise, it just cancels all the
405 transformations and deletes the original active file.  Step 3 should be
406 skipped, because MATCH FILES creates its own case sink and writes to it in step
407 7.  TEMPORARY is not allowed.
408
409 MODIFY VARS:
410
411 REPEATING DATA:
412
413 SORT CASES:
414
415 UPDATE: same as ADD FILES.
416
417 VARSTOCASES: ???
418 ----------------------------------------------------------------------
419 N OF CASES
420
421   * Before TEMPORARY, limits number of cases sent to the sink.
422
423   * After TEMPORARY, limits number of cases sent to the procedure.
424
425   * Without TEMPORARY, those are the same cases, so it limits both.
426
427 SAMPLE
428
429   * Sample is just a transformation.  It has no special properties.
430
431 FILTER
432
433   * Always selects cases sent to the procedure.
434
435   * No effect on cases sent to sink.
436
437   * Before TEMPORARY, selection is permanent.  After TEMPORARY,
438     selection stops after a procedure.
439
440 PROCESS IF
441
442   * Always selects cases sent to the procedure.
443
444   * No effect on cases sent to sink.
445
446   * Always stops after a procedure.
447
448 SPLIT FILE
449
450   * Ignored by AGGREGATE.  Used when procedures write matrices.
451
452   * Always applies to the procedure.
453
454   * Before TEMPORARY, splitting is permanent.  After TEMPORARY,
455     splitting stops after a procedure.
456
457 TEMPORARY
458
459   * TEMPORARY has no effect on AGGREGATE when output goes to the active file.
460
461   * SORT CASES, ADD FILES, RENAME VARIABLES, CASESTOVARS, VARSTOCASES,
462     COMPUTE with a lag function cannot be used after TEMPORARY.
463
464   * Cannot be used in DO IF...END IF or LOOP...END LOOP.
465
466   * FLIP ignores TEMPORARY.  All transformations become permanent.
467
468   * MATCH FILES and UPDATE cannot be used after TEMPORARY if active
469     file is an input source.
470
471   * RENAME VARIABLES is invalid after TEMPORARY.
472
473   * WEIGHT, SPLIT FILE, N OF CASES, FILTER, PROCESS IF apply only to
474     the next procedure when used after TEMPORARY.
475
476 WEIGHT
477
478   * Always applies to the procedure.
479
480   * Before TEMPORARY, weighting is permanent.  After TEMPORARY,
481     weighting stops after a procedure.
482
483
484 -------------------------------------------------------------------------------
485 Local Variables:
486 mode: text
487 fill-column: 79
488 End: