home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / statstcs / codebook.arc / CODEBOOK.DOC < prev    next >
Encoding:
Text File  |  1989-07-26  |  8.4 KB  |  142 lines
  1. Program CODEBOOK.BAS 1.0, 25 July 1989, by Jim Groeneveld.
  2. -----------------------------------------------------------------------------
  3. NIPG TNO - - - - - <work> - - - - -|- <home> - - - - -| GROENEVELD@HDETNO51
  4. Postbus 124    | Wassenaarseweg 56 | Schoolweg 14     | JIM%RULTNO@HDETNO51
  5. 2300 AC Leiden | 2333 AL Leiden    | 8071 BC Nunspeet | TNOSUR::GROENEVELD
  6. Nederland (NL)   071-178810        | 03412-60413      | RULTNO::JIM
  7. -----------------------------------------------------------------------------
  8.  
  9. PURPOSE
  10. -------
  11. This program unformats a fixed formatted ascii data file for (STATGRAPHICS)
  12. using a user created codebook file. STATGRAPHICS can not read ASCII data files
  13. with records longer than 640 bytes. Next, preparing to read suited ASCII files
  14. is time consuming and user-unfriendly: the user has to create a vector
  15. containing the information of the position of each variable in the data file.
  16. This means a lot of initial arithmetic and errors are difficult to correct.
  17. Besides, all fields will be read: the vector only specifies field widths of
  18. fields that are directly following the previous fields. The sum of all widths
  19. cannot exceed 640. So using standard STATGRAPHICS options in this case is
  20. clumsy, time consuming and error sensitive. This asked for the current replacing
  21. solution.
  22.  
  23. DESCRIPTION
  24. -----------
  25. CODEBOOK transforms any (fixed formatted) ASCII file with one record per case of
  26. any (unlimited) length into multiple Blank or Comma delimited (or eventually
  27. Fixed formatted or Report) data files (optionally) with STATGRAPHICS (or
  28. generally acceptable, e.g. Lotus) variable names on the first row, each
  29. containing a user specified number of variables. This has the advantage that
  30. all the necessary preparation can be done within any editor, creation of a
  31. codebook file, indicating for each variable to be transformed a.o. the field
  32. width, the starting and ending columns and the variable name. The resulting
  33. data files may then be read after each other into STATGRAPHICS (or used with
  34. any appropriate program). Completely blank fields (mostly representing missing
  35. values) in the original ASCII file may be replaced automatically by any (user-
  36. specified) numerical or character value in the resulting output data files.
  37. This makes reading ASCII data files much more efficient, less sensitive to
  38. errors, much quicker and more logical and surveyable.
  39.  
  40. (Unique) limit specifications:
  41. ------------------------------
  42. 1) maximum number of variables: 32767 (practically unlimited), default: 58
  43. 2) if not reserved enough space initially when specifying the current maximum
  44.    number of variables: optional automatic (but rather slow) adaptation to the
  45.    actually required number of variables (number of array elements) read from
  46.    the codebook file
  47. 3) maximum input record length (=number of columns per line): unlimited
  48. 4) maximum column specification (interpreted bytes/record):32767*255-1=8,355,584
  49.    (practically unlimited, practically limited by available memory in BASIC)
  50. 5) number of cases: unlimited (only hardware and software (BASIC) restrictions)
  51.  
  52. The resulting unformatted data file(s) contain default 58 variables because of
  53. the STATGRAPHICS limits of 640 bytes max.line length and 10 character variable
  54. names separated by delimiters; STATGRAPHICS, however, allows for a maximum of 64
  55. variables to be edited at the same time within its data editor and even more (?)
  56. within any (STATGRAPHICS) data file.
  57.  
  58. The output records (generally unformatted values) are preceded by a first line
  59. with variable names. As many unformatted, blank or comma delimited (or fixed
  60. formatted or report) output files are generated as are necessary to contain the
  61. total number of variables as a multiple of the number of variables per output
  62. file. They are named automatically by the file name of the original formatted
  63. data file with their sequence number as the extension. All output files may be
  64. read by STATGRAPHICS.
  65.  
  66. USE
  67. ---
  68. A codebook file should be created using any editor in which on each line a
  69. variable should be described as follows:
  70. (all data descriptors, except for the first column, MUST be separated by
  71. COMMA's, only widths and columns may be ended with one or more spaces)
  72. FIRST column :─┬─ space: numeric or character variable to be output 'as is';
  73.  (WITHOUT      ├─ "    : character variable to be output within double quotes;
  74.   ending       ├─ '    : character variable to be output within single quotes;
  75.   delimiter)   └─ any other character (or empty line): comment line, no action.
  76. Missing Value:─┬─ any value to replace originally entirely blank fields, may
  77.  (END with     │  be a character value, optionally enclosed by double quotes;
  78.   a COMMA)     └─ if left empty it will take the value prompted for when run;
  79. Starting Column : integer positive value <=8,355,584 (end with comma or spaces);
  80. Ending Column   : integer positive value <=8,355,584 (end with comma or spaces);
  81. Field Width  :─┬─ integer positive value <=255, for double checking field
  82.  (end with com-│  correspondence with Starting and Ending Column;
  83.   ma or spaces)└─ if 0: disable checking with Starting and Ending Column;
  84. Variable Name:─┬─ any character value up to 255 (!) characters, not quoted;
  85.  (end with     └─ if omitted a default name, consisting of 'VarX' in which X is
  86.   comma/space/    the variable number, will be generated; the Variable Names are
  87.   /EOL:CRLF)      inserted as the first line of the output file(s);
  88. Comment         : optional, may be omitted, not interpreted.
  89.  
  90. Column specifications need not to be contiguous and sequential. Columns may be
  91. skipped or read multiple times (as part of different variables). This allows
  92. for extracting one or more data files with a restricted, specified number of any
  93. variables from the original database file.
  94.  
  95. MEMORY REQUIREMENTS
  96. -------------------
  97. Approximate needed memory space per variable to process:
  98.    1 byte  VAR.TYPE$ (first column of codebook file)
  99. ≈  2 bytes MISSING.VALUE$ (average 2 columns)
  100.    4 bytes BEGIN.COLUMN! (double precision)
  101.    4 bytes END.COLUMN! (double precision)
  102. ≈ 10 bytes VARIABLE.NAME$ (common max. variable name length)
  103. ≈  2 bytes VALUE$ in DATA.LINE$ (average 2 columns)
  104. ──────────
  105. ≈ 23 bytes (say generally no more then 25) per variable altogether.
  106. E.g. for 1000 variables this requires a data space in BASIC memory of ≈25 Kb.
  107. So the programs own algorithmic limit of 32767 variables may not be reached
  108. far enough due to other limitations. (Maybe compiled BASIC allows for more
  109. data space). The same applies for the maximum column specification: this would
  110. assume a data file with at least one line of more than 8 Mb long, which has to
  111. fit within memory entirely.
  112.  
  113. Suggestion: if limits occur while processing a codebook file break it into
  114. smaller pieces (of about the number of variables per output file) and run
  115. CODEBOOK multiple times. This will not take more time in total. Beware of
  116. duplicate file names! Rename, if necessary in between.
  117.  
  118. Suggestion: if limits occur while processing a database file break it into
  119. smaller pieces using COPYFIX (specify record lengths of ≤80 and included and
  120. synchronized CRLF's) and SEPARATE (specify NO record numbers) and rerun CODEBOOK
  121. with adapted (variables and column specifications) parts of the original
  122. codebook file on each of the (renamed!: different FileNameS and no numeric
  123. extensions) generated files from SEPARATE.
  124.  
  125. GWBASIC-LINE INPUT
  126. ------------------
  127. In GWBASIC a LINE INPUT reads at most 255 characters within ONE line. If 255
  128. characters are read any following CRLF has not been encountered yet. Any
  129. succeeding LINE INPUT will start from the point where the previous LINE INPUT
  130. was left. If still more than 255 characters are to be read only 255 will be
  131. read, leaving the rest for the eventual next LINE INPUT. If less than 255
  132. characters on the SAME line are to be read, even if only a remaining CRLF, they
  133. are ALL read, INCLUDING the CRLF, but the CRLF are NOT part of the read STRING.
  134. Any following LINE INPUT starts with the NEXT line. If another BASIC (e.g.
  135. BASICA, according to its manual) processes LINE INPUT in a different way the
  136. course of this program may be unpredicted and erroneous, so BE AWARE of your
  137. BASIC version! The number of characters read by a LINE INPUT statement may be
  138. changed ONLY IF NECESSARY by redefining the BASIC variable MAX.LINE.INPUT.LENGTH
  139. in program line 70.
  140.  
  141. NOTE: (GW)BASIC performs Garbage Collection (or House Cleaning) regularly.
  142.