\HeaderA{disscosangle}{Functions to compute pair-wise distances}{disscosangle}
\aliasA{dissabscor}{disscosangle}{dissabscor}
\aliasA{dissabscosangle}{disscosangle}{dissabscosangle}
\aliasA{disscor}{disscosangle}{disscor}
\aliasA{disseuclid}{disscosangle}{disseuclid}
\aliasA{vdissabscor}{disscosangle}{vdissabscor}
\aliasA{vdissabscosangle}{disscosangle}{vdissabscosangle}
\aliasA{vdissabseuclid}{disscosangle}{vdissabseuclid}
\aliasA{vdisscor}{disscosangle}{vdisscor}
\aliasA{vdisscosangle}{disscosangle}{vdisscosangle}
\aliasA{vdisseuclid}{disscosangle}{vdisseuclid}
\keyword{multivariate}{disscosangle}
\keyword{internal}{disscosangle}
\begin{Description}\relax
Given a matrix \code{X}, these functions compute the pair-wise distances 
between all variables (rows) in \code{X}, across all observations 
(columns) of \code{X}. Each function uses a different distance metric, 
i.e. definition of what it means for two variables to be similar. In 
hoapch version \textgreater{}=2.0.0, these functions return an object of class hdist 
rather than a matrix.
\end{Description}
\begin{Usage}
\begin{verbatim}
disscosangle(X, na.rm = TRUE)

disseuclid(X, na.rm = TRUE)

disscor(X, na.rm = TRUE)

dissabscosangle(X, na.rm = TRUE)

dissabscor(X, na.rm = TRUE)

vdisscosangle(X, y, na.rm = TRUE)

vdisseuclid(X, y, na.rm = TRUE)

vdisscor(X, y, na.rm = TRUE)

vdissabscosangle(X, y, na.rm = TRUE)

vdissabseuclid(X, y, na.rm = TRUE)

vdissabscor(X, y, na.rm = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{X}] A numeric data matrix. Each column corresponds to an observation, and each row corresponds to a variable. In the gene expression context, observations are arrays and variables are genes. All values must be numeric. Missing values are ignored.
\item[\code{na.rm}] Indicator of whether to remove missing values (i.e. only compute distance over non-missing observations).
\item[\code{y}] A numeric data vector of length \code{ncol(X)}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Different choices of distance metric are discussed in the references. 
Briefly, Euclidean distance (\code{disseuclid}) defines two variables 
to be close if they are similar in magnitude across observations. 
Correlation distance (\code{disscor}), in contrast, defines similarity 
to mean having the same pattern, but not necessarily the same magnitude. 
Cosine-angle (\code{disscosangle}) distance is a correlation distance 
that also accounts for magnitude. Cosine-angle distance is also known as 
uncentered correlation distance. The distance metrics with 'abs' in 
their names are absolute versions of each metric; the absolute value is 
applied to the data before computing the distance.

In hopach versions \textless{}2.0.0, these functions returned the square root of 
the usual distance for \code{d="cosangle"}, \code{d="abscosangle"}, 
\code{d="cor"}, and \code{d="abscor"}. Typically, this transformation 
makes the dissimilarity correspond more closely with the norm. In order 
to agree with the \code{dist} function, the square root is no longer 
used in versions \textgreater{}=2.0.0.
\end{Details}
\begin{Value}
For versions \textgreater{}= 2.0.0 \code{distancematrix}, a \code{hdist} 
object of of all pair wise distances between the rows of the data matrix 'X',
i.e. the value of \code{hdist[i,j]} is the distance between rows 'i' and 'j'
of 'X', as defined by 'd'.  A \code{hdist} object is an S4 class containing 
four slots:
\begin{ldescription}
\item[\code{Data}] representing the lower triangle of the symmetric 
distance matrix.    

\item[\code{Size}] the number of objects (i.e. rows of the data 
matrix).

\item[\code{Labels}] labels for the objects, usually the numbers 1 to 
Size.

\item[\code{Call}] the distance used in the call to 
\code{distancematrix}.  

\end{ldescription}


A hdist object and can be converted to a matrix using \code{as.matrix(hdist)}.
(See \code{hdist} for more details.)

For the vector versions (e.g. \code{vdisscosangle}), a numeric vector of 
\code{nrow(X)} pair-wise distances between each variable (row) in 
\code{X} and the vector \code{y}.
\end{Value}
\begin{Author}\relax
Katherine S. Pollard \textless{}kpollard@gladstone.ucsf.edu\textgreater{} and Mark J. van der Laan \textless{}laan@stat.berkeley.edu\textgreater{}, with Greg Wall
\end{Author}
\begin{References}\relax
van der Laan, M.J. and Pollard, K.S. A new algorithm for hybrid hierarchical clustering with visualization and the bootstrap. Journal of Statistical Planning and Inference, 2003, 117, pp. 275-303.

\url{http://www.stat.berkeley.edu/~laan/Research/Research_subpages/Papers/hopach.pdf}

\url{http://www.bepress.com/ucbbiostat/paper107/}

\url{http://www.stat.berkeley.edu/~laan/Research/Research_subpages/Papers/jsmpaper.pdf}
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{distancematrix}{distancematrix}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data<-matrix(rnorm(50),nr=5)
disscosangle(data)
\end{ExampleCode}
\end{Examples}

