MFI/FCS Verification Suite
Some of the figures on this page are composites
that combine portions of images from several of MFI's graphics screens,
or are cropped and slightly rearranged to save space.
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
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
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
- 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.
- Display the contents of C:\FLOWCYTM\VERIFYFC\VERPROGS in
- 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
- FSR (see figure at right)
- Double-click TEACHME.BAT and follow the same procedure.
It runs these tests (click links to see explanations):
- 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:
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.
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.
Copy the specific CFG file provided to MFI.CFG so MFI will use it
by default: 'copy rnd-h5k.cfg mfi.cfg'.
Run MFI, scrutinizing the primary and graphic output.
(You may wish to make a copy of the Shortcut to Mfi.exe to facilitate
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.
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
Contents of file 1E-1P
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.
Contents of file 1E-4P
511 511 255 767
- 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
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.
Ten events with 2 parameters.
Double-click Run 10E-2P to see the preconfigured results.
Contents of file 10E-2P
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 has two events with a single parameter, values 63 and 191.
Double-click Run 2E-1P to see the preconfigured results for
- 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.
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'
- 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.
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.
Contents of file 3E-1P
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.
1 2 3 4 5 6 7 8
1 2 3 4 5 6 7 8 9
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 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 (email@example.com).
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.
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.
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 that each provides.
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.
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
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
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.
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.
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
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
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.
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
"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. For data acquired from cells, it has no noticeable affect.
- Double-click REG-L4K.BAT to see the preconfigured results
from BOTH files.
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.
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
These are just for fun. Enjoy!