MFI VERIFICATION SUITE: SYNTHETIC DATA PROGRAMS MFI is provided free and without support. By the act of using it, you agree to accept responsibility for verifying the accuracy of MFI's results with your data and its suitability for your uses. This MFI verification suite provides tools for constructing synthetic FCS files with known contents. Tests with synthetic data represent one of several methods for verifying accuracy of results. Other methods are described in MFI's on-line help section entitled 'Verification of Result Accuracy'. The programs provided here by no means represent a comprehensive test suite. They are provided to assist users of MFI in designing tests which will verify results of critical importance in their own work. Packing list: Each EXE file is a self-unzipping file. Run it in an empty directory -- it will unpack itself into a group of files. MFIVERIF.DOC: This document file. VERPROGS.EXE: Verification suite programs ready to run. VERSRC.EXE: ANSI C Source codes for all programs in verification suite. (The source codes are unnecessary, but can serve as guides if you wish to make your own programs. The programs were compiled with Borland C++ 3.1.) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - CUTEST TESTS To take a quick peek at a few of the more visually interesting tests, run CUTEST. MOST INFORMATIVE TESTS To see some of the tests which reveal important aspects of MFI's function which you may not be aware of, run TEACHME (and read the relevant sections below). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A2FCS The program A2FCS (ASCII to FCS) can be used to convert ASCII spreadsheet- style data files to FCS files which can be read by MFI. The ASCII data files can be created manually, or with spreadsheet software, or by custom programs (such as those provided here), or by any other means you choose. A2FCS is a modification of the TEXT2FCS 1.0 program written by Joe Trotter. TEXT2FCS allows only range 0-255 values, while A2FCS also allows 0-1023 values. When no value exceeds 255, A2FCS writes the binary data as one byte per value ($PnB = 8, $PnR = 256); when at least one value exeeds 255, A2FCS writes all the binary data as two bytes per value ($PnB = 16, $PnR = 1024). A2FCS has more error checking than does TEXT2FCS 1.0. It insists that all rows contain the same number of columns. If any value is <0 a warning message is issued and it is set to 0. If any value is >1023 it is set to 1023 and a warning message is issued. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - MFI.CFG files. To demonstrate the tests described below, you may wish to use the MFI.CFG files provided. Each CFG file has just the one list mode file of interest on the run organization screen, and is configured to provide the relevant dot plots, gates, etc. Where appropriate, some have conversion to ASCII list mode enabled with the event number column disabled. We'll use RND-H5K (see below for description) as an example to illustrate the general procedure for each test: 1. If there is no ASCII data file (RND-H5K), there will be a program (RND-H5K.EXE) which generates the ASCII data file. Run the program. 2. Use A2FCS to convert the ASCII data file to FCS: 'a2fcs rnd-h5k' produces the file RND-H5K.A2F. 3. Copy the specific CFG file provided to MFI.CFG so MFI will use it by default: 'copy rnd-h5k.cfg mfi.cfg'. 4. Run MFI, scrutinizing the primary and graphic output. 5. Scrutinize the ASCII list mode file produced by MFI (RND-H5K.ALS). A batch file is provided to automate these steps, SYNDAT.BAT. To do steps 1-5 for RND-H5K, run 'syndat rnd-h5k'. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - MANUALLY CREATED ASCII DATA FILES 1E-1P This file contains one 1-parameter event. It primarily shows that MFI behaves acceptably in this extreme condition. 1E-4P This file contains one 4-parameter event. FSC and SSC (P1 and P2) are each 511. FL1 and FL2 (P3 and P4) are 255 and 767 respectively. The dot plot screen showing P4 vs. P3 (a "two-color" plot) shows the one dot at the expected position, verifying that MFI's dot plots position this dot correctly. 1E-4P also shows that medians and means are correct for a single event. Gate 1 is set from 511-511 on parameters P1 and P2 and successfully includes the one event at that value. Gate 2 is set from 510-510 for both parameters and successfully excludes the one event. This verifies that MFI's 2-dimensional gate boundaries work properly. Event number is handled differently by MFI than other parameters. To verify that 2-dimensional gates on event number work properly, gate 3 is set on P4 vs. event number, 767-767 and 0-0 respectively. The event is included. Gate 4 is set on the same parameters, but 735-780 and 1-1023. The event is excluded. If you examine the gate-setting screen, you will notice that the graphic edge of the gate boundaries vs. the point does not accurately reflect whether the point is inside or outside of the gate. (This would be difficult to accomplish, especially for all graphic screens supported by MFI. For real listmode files, it does not cause any serious problem.) Compare with tests 10E-2P and 1024E-4P. 10E-2P The dot plot shows 10 events in a diagonal line. Two gates are provided which include 2 and 7 events. Note that the edges of the gates on the dot plot indicate correctly which events will be included, because a bit more space is left between the edge and the event than in the test gates shown in 1E-4P. 2E-1P, 2E-1PLOG File 2E-1P has two events with a single parameter, values 63 and 191. The median and mean are calculated correctly to be 127. (When the number of events is even, the median is the arithmetic average of the two 'middle' events.) File 2E-1PLOG (also included in 2E-1P.CFG) has the same two events and values, but the list mode file indicates that the data were acquired on a 4-decade log scale. Thus, the channel values 63 and 191 are first converted to a linear scale (see MFI's on-line help on 'Calculation algorithms employed'), then averaged, and the average is then converted back to the log scale, giving the median channel value of 172. The linear equivalent of this is also given, 487. 3E-1P File 3E-1P has three events with a single parameter, values 53, 73, and 191. The median is 73, and the mean is 106. 1E-8P, 1E-9P, 1E-12P, 1E-13P These files contain one event each with the number of parameters indicated by the name of the file. 1E-13P and 1E-12P verify that the 12-parameter limit of A2FCS works properly. 1E-8P and 1E-9P, when converted to FCS files, verify that MFI's 8-parameter limit works properly. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SYNTHETIC DATA-GENERATING PROGRAMS The MFI verification program suite includes a series of small programs each of which generates a synthetic ASCII data file. Here is a list of the programs, explaining the verification tests which each provides. RND-H5K, RND-L5K Many verification tests rely upon MFI's ability to convert list mode files to ASCII files which can be inspected. Therefore, the first goal is to verify that MFI's list mode to ASCII conversion is reliable. The RND* programs write pseudo-random numbers. After conversion to FCS by A2FCS, then back to ASCII by MFI, the original ASCII file and MFI's ASCII file can be compared. The absence of differences verifies that A2FCS works reliably, and that MFI's option to convert list mode to ASCII works reliably. The program RND-H5K generates 20,000 pseudo-random numbers (range 0-1023) arranged in 4 columns, hence 5,000 4-parameter pseudo-events. When this test was first run on the version of MFI current at the time, the A2FCS-converted file RND-H5K.A2F was processed by MFI, which wrote out the ASCII listmode file RND-H5K.ALS using the option "Omit event number in list mode ASCII files". This was hand-edited to remove non-data lines and trailing tabs. The DOS file comparison program FC reported no difference between RND-H5K and the edited RND-H5K.ALS. The program RND-L5K was used similarly, the only difference being that the pseudo-random numbers range from 0-255. Because no value exceeds 255, A2FCS writes the FCS file with single-byte binary data instead of the 2-byte binary data used for range 0-1023. This allows verification of both data modes for A2FCS and MFI. Again, the results showed no difference when tested on the version of MFI current at the time. 1024E-4P This file contains in P1-P3 regular arithmetic series from 0-1023, and in P4, the decreasing series from 1023-0. Thus, both the mean and the median of each parameter must be 512. The dot plots show the expected lines. Various gates are provided which allow testing of gate boundaries and resulting medians and means. TESTING LARGE FILES: RANDA The program RANDA generates arbitrarily-sized tables of pseudo-random numbers. However, the values are generated in identical, repeating sets the same size as the range. The intended use is for range 256 or 1024. The medians and means can be determined by spreadsheet software for the RANDA files containing one cycle (256 or 1024 pseudo-random values). Because this cycle repeats for larger files, the median and mean will be the same for any-sized file with the same range. This strategy allows generation of arbitrarily large files for which the medians and means are known in advance. When RANDA is asked to make a file of range 256 containing 3 parameters by 2,000,128 events, the result is a 23,509,317 byte file. A2FCS converts this to a 6,001,408 byte file. The version of MFI current at the time processed this file correctly. LINES-L This program generates two files, LINES-L and LINES-H, with data ranges of 256 and 1024 respectively. Each file contains a series of parallel lines. In order that each dot be separated from the next, there are only 64 dots per line. LINES-L behaves as expected. However, the lines from LINES-H look uneven. This is because of the way MFI handles 1024-range dotplots. Here is a quote from MFI's on-line help on dot plots: "In order hold up to 5,000 parameter values for up to 8 parameters in memory simultaneously while keeping memory requirements low, the resolution of parameter values used in dot plots is limited to 256 channels. Because the resolution of the VGA screen is slightly better than this, it can cause a noticable regular dot alignment 'corduroy' pattern. To blur this visually distracting artifact, a random value not exceeding 0.4% of full-scale is added to each dot's X and Y positions. Dot positions remain accurate to within 0.4% of full-scale." In the case of the absolutely straight lines contained in LINES-H, this blurring translates to an uneven appearance. REG-L4K This program generates a regular square array of dots in the dot plot, using a value range of 256. In order to have all dots shown within MFI's maximum of 5,000 dots, the dots are placed every 4 channels, making 4,096 dots. Notice the regularity of the dot pattern. The corduroy effects result from the interaction of the dot spacing with the video resolution. The gates give the expected results. REG-H5K This program generates a regular square array of dots in the dot plot, using a value range of 1024. In order to have all dots shown within MFI's maximum of 5,000 dots, the dots are placed every 16 channels, making 4,761 dots. Notice that the dot pattern does not look as regular as did REG-L4K. The irregularity is a result of the random blurring effect described above under LINES-L. FSR, YRSTRULY These files are just for fun. Enjoy! [END OF MFIVERIF.DOC]