annotate cross_sample/src/README @ 3:5f670146a9af draft

Uploaded

This package contains R code for converting and transforming a binary
FCS file, using the FCSTrans software, and the C code for running the
flock1 and flock2 population identification software.

src - contains the C code for flock1, flock2 and cent_adjust
bin - contains the compiled C code for flock1, flock2 and cent_adjust,
      plus the R code for using the FCSTrans algorithm for file
      conversion and data transformation.
doc - documentation for FCSTrans and FLOCK algorithms
example - sample data and output from FCSTrans and FLOCK

To run this software sucessfully the code assumes the software was installed
in the /usr/local/flock directory and that R, plus the Bioconductor flowCore
module has been installed. If you use the ipconvert.sh shell script, you
may need to adjust the location of the RScript executable and the location
of the FCSTrans.R code by editing the shell script.

#############################################################################
# Overview
#############################################################################
ImmPort-FLOCK

FLOCK (FLOw Clustering without K), an automated population discovery tool for
multidimensional FCM data was designed to specifically take into account the
unique feature of FCM data and produce objective segregation of cell
populations.

FLOCK parameter settings can be customized by defining Bins and Density
Threshold.  The number of bins is an integer specifying the number of
equal-sized regions the data will be partitioned into on each axis. Increasing
the number of bins increases the sensitivity to detect rare populations but
may also result in single populations being divided.  Density Threshold is the
cut-off value to separate the dense regions from background. It is a floating
point number that helps define population centers; increasing the threshold
may help separate major populations but could cause the algorithm to overlook
rare populations.

#############################################################################
# Compiling C code
#############################################################################
cd bin
cc -o flock1 ../src/flock1.c ../src/find_connected.c -lm
cc -o flock2 ../src/flock2.c -lm
cc -o cent_adjust ../src/cent_adjust.c -lm

#############################################################################
# FCSTrans
#############################################################################
A shell script named ipconvert.sh is included that runs the FCSTrans R
code for converting and transforming a binary FCS file. The output consists
of one text file containing the transformed channel intensity values and
another file containing a list of the FCS parameters.

cd bin
/usr/local/flock/bin/ipconvert.sh ../example/data/FCS2.fcs
/usr/local/flock/bin/ipconvert.sh ../example/data/FCS3.fcs

#############################################################################
# Running flock1 or flock2
#############################################################################
Running the FLOCK1 and FLOCK2 algorithms generate 8 output files that have
generic file names. For this reason, it is recommended that one output
directory be created for one input file to the program.

cd example/output/FCS2
/usr/local/flock/bin/flock1 ../../data/FCS2.txt

cd example/output/FCS3
/usr/local/flock/bin/flock2 ../../data/FCS3.txt

Files created: MFI.txt, percentage.txt, population_id.txt, profile.txt,
               flock_results.txt, coordinates.txt, population_center.txt
               and percentage.txt

Usage Information for FLOCK1
----------------------------------------------------------------------------
basic mode: flock1 fcs.txt
advanced_ mode: flock1 fcs.txt num_bin density_index max_num_pop

Usage Information for FLOCK2
----------------------------------------------------------------------------
basic mode: flock data_file
advanced mode 0 (specify maximum # of pops): flock data_file max_num_pop
advanced mode 1 (without # of pops): flock data_file num_bin density_index
advanced mode 2 (specify # of pops): flock data_file num_bin density_index
                                           number_of_pop
advanced mode 3 (specify both # of pops): flock data_file num_bin density_index
                                           number_of_pop max_num_pop

FLOCK Output Files
----------------------------------------------------------------------------
coordinates.txt:
    Output is the intensity values for each marker and event

flock_results.txt:
    A combination of the input file, event identifiers and population
    identifiers.

MFI.txt:
    Provides the mean fluorescence intensity for each population for each
    marker/parameter

population_id.txt:
    Contains population identifiers (i.e, values from [1 to n] where n is
    the population assigned to the  corresponding events in the input data
    file, one identifier per row.)

population_center.txt:
    Contains the centroid coordinates for each identified population

percentage.txt:
    Includes the population identifiers and percentage of events within that
    population (relative to the whole data file)

profile.txt:
    Displays an expression profile, where the approximate expression level
    for each marker is assigned a numeric value from 1-4, for each identified
    population

fcs_properties.txt:
    Contains the number of events, number of populations, and number of
    markers, as well as the algorithm parameters used in the  analysis

#############################################################################
# Running cent_adjust 
#############################################################################
Running the cent_adjust algorithm generates 4 output files that have
generic file names. For this reason, it is recommened that one output
directory be created for one input file to the program. 

mkdir example/output/FCS2/cent_adjust
cd example/output/FCS2/cent_adjust
/usr/local/flock/bin/cent_adjust ../population_center.txt ../coordinates.txt

Files created: MFI.txt, percentage.txt, population_id.txt and profile.txt

Usage Information for cent_adjust
----------------------------------------------------------------------------
basic mode: cent_adjust input_center input_data_file