read.FCS              package:rflowcyt              R Documentation

_R_e_a_d_i_n_g _i_n _a _r_a_w _b_i_n_a_r_y _F_l_o_w _C_y_t_o_m_e_t_r_y _S_t_a_n_d_a_r_d (_F_C_S) _f_i_l_e

_D_e_s_c_r_i_p_t_i_o_n:

     Reads in a Flow Cytometry Standard (FCS) file and outputs an "FCS"
     R object.

_U_s_a_g_e:

     read.FCS(fileName, myFCSobj.name="", fcs.type=NULL, 
              fcs.byte.size =2, fcs.signed=TRUE, fcs.endian="auto",
              use.FCS.shortnames = FALSE, no.names = FALSE,
              UseS3 = FALSE,
              MY.DEBUG = TRUE)

_A_r_g_u_m_e_n_t_s:

fileName: string of the FCS file location 

myFCSobj.name: character string of the FCS object name given; default
          is ""

fcs.type: a list of information (version, byte.size, signed, endian)
          about the FCS file; see 'fcs.type'

fcs.byte.size: numeric indicating the fcs file byte size, default is 2 

fcs.signed: TRUE if signed binary data, FALSE if unsigned

fcs.endian: character string; the endian of the fcs file:

     "_a_u_t_o" will automatically determine the endianness

     "_b_i_g" Byte order is 4,3,2,1

     "_l_i_t_t_l_e" Byte order is 1,2,3,4 

use.FCS.shortnames: boolean indicating whether or not to use the short
          or longnames for the dataframe in the FCS object output,
          default is TRUE/to use the short names 

no.names: boolean indicating whether or not to use the names in the fcs
          file for the FCS object output, default is FALSE/to use the
          names in the FCS file

   UseS3: If true, save in old S3 class structure, else save in new S4
          class strucuture

MY.DEBUG: boolean indicating whether or not to print the debugging
          statements, default is TRUE/to print

_D_e_t_a_i_l_s:

     This function also checks if there are discrepancies between the
     data and the metadata in terms of range and size.  If there is,
     then the data is re-read with different fcs.byte.size (1,2,4,8)
     and fcs.signed (TRUE, FALSE) combinations until there is no
     discrepancy between the data and the metadata.  If there is still
     a discrepancy, then the routine is halted.  Note: For FCS version
     3.0 files, only the range of the data is checked against what is
     stated in the metadata because FCS version 3.0 files have extra
     elements that are read into the data.

_V_a_l_u_e:

a "FCS" object: has the following slots:

    data: a dataframe of the cells as rows and the variables for each
          cell as the columns

