%\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}


\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textit{#1}}}

\parindent 0in

\bibliographystyle{abbrvnat}

\begin{document}

\title{\bf Introduction to the Bioconductor marray package : Input component}

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

\maketitle
\begin{center}
1. Department of Medicine, University of California, San Francisco,
   {\tt jean@biostat.berkeley.edu}\\
2. Division of Biostatistics, University of California, Berkeley,
   \url{http://www.stat.berkeley.edu/~sandrine}
\end{center}




% library(tools) 
% setwd("C:/MyDoc/Projects/madman/Rpacks/marray/inst/doc")
% Rnwfile<-file.path("C:/MyDoc/Projects/madman/Rpacks/marray/inst/doc","marrayInput.Rnw")
% options(width=65)
% Sweave(Rnwfile,pdf=TRUE,eps=TRUE,stylepath=TRUE,driver=RweaveLatex())


\tableofcontents

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

This document provides a tutorial for the {\bf data input} component of
the {\tt marray} package.  This is similar to the previous {\tt
marrayInput} package which has now been combined with the suite of other
four packages for diagnostic plots and normalization of cDNA microarray
data.  This package relies on object--oriented class/method mechanism,
provided by the R {\tt methods} package, to allow efficient and
systematic representation and manipulation of microarray data. 

This vignette describeds 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. 

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

{\bf Installing the package.} To install the \Rpackage{marray} package
for Windows operating systems, first start R and make sure you are
connected to the internet. Next, select ``\textbf{Packages}'' from the
menu and click on ``\textbf{ Install package(s) from Bioconductor...}''.
Lastly, select \Rpackage{marray} from the pop--up windows and click
click on ``\textbf{OK}''.  You will find more detailed installation
instructions on the Bioconductor web site.\\
{\bf Loading the package.} To load the {\tt marray} package in your R
session, type {\tt library(marray)}.\\
{\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.GenePix} in a browser, use {\tt help.start()} followed by
{\tt ?  read.GenePix}.\\

A quick start guide on this package are given in the {\tt marray}
document of the {\tt inst/doc} directory.  \\

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\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(marray)
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("swirldata", package="marray")
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()
\end{verbatim}
%@

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
{\bf Note: Sweave.} This document was generated using the \Rfunction{Sweave}
function from the R \Rpackage{tools} package. The source file is in the
\Rfunction{/inst/doc} directory of the package \Rpackage{marray}.

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

\bibliography{marrayPacks}

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