% -*- mode: noweb; noweb-default-code-mode: R-mode; -*-
% building this document: (in R) Sweave ("ctc.Rnw")
\documentclass[a4paper]{article}

\title{Ctc Package}
\author{Antoine Lucas}

\SweaveOpts{echo=FALSE}
%\usepackage{a4wide}
%\VignetteIndexEntry{Introduction to ctc}
%\VignettePackage{ctc}
\usepackage{url}

\begin{document}

\maketitle

\tableofcontents

\section{Overview}

{\tt Ctc} package provides several functions for 
conversion. Specially to export and import data from
Xcluster\footnote{\url{http://genome-www.stanford.edu/~sherlock/cluster.html}} 
 or Cluster\footnote{http://rana.lbl.gov/EisenSoftware.htm} 
 software (very used for Gene's expression
analysis), and to export clusters to TreeView or Freeview visualization
software.

\section{Aim} 

\begin{itemize}
\item To explore clusters made by Xcluster and Cluster . 

\item To cluster data with Xcluster (it requires very low memory usage) 
and analyze the results with R. Warning: results are not exactly the same
as hclust results with R. 
\end{itemize}              
       
\section{Usage}

Standard way of building a hierarchical clustering with R
is with this command:
%<<echo=TRUE,fig=TRUE>>=
<<echo=TRUE>>=
data(USArrests)
h = hclust(dist(USArrests))
plot(h)
@ 
Or for the ``heatmap'':
<<echo=TRUE,fig=TRUE>>=
heatmap(as.matrix(USArrests))
@ 


\subsection{Building hierarchical clustering with another software}

We made these tools
\begin{description}
\item[r2xcluster] Write data table to Xcluster file format 
<<echo=TRUE>>=
library(ctc)
r2xcluster(USArrests,file='USArrests_xcluster.txt')
@ 
 \item[r2cluster] Write data table to Cluster file format 
<<echo=TRUE>>=
r2cluster(USArrests,file='USArrests_xcluster.txt')
@ 
\item[xcluster] Hierarchical clustering (need Xcluster tool  by Gavin Sherlock) 
\begin{verbatim}
> h.xcl=xcluster(USArrests)
> plot(h.xcl)
\end{verbatim}
 
It is roughtly the same as
\begin{verbatim}
> r2xcluster(USArrests,file='USArrests_xcluster.txt')
> system('Xcluster -f USArrests_xcluster.txt -e 0 -p 0 -s 0 -l 0')
> h.xcl=xcluster2r('USArrests_xcluster.gtr',labels=TRUE)
\end{verbatim}


\item[xcluster2r] Importing Xcluster/Cluster output 

\end{description}                 

\subsection{Using other visualization softwares}

We now consider that we have an object of the type produced by 'hclust'
(or a hierarchical cluster imported with previous functions) like:

<<echo=TRUE>>=
hr = hclust(dist(USArrests))
hc = hclust(dist(t(USArrests)))
@ 



\begin{description}
\item[hc2Newick] Export hclust objects to Newick format files
<<echo=TRUE>>=
write(hc2Newick(hr),file='hclust.newick')
@ 
\item[r2gtr,r2atr,r2cdt] Export hclust objects to Freeview or Treeview
visualization softwares
<<echo=TRUE>>=
r2atr(hc,file="cluster.atr")
r2gtr(hr,file="cluster.gtr")
r2cdt(hr,hc,USArrests ,file="cluster.cdt")
@ 
\item[hclust2treeview] Clustering and Export hclust objects to Freeview or Treeview
visualization softwares 
<<echo=TRUE>>=
hclust2treeview(USArrests,file="cluster.cdt")
@ 
\end{description}

    
\section{See Also}

Theses examples can be tested with command
{\tt demo(ctc)}.\\


\noindent
All functions has got man pages, try 
{\tt help.start()}.\\

\noindent
Ctc aims to interact with other softwares, some of them:
\begin{description}
\item[xcluster]
made  by Gavin Scherlock, http://genome-www.stanford.edu/\~\/sherlock/cluster.html
\item[Cluster, Treeview]
made  by Michael Eisen, http://rana.lbl.gov/EisenSoftware.htm
\item[Freeview]
made by Marco Kavcic and Blaz Zupan,
http://magix.fri.uni-lj.si/freeview
\end{description}                 


\noindent
If you want to cite amap or ctc in a publication, use~:

Antoine Lucas and Sylvain Jasson, \emph{Using amap and ctc Packages
  for Huge Clustering}, R News, 2006, vol 6, issue 5 pages 58-60.


\end{document}