%\VignetteIndexEntry{marrayInput Introduction}
%\VignetteKeywords{Preprocessing, Expression Analysis}
%\VignetteDepends{marrayInput}
%\VignettePackage{marrayInput}
\documentclass[11pt]{article}

\usepackage{amsmath,pstricks,fullpage, graphicx}
\usepackage[authoryear,round]{natbib}
\usepackage{hyperref}

\parindent 0in

\bibliographystyle{abbrvnat}

\begin{document}

\title{\bf Introduction to the Bioconductor marrayInput package}

\author{Yee Hwa Yang$^1$ and Sandrine Dudoit$^2$}

\maketitle


\begin{center}
1. Department of Statistics, University of California, Berkeley,
   {\tt yeehwa@stat.berkeley.edu}\\
2. Division of Biostatistics, University of California, Berkeley,
   \url{http://www.stat.berkeley.edu/~sandrine}
\end{center}


%Rnwfile<- file.path("/home/sandrine/CVS_stuff/madman/Rpacks/marrayInput/inst/doc/marrayInput.Rnw")
%Sweave(Rnwfile,pdf=TRUE,eps=TRUE,stylepath=TRUE,driver=RweaveLatex())

\tableofcontents

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Overview}

This document provides a tutorial for the {\tt marrayInput} package,
which is part of a suite of four packages for diagnostic plots and
normalization of cDNA microarray data. Like most Bioconductor packages,
these four packages rely on the object--oriented class/method mechanism,
provided by the R {\tt methods} package, to allow efficient and
systematic representation and manipulation of microarray data. {\tt
marrayInput} provides functionality for reading microarray data into R,
such as intensity data from image processing output files (e.g. {\tt
.spot} and {\tt .gpr} files for the {\tt Spot} and {\tt GenePix}
packages, respectively) and textual information on probes and targets
(e.g. from gal files and god lists). A {\tt tcltk} widget is supplied to
facilitate and automate data input and the creation of microarray
specific R objects for storing these data. The other three packages are

\begin{description}
\item {\tt marrayClasses}.  This package contains basic class
  definitions and associated methods for pre-- and post--normalization
  intensity data for batches of arrays.
\item {\tt marrayPlot}. This package provides functions for diagnostic plots
  of microarray spot statistics, such as boxplots, scatter--plots, and
  spatial color images. Examination of diagnostic plots of intensity
  data is important in order to identify printing, hybridization, and
  scanning artifacts which can lead to biased inference concerning
  gene expression.
\item {\tt marrayNorm}. This package implements robust adaptive location and
  scale normalization procedures, which correct for different types of
  dye biases (e.g. intensity, spatial, plate biases) and allow the use
  of control sequences spotted onto the array and possibly spiked into
  the mRNA samples. Normalization is needed to ensure that observed
  differences in intensities are indeed due to differential expression
  and not experimental artifacts; fluorescence intensities should
  therefore be normalized before any analysis which involves
  comparisons among genes within or between arrays.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Getting started}

{\bf Installing the package.} To install the {\tt marrayInput} package
for Windows operating systems, first download the file {\tt
marrayInput-snapshot.zip} from the Bioconductor website
\url{http://www.bioconductor.org/packages/html/marrayInput.html}.
Next, after starting R, from the menu select {\tt Packages}, then {\tt
Install package from local zip file...}.  Find and highlight the
location of the zip file and click on {\tt open}.\\

{\bf Loading the package.} To load the {\tt marrayInput} package in
your R session, type {\tt library(marrayInput)}.\\

{\bf Help files.}  As with any R package, detailed information on
functions, classes and methods can be obtained in the help files. For
instance, to view the help file for the function {\tt
read.marrayLayout} in a browser, use {\tt help.start()} followed by
{\tt ?  read.marrayLayout}.\\

{\bf Microarray classes.} The {\tt marrayInput} packages relies on
microarray class definitions in {\tt marrayClasses}. You should also
install this package and consult its vignette for more information.\\

{\bf Next.} After reading your data into R, you can use the {\tt
marrayPlots} and {\tt marrayNorm} packages for diagnostic plots and
normalization, respectively.\\

{\bf Sweave.} This document was generated using the {\tt Sweave}
function from the R {\tt tools} package. The source file is in the
{\tt /inst/doc} directory of the package {\tt marrayInput}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Case study: Swirl zebrafish microarray experiment}\label{sData}

