\name{collectSummaryFlowInfo}  
\alias{collectSummaryFlowInfo}
\alias{collectSummaryFlowInfo,flowJoList-method}
\alias{fcsSummary-class}
\alias{fcsSummaryList-class}

\title{ Collect Population Statistics on Flow Files }  

\description{  
Creates a data structure containing a comprehensive list of summary statistics and related information on the cell populations of the FCS files referenced in one or more FlowJo workspaces.  
}  
\usage{  
collectSummaryFlowInfo(fj, \dots)  
}  

\arguments{  
     \item{fj}{ a flowJoList object.  See readFlowJoList. } 
     \item{\dots}{ Additional arguments detailed below:  }
}

\details{
   Additional arguments also include the following:  
   \preformatted{
   fileNamePatterns - a vector of patterns that will be used to pick only specific FCS files from amongst all the FCS files listed in FlowJo workspaces.  The default (\dQuote{.}) returns all of them.  
   gateNamePattern  - a vector of patterns that will be used to pick only a subset of all the gates for all FCS files listed in the FlowJo workspaces.  The default (\dQuote{.}) returns all of them.  \emph{Not implemented yet.}  
   upperCaseGates   - Logical.  Default = FALSE.  If TRUE, converts all gate names to upper case.    
   keywords         - a vector of fields that you want to retrieve from the text section of each FCS file.   
   stripGutters     - Logical.  Currently FALSE and non-functional.  Whether or not to strip out gutter events before doing the main gating.   
   method           - what type of measurement to use for MFIs on each population.  One of mean, median (default), or mode.  \emph{Only median is currently implemented.}   
  }
}  


\value{  
The method collectSummaryFlowInfo returns a moderately complex data structure called an \emph{fcsSummaryList} detailing summary statistics and other information from the cell populations listed in one or more FlowJo workspaces.  The main argument for this method is a flowJoList object that was created using the readFlowJoList method.  The key issue here is that parsing a set of FlowJo workspaces and converting the referenced gates into flowCore style filters takes only a few seconds or minutes.  Reading in each of the referenced FCS files in a very large experiment and gating them with the filters (which this code does), may take many hours.  Thus this method also includes two arguments  (\emph{fileNamePatterns} and \emph{gateNamePatterns}) to reduce the number of FCS files examined.  This method may, optionally, search the text/header section of each FCS file looking for specific keywords (e.g. $P2R, or $DATE, etc.) and collect the appropriate values.  Finally, one of the main operations of this method is to collect the MFIs cell counts for each population in each FCS file.  The user can choose either mean, median, or mode for the MFI values.  Returned values are in untransformed units (e.g. not log intensities).  
}  

\references{ See also FlowJo from TreeStar Inc, at:  \url{http://www.flowjo.com/} }  
\author{ John Gosink }  

\examples{  
 
library(flowFlowJo);
demoLocation <- system.file("extdata", "DemoWorkspace.wsp", package="flowFlowJo"); 
actualFCSLoc <- system.file("extdata/fcsFiles", package="flowFlowJo"); 
testList     <- readFlowJoList(demoLocation, altFileLocation=actualFCSLoc);

# This next statement may take a few moments to run as it is parsing through a FlowJo workspace
# and two dozen FCS files...
summaryStatsObj <- collectSummaryFlowInfo(testList);

}  
\keyword{methods}