diff src/README @ 1:7eab80f86779 draft

add FLOCK

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/src/README	Mon Feb 27 13:26:09 2017 -0500
@@ -0,0 +1,139 @@
+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