readFlowJoList          package:flowFlowJo          R Documentation

_P_a_r_s_e _o_n_e _o_r _m_o_r_e _F_l_o_w_J_o _w_o_r_k_s_p_a_c_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Gather up and organize all of the gates, transformations, and
     compensation matrices in a FlowJo workspace or list of FlowJo
     workspaces.

_U_s_a_g_e:

      
     readFlowJoList(workspaceVec, altFileLocation) 

_A_r_g_u_m_e_n_t_s:

workspaceVec: a list (or vector or single character string) of the path
          to FlowJo workspace(s) one wants to parse

altFileLocation: an alternate location to the FCS files may be
          supplied.  See details below

_D_e_t_a_i_l_s:

     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
     _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: 



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

     Then gatherFlowJoGates will create, as flowCore filter objects: 



     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.

_V_a_l_u_e:

     readFlowJoList returns a _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.

_N_o_t_e:

     For more details see:  The flowFlowJo vignette at <URL:
     ../doc/flowFlowJo.pdf>  FlowJo on the web at: <URL:
     http://www.flowjo.com/>

_A_u_t_h_o_r(_s):

     John Gosink

_E_x_a_m_p_l_e_s:

      

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

