%\VignetteIndexEntry{codelink}
%\VignetteKeywords{Preprocessing, Codelink}
%\VignetteDepends{codelink}
%\VignettePackage{codelink}

\documentclass{article}
\usepackage[latin1]{inputenc}
\usepackage[english]{babel}

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

\begin{document}

\title{Codelink}

\author{Diego Díez Ruiz}

\maketitle

\section{Introduction}

Codelink\textsuperscript{\textsc{tm}} is a platform for the analysis of gene
expression on biological samples using short (30 base long) oligonucleotide
probes.  There is a proprietary software for reading scanned images, spot
intensity quantization and some diagnostics.  Quality flags (Table
\ref{tab:Flag}) are assigned to the spot based on signal to noise ratio (SNR)
computation (Eq: \ref{eq:SNR}) and other morphological characteristics as
irregular shape of the spots, saturation of the signal or manufacturer spots
removed. The results can be exported in many formats as XML, Excel, plain text,
etc. This library allows to read Codelink plain text exported data into R
\cite{r} for analysis of gene expression with any of the available tools in
R+Bioconductor\cite{BIOC}. A new class is defined for convenient storing
Codelink data as \Robject{exprSet} class is not convenient for this purpose.

\begin{table}[ht]
\begin{center}
\begin{tabular}{|c|l|}
\hline \em Flag & \em Meaning \\
\hline
G & Good signal (SNR >= 1)\\
L & Limit signal (SNR < 1)\\
I & Irregular shape \\
S & Saturated signal \\
M & MSR spot \\
C & Background contaminated\\
X & User excluded spots\\
\hline
\end{tabular}
\caption{Quality Flag description. SNR: Signal to Noise Ratio.}
\label{tab:Flag}
\end{center}
\end{table}

\begin{equation}
SNR=\frac{Smean}{(Bmedian + 1.5 * Bstdev)}
\label{eq:SNR}
\end{equation}

\begin{table}[ht]
\begin{center}
\begin{tabular}{|r|l|}
\hline \em Probe type & \em Meaning \\
\hline
DISCOVERY & Gene expression testing probes \\
POSITIVE & Positive control probes \\
NEGATIVE & Negative control probes \\
FIDUCIAL & Grid alignment probes \\
OTHER & Other controls and housekeeping gene probes \\
\hline
\end{tabular}
\caption{Probe types for Codelink arrays.}
\label{tab:Type}
\end{center}
\end{table}

\section{Reading data}

Currently only data exported as plain text from Codelink software can be used.
The Codelink text format can have arbitrary columns and header fields so
depending of what you have exported you can read it or not. The suggestion is
that you put on the files Spot\_mean and Bkgd\_median values so you can do
background correction and normalization in R. If you put Raw\_intensity or
Normalized\_intensity columns then you can also read it directly and avoid
background correction and/or normalization but this is not recommended. To read
some Codelink files you do:

\begin{Sinput}

> library(codelink)
> data <- readCodelink()

\end{Sinput}

This suppose that your files have the extension ``TXT'' (uppercase)
and they are in your working directory. If this is not the case you can specify 
files to be read with the 'file' argument. The function 
\Rfunction{readCodelink} returns and object of \Robject{Codelink}:

<<data>>=

library(codelink)

data(codelink.example)

codelink.example

@

\begin{table}[ht]
\begin{center}
\begin{tabular}{|r|l|}
\hline \em Slot & \em Description \\
\hline
product & Chip name description \\
sample & Sample names vector \\
file & File names vector \\
name & Probe names vector \\
type & Probe types vector \\
method & Methods applied to data \\
method\$background & Background correction method used \\
method\$normalization & Normalization method used \\
method\$merge & Merge method used \\
method\$log & Logical: If data is in log scale \\
flag & Quality flag matrix \\
Smean & Mean signal intensity matrix \\
Bmedian & Median background intensity matrix \\
Ri & Raw intensity matrix \\
Ni & Normalized intensity matrix \\
snr & Signal to Noise Ratio matrix \\
cv & Coefficient of Variation matrix \\
\hline
\end{tabular}
\caption{Description of Codelink object slots.}
\label{tab:Slots}
\end{center}
\end{table}

