This verification suite provides tools for generating synthetic FCS (Flow Cytometry Standard format) data files with known contents. It is provided as a companion to MFI but is suitable for verification of any program capable of reading generic FCS files. Tests with synthetic data represent one of several methods of verifying accuracy of results. Another method is, of course, to compare results with those of trusted software.

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.

The included data files can be used under any operating system, but the verification suite programs that generate the synthetic FCS data files run only under Windows (MS-DOS). However, the programs can be used under DOS to generate additional data files that can then be moved to any operating system.

The suite includes the program A2FCS.EXE that converts ASCII spreadsheet-style data files to FCS. It can handle 8- or 16-bit data, and can mark the data as log-acquired. Programs are provided to generate columns of random numbers; the results (medians etc.) can be independently obtained by the flow cytometry program of your choice, and by generic spreadsheet software for verification. The programs can generate arbitrarily large FCS files of repeating cycles of random numbers (hence with known medians, etc.). MFI has been tested using this strategy for up to 2,000,000 events of 3 parameters each. (Tools are also provided for generating data to display the greeting of your choice as a dot plot.)

The programs provided here by no means represent a comprehensive test suite. They are provided to assist users of MFI in designing tests that will verify results of critical importance in their own work.

Contents of Verification Suite

If you have completed MFI installation, you will have the following folders and files on your hard disk:

• C:\FLOWCYTM\VERIFYFC\VERPROGS -- This folder contains ten synthetic listmode data files, the DOS programs (ready to run .EXE files) that generated these and can generate additional data files, a series of .cfg files needed to demonfistrate the data files in MFI, several .BAT files, and several MS-DOS shortcuts. Two of the latter can be run to produce a demonstration (see below).
• C:\FLOWCYTM\VERIFYFC\VERSRC -- This folder contains the source codes for the verification programs. The programs are written in ANSI C, and were compiled with Borland C++ 3.1 for DOS.

Demonstrations

• Display the contents of C:\FLOWCYTM\VERIFYFC\VERPROGS in Windows Explorer.

• Click open Windows Explorer's View menu, and select Arrange Icons, by Type. Notice that there are 3 types of files: .EXE (programs used to generate data files), .CFG (MFI configuration files for demonstrations), files with no "type" (listmode data files), and 3 .BAT files (programs for showing demonstrations in MFI).

• Double click on CUTEST.BAT. A DOS window will open. Adjust the font (menu at upper left) to a big clear one, and proceed. It will explain the process of constructing a test data file, and then it will run MFI to display it. Once MFI starts, just press Enter repeatedly until you see "RUN COMPLETED", then Quit, and the next demonstration will run similarly. When the series is finished, close the DOS window.
  For explanations of these tests, click these links to see the corresponding sections below. CUTEST.BAT runs the following tests with the appropriate pre-configured MFI.CFG files:
  • FSR (see figure at right)
  • LINES-L
  • 1024E-4P

• Double-click TEACHME.BAT and follow the same procedure. It runs these tests (click links to see explanations):
  • 3E-1P
  • 2E-1P, 2E-1PLOG
  • LINES-L (also in CUTEST.BAT)

• The program SYNDAT.BAT is a subroutine used by CUTEST.BAT and TEACHME.BAT (see also below).

Below, each of the components of the Verification Suite is described.

Converting ASCII to FCS with A2FCS.EXE

The program A2FCS (ASCII to FCS) can be used to convert ASCII spreadsheet- style data files to FCS files that 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.
 
HOW TO USE THE ASCII DATA FILES WITH THE MFI.CFG FILES PROVIDED

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. A batch file is provided to automate these steps, SYNDAT.BAT. To do steps 1-5 for RND-H5K, open an MD-DOS window and run 'syndat rnd-h5k'. Or most simply, just double click the "Run RND-H5K" shortcut provided.

This is the procedure run automatically by SYNDAT.BAT or the various "Run" shortcuts that use it:
1. If there is no ASCII data file (RND-H5K), there will be a program (RND-H5K.EXE) that 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.
   At this point, you can run ANY flow cytometry data analysis program on this data file.

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. (You may wish to make a copy of the Shortcut to Mfi.exe to facilitate running MFI.)

5. Optionally, scrutinize the ASCII list mode file produced by MFI (RND-H5K.ALS).

MANUALLY-CREATED ASCII DATA FILES

The following files were created by putting small numbers of parameter values in plain text (ASCII) files by manual text editing. You can inspect their contents by opening them in Notepad, Wordpad, or Word. (If you modify them, be sure to save the result as plain ASCII text.) Use the instructions in the previous section to convert them to FCS files readable by MFI.

• Contents of file 1E-1P

  63

  1E-1P This file contains one 1-parameter event. It primarily shows that MFI behaves acceptably in this extreme condition. It is not included in CUTEST.BAT or TEACHME.BAT. It can be run by double clicking the shortcut Run 1E-1P (in the folder flowcytm\verifyfc\verprogs).
  

