Automated update eedf82d415de1c780ee818743144b1dc3353cc4f

dev/Tutorial/chapter_bibliography.html

@@ -124,6 +124,10 @@
 <span class="label"><span class="fn-bracket">[</span>Cavener1987<span class="fn-bracket">]</span></span>
 <p>Douglas R. Cavener: Comparison of the consensus sequence flanking translational start sites in Drosophila and vertebrates. <em>Nucleic Acids Research</em> <strong>15</strong> (4): 1353–1361 (1987). <a class="reference external" href="https://doi.org/10.1093/nar/15.4.1353">https://doi.org/10.1093/nar/15.4.1353</a></p>
 </div>
+<div class="citation" id="chakraborty2013" role="doc-biblioentry">
+<span class="label"><span class="fn-bracket">[</span>Chakraborty2013<span class="fn-bracket">]</span></span>
+<p>Chakraborty, A., Bandyopadhyay, S. FOGSAA: Fast Optimal Global Sequence Alignment Algorithm. <em>Sci Rep</em> <strong>3</strong>, 1746 (2013). <a class="reference external" href="https://doi.org/10.1038/srep01746">https://doi.org/10.1038/srep01746</a></p>
+</div>
 <div class="citation" id="chapman2000" role="doc-biblioentry">
 <span class="label"><span class="fn-bracket">[</span>Chapman2000<span class="fn-bracket">]</span></span>
 <p>Brad Chapman and Jeff Chang: Biopython: Python tools for computational biology. <em>ACM SIGBIO Newsletter</em> <strong>20</strong> (2): 15–19 (August 2000).</p>

dev/Tutorial/chapter_pairwise.html

@@ -149,9 +149,10 @@
 <code class="docutils literal notranslate"><span class="pre">Bio.Align</span></code> module contains the <code class="docutils literal notranslate"><span class="pre">PairwiseAligner</span></code> class for global
 and local alignments using the Needleman-Wunsch, Smith-Waterman, Gotoh
 (three-state), and Waterman-Smith-Beyer global and local pairwise
-alignment algorithms, with numerous options to change the alignment
-parameters. We refer to Durbin <em>et al.</em> <a class="reference internal" href="chapter_bibliography.html#durbin1998" id="id1"><span>[Durbin1998]</span></a>
-for in-depth information on sequence alignment algorithms.</p>
+alignment algorithms, and the Fast Optimal Global Alignment Algorithm (FOGSAA),
+with numerous options to change the alignment parameters. We refer to Durbin
+<em>et al.</em> <a class="reference internal" href="chapter_bibliography.html#durbin1998" id="id1"><span>[Durbin1998]</span></a> for in-depth information on sequence alignment
+algorithms.</p>
 <section id="basic-usage">
 <span id="sec-pairwise-basic"></span><h2>Basic usage<a class="headerlink" href="#basic-usage" title="Link to this heading"></a></h2>
 <p>To generate pairwise alignments, first create a <code class="docutils literal notranslate"><span class="pre">PairwiseAligner</span></code>
@@ -384,6 +385,29 @@
 alignments if segments with a score 0 can be added to the alignment. We
 follow the suggestion by Waterman &amp; Eggert
 <a class="reference internal" href="chapter_bibliography.html#waterman1987" id="id2"><span>[Waterman1987]</span></a> and disallow such extensions.</p>
