\HeaderA{hilbertImage}{Produce a matrix that visualizes a long data vector along a Hilbert curve}{hilbertImage}
\begin{Description}\relax
Calculate a Hilbert curve visualization of a long data vector and return it as a square matrix.
\end{Description}
\begin{Usage}
\begin{verbatim}
hilbertImage(data, level = 9, forEBImage = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{data}] A (potentially very long) vector of numerical data. 
\item[\code{level}] The level of the Hilbert curve, determining the size of the returned matrix 
\item[\code{forEBImage}] If set to TRUE, an Image object (as defined in the EBImage
package) will be returned.

NOTE TO MacOS X USERS: Due to a problem with EBImage's GTK+ bindings you 
are advised not to use EBImage and HilbertVis/HilbertVisGUI within the
same R session as it seems to cause crashes. This shall be rectified soon. 
[Note added 2008-12-18]

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
See the package vignette for an explanation of this visualization technique.
\end{Details}
\begin{Value}
A matrix of dimension \code{2\textasciicircum{}level} x \code{2\textasciicircum{}level}. Each matrix element corresponds to a bin of consecutive elements
of the data vector, the bins arranged to follow the Hilbert curve of the given level. The value of a 
matrix element is the maximum value of the data vector elements in the bin.

If \code{forEBIImage=TRUE}, a true-color Image object is returned instead, where each pixel is colored
according to the palette constructed by the function \code{\LinkA{hilbertDefaultPalette}{hilbertDefaultPalette}}.
\end{Value}
\begin{Note}\relax
For an interactive GUI to explore a Hilbert curve visualisation, use the function
\code{\LinkA{hilbertDisplay}{hilbertDisplay}} in the \code{HilbertVisGUI} package.
\end{Note}
\begin{Author}\relax
Simon Anders, EMBL-EBI, sanders@fs.tum.de
\end{Author}
\begin{Examples}
\begin{ExampleCode}
   # Get a vector with example data
   dataVec <- makeRandomTestData( )
   
   # Plot it in conventional (linear) fashion
   plotLongVector( dataVec )
   
   # Note how the peaks look quite uniform

   # Get the Hilbert curve matrix
   hMat <- hilbertImage( dataVec )
   
   # Plot it with the 'image' function and the 'hilbertDefaultPalette'
   image( hMat, col=hilbertDefaultPalette( max(hMat), asArray=FALSE ) )
   
   # Note how you can now see the non-uniformity hidden in the previous plot.
   # Note also the ugly aliasing when you change the size of the plot window.
   # Using EBImage allows to display in each matrix element as one pixel:
   
   # if( require ( EBImage ) )
   #    display( hilbertImage( dataVec, forEBImage=TRUE ) )
\end{ExampleCode}
\end{Examples}

