% automatic manuscript creation for frmaTools
% -*- mode: noweb; noweb-default-code-mode: R-mode; -*-
%\VignetteIndexEntry{frmaTools: Create packages containing the vectors used by frma.}
%\VignetteDepends{frmaTools, frma, affyPLM, hgu133aprobe, hgu133atagprobe, hgu133plus2probe, hgu133acdf, hgu133atagcdf, hgu133plus2cdf, hgu133afrmavecs, frmaExampleData}
%\VignettePackage{frmaTools}
\documentclass[12pt]{article}
\usepackage{hyperref}
\usepackage[authoryear, round]{natbib}

\textwidth=6.2in
\textheight=8.5in
\parskip=.3cm
\oddsidemargin=.1in
\evensidemargin=.1in
\headheight=-.3in

\newcommand\Rpackage[1]{{\textsf{#1}\index{#1 (package)}}}
\newcommand\dataset[1]{{\textit{#1}\index{#1 (data set)}}}
\newcommand\Rclass[1]{{\textit{#1}\index{#1 (class)}}}
\newcommand\Rfunction[1]{{{\small\texttt{#1}}\index{#1 (function)}}}
\newcommand\Rfunarg[1]{{\small\texttt{#1}}}
\newcommand\Robject[1]{{\small\texttt{#1}}}

\author{Matthew N. McCall}

\begin{document}
\title{Tools for Advanced Use of the frma Package (frmaTools)}
\maketitle
\tableofcontents

\section{Introduction}
Frozen RMA (fRMA) is a microarray preprocessing algorithm that allows
one to analyze microarrays individually or in small batches and then
combine the data for analysis. This is accomplished by utilizing
information from the large publicly available microarray databases. In
particular, estimates of probe-specific effects and variances are
precomputed and frozen. Then, with new data sets, these are used in
concert with information from the new array(s) to normalize and
summarize the data. 

This document describes \Rpackage{frmaTools}, which provides a few
advanced usage options above and beyond the basic frma
functionality. Details of the ideas implemented in the frma and
frmaTools packages can be found in: \emph{McCall, MN, Bolstad, BM, and
  Irizarry, RA (2010). Frozen robust multiarray analysis (fRMA),
  Biostatistics, doi: 10.1093/biostatistics/kxp059.} Ideally someone
interested in using this package would first read that paper and then
proceed to the sections below.

\section{Creation of Vectors}
To create the vectors required by the package \Rpackage{frma}, one
needs a large database of biologically diverse samples from a variety
of batches. For this reason, we have attempted to create and supply a
number of these collections of vectors through packages available on
the Bioconductor website. 

To create custom vectors of one's own, follow these steps:
\begin{enumerate}
\item Download and install frmaTools
\item Create a directory and move all the relevant
{\it CEL} files to that directory.
\item If using linux/unix, start R in that directory.
\item If using the Rgui for 
Microsoft Windows make sure your working directory contains the {\it
CEL} files (use ``File -> Change Dir'' menu item).
\item Load the library.
<<eval=FALSE>>=
library(frmaTools)
@ 
\item Create a vector of CEL file names. If your directory contains only CEL files, do:
<<eval=FALSE>>=
files <- dir()
@ 
\item Create batch ids based on your arrays. There needs to be an equal number of arrays in each batch.
\item Run makeVectorsAffyBatch
<<eval=FALSE>>=
vectors <- makeVectorsAffyBatch(files, batch.id)
@ 
\end{enumerate}

This will create a list with the required vectors:
\begin{description}
\item[normVec]{normalization reference vector}
\item[probeVec]{probe effect vector}
\item[probeVarWithin]{within batch probe variance}
\item[probeVarBetween]{between batch probe variance}
\item[probesetSD]{within probeset standard deviation}
\item[medianSE]{median standard error of gene expression estimates}
\end{description}

\section{Platform Conversion}
Occasionally it will be beneficial to convert microarray data from one
platform to another. This is possible in cases where the probes on one
platform are a subset of the probes on another platform. For example,
hgu133a is a subset of hgu133atag; therefore, it is possible convert
hgu133atag data to hgu133a data by discarding those probes that are
present on hgu133atag but not hgu133a. 

Steps to convert an AffyBatch object:
\begin{enumerate}
\item Download and install frmaTools
\item Load the library.
<<echo=T,results=hide>>=
library(frmaTools)
@ 
\item Load the AffyBatch object to convert (for example hgu133atag data)
<<echo=T,results=hide>>=
library(frmaExampleData)
data(list="AffyBatch133atag")
@ 
\item Run convertPlatform (for example convert to hgu133a)
<<echo=T,results=hide>>=
object <- convertPlatform(AffyBatch133atag, "hgu133a")
@ 
\end{enumerate}

\end{document}