\documentclass[12pt]{article}
\usepackage{url,a4wide,alltt,xspace,times}
\usepackage{skaff}
\usepackage{prognames}
\usepackage{optionman}
\usepackage{verbatim}
\newcommand{\Size}[1]{|#1|}
\newcommand{\Ignore}[1]{}
\newcommand{\Alggap}[0]{clustering with gaps\xspace}
\newcommand{\Algovl}[0]{clustering with overlaps\xspace}
\newcommand{\Edist}[2]{edist(#1,#2)}
\newcommand{\EXECUTE}[1]{}

\author{Stefan Kurtz\thanks{\SKaffiliation}}

\title{\textbf{Clustering Matches}\\
       \textbf{using the program matchcluster}\\[2mm]
       \textbf{Manual}}
\begin{document}
\maketitle
This short manual describes the program \MCL which allows to 
cluster matches if they contain pairwise similar sequences,
or if their positions are close together.

\section{The program \MCL and its options}

The program is called as follows:
\par
\noindent\MCL \emph{options} \emph{matchfile}
\par
And here is a description of the options:
\par
\begin{list}{}{}

\Option{erate}{\Showoptionarg{$\epsilon$}}{
Specify the error percentage $\epsilon$ for clustering
by sequence similarity. $\epsilon$ is an integer in the range 0 to 100. 
}

\Option{gapsize}{\Showoptionarg{$\gamma$}}{
Specify the maximum gap size $\gamma$ for clustering
by gap size. $\gamma$ is an non-negative integer.
}

\Option{overlap}{\Showoptionarg{$\omega$}}{
Specify the overlap percentage $\omega$ for clustering
by overlap. $\omega$ is an non-negative integer.
}

\Option{outprefix}{\Showoptionarg{prefix}}{
Specify that each cluster of matches is output into a separate 
file whose name starts with \Showoptionarg{prefix}. 
}

\Option{version}{}{
Show the version of the \emph{Vmatch} software package, the program is part of. 
Also report the compilation date and the compilation options.
}

\Option{help}{}{
Show a summary of all options and terminate.
}
\end{list}

The option \Showoption{outprefix} is mandatory.
Also exactly one of the options
\Showoption{erate}, \Showoption{gapsize}, and \Showoption{overlap}
must be used. \MCL reads in the match file and applies single linkage 
clustering to the matches. The choice of the parameter
\Showoption{erate}, \Showoption{gapsize}, and \Showoption{overlap}
determines which kind of clustering is performed.

Each cluster is reported in a separate file named
\Showoptionarg{prefix}\texttt{.}$s$\texttt{.}$i$\Filenamesuffix{.match}.
This stores all matches which were used to form cluster \(i\).
\(s\) is the size of the cluster with number \(i\). 
The cluster numbers are consecutive numbers beginning with 0.
The matches are reported in the standard \VM format.
Furthermore, each match is preceeded by a comment line showing the 
identification number of the match. At the end of the file, it is 
reported why the cluster was formed.

\section{Examples}

Suppose we have constructed an index for yeast chromosome III, using the
program \MKV:

\EXECUTE{mkvtree -dna -db ychrIII.fna -v -tis -ois -bwt -suf -lcp}

Now compute all repeats of length \(\geq 100\) in yeast chromosome III, using
the program \VM.

\EXECUTE{vmatch -l 100 ychrIII.fna}

Suppose we have stored these matches in a 
matchfile \texttt{ychrIII-100.match}.
The following program call performs clustering by similarity, using an 
error rate 35, producing clusters in files with the prefix \texttt{clout}:

\EXECUTE{matchcluster -erate 35 -outprefix clout ychrIII-100.match}

Three files where generated by this program call:

\EXECUTE{ls -l clout.*}

Consider the last file \texttt{clout.3.1.match} representing cluster 1
with three matches:

\EXECUTE{cat clout.3.1.match}

Cluster 1 thus contains the matches with identification
numbers 7, 8, and 12. For example, match 7 and 12 achieve a distance of 
88, which corresponds to an error rate of 31.43\%, well below the maximum error 
rate of 35\%. Note that
the generated files are in a format that they can be read by \VMS. This,
for example, allows to report the sequence content of the matches:

\EXECUTE{vmatchselect -s leftseq clout.3.1.match}

Alternatively, we cluster by gap size, allowing gaps of size up to 
1000.

\EXECUTE{matchcluster -gapsize 1000 -outprefix clout ychrIII-100.match}

Consider the file \texttt{clout.4.1.match} representing cluster 1
with four matches: It contains the matches with identification
numbers 14, 7, 8, and 12. For example, match 8 and 7 have a gap of
\(276=84469 - 83954 - 239\) which is well below the maximum gap size
of 1000.

\EXECUTE{cat clout.4.1.match}

In a third run we cluster the matches by overlap, allowing overlaps
of minimum 10\%.

\EXECUTE{matchcluster -overlap 10 -outprefix clout ychrIII-100.match}

Consider the file \texttt{clout.3.2.match} representing cluster 2
with three matches: It contains the matches with identification
numbers 0, 6, and 1. For example, match 0 and 1, overlap by
\(82=199591 + 203 - 199712\), which is 40.39\% of the longer
match 203.

\EXECUTE{cat clout.3.2.match}

\appendix

\section{Single Linkage Clustering}
Initially, the single linkage clustering strategy puts each match into 
its own cluster. In every clustering step, each 
match is in exactly one cluster. To compute the clusters,
for each pair \((m,m')\) of matches it is verified, if the matches are
related. Whenever two matches \(m\) and \(m'\) 
are related, the two clusters containing 
\(m\) and \(m'\) are joint to one cluster. 
The different clustering strategies differ by what they consider 
to be related sequences. There are basically two notions
of relatedness: One is sequence based and the other is position 
based.

\paragraph{Clustering by sequence similarity}
For this clustering strategy, the user specifies an error rate 
\(\epsilon\) and two matches \(m\) and \(m'\) are related
if the sequences involved in the matches
are sufficiently similar:
To precisely define this, we have to refer to the sequences involved
in a pairwise match. So let a match be a pair \((u,v)\) of match instances, 
i.e.\ \(u\) and \(v\) are matching sequences.
Let \(m=(u,v)\)  and \(m'=(u',v')\) be the matches for which we want 
to check relatedness alias similarity.
Let \(l\) be the minimal length of all four sequences
\(u\), \(v\), \(u'\), and \(v'\). Then \(e=l\cdot\epsilon/100\) is the
error threshold for this pair \((m,m')\) of matches. 
Let \(\Edist{x}{y}\) denote the edit distance between two sequences 
\(x\) and \(y\), i.e.\
the minimal number of insertions, deletions, and replacements 
required to transform sequence \(x\) into sequence \(y\).
We consider \(m\) and \(m'\) to be similar, if and only if 
at least one of the following four conditions holds:
\begin{itemize}
\item
\(\Edist{u}{u'}\leq e\)
\item
\(\Edist{u}{v'}\leq e\)
\item
\(\Edist{v}{u'}\leq e\)
\item
\(\Edist{v}{v'}\leq e\)
\end{itemize}

\paragraph{Clustering by match positions}
There are two strategies of clustering by positions. These were
originally described and evaluated by
\cite{VOL:HAA:SAL:2001} in the context of repeat clustering.

\begin{itemize}
\item
clustering by \emph{gap size}: in this case the user specifies a
parameter \(\gamma\geq 0\), the maximal size of a gap.
\item
clustering by \emph{overlap}: in this case the user specifies a 
parameter \(\omega\in[0,100]\), the overlap percentage.
\end{itemize}
Both clustering strategies ignore the sequence content of the matches
and only consider the positions where the matches occur.
Therefore, now consider a match to be a quadruple
$(l,i,r,j)$, where \(l\) and \(r\) are the length of the matching
sequences and \(i\) and \(j\) are their start positions.
Let \(M\) be the set of all matches. We mirror \(M\) to obtain
a set \(P\) of partition points, defined as follows:
\[P = M \cup \{(r,j,l,i) \mid (l,i,r,j) \in M\}\]
Now sort the partition points in \(P\) according to their second component.
Partition points with identical second components are sorted according
to their fourth component. Now consider two partition points
$p=(l,i,r,j)$ and $p'=(l',i',r',j')$ from \(P\) such that \(i\leq i'\).
We define \(d(p,p')=\max(0,i'-i-l)\) to be the gap size between \(p\) and 
\(p'\). When clustering with gap size, we consider \(p\) and \(p'\)
to be related, if \(d(p,p')\leq\gamma\).
We also define \(o(p,p')=\max(0,i+l-i')\) to be the overlap size
of \(p\) and \(p\). The overlap percentage is relative to the length of
the longer sequence, i.e.\ it is defined as 
\(\frac{o(p,p')}{\max(l,l')}\).
When clustering with overlap is used, we
consider \(p\) and \(p'\) to be related, if
\(100\cdot \frac{o(p,p')}{\max(l,l')}\geq\omega\).

\bibliographystyle{plain}
\bibliography{genomes}
\end{document}