The chip type (product slot) is read from the PRODUCT field in the header of 
Codelink files. If it is not found then a warning message is shown and product 
slot is set to "Unknown". If one product type disagree with the others an error 
message is shown and reading of files is terminated.

By default, all spots flagged with M, I, and S flags are set to NA. This can be
changed with the flag argument in \Rfunction{readCodelink}. The flag argument 
is a list that can contain a valid flag identifier and a value for that flag.  
For example, if you want to set all M flagged spots to 0.01 and let other spot
untouched you do:

\begin{Sinput}

> data <- readCodelink(flag=list(M=0.01) )

\end{Sinput}

It is possible to find probes wit more that one flag assigned, i.e. CL for a 
probe labeled as C and L, CLI for a probe labeled as C, L and I, and so on. As 
a regular expression is used to find flag types it is possible to manage all 
this situations. When two user modified flags fall in the same probe the 
smallest (or NA if applicable) is assigned.

\section{Background correction}

Smean intensity values can be processed into Ri through
background correction:

\begin{Sinput}

> data <- bkgdCorrect(data, method="half")

\end{Sinput}

The default method used is based on the \emph{half} method from 
\Rpackage{limma} \cite{limma} package. Median background intensity (Bmedian) is 
subtracted from mean spot intensity (Smean) and if the result is less than
0.5 then it is set to 0.5 to ensure no negative numbers are obtained.


\section{Normalization}

Normalization of Ri values are done with the wrapper function
normalize(). The default method is \emph{quantile} normalization
that in fact call \Rfunction{normalizeQuantiles()} from \Rpackage{limma} 
package (that allows for NAs). There is also the possibility to use a modified
version of cyclic loess from \Rpackage{affy} \cite{affy} package that also 
allows NA values.

\begin{Sinput}

> data <- normalize(data, method="quantile")

\end{Sinput}

By default, \Rfunction{normalize} return log2 intensity values.  This could be
changed setting the parameter log.it to FALSE.


\section{Plotting}

There are some plotting functions available that can use directly the
Codelink objects. These are functions for producing MA plots
(\Rfunction{plotMA}), scatterplots (\Rfunction{plotCorrelation}) and density
plots (\Rfunction{plotDensities}).  All functions use the available intensity
value (i.e.  Smean, Ri or Ni) to make the plot.

The function \Rfunction{plotMA} can highlight spots based on type values
(by default) or SNR values setting the argument label. It requires array1 and
array2 arguments and compute M and A values based on equations \ref{eq:M} and
\ref{eq:A}.

\begin{center}

<<plotMA, fig=TRUE>>=

plotMA(codelink.example, legend.x="topright")

@
\end{center}

\begin{equation}
M=Array2-Array1
\label{eq:M}
\end{equation}

\begin{equation}
A=\frac{Array2+Array1}{2}
\label{eq:A}
\end{equation}

The function \Rfunction{plotDensities} plot the density of intensity values of
all arrays. If the subset argument is supplied it can use only a subset of the 
arrays in the \Robject{Codelink} object.

\begin{center}
<<plotDensity, fig=TRUE>>=

plotDensities(codelink.example)

@
\end{center}

\section{Miscellaneus}

There are also some miscellaneous functions used in some analysis that could be
useful for someone.

\subsection{Using weights}

The \Rfunction{createWeights} function creates a matrix of weights based on 
probe type labels to be used, for example, in fitting a linear model with 
\Rpackage{limma} \cite{limma}.

<<createWeights>>=

w <- createWeights(codelink.example, type=list(FIDUCIAL=0.01, NEGATIVE=0.1))

w[1:10,]

@

\subsection{Merging arrays}

In case you want to merge array intensities the \Rfunction{mergeArray} function 
help on this task. It computes the mean of Ni values on arrays of the same 
class.  The grouping is done by means of the 'class' argument (numerical vector 
of classes). New sample names should be assigned to sample slot with the 
'names' argument. The function also returns the coefficient of variation in the 
'cv' slot. The distribution of coefficients of variations can be checked with 
the function \Rfunction{plotCV}.

\begin{Sinput}

> data <- mergeArray(data, group=c(1,1,2,2),
+ names=c("A","B"))

> plotCV(data)

\end{Sinput}


\bibliographystyle{plain} \bibliography{codelink}


\end{document}
