\HeaderA{invertMap}{Inverts a read or a write map}{invertMap}
\keyword{file}{invertMap}
\keyword{IO}{invertMap}
\keyword{internal}{invertMap}
\begin{Description}\relax
Inverts a read or a write map.
\end{Description}
\begin{Usage}
\begin{verbatim}invertMap(map, ...)\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{map}] An \code{\LinkA{integer}{integer}} \code{\LinkA{vector}{vector}}.
\item[\code{...}] Not used.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
An map is defined to be a \code{\LinkA{vector}{vector}} of \emph{n} with unique finite
values in \eqn{[1,n]}{}.  Finding the inverse of a map is the same as
finding the rank of each element, cf. \code{\LinkA{order}{order}}().  However,
this method is much faster, because it utilizes the fact that all
values are unique and in \eqn{[1,n]}{}.  Moreover, for any map it holds
that taking the inverse twice will result in the same map.
\end{Details}
\begin{Value}
Returns an \code{\LinkA{integer}{integer}} \code{\LinkA{vector}{vector}}.
\end{Value}
\begin{Author}\relax
Henrik Bengtsson (\url{http://www.braju.com/R/})
\end{Author}
\begin{SeeAlso}\relax
To generate an optimized write map for a CDF file, see
\code{\LinkA{readCdfUnitsWriteMap}{readCdfUnitsWriteMap}}().
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# Simulate a read map for a chip with 2.6 million cells
nbrOfCells <- 2600000
readMap <- sample(nbrOfCells)

# Get the corresponding write map
writeMap <- invertMap(readMap)

# A map inverted twice should be equal itself
stopifnot(identical(invertMap(writeMap), readMap))

# Another example illustrating that the write map is the
# inverse of the read map
idx <- sample(nbrOfCells, size=1000)
stopifnot(identical(writeMap[readMap[idx]], idx))

# invertMap() is much faster than order()
t1 <- system.time(invertMap(readMap))[3]
cat(sprintf("invertMap()  : %5.2fs [ 1.00x]\n", t1))

t2 <- system.time(writeMap2 <- sort.list(readMap, na.last=NA, method="quick"))[3]
cat(sprintf("'quick sort' : %5.2fs [%5.2fx]\n", t2, t2/t1))
stopifnot(identical(writeMap, writeMap2))

t3 <- system.time(writeMap2 <- order(readMap))[3]
cat(sprintf("order()      : %5.2fs [%5.2fx]\n", t3, t3/t1))
stopifnot(identical(writeMap, writeMap2))

# Clean up
rm(nbrOfCells, idx, readMap, writeMap, writeMap2)

\end{ExampleCode}
\end{Examples}