metadata: a list of the variable names and comments as in the FCS file
          which may include the following (for FCS file version
          3.2.19):

     $_P_A_R the number of columns/parameters

     $_T_O_T the total number of cells/rows

     $_M_O_D_E the mode of the FCS file

     $_B_E_G_I_N_A_N_A_L_Y_S_I_S part of FCS file heading indicating the position of
          the beginning of the analysis portion

     $_B_E_G_I_N_D_A_T_A part of FCS file heading indicating the beginning of
          the data portion

     $_B_Y_T_E_O_R_D part of FCS file heading indicating byte order/endian

     $_B_E_G_I_N_S_T_E_X_T part of FCS file heading indicating beginning of text

     $_D_A_T_A_T_Y_P_E part of FCS file heading indicating the type of data

     $_E_N_D_A_N_A_L_Y_S_I_S part of FCS file heading indicating the end of the
          analysis portion

     $_E_N_D_D_A_T_A part of FCS file heading indicating the end of the data
          portion

     $_E_N_D_S_T_E_X_T part of FCS file heading indicating the end of the text
          portion

     $_N_E_X_T_D_A_T_A part of FCS file heading indicating the next data

     $_P_n_B Number of bits reserved for parameter number n

     $_P_n_E Amplification type for parameter n

     $_P_n_R Range for parameter number n

     $_A_B_R_T Events lost due to data acquisition electronic coincidence

     $_B_T_I_M Clock time at beginning of data acquisition

     $_C_E_L_L_S Description of objects measured.

     $_C_O_M Comment

     $_C_O_M_P Fluorescence compensation matrix.

     $_C_S_M_O_D_E Cell subset mode, number of subsets to which an object may
          belong

     $_C_S_V_B_I_T_S Number of bits used to encode a cell subset identifier

     $_C_S_V_n_F_L_A_G The bit set as a flag for subset n.

     $_C_Y_T Type of flow cytometer

     $_C_Y_T_S_N Flow cytometer serial number

     $_D_A_T_E Date of data set acquisition

     $_E_T_I_M Clock time at end of data acquisition

     $_E_X_P Name of investigator initiating the experiment

     $_F_I_L Name of the data file containing the data set

     $_G_A_T_E Number of gating parameters

     $_G_A_T_I_N_G Specifies region combinations used for gating

     $_G_n_E Amplification type for gating parameter number n

     $_G_n_F Optical filter used for gating parameter number n

     $_G_n_N Name of gating parameter number n

     $_G_n_P Percent of emitted light collected by gating parameter n

     $_G_n_R Range of gating parameter n

     $_G_n_S Name used for gating parameter n

     $_G_n_T Detector type for gating parameter n

     $_G_n_V Detector voltage for gating parameter n

     $_I_N_S_T Institution at which data acquired

     $_L_O_S_T Number of events lost due to computer busy

     $_O_P Name of flow cytometry operator

     $_P_k_n Peak channel number of univariate histogram for parameter n

     $_P_K_N_n Count in peak channel of univariate histogram for parameter
          n

     $_P_n_F Name of optical filter for parameter n

     $_P_n_G Amplifier gain used for acquisition of parameter n

     $_P_n_L Excitation wavelength for parameter n

     $_P_n_N Short name for parameter n

     $_P_n_O Excitation power for parameter n

     $_P_n_P Percent of emitted light collected by parameter n

     $_P_n_S Long name/Name used for parameter n in the dataset

     $_P_n_T Detector type for parameter n

     $_P_n_V Detector voltage for parameter n

     $_P_R_O_J Name of the experiment project

     $_R_n_I Gating region for parameter number n

     $_R_n_W Window settings for gating region n

     $_S_M_N_O Specimen (tube or well) label

     $_S_R_C Source of the specimen (patient name,cell types)

     $_S_Y_S Type of computer and its operating system

     $_T_I_M_E_S_T_E_P Time step for time parameter

     $_T_R Trigger parameter and its threshold

     $_U_N_I_C_O_D_E UNICODE code page for string type keyword values

     _R_F_A_C_S_a_d_d$>>$... metadata information added using rflowcyt package
          via 'addParameter', 'extractGatedData'

_W_A_R_N_I_N_G:

     The following scenerios may happen in which read.FCS has failed:

_P_r_o_b_l_e_m _1 A number of names assigned to the columns of the data is
     different from the number of columns.

_P_o_s_s_i_b_l_e _S_o_l_u_t_i_o_n Use read.FCS again and choose a different
     fcs.byte.size value (such as 1, 2, 4, 8, 12, 16, etc.)


_P_r_o_b_l_e_m _2 The file has been read properly by read.FCS, but the range of
     the resulting FCS R-object is wrong (ie, there are negative values
     when all values should be positive).

_P_o_s_s_i_b_l_e _S_o_l_u_t_i_o_n_s Use read.FCS again, and choose a different
     fcs.signed value (either TRUE or FALSE) and/or choose a different
     fcs.endian value (either "big", or "little" or "auto"). 

_N_o_t_e:

     Thanks to Peter Rabinovitch for informaton and Julie McElrath lab
     for the example data.

_A_u_t_h_o_r(_s):

     A.J. Rossini and J.Y. Wan

_S_e_e _A_l_s_o:

     'summary', 'print', 'extractGatedData', 'addParameter',
     '"[-methods"', '"[[-methods"', 'fcs.type'

_E_x_a_m_p_l_e_s:

       if (require(rfcdmin)) {
         ## obtaining the location of the fcs files in the data

         FACSCAN256<- paste(system.file("fcs", package="rfcdmin"),
                                 "facscan256.fcs",
                                 sep="/")

         ## reading in the FCS files
         FCSobj1<-read.FCS(FACSCAN256)

         ## If a known type, then:
         ## read.FCS(fileName, fcs.type=foo)

         ## currently, the type doesn't have to be an argument
         ## the read.FCS function will check against different
         ## fcs.byte.size and fcs.signed options
         ## if the data is not the correct size or
         ## range as in the metadata
         ## NOTE: for FCS version 3.0 only
         ## the ranges NOT the sizes are checked
       }

