\HeaderA{glad}{Analysis of array CGH data}{glad}
\methaliasA{glad.profileCGH}{glad}{glad.profileCGH}
\begin{Description}\relax
This function allows the detection of breakpoints in genomic profiles
obtained by array CGH technology and affects a status (gain, normal
or lost) to each BAC.
\end{Description}
\begin{Usage}
\begin{verbatim}
glad.profileCGH(profileCGH, smoothfunc="aws", base=FALSE, sigma,
                   bandwidth=10, round=2, lambdabreak=8, lambdacluster=8,
                   lambdaclusterGen=40, type="tricubic",
                   param=c(d=6),alpha=0.001, method="centroid", nmax=8, verbose=FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{profileCGH}] Object of class \code{\LinkA{profileCGH}{profileCGH}}
\item[\code{smoothfunc}] Type of algorithm used to smooth \code{LogRatio} by a
piecewise constant function. Choose either \code{\LinkA{aws}{aws}} or
\code{\LinkA{laws}{laws}}.
\item[\code{base}] If TRUE, the position of BAC is the physical position onto
the chromosome, otherwise the rank position is used.
\item[\code{sigma}] Value to be passed to either argument \code{sigma2}   
of\code{ \LinkA{aws}{aws}} function or \code{shape} of
\code{\LinkA{laws}{laws}}. If \code{NULL}, sigma is calculated from
the data.
\item[\code{bandwidth}] Set the maximal bandwidth \code{hmax} in the
\code{\LinkA{aws}{aws}} or  \code{\LinkA{laws}{laws}} function. For
example, if \code{bandwidth=10} then the \code{hmax} value is set
to 10*\eqn{X_N}{} where \eqn{X_N}{} is the position of the last BAC.
\item[\code{round}] The smoothing results of either \code{\LinkA{aws}{aws}}
or \code{\LinkA{laws}{laws}} function are rounded or not depending on
the \code{round} argument. The \code{round} value is passed to the
argument \code{digits} of the \code{\LinkA{round}{round}} function.
\item[\code{lambdabreak}] Penalty term (\eqn{\lambda'}{}) used during the 
"Optimization of the number of breakpoints" step.
\item[\code{lambdacluster}] Penalty term (\eqn{\lambda*}{}) used during the "MSHR
clustering by chromosome" step.
\item[\code{lambdaclusterGen}] Penalty term (\eqn{\lambda*}{}) used during the "HCSR
clustering throughout the genome" step.
\item[\code{type}] Type of kernel function used in the penalty term during the "Optimization of the
number of breakpoints" step, the "MSHR
clustering by chromosome" step and the "HCSR
clustering throughout the genome" step.
\item[\code{param}] Parameter of kernel used in the penalty term.
\item[\code{alpha}] Risk alpha used for the "Outlier detection" step.
\item[\code{method}] The agglomeration method to be used during the "MSHR
clustering by chromosome" and the "HCSR
clustering throughout the genome" clustering steps.
\item[\code{nmax}] Maximum number of clusters (N*max) allowed during
the the "MSHR
clustering by chromosome" and the "HCSR
clustering throughout the genome" clustering steps.
\item[\code{verbose}] If \code{TRUE} some information are printed
\item[\code{...}] parameters to be passed to \code{\LinkA{chrBreakpoints}{chrBreakpoints}}
function. Typically, you will have to specify the following
arguments : \code{lkern="exponential", model="Gaussian", qlambda=0.999}. 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The function \code{glad} implements the methodology which
is described in the article : Analysis of array CGH data: from signal
ratio to gain and loss of DNA regions (Hupé et al., 2004 submitted).

First, \code{\LinkA{chrBreakpoints}{chrBreakpoints}} detects breakpoints and
\code{\LinkA{detectOutliers}{detectOutliers}} allows the detection of MAD
outliers. Then, the number of breakpoints is optimized with
\code{\LinkA{removeBreakpoints}{removeBreakpoints}}.  The two-step clustering ("MSHR
clustering by chromosome" and the "HCSR
clustering throughout the genome") is performed with
\code{\LinkA{findCluster}{findCluster}}. The function
\code{\LinkA{affectationGNL}{affectationGNL}} give a status to each BAC.
\end{Details}
\begin{Value}
\begin{ldescription}
\item[\code{Smoothing}] Smoothing results of either \code{\LinkA{aws}{aws}} or
\code{\LinkA{laws}{laws}} function after being rounded or not
depending on the \code{round} argument.
\item[\code{Breakpoints}] The last position of a region with identical amount
of DNA is flagged by 1 otherwise it is 0. Note that during the
"Optimization of the number of breakpoints" step, removed
breakpoints are flagged by -1.
\item[\code{Region}] Each position between two breakpoints are labelled the
same way with an integer value starting from one. The label is
incremented by one when a new breakpoints occurs or when moving to
the next chromosome. The variable \code{region} is what we call MSHR.
\item[\code{Level}] Each position with equal smoothing value are labelled the
same way with an integer value starting from one. The label is
incremented by one when a new level occurs or when moving to the
next chromosome.
\item[\code{OutliersAws}] Each AWS outliers are flagged by -1 (if it is
in the \eqn{\alpha/2}{} lower tail of the distribution) or 1 (if it is
in the \eqn{\alpha/2}{} upper tail of the distribution)
otherwise  it is 0.
\item[\code{OutliersMad}] Each MAD outliers are flagged by -1 (if it is
in the \eqn{\alpha/2}{} lower tail of the distribution) or 1 (if it is
in the \eqn{\alpha/2}{} upper tail of the distribution)
otherwise  it is 0.
\item[\code{OutliersTot}] OutliersAws + OutliersMad.
\item[\code{ZoneChr}] Clusters identified after MSHR (i.e. \code{Region})
clustering by chromosome.
\item[\code{ZoneGen}] Clusters identified after HCSR clustering throughout the
genome.
\item[\code{ZoneGNL}] Status of each BAC : Gain is coded by 1, Loss by -1 and Normal by 0.
\end{ldescription}
\end{Value}
\begin{Author}\relax
Philippe Hupé, \email{Philippe.Hupe@curie.fr}.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{chrBreakpoints}{chrBreakpoints}},
\code{\LinkA{removeBreakpoints}{removeBreakpoints}},\code{\LinkA{detectOutliers}{detectOutliers}},
\code{\LinkA{findCluster}{findCluster}},  \code{\LinkA{affectationGNL}{affectationGNL}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

data(snijders)
profileCGH <- list(profileValues=gm13330)
class(profileCGH) <- "profileCGH"

res <- glad(profileCGH, smoothfunc="laws", base=FALSE,
               bandwidth=10, round=2, lambdabreak=8, lambdacluster=8,
               lambdaclusterGen=40, alpha=0.001, method="centroid",
               nmax=8, lkern="exponential", model="Gaussian",
               qlambda=0.999)

# color code for region status

col <- rep("yellow",length(res$profileValues$PosOrder))
col[which(res$profileValues$ZoneGNL==-1)] <- "green"
col[which(res$profileValues$ZoneGNL==1)] <- "red"

# outliers

outliers <- rep(20,length(res$profileValues$PosOrder))
outliers[which(res$profileValues$OutliersTot!=0)] <- 13

plot(LogRatio ~ PosOrder, data=res$profileValues, col=col, pch=outliers)

# Limit between chromosomes

LimitChr <- unique(res$profileValues$LimitChr)+0.5
abline(v=LimitChr, col="grey", lty=2)

lines(res$profileValues$Smoothing ~ res$profileValues$PosOrder, col="black")

# Breakpoints identified

indexBP <- which(res$profileValues$Breakpoints==1)
BP <- res$profileValues$PosOrder[indexBP]+0.5
abline(v=BP, col="red", lty=2)

\end{ExampleCode}
\end{Examples}