• Contents of file 1E-4P

  511 511 255 767

  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.
  • Double-click Run 1E-4P to see the preconfigured results.
  • 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. The following warnings are illustrated in the primary (text) output:
    P1 caution: 100% of events are in a single occupied channel, 511.
    PEAK DETECTION DISABLED because there are <300 events in gate.
  • 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. On the histogram screen, in the gate dot plot, the gate is too small to see -- it superimposes on the one dot.
  • Gate 2 is set from 510-510 for both parameters and successfully excludes the one event. Gates 1 and 2 verify that MFI's 2-dimensional gate boundaries work properly. You will see:
    ERROR: no events in gate.
    MFI will try to force you to change the gate. When asked "Do you want to change the gate now?", reply No. Then go to the Next file.
  • Gate 3: 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.
  
   
  

• Contents of file 10E-2P

  20 20 40 40 60 60 80 80 100 100 120 120 140 140 160 160 180 180 200 200

  10E-2P Ten events with 2 parameters. Double-click Run 10E-2P to see the preconfigured results.
  The dot plot shows 10 events in a diagonal line. Two gates are provided that 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.
  
   
  

• File 2E-1P	File 2E-1PLOG
  63 191	LOG 63 191

  2E-1P, 2E-1PLOG File 2E-1P has two events with a single parameter, values 63 and 191. Double-click Run 2E-1P to see the preconfigured results for both files.
  • Primary (text) output demonstrates these warnings:
    P1 caution: 50% of events are in 1st occupied channel, 63.
    P1 caution: 50% of events are in last occupied channel, 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.
  
   
  

• Contents of file 3E-1P

  53 191 73

  3E-1P File 3E-1P has three events with a single parameter, values 53, 73, and 191. Double-click Run 3E-1P to see the preconfigured results. The median is 73, and the mean is 106.
  

• File 1E-8P	File 1E-9P
  1 2 3 4 5 6 7 8	1 2 3 4 5 6 7 8 9
  File 1E-12P	File 1E-13P
  1 2 3 4 5 6 7 8 9 10 11 12	1 2 3 4 5 6 7 8 9 10 11 12 13

  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. Double-click 1E-8P.BAT to see the preconfigured results -- it runs all 4 files.
  • 1E-8P and 1E-9P, when converted to FCS files, verify that MFI's 8-parameter limit works properly. The latter demonstrates this error message from MFI:
    Fatal error: more than 8 parameters in data file.
    8 is the maximum number of parameters supported by MFI.
    Program will abort on next keystroke ...

  • 1E-12P and 1E-13P verify that the 12-parameter limit of A2FCS works properly. The latter file causes A2FCS to emit the following messages:
    

    A2FCS version 1.1, August, 1996 (emartz@microbio.umass.edu).
    Pass 1 to determine maximum value:
    ERROR: More than 12 columns per line.
    ASCII to FCS conversion program A2FCS version 1.1*
    by Joe Trotter, modified by Eric Martz July 1995; revised August, 1996.
    Usage:
      a2fcs <infile> <outfile> [sample_id]
        where items in <> are mandatory, in [] are optional.
    Data must begin in first line and end in last line of infile.
    Columns must be separated by tabs.  All lines must have same number of columns.
    If any value is <0 or >1023, a warning is issued and it is set to 0 or 1023.
    If all values are 0-255, they are written as 1 byte ($PnB=8, $PnR=256).
    If any value exceeds 255, all are written as 2 bytes ($PnB=16, $PnR=1024).
    If the first line in infile begins 'LOG', parameters are marked log-acquired.
    

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 that each provides.

• Contents of file RND-H5K

  66 742 130 346 271 187 973 392 222 812 406 420 [4,994 lines omitted] 100 239 779 637 767 619 455 206 772 713 189 878

  RND-H5K, RND-L5K Many verification tests rely upon MFI's ability to convert list mode files to ASCII files that 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.EXE generates a file named RND-H5K containing 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.EXE 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.
   

• Contents of file 1024E-4P

  0 0 0 1023 1 1 1 1022 2 2 2 1021 [1,018 lines omitted] 1021 1021 1021 2 1022 1022 1022 1 1023 1023 1023 0

  1024E-4P Double-click Run 1024E-4P to see the preconfigured results. Program 1024E-4P.EXE generates ASCII data file 1024E-4P. This file contains in parameters 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 that allow testing of gate boundaries and resulting medians and means.

TESTING LARGE FILES: RANDA.EXE

There is no shortcut for using this program. You must open an MS-DOS window (Start, Programs, MS-DOS Prompt), change to folder \FLOWCYTM\VERIFYFC\VERPROGS, and issue the commands as explained above. Run the program RANDA without parameters for more explanation.

The program RANDA.EXE 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.EXE

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 (not shown as a screenshot). 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."

REG-L4K.EXE, REG-H5K.EXE

• Double-click REG-L4K.BAT to see the preconfigured results from BOTH files.

• REG-L4K.EXE 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.EXE 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.

These are just for fun. Enjoy!