+<p>If <cite>aligner.mode</cite> is set to <cite>“fogsaa”</cite>, then the Fast Optimal Global Alignment
+Algorithm <a class="reference internal" href="chapter_bibliography.html#chakraborty2013" id="id3"><span>[Chakraborty2013]</span></a> with some modifications is used. This mode
+calculates a global alignment, but it is not like the regular <cite>“global”</cite> mode.
+It is best suited for long alignments between similar sequences. Rather than
+calculating all possible alignments like other algorithms do, FOGSAA uses a
+heuristic to detect steps in an alignment that cannot lead to an optimal
+alignment. This can speed up alignment, however, the heuristic makes
+assumptions about your match, mismatch, and gap scores. If the match score is
+less than the mismatch score or any gap score, or if any gap score is greater
+than the mismatch score, then a warning is raised and the algorithm may return
+incorrect results. Unlike other modes that may return more than one alignment,
+FOGSAA always returns only one alignment.</p>
+<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">aligner</span><span class="o">.</span><span class="n">mode</span> <span class="o">=</span> <span class="s2">&quot;fogsaa&quot;</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">aligner</span><span class="o">.</span><span class="n">mismatch_score</span> <span class="o">=</span> <span class="o">-</span><span class="mi">10</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">alignments</span> <span class="o">=</span> <span class="n">aligner</span><span class="o">.</span><span class="n">align</span><span class="p">(</span><span class="s2">&quot;AAACAAA&quot;</span><span class="p">,</span> <span class="s2">&quot;AAAGAAA&quot;</span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="nb">len</span><span class="p">(</span><span class="n">alignments</span><span class="p">)</span>
+<span class="go">1</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">alignments</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
+<span class="go">target            0 AAAC-AAA 7</span>
+<span class="go">                  0 |||--||| 8</span>
+<span class="go">query             0 AAA-GAAA 7</span>
+</pre></div>
+</div>
 </section>
 <section id="the-pairwise-aligner-object">
 <span id="sec-pairwise-aligner"></span><h2>The pairwise aligner object<a class="headerlink" href="#the-pairwise-aligner-object" title="Link to this heading"></a></h2>
@@ -452,7 +476,7 @@
 <li><p>By specifying a match score for identical letters, and a mismatch
 scores for mismatched letters. Nucleotide sequence alignments are
 typically based on match and mismatch scores. For example, by default
