#########################################################################/**

 # @RdocDocumentation "9. Advanced - Cell-index maps for reading and writing"

 #
 # \description{
 #   This part defines read and write maps that can be used to remap 
 #   cell indices before reading and writing data from and to file,
 #   respectively.
 #
 #   This package provides methods to create read and write (cell-index) 
 #   maps from Affymetrix CDF files.  These can be used to store the cell
 #   data in an optimal order so that when data is read it is read in
 #   contiguous blocks, which is faster.

 #
 #   In addition to this, read maps may also be used to read CEL files that
 #   have been "reshuffled" by other software.  For instance, the dChip 
 #   software (\url{http://www.dchip.org/}) rotates Affymetrix Exon,
 #   Tiling and Mapping 500K data.  See example below how to read 
 #   such data "unrotated".

 #
 #   For more details how cell indices are defined, see 

 #   @see "2. Cell coordinates and cell indices".

 # }
 #
 # \section{Motivation}{
 #   When reading data from file, it is faster to read the data in
 #   the order that it is stored compared with, say, in a random order.

 #   The main reason for this is that the read arm of the hard drive

 #   has to move more if data is not read consecutively.  Same applies
 #   when writing data to file.  The read and write cache of the file
 #   system may compensate a bit for this, but not completely.
 #
 #   In Affymetrix CEL files, cell data is stored in order of cell indices.
 #   Moreover, (except for a few early chip types) Affymetrix randomizes
 #   the locations of the cells such that cells in the same unit (probeset)
 #   are scattered across the array.  
 #   Thus, when reading CEL data arranged by units using for instance 
 #   @see "readCelUnits", the order of the cells requested is both random
 #   and scattered.  
 #   
 #   Since CEL data is often queried unit by unit (except for some
 #   probe-level normalization methods), one can improve the speed of
 #   reading data by saving data such that cells in the same unit are
 #   stored together.  A \emph{write map} is used to remap cell indices
 #   to file indices.  When later reading that data back, a 

 #   \emph{read map} is used to remap file indices to cell indices.

 #   Read and write maps are described next.
 # }
 #
 # \section{Definition of read and write maps}{
 #   Consider cell indices \eqn{i=1, 2, ..., N*K} and file indices 
 #   \eqn{j=1, 2, ..., N*K}.
 #   A \emph{read map} is then a \emph{bijective} (one-to-one) function
 #   \eqn{h()} such that
 #   \deqn{
 #     i = h(j),
 #   }
 #   and the corresponding \emph{write map} is the inverse function
 #   \eqn{h^{-1}()} such that
 #   \deqn{
 #     j = h^{-1}(i).
 #   }
 #   Since the mapping is required to be bijective, it holds that 
 #   \eqn{i = h(h^{-1}(i))} and that \eqn{j = h^{-1}(h(j))}. 
 #   For example, consider the "reversing" read map function
 #   \eqn{h(j)=N*K-j+1}.  The write map function is \eqn{h^{-1}(i)=N*K-i+1}.
 #   To verify the bijective property of this map, we see that
 #   \eqn{h(h^{-1}(i)) = h(N*K-i+1) = N*K-(N*K-i+1)+1 = i} as well as
 #   \eqn{h^{-1}(h(j)) = h^{-1}(N*K-j+1) = N*K-(N*K-j+1)+1 = j}.
 # }
 #
 # \section{Read and write maps in R}{
 #   In this package, read and write maps are represented as @integer 
 #   @vectors of length \eqn{N*K} with \emph{unique} elements in
 #   \eqn{\{1,2,...,N*K\}}.
 #   Consider cell and file indices as in previous section.
 #
 #   For example, the "reversing" read map in previous section can be
 #   represented as
 #   \preformatted{
 #     readMap <- (N*K):1
 #   }
 #   Given a @vector \code{j} of file indices, the cell indices are
 #   the obtained as \code{i = readMap[j]}. 
 #   The corresponding write map is
 #   \preformatted{
 #     writeMap <- (N*K):1
 #   }
 #   and given a @vector \code{i} of cell indices, the file indices are
 #   the obtained as \code{j = writeMap[i]}.
 #
 #   Note also that the bijective property holds for this mapping, that is
 #   \code{i == readMap[writeMap[i]]} and \code{i == writeMap[readMap[i]]} 
 #   are both @TRUE.
 #
 #   Because the mapping is bijective, the write map can be calculated from
 #   the read map by:
 #   \preformatted{
 #     writeMap <- order(readMap)
 #   }
 #   and vice versa:
 #   \preformatted{
 #     readMap <- order(writeMap)
 #   }

 #   Note, the @see "invertMap" method is much faster than \code{order()}.

 #
 #   Since most algorithms for Affymetrix data are based on probeset (unit)
 #   models, it is natural to read data unit by unit.  Thus, to optimize the
 #   speed, cells should be stored in contiguous blocks of units.

 #   The methods @see "readCdfUnitsWriteMap" can be used to generate a 
 #   \emph{write map} from a CDF file such that if the units are read in
 #   order, @see "readCelUnits" will read the cells data in order.  

 #   Example:
 #   \preformatted{
 #     Find any CDF file
 #     cdfFile <- findCdf()
 #
 #     # Get the order of cell indices

 #     indices <- readCdfCellIndices(cdfFile)

 #     indices <- unlist(indices, use.names=FALSE)
 #

 #     # Get an optimal write map for the CDF file
 #     writeMap <- readCdfUnitsWriteMap(cdfFile)

 #

 #     # Get the read map
 #     readMap <- invertMap(writeMap)
 #
 #     # Validate correctness

 #     indices2 <- readMap[indices]    # == 1, 2, 3, ..., N*K
 #   }
 #
 #   \emph{Warning}, do not misunderstand this example.  It can not be used

 #   improve the reading speed of default CEL files.  For this, the data in 
 #   the CEL files has to be rearranged (by the corresponding write map).

 # }
 #

 # \section{Reading rotated CEL files}{
 #   It might be that a CEL file was rotated by another software, e.g.
 #   the dChip software rotates Affymetrix Exon, Tiling and Mapping 500K
 #   arrays 90 degrees clockwise, which remains rotated when exported 
 #   as CEL files.  To read such data in a non-rotated way, a read
 #   map can be used to "unrotate" the data.  The 90-degree clockwise 

 #   rotation that dChip effectively uses to store such data is explained by:

 #   \preformatted{
 #     h <- readCdfHeader(cdfFile)
 #     # (x,y) chip layout rotated 90 degrees clockwise
 #     nrow <- h$cols
 #     ncol <- h$rows
 #     y <- (nrow-1):0
 #     x <- rep(1:ncol, each=nrow)
 #     writeMap <- as.vector(y*ncol + x)
 #   }
 #
 #   Thus, to read this data "unrotated", use the following read map:
 #   \preformatted{
 #     readMap <- invertMap(writeMap)
 #     data <- readCel(celFile, indices=1:10, readMap=readMap)
 #   }
 # }
 #

 # @author "HB"

 #
 # @keyword internal

 #*/#########################################################################