%
% NOTE -- ONLY EDIT THE .Rnw FILE!!!  The .tex file is
% likely to be overwritten.
%
% \VignetteIndexEntry{marrayClasses Tutorial}
% \VignetteDepends{tools}
% \VignetteKeywords{Expression Analysis, Preprocessing}
% \VignettePackage{marrayClasses}

\documentclass[11pt]{article}

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

\parindent 0in

%%%\bibliographystyle{abbrvnat}

\begin{document}

\title{\bf Tutorial for Bioconductor's marrayClasses package}

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

\maketitle


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

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


\tableofcontents


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

This document provides a short tutorial for the {\tt marrayClasses} package, which is part of a suite of four packages for diagnostic plots and normalization of cDNA microarray data, with {\tt marrayInput}, {\tt marrayNorm}, and {\tt marrayPlots}. The {\tt marrayClasses} packages contains basic class definitions and associated methods for pre-- and post--normalization intensity data for batches of arrays. Greater details on the package are given in the {\tt marrayClasses} document of the {\tt inst/doc} directory.  \\

{\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 class {\tt marrayRaw} in a browser, use {\tt help.start()} followed by {\tt ? marrayRaw} or alternately the dyadic {\tt class ? marrayRaw}.\\

{\bf Case study.} We demonstrate the functionality of this collection of R packages using gene expression data from the Swirl zebrafish experiment. To load the Swirl dataset, use {\tt data(swirl)}, and to view a description of the experiments and data, type {\tt ? swirl}.

<<eval=TRUE, echo=TRUE>>=
library("marrayClasses")
data(swirl)
@

\section{Microarray classes}

The three main classes for cDNA microarray data are 

\begin{description}
\item
{{\tt marrayLayout}:} This class is used to keep track of important layout parameters for two--color cDNA microarrays. It contains slots for: the total number of spotted probe sequences on the array, the
dimensions of the spot and grid matrices, the plate origin of the probes, information on spotted control sequences (e.g. probe sequences which should have equal abundance in the two
target samples, such as housekeeping genes). 
\item
{{\tt marrayRaw}:} This class represents pre--normalization intensity data for a batch of cDNA microarrays. A {\it batch} of arrays consists of a collection of arrays with the same layout ("marrayLayout"). The
class contains slots for the green (Cy3) and red (Cy5) foreground and background intensities, the layout of the arrays, and descriptions of the target samples hybridized to the arrays
and probe sequences spotted onto the arrays. 
\item
{{\tt marrayNorm}:} This class represents post--normalization intensity data for a batch of cDNA microarrays. 
The class contains slots for the average log--intensities $A = \log_2 \sqrt{RG}$, the normalized log--ratios $M = \log_2 R/G$, the location and scale normalization values, the layout of the arrays, and descriptions of the
target samples hybridized to the arrays and probe sequences spotted onto the arrays. 
\end{description}

Other classes are {\tt marrayInfo}, {\tt marraySpots}, and {\tt marrayTwo}. The function {\tt slotNames} can be used to get information on the slots of a formally defined class or an instance of the class. For example, to get information of the slots for the {\tt marrayLayout} class or on the slots for the object {\tt swirl} use

<<eval=TRUE>>=
slotNames("marrayLayout")
slotNames(swirl)
@




\section{Creating and accessing slots of microarray objects} 

{\bf Creating new objects.} The function {\tt new} from the {\tt methods} package may be used to create new objects from a given class. For example, to create an object of class {\tt marrayInfo} describing the target samples in the Swirl experiment, one could use the following code 

<<eval=TRUE>>=
zebra.RG<-as.data.frame(cbind(c("swirl","WT","swirl","WT"),						c("WT","swirl","WT","swirl")))
dimnames(zebra.RG)[[2]]<-c("Cy3","Cy5")
zebra.samples<-new("marrayInfo",
		    maLabels=paste("Swirl array ",1:4,sep=""), 
		    maInfo=zebra.RG,
		    maNotes="Description of targets for Swirl experiment")
zebra.samples
@

Slots which are not specified in {\tt new} are initialized to the prototype for the corresponding class. These are usually "empty", e.g., {\tt matrix(0,0,0)}. In most cases, microarray objects can be created automatically using the input functions and their corresponding widgets in the {\tt marrayInput} package. These were used to create the object {\tt swirl} of class {\tt marrayRaw}.\\
%%% As described in greater details in Section \ref{sInput}, the input functions in {\tt marrayInput} were used to generate microarray objects {\tt swirl.gnames}, {\tt swirl.samples}, {\tt swirl.layout}, and {\tt swirl} for the Swirl experiment (the first two are of class {\tt marrayInfo}, and the last two of class {\tt marrayLayout} and {\tt marrayRaw}, respectively).  

{\bf Accessing slots.} Different components or slots of the microarray objects may be accessed using the operator {\tt @}, or alternately, the function {\tt slot}, which evaluates the slot name. For example, to access the {\tt maLayout} slot in the object {\tt swirl} and the {\tt maNgr} slot in the layout object {\tt L}

<<eval=TRUE>>=
L<-slot(swirl, "maLayout")
L@maNgr
@

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Basic microarray methods}\label{smethods}


The following basic methods were defined to facilitate manipulation of microarray data objects. 
To see all methods available for a particular class, e.g., {\tt marrayLayout}, or just the print methods

<<eval=FALSE>>==
showMethods(classes="marrayLayout")
showMethods("print",classes="marrayLayout") 
@


\subsection{Printing methods for microarray objects} 

Since there is usually no need to print out fluorescence intensities for thousands of genes, the {\tt print} method was overloaded for microarray classes by simple report generators. For an overview of the available microarray printing methods, type {\tt  methods ? print}, or to see all print methods for the session

<<eval=TRUE>>=
showMethods("print")
@

For example, summary statistics for an object of class {\tt marrayRaw}, such as {\tt swirl}, can be obtained by {\tt print(swirl)} or simply {\tt swirl}.

<<eval=TRUE>>=
swirl
@

\subsection{Subsetting methods for microarray objects} 

In many instances, one is interested in accessing only a subset of arrays in a batch and/or spots in an array. Subsetting methods {\tt "["} were defined for this purpose. 
For an overview of the available microarray subsetting methods, type {\tt  methods ? "["} or to see all subsetting methods for the session {\tt showMethods("[")}.
When using the {\tt "["} operator, the first index refers to spots and the second to arrays in a batch. Thus, to access the first 100 probe sequences in the second and third arrays in the batch {\tt swirl} use

<<eval=TRUE>>=
swirl[1:100,2:3]
@


\subsection{Methods for accessing slots of microarray objects} 


A number of simple methods were defined to access slots of the microarray classes.  Using such methods is more general than using the {\tt slot} function or {\tt @} operator. In particular, if the class definitions are changed, any function which uses the {\tt @} operator will need to be modified. When using a method to access the data in the slot, only that particular method needs to be modified. Thus, to access the layout information for the array batch {\tt swirl} one may also use {\tt maLayout(swirl)}.\\

 In addition, various methods were defined to compute basic statistics from microarray object slots. For instance, for memory management reasons, objects of class {\tt marrayLayout} do not store the spot coordinates of each probe. Rather, these can be obtained from the dimensions of the grid and spot matrices by applying methods: {\tt maGridRow}, {\tt maGridCol}, {\tt maSpotRow}, and {\tt maSpotCol} to objects of class {\tt marrayLayout}. Print--tip--group coordinates are given by {\tt maPrintTip}. Similar methods were also defined to operate directly on objects of class {\tt marrayRaw}, {\tt marrayNorm}, {\tt marraySpots}, and {\tt marrayTwo}. The commands below may be used to display the number of spots on the array, the dimensions of the grid matrix, and the print--tip--group coordinates.

<<eval=TRUE>>=
swirl.layout<-maLayout(swirl)
maNspots(swirl)
maNspots(swirl.layout)
maNgr(swirl)
maNgc(swirl.layout)
maPrintTip(swirl[1:10,3])
@

\subsection{Methods for assigning slots of microarray objects}

A number of methods were defined to replace slots of microarray objects, without explicitly using the {\tt @} operator or {\tt slot} function. These make use of the {\tt setReplaceMethod} function from the R {\tt methods} package.
 As with the accessor methods just described, the assignment methods are named after the slots. For example, to replace the {\tt maNotes} slot of {\tt swirl.layout}

<<eval=TRUE>>=
maNotes(swirl.layout)
maNotes(swirl.layout)<- "New value"
maNotes(swirl.layout)
@

To initialize slots of an empty {\tt marrayLayout} object

<<eval=TRUE>>=
L<-new("marrayLayout")
L
maNgr(L)<-4
@


Similar methods were defined to operate on objects of class {\tt marrayInfo}, {\tt marrayRaw}, {\tt marrayNorm}, {\tt marraySpots}, and {\tt marrayTwo}.


\subsection{Methods for coercing microarray objects} 

To facilitate navigation between different classes of microarray objects, we have defined methods for coercing microarray objects from one class into another. A list of such methods can be obtained by {\tt methods ? coerce}. For example, to coerce an object of class {\tt marrayRaw} into an object of class {\tt marrayNorm}

<<eval=TRUE>>=
swirl.norm<-as(swirl, "marrayNorm")    
@

It is also possible to convert objects of class {\tt marrayRaw} or {\tt marrayNorm} into objects of class {\tt exprSet} (see definition in the {\tt Biobase} package)

<<eval=TRUE>>=
as(swirl, "exprSet")    
@

\subsection{Functions for computing layout parameters}

In some cases, plate information is not stored in {\tt marrayLayout} objects when the data are first read into R. We have defined a function {\tt maCompPlate} which computes plate indices from the dimensions of the grid matrix and number of wells in a plate. For example, the Swirl arrays were printed from 384--well plates, but the plate IDs were not stored in the {\tt fish.gal} file. To generate plate IDs (arbitrarily labeled by integers starting with 1) and store these in the {\tt maPlate} slot of the {\tt marrayLayout} object use

<<eval=TRUE>>=
maPlate(swirl)<-maCompPlate(swirl,n=384)
@

Similar functions were defined to generate and manipulate spot coordinates: {\tt maCompCoord}, {\tt maCompInd}, {\tt maCoord2Ind}, {\tt maInd2Coord}. The function {\tt maGeneTable} produces a table of spot coordinates and gene names for objects of class {\tt marrayRaw}, {\tt marrayNorm}, and {\tt marraySpots}. 



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

%%%\bibliography{marrayPacks}

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