\HeaderA{flag}{Create an object of type flag}{flag}
\aliasA{to.flag}{flag}{to.flag}
\begin{Description}\relax
A \code{flag} object is a list which contains essentially a function
(flag action) and a character, optionally arguments to be passed to the
function.
We make the distinction between two different flag types,
corresponding to two different purposes:
- \emph{permanent flags} identify poor quality spots or clones and remove them from further
analysis (eg spots with low signal to noise ratio)
- \emph{temporary flags} identify spots or clones that have not to be taken into account for
the computation of a (scaling) normalization coefficient (eg X chromosome in case of sex mismatch)
\end{Description}
\begin{Usage}
\begin{verbatim}
 to.flag(FUN, char=NULL, args=NULL, type="perm.flag", label=NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{FUN}] a R function to be applied to an \code{\LinkA{arrayCGH}{arrayCGH}}, and optionally
other arguments. If char is not NULL, must return a list of spots (lines of
\code{arrayCGH\$arrayValues}) to be flagged out; if \code{char==NULL}, must return
an object of type \code{\LinkA{arrayCGH}{arrayCGH}}
\item[\code{char}] a character value to identify flagged spots; defaults to NULL
\item[\code{args}] a list of further arguments to be passed to \code{FUN}; defaults
to NULL (ie \code{\LinkA{arrayCGH}{arrayCGH}} is the only argument to \code{FUN})
\item[\code{type}] a character value defaulting to "perm.flag" which makes
the distinction between permanent flags (type="perm.flag") and
temporary flags (type="temp.flag")
\item[\code{label}] a character value for flag labelling
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If \code{flag\$char} is null, \code{flag\$FUN} is supposed to return a
\code{arrayCGH} object; if it is not null, \code{flag\$FUN} is supposed
to return a list of spots to be flagged with \code{flag\$char}.
\end{Details}
\begin{Value}
An object of class \code{flag}.
\end{Value}
\begin{Note}\relax
People interested in tools for array-CGH analysis can
visit our web-page: \url{http://bioinfo.curie.fr}.
\end{Note}
\begin{Author}\relax
Pierre Neuvial, \email{manor@curie.fr}.
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{flag.arrayCGH}{flag.arrayCGH}}, \code{\LinkA{norm.arrayCGH}{norm.arrayCGH}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
### creation of a permanent flag:
## flag spots with low signal to noise ratios
SNR.FUN <- function(arrayCGH, snr.thr)
    which(arrayCGH$arrayValues$F2 < arrayCGH$arrayValues$B2+log(snr.thr, 2))
SNR.char <- "B"
SNR.flag <- to.flag(SNR.FUN, SNR.char, args=alist(snr.thr=3))

### creation of a permanent flag returning an arrayCGH object:
## correct log-ratios for spatial trend

global.spatial.FUN <- function(arrayCGH, var)
  {
    Trend <- arrayTrend(arrayCGH, var, span=0.03, degree=1,
iterations=3, family="symmetric")
    arrayCGH$arrayValues[[var]] <- Trend$arrayValues[[var]]-Trend$arrayValues$Trend
    arrayCGH
  }
global.spatial.flag <- to.flag(global.spatial.FUN, args=alist(var="LogRatio"))

### creation of a temporary flag:
## exclude sexual chromosomes from signal scaling
chromosome.FUN <- function(arrayCGH, var)
  which(!is.na(match(as.character(arrayCGH$arrayValues[[var]]), c("X", "Y"))))
chromosome.char <- "X"
chromosome.flag <- to.flag(chromosome.FUN, chromosome.char, type="temp.flag",
args=alist(var="Chromosome")) 

data(spatial)

SNR.flag$args$snr.thr <- 3                   ## set SNR threshold
gradient <- flag.arrayCGH(SNR.flag, gradient)    ## apply SNR.flag to array CGH

gradient <- flag.arrayCGH(global.spatial.flag, gradient)

gradient <- flag.arrayCGH(chromosome.flag, gradient)

summary.factor(gradient$arrayValues$Flag)   ## permanent flags
summary.factor(gradient$arrayValues$FlagT)  ## temporary flags
\end{ExampleCode}
\end{Examples}