We demonstrate the functionality of this collection of R packages
using gene expression data from the Swirl zebrafish experiment. These
data were provided by Katrin Wuennenberg--Stapleton from the Ngai Lab
at UC Berkeley. (The swirl embryos for this experiment were provided
by David Kimelman and David Raible at the University of Washington.) 
This experiment was carried out using zebrafish as a model organism to
study early development in vertebrates. Swirl is a point mutant in the
BMP2 gene that affects the dorsal/ventral body axis. Ventral fates
such as blood are reduced, whereas dorsal structures such as somites
and notochord are expanded. A goal of the Swirl experiment is to
identify genes with altered expression in the swirl mutant compared to
wild--type zebrafish. Two sets of dye--swap experiments were
performed, for a total of four replicate hybridizations. For each of
these hybridizations, target cDNA from the swirl mutant was labeled
using one of the Cy3 or Cy5 dyes and the target cDNA wild--type mutant
was labeled using the other dye. Target cDNA was hybridized to
microarrays containing 8,448 cDNA probes, including 768 controls spots
(e.g. negative, positive, and normalization controls
spots). Microarrays were printed using $4 \times 4$ print--tips and 
are thus partitioned into a $4 \times 4$ grid matrix. Each grid
consists of a $22 \times 24$ spot matrix that was printed with a
single print--tip. Here, spot row and plate coordinates should
coincide, as each row of spots corresponds to probe sequences from the
same 384 well--plate.\\

Each of the four hybridizations produced a pair of 16--bit images,
which were processed using the image analysis software package {\tt
Spot} \citep{Spot,Image}. Raw images of the Cy3 and Cy5 fluorescence
intensities for all four hybridizations are available at
\url{http://fgl.lsa.berkeley.edu/Swirl/index.html}. The dataset
includes four output files {\tt swirl.1.spot}, {\tt swirl.2.spot},
{\tt swirl.3.spot}, and {\tt swirl.4.spot} from the {\tt Spot}
package.  Each of these files contains 8,448 rows and 30 columns; rows
correspond to spots and columns to different statistics from the {\tt
Spot} image analysis output. The file {\tt fish.gal} is a gal file
generated by the {\tt GenePix} program; it contains information on
individual probe sequences, such as gene names, spot ID, spot
coordinates.  Hybridization information for the mutant and wild--type
target samples is stored in {\tt SwirlSample.txt}. All fluorescence
intensity data from processed images are included in the {\tt
marrayInput} package (see Section \ref{sInput} for greater details).\\

To load the swirl dataset, use {\tt data(swirl)}, and to view a
description of the experiments and data, type {\tt ? swirl}.  Below,
we give step--by--step instructions for reading the swirl data into
R. For convenience, we have also stored the resuls in the object {\tt
swirl} of class {\tt marrayRaw}.

<<eval=TRUE>>=
library(marrayInput)
data(swirl)
swirl
@


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Package {\tt marrayInput} --  Reading microarray data into R}\label{sInput}

We begin our analysis of microarray data with the fluorescence
intensities produced by image processing of the microarray scanned
images. These data are typically stored in tables whose rows correspond
to the spotted probe sequences and columns to different spot statistics:
e.g. grid row and column coordinates, spot row and column coordinates,
red and green background and foreground intensities for different
segmentation and background adjustment methods, spot morphology
statistics, etc. For the {\tt GenePix} image processing software, these
are the {\tt .gpr} files, and for {\tt Spot}, these are the {\tt .spot}
files. We also consider probe and target textual information stored, for
example, in {\tt .gal} and {\tt .gdl} (god list) files. The main
functions in the {\tt marrayInput} package are {\tt read.marrayLayout},
{\tt read.marrayInfo}, and {\tt read.marrayRaw}, which create objects of
classes {\tt marrayLayout}, {\tt marrayInfo}, and {\tt marrayRaw},
respectively. Widgets are provided for each of these functions to
facilitate data entry.\\

 For the Swirl zebrafish experiment, textual information and
 fluorescence intensity data from processed images were included as part
 of the {\tt marrayInput} package and can be accessed as follows, where
 {\tt datadir} is the name of the R package sub--directory containing the
 data files.

<<eval=TRUE>>=
datadir <- system.file("data", package="marrayInput")
dir(datadir)
@

 \subsection{Main input functions}

 Consider first the function {\tt read.marrayLayout}, which may be used
 to read in and store information on the layout of spots in a batch of
 arrays. The main quantities are the dimensions of the grid and spot
 matrices. In addition, it is useful to keep track of information on the
 location and nature of control spots, and the print--tip--group and plate
 origin of the probes. The following command stores such layout
 information in the object {\tt swirl.layout} of class {\tt
 marrayLayout}.  The location of the control spots is extracted from the
 fourth ({\tt ctl.col=4}) column of the file {\tt fish.gal}.