-BLAST <a class="reference internal" href="chapter_bibliography.html#altschul1990" id="id3"><span>[Altschul1990]</span></a> uses a match score of
+BLAST <a class="reference internal" href="chapter_bibliography.html#altschul1990" id="id4"><span>[Altschul1990]</span></a> uses a match score of
 <span class="math notranslate nohighlight">\(+1\)</span> and a mismatch score of <span class="math notranslate nohighlight">\(-2\)</span> for nucleotide
 alignments by <code class="docutils literal notranslate"><span class="pre">megablast</span></code>, with a gap penalty of 2.5 (see section
 <a class="reference internal" href="#sec-pairwise-affine-gapscores"><span class="std std-ref">Affine gap scores</span></a> for more information on gap
@@ -492,7 +516,7 @@
 allows you to apply different scores for different pairs of matched
 and mismatched letters. This is typically used for amino acid
 sequence alignments. For example, by default BLAST
-<a class="reference internal" href="chapter_bibliography.html#altschul1990" id="id4"><span>[Altschul1990]</span></a> uses the BLOSUM62 substitution
+<a class="reference internal" href="chapter_bibliography.html#altschul1990" id="id5"><span>[Altschul1990]</span></a> uses the BLOSUM62 substitution
 matrix for protein alignments by <code class="docutils literal notranslate"><span class="pre">blastp</span></code>. This substitution matrix
 is available from Biopython:</p>
 <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">Bio.Align</span> <span class="kn">import</span> <span class="n">substitution_matrices</span>
@@ -1107,7 +1131,7 @@ <h2>Aligning to the reverse strand<a class="headerlink" href="#aligning-to-the-r
 </section>
 <section id="substitution-matrices">
 <span id="sec-substitution-matrices"></span><h2>Substitution matrices<a class="headerlink" href="#substitution-matrices" title="Link to this heading"></a></h2>
-<p>Substitution matrices <a class="reference internal" href="chapter_bibliography.html#durbin1998" id="id5"><span>[Durbin1998]</span></a> provide the scoring
+<p>Substitution matrices <a class="reference internal" href="chapter_bibliography.html#durbin1998" id="id6"><span>[Durbin1998]</span></a> provide the scoring
 terms for classifying how likely two different residues are to
 substitute for each other. This is essential in doing sequence
 comparisons. Biopython provides a ton of common substitution matrices,
@@ -1551,7 +1575,7 @@ <h3>Reading <code class="docutils literal notranslate"><span class="pre">Array</
 <p>For two-dimensional arrays, we follow the file format of substitution
 matrices provided by NCBI. For example, the BLOSUM62 matrix, which is
 the default substitution matrix for NCBI’s protein-protein BLAST
-<a class="reference internal" href="chapter_bibliography.html#altschul1990" id="id6"><span>[Altschul1990]</span></a> program <code class="docutils literal notranslate"><span class="pre">blastp</span></code>, is stored as
+<a class="reference internal" href="chapter_bibliography.html#altschul1990" id="id7"><span>[Altschul1990]</span></a> program <code class="docutils literal notranslate"><span class="pre">blastp</span></code>, is stored as
 follows:</p>
 <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>#  Matrix made by matblas from blosum62.iij
 #  * column uses minimum score
@@ -1621,8 +1645,8 @@ <h3>Reading <code class="docutils literal notranslate"><span class="pre">Array</
 <h3>Loading predefined substitution matrices<a class="headerlink" href="#loading-predefined-substitution-matrices" title="Link to this heading"></a></h3>
 <p>Biopython contains a large set of substitution matrices defined in the
 literature, including BLOSUM (Blocks Substitution Matrix)
-<a class="reference internal" href="chapter_bibliography.html#henikoff1992" id="id7"><span>[Henikoff1992]</span></a> and PAM (Point Accepted Mutation)
-matrices <a class="reference internal" href="chapter_bibliography.html#dayhoff1978" id="id8"><span>[Dayhoff1978]</span></a>. These matrices are available
+<a class="reference internal" href="chapter_bibliography.html#henikoff1992" id="id8"><span>[Henikoff1992]</span></a> and PAM (Point Accepted Mutation)
+matrices <a class="reference internal" href="chapter_bibliography.html#dayhoff1978" id="id9"><span>[Dayhoff1978]</span></a>. These matrices are available
 as flat files in the <code class="docutils literal notranslate"><span class="pre">Bio/Align/substitution_matrices/data</span></code> directory,
 and can be loaded into Python using the <code class="docutils literal notranslate"><span class="pre">load</span></code> function in the
 <code class="docutils literal notranslate"><span class="pre">substitution_matrices</span></code> submodule. For example, the BLOSUM62 matrix
@@ -1647,7 +1671,7 @@ <h3>Loading predefined substitution matrices<a class="headerlink" href="#loading
 </pre></div>
 </div>
 <p>Note that the substitution matrix provided by Schneider <em>et al.</em>
-<a class="reference internal" href="chapter_bibliography.html#schneider2005" id="id9"><span>[Schneider2005]</span></a> uses an alphabet consisting of
+<a class="reference internal" href="chapter_bibliography.html#schneider2005" id="id10"><span>[Schneider2005]</span></a> uses an alphabet consisting of
 three-nucleotide codons:</p>
 <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">m</span> <span class="o">=</span> <span class="n">substitution_matrices</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="s2">&quot;SCHNEIDER&quot;</span><span class="p">)</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">m</span><span class="o">.</span><span class="n">alphabet</span>  
@@ -1776,7 +1800,7 @@ <h3>Loading predefined substitution matrices<a class="headerlink" href="#loading
 describe some examples of such generalized pairwise alignments.</p>
 <section id="generalized-pairwise-alignments-using-a-substitution-matrix-and-alphabet">
 <h3>Generalized pairwise alignments using a substitution matrix and alphabet<a class="headerlink" href="#generalized-pairwise-alignments-using-a-substitution-matrix-and-alphabet" title="Link to this heading"></a></h3>
-<p>Schneider <em>et al.</em> <a class="reference internal" href="chapter_bibliography.html#schneider2005" id="id10"><span>[Schneider2005]</span></a> created a
+<p>Schneider <em>et al.</em> <a class="reference internal" href="chapter_bibliography.html#schneider2005" id="id11"><span>[Schneider2005]</span></a> created a
 substitution matrix for aligning three-nucleotide codons (see
 <a class="reference external" href="#codonmatrix">below</a> in section <a class="reference internal" href="#sec-substitution-matrices"><span class="std std-ref">Substitution matrices</span></a>
 for more information). This substitution matrix is associated with an
@@ -2237,13 +2261,13 @@ <h4>Calculating the number of nonsynonymous and synonymous substitutions per sit
 (<code class="docutils literal notranslate"><span class="pre">NG86</span></code>, <code class="docutils literal notranslate"><span class="pre">LWL85</span></code>, <code class="docutils literal notranslate"><span class="pre">YN00</span></code>) as well as the maximum likelihood method
 (<code class="docutils literal notranslate"><span class="pre">ML</span></code>) to estimate dN and dS:</p>
 <ul class="simple">
-<li><p><code class="docutils literal notranslate"><span class="pre">NG86</span></code>: Nei and Gojobori (1986) <a class="reference internal" href="chapter_bibliography.html#nei1986" id="id11"><span>[Nei1986]</span></a>
+<li><p><code class="docutils literal notranslate"><span class="pre">NG86</span></code>: Nei and Gojobori (1986) <a class="reference internal" href="chapter_bibliography.html#nei1986" id="id12"><span>[Nei1986]</span></a>
 (default). With this method, you can also specify the ratio of the
 transition and transversion rates via the argument <code class="docutils literal notranslate"><span class="pre">k</span></code>, defaulting
 to <code class="docutils literal notranslate"><span class="pre">1.0</span></code>.</p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">LWL85</span></code>: Li <em>et al.</em> (1985) <a class="reference internal" href="chapter_bibliography.html#li1985" id="id12"><span>[Li1985]</span></a>.</p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">YN00</span></code>: Yang and Nielsen (2000) <a class="reference internal" href="chapter_bibliography.html#yang2000" id="id13"><span>[Yang2000]</span></a>.</p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">ML</span></code>: Goldman and Yang (1994) <a class="reference internal" href="chapter_bibliography.html#goldman1994" id="id14"><span>[Goldman1994]</span></a>. With
+<li><p><code class="docutils literal notranslate"><span class="pre">LWL85</span></code>: Li <em>et al.</em> (1985) <a class="reference internal" href="chapter_bibliography.html#li1985" id="id13"><span>[Li1985]</span></a>.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">YN00</span></code>: Yang and Nielsen (2000) <a class="reference internal" href="chapter_bibliography.html#yang2000" id="id14"><span>[Yang2000]</span></a>.</p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">ML</span></code>: Goldman and Yang (1994) <a class="reference internal" href="chapter_bibliography.html#goldman1994" id="id15"><span>[Goldman1994]</span></a>. With
 this method, you can also specify the equilibrium codon frequency via
 the <code class="docutils literal notranslate"><span class="pre">cfreq</span></code> argument, with the following options:</p>
 <ul>

dev/api/Bio.Align.html

@@ -2966,7 +2966,15 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Link to this headi
 and the mismatch and gap scores are zero.  Based on the values of the gap
 scores, a PairwiseAligner object automatically chooses the appropriate
 alignment algorithm (the Needleman-Wunsch, Smith-Waterman, Gotoh, or
-Waterman-Smith-Beyer global or local alignment algorithm).</p>
+Waterman-Smith-Beyer global or local alignment algorithm, or the Fast
+Optimal Global Sequence Alignment Algorithm).</p>
+<p>The Fast Optimal Global Sequence Alignment Algorithm (FOGSAA) will never be
+automatically selected. If you wish to use FOGSAA, you must set the “mode”
+attribute to “fogsaa”. As its name suggests, it only finds global
+alignments and cannot be used for local alignment. FOGSAA will raise a
+warning and may return incorrect results if the match score is less than
+the mismatch score or any gap score or if any gap score is greater than the
+mismatch score.</p>
 <p>Calling the “score” method on the aligner with two sequences as arguments
 will calculate the alignment score between the two sequences.
 Calling the “align” method on the aligner with two sequences as arguments