\documentclass[12pt]{article}
\usepackage[a4paper,top=20mm,bottom=20mm,left=20mm,right=20mm]{geometry}
\usepackage{url}
\usepackage{alltt}
\usepackage{xspace}
\usepackage{times}
\usepackage{listings}
\usepackage{bbm}
\usepackage{verbatim}
\usepackage{prognames}
\usepackage{optionman}
\usepackage{skaff}
\newcommand{\Uniquesub}[0]{\texttt{uniquesub}\xspace}
\newcommand{\Mup}[1]{\mathit{mup(s,#1)}}
\newcommand{\Lmin}[0]{\mathit{mup(s)}}
\newcommand{\Substring}[3]{#1[#2..#3]}
%\newcommand{\EXECUTE}[1]{#1}

\title{Extracting unique substrings\\
a manual}
\author{\begin{tabular}{c}
         \emph{Stefan Kurtz}\\
         Center for Bioinformatics,\\
         University of Hamburg
        \end{tabular}}

\begin{document}
\maketitle
\section{The Program \MKRC}
\MKRC is required whenever you want to determine the minimal unique prefix
lengths w.r.t\ to the forward and the reverse strand.
\MKRC generates from the given input
files an index (i.e.\ a collection of files) which allows \Uniquesub to 
simultaneously match a sequence against the forward and the reverse strand.

\input{mkrcidx}

\section{The program \Uniquesub}

The program \Uniquesub is called as follows:
\par
\noindent\Uniquesub [\emph{options}] \emph{indexname} \emph{queryfile}
\par
\emph{indexname} is the name of an index
computed by \MKV (using the output options \Showoption{suf} and
\Showoption{tis}) or by \MKRC. The \emph{queryfile} must be in multiple 
\Fasta format and can optionally be gzipped, in which case it must end 
with the suffix \texttt{gz}.
Each sequence in \texttt{queryfile} is called \emph{unit} in the following.
The program computes for all positions \(i\) in each unit, say \(s\) of length
\(n\), the length \(\Mup{i}\) of the minimum unique prefix 
at position \(i\), if it exists. Uniqueness always refers to all substrings
represented by the index. If the index was constructed by \MKV, then
it contains all substrings of a given string (in forward direction for
DNA sequences). If the index was constructed by \MKRC (which only works
for DNA sequences), then it represents all substrings in forward and
in reverse complemented direction.
\(\Mup{i}\) is defined by the following two statements:
\begin{enumerate}
\item
If \(\Substring{s}{i}{n-1}\) is not unique in the index, then \(\Mup{i}=\bot\).
That is, it is undefined.
\item
If \(\Substring{s}{i}{n-1}\) is unique in the index, then \(\Mup{i}=m\), where 
\(m\) is the smallest value such that \(i+m-1\leq n-1\) and 
\(\Substring{s}{i}{i+m-1}\) occurs exactly once as a substring in the index.
\end{enumerate}
If no option is used, then for each unit \(s\), \Uniquesub computes 
\[\Lmin=\min\{\Mup{i}\mid i\in[0,n-1],\Mup{i}\neq\bot\}\]
It reports \(\Lmin\) and all positions \(i\) in unit \(s\)
satisfying \(\Mup{i}=\Lmin\). For each such \(i\), it also 
shows the corresponding unique absolute position in the index.
Note that it is possible that for all \(i\in[0,n-1]\) we have 
\(\Mup{i}=\bot\), which means that unit \(s\) does not contain any unique 
substring. In this case, \(\Lmin=\min\emptyset=\bot\), i.e.\ 
\(\Lmin\) is undefined and the program reports that for this unit there 
are no unique substrings.

The following options are available in \Uniquesub:

\begin{Justshowoptions}
\Option{min}{$\ell$}{
Specify the minimum length $\ell$ of minimum unique prefixes to 
be reported. That is, for each unit \(s\) and each position in \(s\), the 
program reports all values \(i\) and \(\Mup{i}\) if \(\Mup{i}\geq\ell\).
}

\Option{max}{$\ell$}{
Specify the maximum length $\ell$ of minimum unique prefixes to 
be reported. That is, for each unit \(s\) and each position in \(s\), the 
program reports all values \(i\) and \(\Mup{i}\) if \(\Mup{i}\leq\ell\).
}

\Option{output}{(\Showoptionkey{subjectpos}$\mid$\Showoptionkey{querypos}$\mid$\Showoptionkey{sequence})}{
Specify what to output. At least one of the three keys words
$\Showoptionkey{subjectpos}$,
$\Showoptionkey{querypos}$, and
$\Showoptionkey{sequence}$ must be used.
Using the keyword $\Showoptionkey{subjectpos}$ shows the subject position
as sequence number and relative position in the subject sequence.
Using the keyword $\Showoptionkey{querypos}$ shows the query position.
Using the keyword $\Showoptionkey{sequence}$ shows the sequence content
of the minimum unique prefix.
}

\Helpoption

\end{Justshowoptions}
The following conditions must be satisfied:
\begin{enumerate}
\item
If both options \Showoption{min} and \Showoption{max} are used, then
the value specified by option \(\Showoption{min}\) must be smaller
than the value specified by option \(\Showoption{max}\).
\end{enumerate}

\section{Examples}

Suppose we have two files \texttt{indexfile.fna} and
\texttt{queryfile.fna}. In the first step, we index \texttt{indexfile.fna}
using the program \MKV:

\EXECUTE{mkvtree -dna -pl -suf -tis -v -db indexfile.fna -indexname indexname}

We obtain one index \texttt{indexname}.
This is used in the following call to the program \Uniquesub:

\EXECUTE{uniquesub -output subjectpos querypos indexname queryfile.fna}

For all units \(s\) in the multiple \Fasta file \texttt{queryfile.fna},
a line is shown, reporting the corresponding value \(\Lmin\).
Also, all positions \(i\) in \(s\) with \(\Mup{i}=\Lmin\)
are reported, together with the corresponding unique position
in the index, shown in the first two columns. The first column is the
sequence number in the index. The second number is the relative position
in this sequence. The \symbol{43}-sign prepended to this position
means that the unique occurrence is on the forward strand of the
indexed sequences. The \(\Lmin\)-value for both units is 3. In the first
unit, there are four positions with a minimum unique prefix of length 3,
namely position 9, 13, 31, and 82.
In the second unit, there is only one position with a minimum unique prefix
of length 3, namely position 12.

To additionally report the sequence content of the
minimum unique prefixes we add option \Showoption{s}.

\EXECUTE{uniquesub -output subjectpos querypos sequence indexname queryfile.fna}

Instead of reporting positions with minimum length prefix over a
unit we can report all \(\Mup{i}\) values in a
given range, using the options \Showoption{min} and \Showoption{max}.
For example, the following program call reports all positions
with a maximal unique prefix of length 5 or longer, again
with the corresponding unique sequence.

\EXECUTE{uniquesub -min 5 -output querypos sequence indexname queryfile.fna}

In each line showing the unique substrings, the first first number is the 
query position and the second is the length. Note that we have omitted
the argument $\Showoptionkey{subjectpos}$ to option \Showoption{output}
to suppress the subject positions.

An upper bound on the length of the minimum unique prefix can be specified 
by the option \Showoption{max}.

\EXECUTE{uniquesub -max 4 -output querypos sequence indexname queryfile.fna}

Of course, the options \Showoption{min} and \Showoption{max}
can be combined. 

Next we create an index \texttt{indexname-bothstrands.rcm}
for both strands of the sequences in \texttt{indexfile.fna}:

\EXECUTE{mkrcidx -v -db indexfile.fna -indexname indexname-bothstrands}

Note that the suffix \texttt{.rcm} is automatically appended to
the given indexname.

We run \Uniquesub on this index and obtain sequences which are
unique on both strands. 

\EXECUTE{uniquesub -output subjectpos querypos sequence indexname-bothstrands.rcm queryfile.fna}

Note that several of the reported sequences are unique on the reverse
strands, which is signified by prepending the symbol \symbol{45} to the
relative subject position.

\section{Change history}

\Showrecentchange{2006-09-22}{\Uniquesub}
The program now also handles reverse complemented indexes to allow
computing strings which are unique both on the forward and the reverse
strand.

\Showrecentchange{2006-09-22}{\Uniquesub}
The option \Showoption{s} has been deleted. Instead use the
option \Showoption{output} with argument $\Showoptionkey{sequence}$.
The option \Showoption{output} also allows to specify that
subject positions and query positions are to be output. In the default
case, neither the sequence, nor the positions are output.

\Showrecentchange{2006-09-18}{\Uniquesub}
If a unit does not contain a unique substring, then the program
now reports this explicitely by a line of the following form:
\begin{verbatim}
unit 13: no unique substrings
\end{verbatim}

\Showrecentchange{2006-09-18}{\Uniquesub}
Besides the unit number, the program also reports the description of the
query sequence, as stored in the fasta header.

\Showrecentchange{2006-09-18}{\Uniquesub}
The program now also accepts a gzipped query file.

\end{document}
