File: README.html

package info (click to toggle)
tantan 22-1
links: PTS, VCS
area: main
in suites: buster
size: 492 kB
sloc: cpp: 2,025; sh: 58; makefile: 39
file content (555 lines) | stat: -rw-r--r-- 17,186 bytes
parent folder | download | duplicates (2)
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>tantan</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left{
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: left }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="tantan">
<h1 class="title">tantan</h1>

<div class="section" id="introduction">
<h1>Introduction</h1>
<p>tantan is a tool for masking simple regions (low complexity and
short-period tandem repeats) in biological sequences.</p>
<p>The aim of tantan is to prevent false predictions when searching for
homologous regions between two sequences.  Simple repeats often align
strongly to each other, causing false homology predictions.</p>
</div>
<div class="section" id="setup">
<h1>Setup</h1>
<p>You need to have a C++ compiler.  On Linux, you might need to install
a package called &quot;g++&quot;.  On Mac, you might need to install
command-line developer tools.  On Windows, you might need to install
Cygwin.</p>
<p>Using the command line, go into the tantan directory.  To compile it,
type:</p>
<pre class="literal-block">
make
</pre>
<p>Optionally, copy tantan to a standard &quot;bin&quot; directory (using &quot;sudo&quot; to
request administrator permissions):</p>
<pre class="literal-block">
sudo make install
</pre>
<p>Or copy it to your personal bin directory:</p>
<pre class="literal-block">
make install prefix=~
</pre>
<p>You might need to log out and back in for your computer to recognize
the new program.</p>
</div>
<div class="section" id="normal-usage">
<h1>Normal usage</h1>
<ul>
<li><p class="first">Suppose you have some nucleotide sequences (DNA or RNA) in a
FASTA-format file called &quot;ntseqs.fa&quot;.  You can identify simple
repeats like this:</p>
<pre class="literal-block">
tantan ntseqs.fa &gt; masked.fa
</pre>
<p>This will create a new FASTA file called &quot;masked.fa&quot; that replaces
all masked regions with lowercase letters.  (tantan also works on
FASTQ-format, though it does not use the quality data.)</p>
</li>
<li><p class="first">To mask proteins effectively, tantan needs to use different
algorithm parameters than for nucleotides.  You have to tell it when
you have proteins, using the &quot;-p&quot; option:</p>
<pre class="literal-block">
tantan -p aaseqs.fa &gt; masked.fa
</pre>
<p>If you omit &quot;-p&quot; and the sequences look proteinaceous, tantan will
print a warning message.</p>
</li>
</ul>
</div>
<div class="section" id="advanced-usage">
<h1>Advanced usage</h1>
<ul>
<li><p class="first">By default, tantan indicates repetitive regions with lowercase
letters.  You can make it replace repetitive letters with (say) &quot;N&quot;
by using the &quot;-x&quot; option:</p>
<pre class="literal-block">
tantan -x N ntseqs.fa &gt; masked.fa
</pre>
</li>
<li><p class="first">By default, tantan does not preserve lowercase letters in the input
sequences.  You can tell it to preserve them by using the &quot;-c&quot;
option.  So the output will have the union of the lowercase in the
input and the lowercase assigned by tantan:</p>
<pre class="literal-block">
tantan -c ntseqs.fa &gt; masked.fa
</pre>
</li>
<li><p class="first">tantan's masking rate is usually OK, but you can alter it by
changing the &quot;-r&quot; parameter from its default value of 0.005.  Higher
values increase the amount of masking, and lower values decrease it.
This increases the masking rate:</p>
<pre class="literal-block">
tantan -r 0.02 ntseqs.fa &gt; masked.fa
</pre>
</li>
<li><p class="first">Finally, to mask extremely AT-rich DNA, you should change tantan's
scoring matrix.  The &quot;test&quot; directory contains a matrix &quot;atMask.mat&quot;
that works well for DNA with ~80% A+T, such as Plasmodium and
Dictyostelium genomes.  We recommend masking such DNA like this:</p>
<pre class="literal-block">
tantan -m atMask.mat -r 0.01 atrich.fa &gt; masked.fa
</pre>
</li>
</ul>
<p>The preceding examples cover all of tantan's options that you should
ever need.</p>
</div>
<div class="section" id="recommendations-for-homology-search">
<h1>Recommendations for homology search</h1>
<ol class="arabic simple">
<li>Mask <em>both</em> (sets of) sequences.</li>
<li>If for some reason you wish to mask only one (set of) sequence(s),
increase &quot;-r&quot; to 0.02 (0.05 for AT-rich DNA).</li>
<li>For DNA-versus-protein alignment, increase &quot;-r&quot; for the proteins to
0.02.  If for some reason you mask only one (set of) sequence(s),
make sure it's the proteins.</li>
<li>Some alignment tools exclude lowercase from their initial seeding
phase, but treat lowercase identically to uppercase during their
subsequent extension phase.  Unfortunately, this does not reliably
prevent false homology predictions.  It is OK to re-align without
masking after homology has been decided: FASTA and LAST can do
this.</li>
</ol>
<p>For more information, please read the tantan publication (see below).</p>
</div>
<div class="section" id="faq">
<h1>FAQ</h1>
<div class="section" id="why-does-tantan-sometimes-mask-isolated-bases">
<h2>Why does tantan sometimes mask isolated bases?</h2>
<p>This happens when a region is borderline repetitive, and a single base
creeps just over the threshold.  Don't worry about it, it's not a
problem (at least for tantan's aim of preventing false homology).</p>
</div>
<div class="section" id="does-tantan-mask-functional-sequence">
<h2>Does tantan mask functional sequence?</h2>
<p>Of course.  Proteins and protein-coding exons can contain simple
repeats.  Repeats can be functional.  If we want to avoid false
homology we have to mask them.  Remember that tantan merely lowercases
repeats, so it's easy to lift the masking after determining homology.</p>
</div>
</div>
<div class="section" id="options">
<h1>Options</h1>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-p</span></kbd></td>
<td>interpret the sequences as proteins</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-x</span></kbd></td>
<td>letter to use for masking, instead of lowercase</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-c</span></kbd></td>
<td>preserve uppercase/lowercase in non-masked regions</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-m</span></kbd></td>
<td>file for letter-pair score matrix</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-r</span></kbd></td>
<td>probability of a repeat starting per position</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-e</span></kbd></td>
<td>probability of a repeat ending per position</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-w</span></kbd></td>
<td>maximum tandem repeat period to consider</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-d</span></kbd></td>
<td>probability decay per period (period-(i+1) / period-i)</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-i</span></kbd></td>
<td>match score</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-j</span></kbd></td>
<td>mismatch cost</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-a</span></kbd></td>
<td>gap existence cost</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-b</span></kbd></td>
<td>gap extension cost</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-s</span></kbd></td>
<td>minimum repeat probability for masking</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-n</span></kbd></td>
<td>minimum copy number, affects -f4 only</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-f</span></kbd></td>
<td>output type: 0=masked sequence, 1=repeat probabilities,
2=repeat counts, 3=BED, 4=tandem repeats</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></td>
<td>show help message, then exit</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--version</span></kbd></td>
<td>show version information, then exit</td></tr>
</tbody>
</table>
</div>
<div class="section" id="advanced-issues">
<h1>Advanced issues</h1>
<p>When tantan masks tandem repeats, it tends to leave the first
(left-most) repeat unit unmasked.  This sometimes allows us to find
homologs we would otherwise miss:</p>
<pre class="literal-block">
TGCAAGCTA TTAGGCTTAGGTCAGTGC ttaagcttaggtcagtgc AACATA
||| ||| | |||||||||||||||||| ||| |||||||||||||| ||| ||
TGCTAGCAA TTAGGCTTAGGTCAGTGC ttaggcttaggtcagtgc AACGTA
</pre>
<p>However, there is a danger of non-equivalent repeat units being
unmasked.  This happens especially if we mask DNA on one strand but
align it on the other strand:</p>
<pre class="literal-block">
                   TGCAAGCTA TTAGGCTTAGGTCAGTGC ttaagcttaggtcagtgc AACATA
                             ||||||||||||||||||
TGCTAGCAA ttaggcttaggtcagtgc TTAGGCTTAGGTCAGTGC AACGTA
</pre>
<p>(My thanks to Junko Tsuji and Paul Horton for finding these issues.)</p>
</div>
<div class="section" id="finding-straightforward-tandem-repeats">
<h1>Finding straightforward tandem repeats</h1>
<p>Option -f4 runs tantan in a different mode, where it finds
straightforward tandem repeats only.  (Technically, it uses a Viterbi
algorithm instead of a Forward-Backward algorithm.)  This is <em>not</em>
recommended for avoiding false homologs!  But it might be useful for
studying tandem repeats.  The output looks like this:</p>
<pre class="literal-block">
mySeq   14765   14780   6       2.5     GTCATG  GTCATG,GTCATG,GTC
mySeq   632362  632377  2       6       GC      GC,GC,GC,GCt,GCT,GCT
mySeq   1278353 1278369 3       6.5     TCA     TCA,TCA,TCA,TC-,TC,TC,T
mySeq   3616084 3616100 3       5.33333 TGG     TGA,TGA,TGG,TGG,TGG,T
</pre>
<p>The first 3 columns show the start and end coordinates of the
repetitive region, in <a class="reference external" href="https://genome.ucsc.edu/FAQ/FAQformat.html#format1">BED</a> format.  Column
4 shows the length of the repeating unit (which might vary due to
insertions and deletions, so this column shows the most common
length).  Column 5 shows the number of repeat units.  Column 6 shows
the repeating unit (which again might vary, so this is just a
representative).  Column 7 shows the whole repeat: lowercase letters
are insertions relative to the previous repeat unit, and dashes are
deletions relative to the previous repeat unit.</p>
</div>
<div class="section" id="miscellaneous">
<h1>Miscellaneous</h1>
<p>tantan is distributed under the GNU General Public License, either
version 3 of the License, or (at your option) any later version.  For
details, see COPYING.txt.</p>
<p>If you use tantan in your research, please cite:
&quot;A new repeat-masking method enables specific detection of homologous
sequences&quot;, MC Frith, Nucleic Acids Research 2011 39(4):e23.</p>
<p>tantan's website is: <a class="reference external" href="http://www.cbrc.jp/tantan/">http://www.cbrc.jp/tantan/</a></p>
<p>If you have any questions, comments, or problems concerning tantan,
please email: tantan (ATmark) cbrc (dot) jp.</p>
</div>
</div>
</body>
</html>