\documentclass{article}
% Commands to recognize Rnw file in xemacs
% M-x noweb-mode
% M-x font-lock-mode

% -*- mode: noweb; noweb-default-code-mode: R-mode; -*-
%\VignetteIndexEntry{rflowcyt overview}
%\VignetteKeywords{FACS, FCS, Flow Cytometry}
%\VignetteDepends{rflowcyt,lattice,locfit}
%\VignettePackage{rflowcyt}




%% Postscript fonts
\usepackage{hyperref}
\usepackage{times}
\usepackage{graphicx}
\usepackage[authoryear,round]{natbib}

%% layout
\textwidth=6.2in
\textheight=8.5in
\oddsidemargin=.1in
\evensidemargin=.1in
\headheight=-.3in

%% Special fonts
\newcommand{\scscst}{\scriptscriptstyle}
\newcommand{\scst}{\scriptstyle}
\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Rargument}[1]{{\textit{#1}}}
\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rmethod}[1]{{\texttt{#1}}}
\newcommand{\Rclass}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textit{#1}}}
\newcommand{\code}[1]{{\texttt{#1}}}


\title{Using RFlowCyt}
\author{A.J. Rossini \and J.Y. Wan \and N. Le Meur}
\date{\today}

\usepackage{d:/biocbld/R-2.3.0/share/texmf/Sweave}
\begin{document}
\maketitle
\begin{abstract}
  This manual describes the usage of the functions in the \Rpackage{rflowcyt} library package,
 part of the Bioconductor\footnote{\url{http://www.bioconductor.org/}} project.
 The main categories are Data Mananagement and Retrieval, Flow Cytometry Visualizations,
 Exploratory Analysis, Gating, and Flow Cytometry Hypothesis Testing and Statistical Inference.
 Examples are also shown for each category.
\end{abstract}

\tableofcontents

\clearpage
\section{Data Management and Retrieval}
\label{SEC:data-man-intro}

The \Rpackage{rflowcyt} tools in this category are
used for the following tasks:

\begin{enumerate}
\item \Rfunction{read.FCS} to read in FCS binary files into R-objects of S4 class \Rclass{FCS}
\item \Rfunction{[i,j]} to extract or subset information from the \Robject{data} 
(a \Robject{matrix} object) of the \Robject{FCS} R-object
\item \Rfunction{[[i]]} to extract \Robject{metadata} 
(which is of S4 class \Rclass{FCSmetadata}) portion of the \Robject{FCS} R-object
\item \Rfunction{[i,j]<-} to replace \Robject{data} information
\item \Rfunction{addParameter} to add column variables in the \Robject{data}
\item \Rfunction{[[i]]<-} to replace or add new information to the \Robject{metadata} 
portion of the \Robject{FCS} R-object
\item \Rfunction{as} to coerce among \Rclass{FCS}, \Rclass{data.frame} and \Rclass{matrix} class
  objects
\item \Rfunction{equals} to demonstrate equality between two FCS R objects
\item \Rmethod{print-methods}, \Rmethod{show-methods} print or show methods for
  \Robject{FCS} objects
\item \Rfunction{checkvars} to check for any discrepancies between the
  \Robject{metadata} and the \Robject{data} of the \Robject{FCS} object
\item \Rfunction{fixvars} to fix the \Robject{metadata} to relect the information
  obtained from the \Robject{data} if there are discrepancies
\item \Rfunction{summary-methods} to summarize the \Robject{FCS} R-object with Tukey's
  five number summary of the \Robject{data} and with slot information in the
  \Robject{metadata} and to output an \Robject{FCSsummary} S4 class object
\end{enumerate}

\subsection{Datasets}
\label{SUBSEC:Datasets}

There are four types of data sets that are available in the required
data package \Rpackage{rfcdmin}. The first two types of data set consists of
raw binary Flow Cytometry Standard (FCS) files, and the second type
consists of R-objects of S4 class \Rclass{FCS} and is the result of reading
in FCS binary files using \Rfunction{read.FCS} or \Rfunction{read.series.FCS} function.
Table~\ref{tab:1} summarizes the current reading information for the
raw binary files in the \Rpackage{rfcdmin} data package.

For more information about the binary FCS files and the dataset contain in the \Rpackage{rfcdmin} package, look at the package documentation files using the commands in R:

\begin{Schunk}
\begin{Sinput}
> help(package = "rfcdmin")
\end{Sinput}
\end{Schunk}


Loading required package: xtable
% latex table generated in R 2.3.0 by xtable 1.3-1 package
% Tue Apr 25 01:36:06 2006
\begin{table}[ht]
\begin{center}
\begin{tabular}{rlllll}
\hline
 & FCS Version & Source & Machine & bit resolution & Integer range \\
\hline
facscan256.fcs & 2.0 & UW & facscan & 8 & 0-256 \\
SEB-NP22.fcs & 3.0 & FHCRC & DiVa & 10 & 0-1024 \\
A06-H06 & 2.0 & BCCRC & FACSCalibur & 10 & 0-1024 \\
\hline
\end{tabular}
\caption{Example FCS binary files in 'rfcdmin' package that can be 
         read in using Rfunction{read.FCS} or Rfunction{read.series.FCS}.
         (UW: University of Washington, Seattle; FHCRC: Fred Hutchinson Cancer 
         Research Center, Seattle; BCCRC: British Columbia Cancer Research Center, Vancouver)}
\label{tab:1}
\end{center}
\end{table}

\subsubsection{Binary FCS data files} 
\label{SUBSUBSEC:BinaryFCSFiles}

The Flow Cytometry Standard (FCS) binary files consist of a HEADER, a
TEXT, a DATA, and an optional ANALYSIS segment. The HEADER in ASCII
text gives information about the version of the FCS file and the byte
offsets of the beginning and ending of the other segments within the
FCS file. The FCS version 3.0 is currently used and has been updated
from version 2.0 to accommodate data sets longer than 99,999,999 bytes
and allowing for primary and supplemental portions within the TEXT
segment, among other changes. Located after the HEADER, the TEXT
segment in ASCII text includes summary information in keywords such as
the number of observations and names of column variables in the DATA
segment.  The DATA segment that follows consists of the raw binary
data.  The optional ANALYSIS segment includes some results of earlier
data analyses \citep{robin:2001}.

When specific immunofluoroescence signals are received and digitized
by the analog-to-digital converters (ADCs) of a flow cytometer
machine, the measurements are grouped into a number of bins based on
the bit-resolution of the ADC.  Thus, a \textit{n}-bit resolution ADC
will group the data into $2^n$ bins or "channels".  Thus, each
immunofluoroescence measurement variable is actually categorical and
has an integer range from 0 to $2^n$, depending on the ADC
bit-resolution, which is usually 10 or 8 \citep{robin:2001}.

\subsubsection{Reading in the FCS binary file}
\label{SUBSUBSEC:readFCS}
 
The subsequent code allows us to call the \Rpackage{rflowcyt}
library.  If the  \Rpackage{rflowcyt} library is in the working library
location, then the \Rargument{library.location} is a character string
identifying the location of the \Rpackage{rflowcyt} library.

\begin{Schunk}
\begin{Sinput}
> if (!require(rflowcyt)) {
+     stop("Rflowcyt not available?")
+ }
\end{Sinput}
\begin{Soutput}
Loading required package: rflowcyt
Loading required package: survival
Loading required package: splines
Loading required package: KernSmooth
KernSmooth 2.22 installed
Copyright M. P. Wand 1997
Loading required package: MASS
Loading required package: grid
Loading required package: splancs
Loading required package: sp

Spatial Point Pattern Analysis Code in S-Plus

 Version 2 - Spatial and Space-Time analysis
Loading required package: hexbin
Loading required package: lattice
Loading required package: colorspace

Attaching package: 'colorspace'


	The following object(s) are masked from package:grDevices :

	 hcl 

Loading required package: rfcdmin
Loading required package: fields
fields is loaded use help(fields) for an overview of this library

Attaching package: 'fields'


	The following object(s) are masked from package:grDevices :

	 trans3d 

Loading required package: lattice
Loading required package: locfit
Loading required package: akima
locfit 1.5-3 	 2006-04-06 
\end{Soutput}
\begin{Sinput}
> if (!require(rfcdmin)) {
+     stop("rfcdmin not available?")
+ }
\end{Sinput}
\end{Schunk}


The raw binary FCS files can have the extension "\*.fcs" or no extension at all.
The raw binary FCS files can be read one by one using  the \Rfunction{read.FCS} function or
in a set using the \Rfunction{read.series.FCS} function. The output is either 
a \Robject{FCS} R object of S4 or S3 class or a list of \Robject{FCS} R-objects.
(\textit{NB: Currently, the \Rpackage{rflowcyt} package implements functions and methods with the S4 class.})
  
In order to read in the FCS binary file, the location of the FCS
binary file in the fcs or bccrc directories of the \Rpackage{rfcdmin}
package has to be input as a parameter in the calling for 
\Rfunction{read.FCS} or \Rfunction{read.series.FCS}.


\begin{Schunk}
\begin{Sinput}
> fcs.loc <- system.file("fcs", package = "rfcdmin")
\end{Sinput}
\end{Schunk}

After finding the \*.fcs file location, we will read in the raw binary
file "facscan256.fcs" using \Rfunction{read.FCS} and call it
\Robject{FC.FCSRobj}.  In order to demonstrate a S3-to-S4 class change, we
will incorrectly read in the binary file as an S3 object.

\begin{Schunk}
\begin{Sinput}
> file.location <- paste(fcs.loc, "facscan256.fcs", sep = "/")
> FC.FCSRobj <- read.FCS(file.location, UseS3 = TRUE, MY.DEBUG = FALSE, 
+     fcs.type = NULL)
\end{Sinput}
\begin{Soutput}
NOTE: Long names $PnS are missing. 
Short names $PnN are assigned to the dataset instead. 
\end{Soutput}
\end{Schunk}

If the \Rargument{fcs.type} option is specified for a particular flow cytometer
machine, the \Rfunction{read.FCS} options will be pre-specified automatically
without user input.  Depending on the machine from which the FCS
binary file was obtained, the \Rargument{fcs.type} can be specified as one of
the following in Table ~\ref{tab:2}.See also \Rargument{fcs.type} documentation for more details. 


% latex table generated in R 2.3.0 by xtable 1.3-1 package
% Tue Apr 25 01:36:11 2006
\begin{table}[ht]
\begin{center}
\begin{tabular}{rl}
\hline
 & fcs.type \\
\hline
1 & fcs.type.LYSYS \\
2 & fcs.type.cellquest.3.1.FACS.Vantage \\
3 & fcs.type.cellquest.3.1.FACScan \\
4 & fcs.type.cellquest.3.3 \\
5 & fcs.type.default \\
6 & fcs.type.LSR256 \\
7 & fcs.type.facscan256 \\
8 & fcs.type.DiVa1024 \\
9 & fcs.type.FACSCalibur1024 \\
10 & fcs.type.LSR1024 \\
11 & fcs.type.facscan1024 \\
\hline
\end{tabular}
\caption{Summary of FCS types used by read.FCS}
\label{tab:2}
\end{center}
\end{table}


The following are \Robject{FCS} R-objects which are readily accessible in R and
can be used for analysis using the tools in the \Rpackage{rflowcyt}
package.  Prior to this release, the FCS class has been S3.  Now the
FCS class among other classes (\Rclass{FCSmetadata}, \Rclass{FCSgate} (described in the
Gating section), \Rclass{FCSggobi} (still in working progress) ) are S4.  Use
\textbf{convertS3toS4} to convert S3-class \Robject{FCS} to S4-class \Robject{FCS} R
objects.
To exemplify the conversion, the following demonstrates the
conversion of an S3 \Robject{FCS} R-object to an S4 \Robject{FCS} R-object:

\begin{Schunk}
\begin{Sinput}
> FC.FCSRobj <- convertS3toS4(FC.FCSRobj, myFCSobj.name = "FC.FCSRobj", 
+     fileName = file.location)
\end{Sinput}
\end{Schunk}

The \Rfunction{read.series.FCS} function allows to read multiple FCS files. The output is a list of \Robject{FCS} R-object.
\begin{Schunk}
\begin{Sinput}
> pathFiles <- system.file("bccrc", package = "rfcdmin")
> drugFiles <- dir(pathFiles)
> drugData <- read.series.FCS(drugFiles, path = pathFiles, MY.DEBUG = FALSE)
\end{Sinput}
\end{Schunk}


A \Robject{FCS} R-object has slots \Robject{data} and \Robject{metadata}. 
The \Robject{data} component is a matrix in which the rows are the individual cells or
observations, and the columns are the different immunofluoroescence
measurements or variables.  The metadata is of S4-class \Rclass{FCSmetadata}
and has slots referring to keywords that are in the TEXT segment of
the FCS raw binary file.  Information such as variable names
(\Robject{longnames} and \Robject{shortnames}) and ranges (\Robject{paramranges}) are also
slots in the \Robject{metadata} component.  For more details, see the help files
for \Robject{FCS} and \Robject{FCSmetadata}.


\subsubsection{Opening \Rpackage{rflowcyt} data with \Robject{FCS} R-objects}
\label{SUBSUBSEC:dataFCSRobj}

The \Rpackage{rfcdmin} data package also contains archived  \Robject{FCS} R-object:


\begin{Schunk}
\begin{Sinput}
> data(VRCmin)
> data(MC.053min)
> data(flowcyt.fluors)
\end{Sinput}
\end{Schunk}
For more details of the \Robject{FCS} R-object available see \Rfunction{data(package="rfcdmin")}.

\subsubsection{Other S4 class R-objects}
\label{SUBSUBSEC:OtherS4objs}

Besides the \Rclass{FCS} class, other S4 class R-objects
include \Rclass{FCSmetadata}, \Rclass{FCSsummary}, and \Rclass{FCSgate}. 
The \Rclass{FCS} class is the class of all FCS files that are read into R using
\Rfunction{read.FCS} or \Rfunction{read.series.FCS}.  The \Rclass{FCSmetadata} is 
the class of the \Robject{metadata} slot of an \textit{FCS} R-object. 
The \textit{FCSsummary} class is the class of the output of the \Rmethod{summary} method 
implemented on a \Robject{FCS} R-object.  The \Rclass{FCSgate} class
contains the \Rclass{FCS} class and extends it to include gating information
(ie, the information about the indexing of row observations for
subsequent extraction).

The following is a brief summary of the available, generic methods
associated with each class object.

\begin{itemize}
\item \textbf{"new" Generic Method}
Default objects can be made by using the \Rmethod{new(object-contents,
  S4-class-name)} method, where object-contents refer to the contents
of each slot for the specified S4-class-name.

The following commands produce default class objects with no slot
information:

\begin{Schunk}
\begin{Sinput}
> new.FCS <- new("FCS")
> new.FCSmetadata <- new("FCSmetadata")
> new.FCSsummary <- new("FCSsummary")
> new.FCSgate <- new("FCSgate")
\end{Sinput}
\end{Schunk}

\item \textbf{"coercian" Generic Method}
Currently, there are only coercian methods to and from the \Rclass{FCS} class
and the \Rclass{matrix} and \Rclass{data.frame} classes.

A user makes a \Robject{FCS} R-object by the coercian method \Rmethod{as} exemplified in
the following code, where data2 is a \Robject{matrix} or \Robject{data.frame} identifying
the rows as the cell observations and the columns as the different
variables:

\begin{Schunk}
\begin{Sinput}
> data2 <- rbind(1:10, 2:11, 3:12)
> data2.matrix <- as(data2, "matrix")
> data2.df <- as.data.frame(data2)
> test.FCSRobj <- as(data2.matrix, "FCS")
> test.FCSobj2 <- as(data2.df, "FCS")
> original.matrix <- as(test.FCSobj2, "matrix")
> original.matrix <- as(test.FCSobj2, "data.frame")
> metadata <- new("FCSmetadata", size = dim(data2)[1], nparam = dim(data2)[2], 
+     fcsinfo = list(comment = "This is a pseudo FCS-R object."))
> test.FCSRobj@metadata <- metadata
> test.FCSRobj
\end{Sinput}
\begin{Soutput}
     Original Object of class `FCS' from: None 
     Object name: None 
     Dimensions 3 by 10 
\end{Soutput}
\end{Schunk}

\item \textbf{"is" Generic Method}
The S4 R-object class can be verified by using the \Rmethod{is} method.  

\begin{Schunk}
\begin{Sinput}
> is(MC.053, "matrix")
\end{Sinput}
\begin{Soutput}
[1] FALSE
\end{Soutput}
\begin{Sinput}
> is(MC.053, "FCS")
\end{Sinput}
\begin{Soutput}
[1] TRUE
\end{Soutput}
\begin{Sinput}
> is(MC.053@metadata, "FCSmetadata")
\end{Sinput}
\begin{Soutput}
[1] TRUE
\end{Soutput}
\begin{Sinput}
> is(MC.053, "FCSgate")
\end{Sinput}
\begin{Soutput}
[1] FALSE
\end{Soutput}
\end{Schunk}

The \Rclass{FCSsummary} class is exemplified below:

\begin{Schunk}
\begin{Sinput}
> sum.FCS <- summary(MC.053)
\end{Sinput}
\begin{Soutput}
I. Data reports:

   A. Dimension Check: Dimensions: (row X col): 126795 X 7 

   B. Data Column Names & Univariate Summary:
    Using Tukey's method for the five number summary 
                column min lower-hinge median upper-hinge  max    mean      sd
Forward Scatter      1   0         430    504         687 1023 568.045 196.049
Side Scatter         2   0          70     94         275 1023 185.913 185.470
IFNgamma FITC        3   0         194    236         308  955 246.718  81.965
CD69 PE              4   0         291    353         422 1023 357.339 108.511
CD8 PerCP            5   0         111    186         286  986 237.867 187.510
<NA>                 6   0           0      0           0 1023   0.906   9.737
CD3 APC              7   0         276    740         806 1023 571.022 288.345


 II. Metadata Variable/Slot reports: 
   A. Metadata Slots: 
          slotnames                     description           values
1              mode                            Mode                L
2         size/$TOT            number of cells/rows           126795
3       nparam/$PAR         number of column params                7
4   shortnames/$PnN Shortnames of column parameters        see below
5    longnames/$PnS  Longnames of column parameters        see below
6  paramranges/$PnR Ranges/max of column parameters        see below
7          filename           original FCS filename 042402c1.053.fcs
8        objectname          name of current object           MC.053
9          original  current object original status             TRUE
10          fcsinfo             misc. metadata info   see part II B.

$ColumnParametersSummary
     $PnN    $PnS              $PnR  
[1,] "FSC-H" "Forward Scatter" "1024"
[2,] "SSC-H" "Side Scatter"    "1024"
[3,] "FL1-H" "IFNgamma FITC"   "1024"
[4,] "FL2-H" "CD69 PE"         "1024"
[5,] "FL3-H" "CD8 PerCP"       "1024"
[6,] "FL1-A" NA                "1024"
[7,] "FL4-H" "CD3 APC"         "1024"


   B. Metadata 'fcsinfo' slot length= 103  & slot names: 

$fcsinfoNames
  [1] "$BYTEORD"         "$DATATYPE"        "$NEXTDATA"       
  [4] "$SYS"             "CREATOR"          "$P1B"            
  [7] "$P1E"             "$P2B"             "$P2E"            
 [10] "$P3B"             "$P3E"             "$P4B"            
 [13] "$P4E"             "$P5B"             "$P5E"            
 [16] "$P6B"             "$P6E"             "$P7B"            
 [19] "$P7E"             "PATIENT ID"       "SAMPLE ID"       
 [22] "$CYT"             "CYTNUM"           "$BTIM"           
 [25] "$ETIM"            "BD$AcqLibVersion" "BD$NPAR"         
 [28] "BD$P1N"           "BD$P2N"           "BD$P3N"          
 [31] "BD$P4N"           "BD$P5N"           "BD$P6N"          
 [34] "BD$P7N"           "BD$WORD0"         "BD$WORD1"        
 [37] "BD$WORD2"         "BD$WORD3"         "BD$WORD4"        
 [40] "BD$WORD5"         "BD$WORD6"         "BD$WORD7"        
 [43] "BD$WORD8"         "BD$WORD9"         "BD$WORD10"       
 [46] "BD$WORD11"        "BD$WORD12"        "BD$WORD13"       
 [49] "BD$WORD14"        "BD$WORD15"        "BD$WORD16"       
 [52] "BD$WORD17"        "BD$WORD18"        "BD$WORD19"       
 [55] "BD$WORD20"        "BD$WORD21"        "BD$WORD22"       
 [58] "BD$WORD23"        "BD$WORD24"        "BD$WORD25"       
 [61] "BD$WORD26"        "BD$WORD27"        "BD$WORD28"       
 [64] "BD$WORD29"        "BD$WORD30"        "BD$WORD31"       
 [67] "BD$WORD32"        "BD$WORD33"        "BD$WORD34"       
 [70] "BD$WORD35"        "BD$WORD36"        "BD$WORD37"       
 [73] "BD$WORD38"        "BD$WORD39"        "BD$WORD40"       
 [76] "BD$WORD41"        "BD$WORD42"        "BD$WORD43"       
 [79] "BD$WORD44"        "BD$WORD45"        "BD$WORD46"       
 [82] "BD$WORD47"        "BD$WORD48"        "BD$WORD49"       
 [85] "BD$WORD50"        "BD$WORD51"        "BD$WORD52"       
 [88] "BD$WORD53"        "BD$WORD54"        "BD$WORD55"       
 [91] "BD$WORD56"        "BD$WORD57"        "BD$WORD58"       
 [94] "BD$WORD59"        "BD$WORD60"        "BD$WORD61"       
 [97] "BD$WORD62"        "BD$WORD63"        "BD$LASERMODE"    
[100] "CalibFile"        "P7THRESVOL"       "$FIL"            
[103] "$DATE"           
\end{Soutput}
\begin{Sinput}
> is(sum.FCS, "FCSsummary")
\end{Sinput}
\begin{Soutput}
[1] TRUE
\end{Soutput}
\end{Schunk}
\end{itemize}

\subsection{Tools to access and manipulate \Robject{FCS} R-objects}
\label{SUBSEC:DescriptTools}
\subsubsection{Descriptive tools for \Rclass{FCSmetadata} class R-objects}
\label{SUBSUBSEC:DescriptToolsFCSmetadata}

To access or extract the metadata components, use either the \Rfunction{@}
or \Rfunction{metaData}.

\begin{Schunk}
\begin{Sinput}
> meta1 <- st.1829@metadata
> meta1 <- metaData(st.1829)
\end{Sinput}
\end{Schunk}

To get a description of the \Rclass{FCSmetadata} class, use for example the \Rfunction{show},
\Rfunction{print}, and \Rfunction{summary} functions.

\begin{Schunk}
\begin{Sinput}
> show(st.1829@metadata)
\end{Sinput}
\begin{Soutput}
FACSmetadata for original FCS object: st.1829 from original file 1829_GAG.fcs 
 with  126675 cells and 8 parameters.
\end{Soutput}
\end{Schunk}

The following code would output the \Robject{metadata} as a string and is not
shown because of its lengthy output.

\begin{Schunk}
\begin{Sinput}
> summary(st.1829@metadata)
\end{Sinput}
\end{Schunk}

The slots for an \Rclass{FCSmetadata} are summarized in Table~\ref{tab:4}.


% latex table generated in R 2.3.0 by xtable 1.3-1 package
% Tue Apr 25 01:36:29 2006
\begin{table}[ht]
\begin{center}
\begin{tabular}{rll}
\hline
 & slotnames & description \\
\hline
1 & mode & Mode \\
2 & size & number of cells/rows \\
3 & nparam & number of column parameters \\
4 & shortnames & shortnames of column parameters \\
5 & longnames & longnames of column parameters \\
6 & paramranges & Ranges/Max value of the columns \\
7 & filename & original FCS filename \\
8 & objectname & name of the current object \\
9 & original & current object original status \\
10 & fcsinfo & misc.metadata info \\
\hline
\end{tabular}
\caption{FCSmetadata slot descriptions}
\label{tab:4}
\end{center}
\end{table}
Slots and slot components of the metadata can be retreived by using
\Rfunction{@}, \Rfunction{[i]}, or \Rfunction{[[i]]}. Currently to extract
metadata information, we can use a single character string index being
one of the slotnames in Table ~\ref{tab:4} or one of the slotnames in
the \Robject{fcsinfo} slot.  In the case that there is a common slotname that
is also in the \Robject{fcsinfo} slot, only the slot from Table ~\ref{tab:4}
will be retrieved.

A single numeric index or a vector of numeric indices refers to only
the slot positions of the \Robject{fcsinfo} slot.

The following examples extract the column parameter ranges or maximum
value.
\begin{Schunk}
\begin{Sinput}
> st.1829@metadata@paramranges
\end{Sinput}
\begin{Soutput}
[1] 1024 1024 1024 1024 1024 1024 1024 1024
\end{Soutput}
\begin{Sinput}
> st.1829@metadata["paramranges"]
\end{Sinput}
\begin{Soutput}
[1] 1024 1024 1024 1024 1024 1024 1024 1024
\end{Soutput}
\begin{Sinput}
> st.1829@metadata[["$PnR"]]
\end{Sinput}
\begin{Soutput}
[1] 1024 1024 1024 1024 1024 1024 1024 1024
\end{Soutput}
\end{Schunk}

A single component of the range can also be retrieved
\begin{Schunk}
\begin{Sinput}
> st.1829@metadata[["$P1R"]]
\end{Sinput}
\begin{Soutput}
[1] 1024
\end{Soutput}
\end{Schunk}

Items in the \Rclass{FCSmetadata} can be replaced by using \Rfunction{[...]<-} 
or \Rfunction{[[...]]<-}.  

The following example will replace the \Robject{longnames} with dummy names.

\begin{Schunk}
\begin{Sinput}
> st.1829@metadata["longnames"]
\end{Sinput}
\begin{Soutput}
[1] "FSC-Height"         "Side Scatter"       "CD8 FITC"          
[4] "IFN, IL2, TNF PE"   "CD4 perCP"          " "                 
[7] "CD3 APC"            "Time (204.80 sec.)"
\end{Soutput}
\begin{Sinput}
> st.1829@metadata["longnames"] <- rep("dummy", length(st.1829@metadata["longnames"]))
> st.1829@metadata["$P3S"] <- "wrongname"
> st.1829@metadata["longnames"]
\end{Sinput}
\begin{Soutput}
[1] "dummy"     "dummy"     "wrongname" "dummy"     "dummy"     "dummy"    
[7] "dummy"     "dummy"    
\end{Soutput}
\end{Schunk}

To extract and replace slots of the metadata of a \Robject{FCS} object, use
only \Rfunction{[[..]]} and \Rfunction{[[...]]<-}, respectively.

\begin{Schunk}
\begin{Sinput}
> shortnames.1829 <- st.1829[["shortnames"]]
> shortnames.1829
\end{Sinput}
\begin{Soutput}
[1] "FSC-H" "SSC-H" "FL1-H" "FL2-H" "FL3-H" "FL2-A" "FL4-H" "Time" 
\end{Soutput}
\begin{Sinput}
> st.1829[["$PnR"]]
\end{Sinput}
\begin{Soutput}
[1] 1024 1024 1024 1024 1024 1024 1024 1024
\end{Soutput}
\begin{Sinput}
> st.1829[["$P1R"]] <- 0
> st.1829[["paramranges"]]
\end{Sinput}
\begin{Soutput}
[1]    0 1024 1024 1024 1024 1024 1024 1024
\end{Soutput}
\begin{Sinput}
> st.1829[["newslot"]]
\end{Sinput}
\begin{Soutput}
NULL
\end{Soutput}
\begin{Sinput}
> st.1829[["newslot"]] <- "this is even cooler"
> st.1829[["newslot"]]
\end{Sinput}
\begin{Soutput}
[1] "this is even cooler"
\end{Soutput}
\end{Schunk}


When using the replacement method for a \Robject{FCSmetadata} R-object
(\textit{i.e.},\Rfunction{[...]<-} or \Rfunction{[[...]]<-}), if the slotname is
not found, then a new slot with the current character index is made
under the \Robject{fcsinfo} slot.  In the following example, we will add a new
slot named \Robject{newslot} to the metadata.


\begin{Schunk}
\begin{Sinput}
> st.1829@metadata[["newslot"]] <- "wow this is cool"
> st.1829@metadata@fcsinfo[["newslot"]]
\end{Sinput}
\begin{Soutput}
[1] "wow this is cool"
\end{Soutput}
\end{Schunk}

\subsubsection{Descriptive tools for \Rclass{FCS} class R-objects}
\label{SUBSUBSEC:DescriptToolsFCS}

To access or extract the data components, use either \Rfunction{@} or \Rfunction{fluors}.

\begin{Schunk}
\begin{Sinput}
> meta1 <- st.1829@metadata
> meta1 <- metaData(st.1829)
\end{Sinput}
\end{Schunk}

\begin{Schunk}
\begin{Sinput}
> data1 <- st.1829@data
> data1 <- fluors(st.1829)
> summary(data1)
\end{Sinput}
\begin{Soutput}
   FSC-Height      Side Scatter      CD8 FITC     IFN, IL2, TNF PE
 Min.   : 125.0   Min.   :167.0   Min.   :  0.0   Min.   :  0.0   
 1st Qu.: 339.0   1st Qu.:410.0   1st Qu.:155.0   1st Qu.:222.0   
 Median : 441.0   Median :473.0   Median :227.0   Median :285.0   
 Mean   : 489.9   Mean   :475.6   Mean   :235.2   Mean   :276.1   
 3rd Qu.: 680.0   3rd Qu.:543.0   3rd Qu.:274.0   3rd Qu.:340.0   
 Max.   :1023.0   Max.   :969.0   Max.   :856.0   Max.   :882.0   
   CD4 perCP                            CD3 APC      Time (204.80 sec.)
 Min.   :  0.0   Min.   :   0.0000   Min.   :  0.0   Min.   :  0.0     
 1st Qu.:121.0   1st Qu.:   0.0000   1st Qu.:199.0   1st Qu.:140.0     
 Median :264.0   Median :   0.0000   Median :272.0   Median :291.0     
 Mean   :256.8   Mean   :   0.8412   Mean   :321.8   Mean   :292.5     
 3rd Qu.:371.0   3rd Qu.:   0.0000   3rd Qu.:399.0   3rd Qu.:444.0     
 Max.   :948.0   Max.   :1023.0000   Max.   :969.0   Max.   :599.0     
\end{Soutput}
\end{Schunk}

A set of descriptive tools are attached to the FCS R-object. The
method \Rmethod{print} (using an \Robject{FCS} object in its signature) will
automatically give a short summary of the \Robject{FCS} R-object without
printing out all the contents of the data and the metadata.  The
following examples are different incantations of the \Rmethod{print} method
for FCS objects:

\begin{Schunk}
\begin{Sinput}
> print(unst.1829)
\end{Sinput}
\begin{Soutput}
     Original Object of class `FCS' from: 1829_28+49d.fcs 
     Object name: unst.1829 
     Dimensions 197025 by 8 
\end{Soutput}
\begin{Sinput}
> print(MC.053)
\end{Sinput}
\begin{Soutput}
     Original Object of class `FCS' from: 042402c1.053.fcs 
     Object name: MC.053 
     Dimensions 126795 by 7 
\end{Soutput}
\end{Schunk}

A longer and more detailed summary with statistics for the column
variables can be displayed by using the \Rmethod{summary} method, whose output is 
a \Rclass{FCSsummary} S4 class.


To extract and replace components within the data matrix of a 
\Robject{FCS} object, use only \Rfunction{[..]} and 
\Rfunction{[...]<-}, respectively.

\begin{Schunk}
\begin{Sinput}
> firstten.1829 <- as(st.1829[1:10, ], "matrix")
> firstten.1829
\end{Sinput}
\begin{Soutput}
   FSC-Height Side Scatter CD8 FITC IFN, IL2, TNF PE CD4 perCP   CD3 APC
1         341          408      154              238       232 0     532
2         690          564      265              371       255 0     313
3         335          455      562              128       106 0     744
4         367          550      165              283       113 0     240
5         190          495      219              334       107 0     284
6         441          414      194              229       159 0     339
7         144          443      199              296         0 0     261
8         730          509      257              344       366 0     247
9         542          480      243              337       278 0     326
10        305          463       61              113       472 0     563
   Time (204.80 sec.)
1                   0
2                   0
3                   0
4                   0
5                   0
6                   0
7                   0
8                   0
9                   0
10                  0
\end{Soutput}
\begin{Sinput}
> firstobs.1829 <- as(st.1829[1, 1], "matrix")
> firstobs.1829
\end{Sinput}
\begin{Soutput}
  FSC-Height
1        341
\end{Soutput}
\begin{Sinput}
> st.1829[1, 1] <- 99999999
> as(st.1829[1, 1], "matrix")
\end{Sinput}
\begin{Soutput}
  FSC-Height
1      1e+08
\end{Soutput}
\begin{Sinput}
> st.1829[1, 1] <- firstobs.1829
> as(st.1829[1, 1], "matrix")
\end{Sinput}
\begin{Soutput}
  FSC-Height
1        341
\end{Soutput}
\begin{Sinput}
> st.1829[1, 1]
\end{Sinput}
\begin{Soutput}
     Non-original Object of class `FCS' from: 1829_GAG.fcs 
     Object name: st.1829 
     Dimensions 1 by 1 
\end{Soutput}
\end{Schunk}

Note that the "original" slot within the metadata is only changed to
FALSE when the data is changed.

Changing the metadata itself will not alter the status of the
"original" slot.

\begin{Schunk}
\begin{Sinput}
> st.1829[["original"]]
\end{Sinput}
\begin{Soutput}
[1] FALSE
\end{Soutput}
\end{Schunk}

The function \Rfunction{dim.FCS} retrieves the dimensions of the data matrix
of a \Robject{FCS} R-object.

\begin{Schunk}
\begin{Sinput}
> dim.1829 <- dim.FCS(st.1829)
> dim.1829
\end{Sinput}
\begin{Soutput}
[1] 126675      8
\end{Soutput}
\end{Schunk}

A data parameter column can be appended to the data matrix of a
\Robject{FCS} R-object by using the method \Rmethod{addParameter}, which will also
result in the change of the "original" metadata slot to be FALSE.

\begin{Schunk}
\begin{Sinput}
> column.to.add <- rep(0, dim.1829[1])
> st.1829 <- addParameter(st.1829, colvar = column.to.add, shortname = "test", 
+     longname = "example", use.shortname = FALSE)
\end{Sinput}
\end{Schunk}

\clearpage
\section{Data Assessment}
\subsection{Checking Validity of the \Robject{FCS} R-object and Fixing errors}
\label{SUBSEC:checkfixvars}

The method \Rmethod{checkvars} checks the ranges, dimensions, and the column
variable names of the data against what is specified in the
metadata.  If details are not specified in the metadata, then the
available information is added to the metadata.  The output is a
boolean as to whether the object passes the check.  The option,
\Rargument{MY.DEBUG=TRUE}, allows us to view the checking statments.

\begin{Schunk}
\begin{Sinput}
> st.1829.checkstat <- checkvars(st.1829, MY.DEBUG = TRUE)
\end{Sinput}
\begin{Soutput}
[1] "Class is FCS"
[1] "Object has data"
[1] "Object has metadata"
[1] "Object has a name:st.1829"
[1] "Data Dimension Check: Dimensions: (row X col)"
[1] "     Data: (126675 X 9)"
[1] "     Metadata: (126675 X 9)"
[1] "Names Check:"
      Data Parameter Names st.1829@metadata@longnames
 [1,] "FSC-Height"         "dummy"                   
 [2,] "Side Scatter"       "dummy"                   
 [3,] "CD8 FITC"           "wrongname"               
 [4,] "IFN, IL2, TNF PE"   "dummy"                   
 [5,] "CD4 perCP"          "dummy"                   
 [6,] " "                  "dummy"                   
 [7,] "CD3 APC"            "dummy"                   
 [8,] "Time (204.80 sec.)" "dummy"                   
 [9,] "example"            "example"                 
[1] "    st.1829@metadata@longnames do not match with that of the data."
[1] "Range Check: Column parameters are within specified metadata range."
                   Data Ranges st.1829@paramranges
FSC-Height                1023                1023
Side Scatter               969                 969
CD8 FITC                   856                 856
IFN, IL2, TNF PE           882                 882
CD4 perCP                  948                 948
                          1023                1023
CD3 APC                    969                 969
Time (204.80 sec.)         599                 599
example                      0                   0
\end{Soutput}
\begin{Sinput}
> st.1829.checkstat
\end{Sinput}
\begin{Soutput}
[1] FALSE
\end{Soutput}
\end{Schunk}

Because st.1829 has been altered such that there is a discrepancy
between the metadata and the data portions of this \Robject{FCS} object,
\Rfunction{fixvars} will be used to correct major errors.
 
\begin{Schunk}
\begin{Sinput}
> if (st.1829.checkstat == FALSE) {
+     st.1829 <- fixvars(st.1829, MY.DEBUG = TRUE)
+ }
\end{Sinput}
\begin{Soutput}
[1] "Class is FCS"
[1] "Object has data"
[1] "Object has metadata"
[1] "Object has a name: st.1829"
[1] "Data Dimension Check: Dimensions: (row X col)"
[1] "     Data: (126675 X 9)"
[1] "     Metadata: (126675 X 9)"
[1] "Names Check:"
      Data Parameter Names st.1829@metadata@longnames
 [1,] "FSC-Height"         "dummy"                   
 [2,] "Side Scatter"       "dummy"                   
 [3,] "CD8 FITC"           "wrongname"               
 [4,] "IFN, IL2, TNF PE"   "dummy"                   
 [5,] "CD4 perCP"          "dummy"                   
 [6,] " "                  "dummy"                   
 [7,] "CD3 APC"            "dummy"                   
 [8,] "Time (204.80 sec.)" "dummy"                   
 [9,] "example"            "example"                 
[1] "    st.1829@metadata@longnames do not match with that of the data."
[1] "Names Fix: Replacement of the metadata parameter(s):"
     [,1]  
[1,] "$P1S"
[2,] "$P2S"
[3,] "$P3S"
[4,] "$P4S"
[5,] "$P5S"
[6,] "$P6S"
[7,] "$P7S"
[8,] "$P8S"
[1] "  from the old name(s) of the original metadata:"
     [,1]       
[1,] "dummy"    
[2,] "dummy"    
[3,] "wrongname"
[4,] "dummy"    
[5,] "dummy"    
[6,] "dummy"    
[7,] "dummy"    
[8,] "dummy"    
[1] "  to the following name(s) from the data:"
     [,1]                
[1,] "FSC-Height"        
[2,] "Side Scatter"      
[3,] "CD8 FITC"          
[4,] "IFN, IL2, TNF PE"  
[5,] "CD4 perCP"         
[6,] " "                 
[7,] "CD3 APC"           
[8,] "Time (204.80 sec.)"
[1] "Range Check: Column parameters are within specified metadata range."
                   Data Ranges st.1829@paramranges
FSC-Height                1023                1023
Side Scatter               969                 969
CD8 FITC                   856                 856
IFN, IL2, TNF PE           882                 882
CD4 perCP                  948                 948
                          1023                1023
CD3 APC                    969                 969
Time (204.80 sec.)         599                 599
example                      0                   0
\end{Soutput}
\end{Schunk}

The original FCS R-object can be retrieved by using the function
\Rfunction{get}, if the original object is on the current workspace and has been
unchanged.  Alternatively, the original FCS R-object can be obtained
by reading in the binary, fcs file from the /fcs directory (if this
raw binary file exists) of the data package \Rpackage{rfcdmin}.

\begin{Schunk}
\begin{Sinput}
> st.1829 <- get(st.1829[["objectname"]])
> original.FC.FCSRobj <- read.FCS(FC.FCSRobj[["filename"]], MY.DEBUG = FALSE)
\end{Sinput}
\begin{Soutput}
NOTE: Long names $PnS are missing. 
Short names $PnN are assigned to the dataset instead. 
\end{Soutput}
\end{Schunk}


\subsection{Equality between \Robject{FCS} objects}
\label{SUBSEC:FCSequal}

Two \Robject{FCS} objects can be checked for equality by using the \Rmethod{equals}
method.  The default check is to verify the equality of the metadata
(except for the \Rargument{filename} and the \Rargument{objectname}) and all
the elements of the data.

\begin{Schunk}
\begin{Sinput}
> equals(st.1829, unst.1829)
\end{Sinput}
\begin{Soutput}
[1] FALSE
\end{Soutput}
\end{Schunk}

The \Rargument{check.filename} and \Rargument{check.objectname} set to TRUE will allow the
equality verification of the \Robject{filename} and \Robject{objectname} slots in the
metadata.

\begin{Schunk}
\begin{Sinput}
> equals(st.1829, st.1829, check.filename = TRUE, check.objectname = TRUE)
\end{Sinput}
\begin{Soutput}
[1] TRUE
\end{Soutput}
\end{Schunk}

\subsection{Data quality assessment between \Robject{FCS} objects}
\label{SUBSEC:FCSassessment}

Data assessment is the act of inspecting data, measuring the defects and 
analyzing the cause (and potentially the impact of those defects). 

You may have an experiment where one sample has been divided in several aliquots and 
therefore you should be able to compare some measured parameters like the size 
(FSC - Forward SCatter) or the granularity (SSC - Side SCatter) of the different aliquots. 
In order to assess the data quality, we propose 3 graphical methods to explore 
the data and to detect whether any aliquots or samples were substantially different from 
the others, in a way that were not likely to be biologically motivated and therefore misleading. 

\begin{enumerate}
\item Boxplot (or box-and-whisker) plot is a graphical representation of dispersions 
and extreme scores. Represented in this graphic are minimum, maximum, and quartile 
scores in the form of a box with "whiskers." The box includes the range of scores 
falling into the middle 50\% of the distribution (median) (Inter Quartile Range = 
75 th percentile - 25 th percentile) and the whiskers are lines extended to the 
minimum and maximum scores in the distribution or to mathematically defined (+/-1.5*IQR) 
upper and lower fences. Boxplot summarizes the location and the shape of the distribution. 
For more details, see \Rfunction{boxplot} and \Rfunction{boxplot.FCS} in the 
\Rpackage{graphics} and\Rpackage{rflowcyt} package, respectively .

\item Empirical cumulative distribution function (\Rfunction{ecdf}) reveals 
differences in the distributions. For more details, see \Rfunction{ecdf} and 
\Rfunction{plotECDF.FCS} in the \Rpackage{stats} and\Rpackage{rflowcyt} package, respectively.

\item Density plot reveals the shape of the distributions.For more details, see 
\Rfunction{density.lf} and \Rfunction{plotdensity.FCS} in the \Rpackage{locfit} 
and \Rpackage{rflowcyt} package, respectively.
\end{enumerate}

As an example, we draw the differents plot for two different datasets from the 
British Columbia Cancer Research Center, Vancouver (Canada):
\begin{enumerate}
\item Time course experiment: collection of weekly peripheral blood samples 
from 1 patient (R object \Robject{flowcyt.fluors} in the \Rpackage{rfcdmin} data package).
\item Cell line dataset: Flow Cytometry High Content Screening (FC-HCS) of a 2000-compound 
library by the mean of one cell line (FCS files from A06 to H06 in the \Rpackage{rfcdmin} 
data package -in this experiment, the name of the sample corresponds to its position 
in a 96 wells plates) \citep{gasparetto:smith:2004}. 
\end{enumerate}
For more details, see \Rfunction{help="rfcdmin"}.

\subsubsection{Time course experiment}
\label{SUBSUBSEC:FCSTimeCourse}
This dataset is an abstract of a time couse experiment realised at the British 
Columbia Cancer Research Center (Thanks to R. Brinkman, C. Smith and M. Gasparetto).
It is a collection of weekly peripheral blood samples from 1 patient, divided 
in 8 aliquots at each time point and labeled by 4 markers to identify 8 differents stains.

First, we load the data:
\begin{Schunk}
\begin{Sinput}
> require(rfcdmin)
\end{Sinput}
\begin{Soutput}
[1] TRUE
\end{Soutput}
\begin{Sinput}
> data(flowcyt.data)
\end{Sinput}
\end{Schunk}

Then, we can draw a density plot for the Foward SCatter parameter 
(\Rargument{varpos}=1) at the time points 1 and 9.

\clearpage

\begin{figure}[htbp]
 \centering  
\begin{Schunk}
\begin{Sinput}
> old.par <- par(no.readonly = TRUE)
> mat <- matrix(c(1:2), 1, 2, byrow = TRUE)
> nf <- layout(mat, respect = TRUE)
> plotdensity.FCS(flowcyt.data[1:8], varpos = c(1), main = "FSC density plot at time point 1", 
+     ylim = c(0, 0.015), ylab = "density of cells")
> legend(450, 0.012, paste("stain", c(1:8), sep = ""), col = c(1:8), 
+     pch = 22)
> plotdensity.FCS(flowcyt.data[65:72], varpos = c(1), main = "FSC density plot at time point 9", 
+     ylim = c(0, 0.015), ylab = "density of cells")
> legend(450, 0.012, paste("stain", c(1:8), sep = ""), col = c(1:8), 
+     pch = 22)
> par(old.par)
\end{Sinput}
\end{Schunk}
\includegraphics{rflowcyt-PlotDensityTimeCourse}
\caption{plotdensity.FCS: Density plots of the forward scatter 
parameter of the different stains, at different 2 different 
time points (\Robject{flowcyt.fluors}  FCS R object)}
\label{fig:plotdensitTimeCourse}
\end{figure}

At the time point 9, we can see that the data for the first 
stain looks peculiar. We can also observe the multimodal distribution of the data. 

\clearpage

To minimize the effect of multimodal distribution on the shape of the distributions, 
we can represent the FSC data \textit{via} a ECDF plot. This representation eventially 
allows us to confirm the previously observed phenomenon.

\begin{figure}[htbp]
  \centering
\begin{Schunk}
\begin{Sinput}
> print(plotECDF.FCS(flowcyt.fluors, varpos = c(1), var.list = c(paste("time", 
+     1:12, sep = "")), group.list = paste("Stain", c(1:8), sep = ""), 
+     main = "ECDF of the FSC for different stains at a particular time point", 
+     lwd = 2, cex = 1.5))