<<eval=TRUE>>=
swirl.layout <- read.marrayLayout(fname=file.path(datadir, "fish.gal"),
                                  ngr=4, ngc=4, nsr=22, nsc=24,
                                  skip=21,ctl.col=4)
ctl<-rep("Control",maNspots(swirl.layout))
ctl[maControls(swirl.layout)!="control"]<-"N"
maControls(swirl.layout)<-factor(ctl)
swirl.layout
@

Objects of class {\tt marrayInfo} may be used to store information on
probe sequences and target samples. The following commands create such
objects for the Swirl experiment, by reading in text files supplied by
the experimenter.

<<eval=TRUE>>=
swirl.samples <- read.marrayInfo(file.path(datadir, "SwirlSample.txt"))
swirl.samples
swirl.gnames <- read.marrayInfo(file.path(datadir, "fish.gal"),
                         info.id=4:5, labels=5, skip=21)
swirl.gnames
@

The function {\tt read.marrayRaw} takes as its main argument a list of
names for files containing the intensity data (e.g. {\tt GenePix}
output files {\tt .gpr}). It also takes as arguments the names of
already created layout, probe, and target description objects, e.g.,
{\tt swirl.layout}, {\tt swirl.gnames}, and {\tt swirl.samples} for
the Swirl experiment. The following commands read in all the {\tt
Spot} files residing in the {\tt datadir} directory. The arguments
further specify that the red and green foreground intensities are
stored under the headings {\tt Rmean} and {\tt Gmean}, and that the
red and green background intensities are store under the headings {\tt
morphR} and {\tt morphG}, respectively.

<<eval=TRUE>>=
fnames <- dir(path=datadir,pattern=paste("*", "spot", sep="\."))
swirl.raw <- read.marrayRaw(fnames, path = datadir,
                             name.Gf = "Gmean", name.Gb = "morphG",
                             name.Rf = "Rmean", name.Rb = "morphR",
                             layout = swirl.layout,
                             gnames = swirl.gnames,
                             targets = swirl.samples
                             )
@


 \subsection{Widgets for input functions}

 To facilitate the creation of microarray data objects, each of these
 three input functions has a corresponding {\tt tcltk} widget: {\tt
 widget.marrayLayout}, {\tt widget.marrayInfo}, and {\tt
 widget.marrayRaw}.  A screen--shot of the {\tt marrayRaw} widget is
 shown in Figure \ref{fig:WidgetRaw}; the command to launch the widget
 is as follows (here, {\tt ext} specifies the image output file
 extension)

\begin{verbatim}
 widget.marrayRaw(path=datadir, ext="spot")
\end{verbatim}

 \subsection{Wrapper input functions}

 For users who prefer command line input for a specific class of image
 processing output files, we have defined three additional
 functions. The functions {\tt read.Spot}, {\tt read.GenePix}, and {\tt
 read.SMD} automate the creation of {\tt marrayRaw} objects from {\tt
 Spot} and {\tt GenePix} image analysis files, and from the Stanford
 Microarray Database (SMD) raw data files ({\tt .xls}). The main
 arguments to these functions are a list of files and the directory path
 of the files.  The following commands read two specific files from the
 {\tt datadir} directory.

%RG: changed to get a build
%% %<<eval=FALSE>>=
\begin{verbatim}
fnames <- dir(path=datadir,pattern=paste("*", "spot", sep="\."))[1:2]
swirl <- read.Spot(fnames, path=datadir,
          layout = swirl.layout,
          gnames = swirl.gnames,
          targets = swirl.samples)
\end{verbatim}

%%%@

 Alternatively, without specifying any arguments, the functions {\tt
 read.spot} and {\tt read.GenePix} by default will read in all {\tt
 Spot} or {\tt GenePix} files within a current working directory. One
 has the option of setting the layout, probe, and target information
 manually at a later stage.


%<<eval=FALSE>>=
\begin{verbatim}
 swirl <- read.Spot()
 test.raw <- read.GenePix()
 slot(swirl, "layout") <- swirl.layout
 slot(swirl, "gnames") <- swirl.gnames
\end{verbatim}
%@


\begin{figure}[htbp]
\centering
\includegraphics{widget1}
\caption{Screenshot of the widget for creating objects of class {\tt marrayRaw} from image processing output files.}
\protect\label{fig:WidgetRaw}
\end{figure}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\bibliography{marrayPacks}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{document}
