\HeaderA{updateCelUnits}{Updates a CEL file unit by unit}{updateCelUnits}
\keyword{file}{updateCelUnits}
\keyword{IO}{updateCelUnits}
\begin{Description}\relax
Updates a CEL file unit by unit.\\

\emph{Please note that, contrary to \code{\LinkA{readCelUnits}{readCelUnits}}(), this method
can only update a single CEL file at the time.}
\end{Description}
\begin{Usage}
\begin{verbatim}updateCelUnits(filename, cdf=NULL, data, ..., verbose=0)\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{filename}] The filename of the CEL file.
\item[\code{cdf}] A (optional) CDF \code{\LinkA{list}{list}} structure either with
field \code{indices} or fields \code{x} and \code{y}.
If \code{\LinkA{NULL}{NULL}}, the unit names (and from there the cell indices) are
inferred from the names of the elements in \code{data}.

\item[\code{data}] A \code{\LinkA{list}{list}} structure in a format similar to what is returned
by \code{\LinkA{readCelUnits}{readCelUnits}}() for \emph{a single CEL file only}.
\item[\code{...}] Optional arguments passed to \code{\LinkA{readCdfCellIndices}{readCdfCellIndices}}(),
which is called if \code{cdf} is not given.
\item[\code{verbose}] An \code{\LinkA{integer}{integer}} specifying how much verbose details are
outputted.
\end{ldescription}
\end{Arguments}
\begin{Value}
Returns what \code{\LinkA{updateCel}{updateCel}}() returns.
\end{Value}
\begin{Section}{Working with re-arranged CDF structures}
Note that if the \code{cdf} structure is specified the CDF file is
\emph{not} queried, but all information about cell x and y locations,
that is, cell indices is expected to be in this structure.  This can
be very useful when one work with a cdf structure that originates
from the underlying CDF file, but has been restructured for instance
through the \code{\LinkA{applyCdfGroups}{applyCdfGroups}}() method, and \code{data}
correspondingly.  This update method knows how to update such
structures too.
\end{Section}
\begin{Author}\relax
Henrik Bengtsson (\url{http://www.braju.com/R/})
\end{Author}
\begin{SeeAlso}\relax
Internally, \code{\LinkA{updateCel}{updateCel}}() is used.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
##############################################################
if (require("AffymetrixDataTestFiles")) {            # START #
##############################################################

# Search for some available Calvin CEL files
path <- system.file("rawData", package="AffymetrixDataTestFiles")
files <- findFiles(pattern="[.](cel|CEL)$", path=path, recursive=TRUE, firstOnly=FALSE)
files <- grep("FusionSDK_Test3", files, value=TRUE)
files <- grep("Calvin", files, value=TRUE)
file <- files[1]

# Convert to an XDA CEL file
pathname <- file.path(tempdir(), basename(file))
if (file.exists(pathname))
  file.remove(pathname)
convertCel(file, pathname)



# Check for the CDF file
hdr <- readCelHeader(pathname)
cdfFile <- findCdf(hdr$chiptype)

hdr <- readCdfHeader(cdfFile)
nbrOfUnits <- hdr$nunits
print(nbrOfUnits);

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example: Read and re-write the same data
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
units <- c(101, 51)
data1 <- readCelUnits(pathname, units=units, readStdvs=TRUE)
cat("Original data:\n")
str(data1)
updateCelUnits(pathname, data=data1)
data2 <- readCelUnits(pathname, units=units, readStdvs=TRUE)
cat("Updated data:\n")
str(data2)
stopifnot(identical(data1, data2))

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example: Random read and re-write "stress test"
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
for (kk in 1:10) {
  nunits <- sample(min(1000,nbrOfUnits), size=1)
  units <- sample(nbrOfUnits, size=nunits)
  cat(sprintf("%02d. Selected %d random units: reading", kk, nunits));
  t <- system.time({
    data1 <- readCelUnits(pathname, units=units, readStdvs=TRUE)
  }, gcFirst=TRUE)[3]
  cat(sprintf(" [%.2fs=%.2fs/unit], updating", t, t/nunits))
  t <- system.time({
    updateCelUnits(pathname, data=data1)
  }, gcFirst=TRUE)[3]
  cat(sprintf(" [%.2fs=%.2fs/unit], validating", t, t/nunits))
  data2 <- readCelUnits(pathname, units=units, readStdvs=TRUE)
  stopifnot(identical(data1, data2))
  cat(". done\n")
}

##############################################################
}                                                     # STOP #
##############################################################
\end{ExampleCode}
\end{Examples}

