\name{readFlowJoList} 
\alias{readFlowJoList}
\alias{readFlowJoFile}
\alias{readFlowJoFile,character-method}

\alias{flowJoList-class}
\alias{flowJoObj-class}

\alias{gateNodeToFilterObject}
\alias{gateNodeToFilterObject,XMLInternalElementNode-method}
\alias{gatherFlowJoTransformations}
\alias{gatherFlowJoTransformations,XMLInternalDocument-method}
\alias{gatherFlowJoGates}
\alias{gatherFlowJoGates,XMLInternalDocument-method}
\alias{getFlowJoCompMatrix}
\alias{getFlowJoCompMatrix,XMLInternalDocument-method}
\alias{getFlowJoVersion}
\alias{getFlowJoVersion,XMLInternalDocument-method}
\alias{getWellId}
\alias{getWellId,flowFrame-method}


\title{Parse one or more FlowJo workspaces} 
\description{ 
 Gather up and organize all of the gates, transformations, and compensation matrices in a FlowJo workspace or list of FlowJo workspaces.
} 
\usage{ 
readFlowJoList(workspaceVec, altFileLocation) 
} 


\arguments{ 
 \item{workspaceVec}{ a list (or vector or single character string) of the path to FlowJo workspace(s) one wants to parse} 
 \item{altFileLocation}{ an alternate location to the FCS files may be supplied.  See details below}
}
 
\details{ 
 
FlowJo is a commercial flow cytometry application from the company TreeStar, Inc. The 'save' format for FlowJo is the FlowJo workspace.  A FlowJo workspace is an XML document that specifies all of the information necessary to recapitulate the exact user experience in the program at the time of the save.  This files includes information on the location of all the relevant FCS files, their grouping, transformation, compensation, gating, and graphical displays last used by the researcher. 

In some cases a FlowJo workspace and the associated FCS files need to be moved on the file system.  If this is done the paths to the FCS files as embedded in the workspace will be stale (wrong).  The \emph{altFileLocation} argument allows the user to supply an alternate path to the FCS files.

The readFlowJoList method parses one or more FlowJo workspaces collecting all of the gate structures designed by the user.  These gating structures are converted to flowCore style filter objects.  Furthermore, because FlowJo users are often interested in not only the results of the final (i.e. terminal tip) gate, but also the results of many of the intermediate gates, readFlowJoList collects together all possible ordered subgates and chains them together as  intersect-filter objects.  Thus, if the user specifies the following gating scheme in FlowJo: 
\preformatted{

   Gate_A 
     | 
     ----> Gate_B 
             | 
             -----> Gate_C 

}
Then gatherFlowJoGates will create, as flowCore filter objects: 
\preformatted{

Gate_A 
Gate_A  &  Gate_B 
Gate_A  &  Gate_B  & Gate_C 
Gate_C 

}
To further complicate issues, a single FlowJo workspace often references dozens of FCS files.  In addition, each FCS file may be compensated with a different compensation matrix.  Finally, the FlowJo user may have implemented many different types of transformations on the data.  While currently tracked, it seems that the gating coordinates in the FlowJo workspace are listed in linear space and not as transformed values.   Thus, while retrieved, the transformation information is not otherwise used by the code. 

Thus, the return value for the readFlowJoList method is a moderately complex data structure (called a flowJoList) that captures the path to all of the referenced FCS files, all of their gates, their compensation matrices, as well as the path to the FlowJo workspace, the version of FlowJo used, and when the file was last updated.  This last item can be useful when tracking changes to the gating structures that are made by the cytometrist.  The data corresponding to a single FlowJo workspace is called a flowJoObj.  One or more flowJoObjs are contained in each flowJoList. 
}

\note{
For more details see: 
  The flowFlowJo vignette at \url{../doc/flowFlowJo.pdf} 
  FlowJo on the web at: \url{http://www.flowjo.com/}  

} 

\value{  readFlowJoList returns a \emph{flowJoList}.  A flowJoList is essentially a list of lists containing the gating structures, compensation matrices, and other information related to a set of FlowJo workspaces. } 


\author{ John Gosink } 

\examples{ 

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

} 

\keyword{methods}
\keyword{list}