Automated update 6dfefa86f1eccc7df68ec14d932bb96e343d05cc

Author: Sphinx

dev/Tutorial/chapter_align.html

@@ -77,6 +77,7 @@
 <li class="toctree-l4"><a class="reference internal" href="#adding-alignments">Adding alignments</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#mapping-a-pairwise-sequence-alignment">Mapping a pairwise sequence alignment</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#mapping-a-multiple-sequence-alignment">Mapping a multiple sequence alignment</a></li>
+<li class="toctree-l4"><a class="reference internal" href="#using-from-alignments-with-same-reference">Using from_alignments_with_same_reference</a></li>
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference internal" href="#the-alignments-class">The Alignments class</a></li>
@@ -1523,6 +1524,52 @@ <h3>Mapping a multiple sequence alignment<a class="headerlink" href="#mapping-a-
 <span class="go">rn7.chr2  174256650</span>
 </pre></div>
 </div>
+</section>
+<section id="using-from-alignments-with-same-reference">
+<h3>Using from_alignments_with_same_reference<a class="headerlink" href="#using-from-alignments-with-same-reference" title="Link to this heading"></a></h3>
+<p>The <a class="reference internal" href="../api/Bio.Align.html#Bio.Align.Alignment.from_alignments_with_same_reference" title="Bio.Align.Alignment.from_alignments_with_same_reference"><code class="xref py py-meth docutils literal notranslate"><span class="pre">from_alignments_with_same_reference()</span></code></a> method
+constructs a new multiple sequence alignment from a collection of pairwise
+alignments that all share the same reference sequence. This is useful when you
+have aligned several sequences independently to the same reference and want to
+combine those results into a single multiple alignment.</p>
+<p>Suppose you have a pairwise alignment of a reference sequence to sequence A and
+a multiple alignment of sequences B and C to the same reference. To merge
+these into a single multiple alignment of the reference and sequences A, B, and C,
+you can use the <code class="docutils literal notranslate"><span class="pre">from_alignments_with_same_reference</span></code> method as follows:</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="w"> </span><span class="nn">Bio.Seq</span><span class="w"> </span><span class="kn">import</span> <span class="n">Seq</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">Bio.Align</span><span class="w"> </span><span class="kn">import</span> <span class="n">PairwiseAligner</span><span class="p">,</span> <span class="n">Alignment</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">numpy</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">np</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="n">reference_str</span> <span class="o">=</span> <span class="s2">&quot;ACGT&quot;</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">seq1_str</span> <span class="o">=</span> <span class="s2">&quot;ACT&quot;</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">seq2_str</span> <span class="o">=</span> <span class="s2">&quot;ACGGT&quot;</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">seq3_str</span> <span class="o">=</span> <span class="s2">&quot;AT&quot;</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="n">aligner</span> <span class="o">=</span> <span class="n">PairwiseAligner</span><span class="p">()</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">alignment_1</span> <span class="o">=</span> <span class="nb">next</span><span class="p">(</span><span class="n">aligner</span><span class="o">.</span><span class="n">align</span><span class="p">(</span><span class="n">reference_str</span><span class="p">,</span> <span class="n">seq1_str</span><span class="p">))</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="n">coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">]])</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="n">alignment_2</span> <span class="o">=</span> <span class="n">Alignment</span><span class="p">([</span><span class="n">reference_str</span><span class="p">,</span> <span class="n">seq2_str</span><span class="p">,</span> <span class="n">seq3_str</span><span class="p">],</span> <span class="n">coords</span><span class="p">)</span>
+
+<span class="gp">&gt;&gt;&gt; </span><span class="n">combined_alignment</span> <span class="o">=</span> <span class="n">Alignment</span><span class="o">.</span><span class="n">from_alignments_with_same_reference</span><span class="p">(</span>
+<span class="gp">... </span>    <span class="p">[</span><span class="n">alignment_1</span><span class="p">,</span> <span class="n">alignment_2</span><span class="p">]</span>
+<span class="gp">... </span><span class="p">)</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">combined_alignment</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
+<span class="go">&#39;ACG-T&#39;</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">combined_alignment</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
+<span class="go">&#39;AC--T&#39;</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">combined_alignment</span><span class="p">[</span><span class="mi">2</span><span class="p">])</span>
+<span class="go">&#39;ACGGT&#39;</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">combined_alignment</span><span class="p">[</span><span class="mi">3</span><span class="p">])</span>
+<span class="go">&#39;A---T&#39;</span>
+</pre></div>
+</div>
+<p>The resulting alignment contains all sequences aligned to the shared reference.
+This method differs from <a class="reference internal" href="../api/Bio.Align.html#Bio.Align.Alignment.map" title="Bio.Align.Alignment.map"><code class="xref py py-meth docutils literal notranslate"><span class="pre">map()</span></code></a> and
+<a class="reference internal" href="../api/Bio.Align.html#Bio.Align.Alignment.mapall" title="Bio.Align.Alignment.mapall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">mapall()</span></code></a> in that it <em>builds</em> a new multiple alignment
+directly from a set of pairwise alignments, rather than transforming an existing
+multiple alignment using mappings. Each input alignment must have the same
+reference sequence (in the same orientation), otherwise an error is raised.</p>
 <p>The <code class="docutils literal notranslate"><span class="pre">mapall</span></code> method can also be used to create a multiple alignment of
 codon sequences from a multiple sequence alignment of the corresponding
 amino acid sequences (see Section <a class="reference internal" href="chapter_pairwise.html#sec-msa-codons"><span class="std std-ref">Generating a multiple sequence alignment of codon sequences</span></a>

dev/api/Bio.Align.html

@@ -1339,6 +1339,88 @@ <h2>Submodules<a class="headerlink" href="#submodules" title="Link to this headi
 </div>
 </dd></dl>
 
+<dl class="py method">
+<dt class="sig sig-object py" id="Bio.Align.Alignment.from_alignments_with_same_reference">
+<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">from_alignments_with_same_reference</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">alignments</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><a class="reference internal" href="#Bio.Align.Alignment" title="Bio.Align.Alignment"><span class="pre">Alignment</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><a class="reference internal" href="#Bio.Align.Alignment" title="Bio.Align.Alignment"><span class="pre">Alignment</span></a><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#Bio.Align.Alignment" title="Bio.Align.Alignment"><span class="pre">Alignment</span></a></span></span><a class="headerlink" href="#Bio.Align.Alignment.from_alignments_with_same_reference" title="Link to this definition"></a></dt>
+<dd><p>Create an Alignment from a list of alignments in which the first sequence is the same (reference sequence).</p>
+<p>This method combines multiple alignments into a single multiple sequence alignment.
+All alignments must share the same reference sequence (ignoring gaps).</p>
+<dl>
+<dt>Args:</dt><dd><p>alignments: A list or tuple of Alignment objects.</p>
+</dd>
+<dt>Returns:</dt><dd><p>An Alignment object representing a multiple sequence alignment.</p>
+</dd>
+<dt>Raises:</dt><dd><p>ValueError: If no alignments are provided or if the reference
+sequences do not match across all alignments.</p>
+</dd>
+<dt>Example 1: Basic Usage with Strings</dt><dd><div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">Bio.Seq</span><span class="w"> </span><span class="kn">import</span> <span class="n">Seq</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">Bio.SeqRecord</span><span class="w"> </span><span class="kn">import</span> <span class="n">SeqRecord</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">Bio.Align</span><span class="w"> </span><span class="kn">import</span> <span class="n">PairwiseAligner</span><span class="p">,</span> <span class="n">Alignment</span>
+<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span><span class="w"> </span><span class="nn">numpy</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">np</span>
+</pre></div>
+</div>
+<p>Consider the following reference and sequences:
+&gt;&gt;&gt; reference_str = “ACGT”
+&gt;&gt;&gt; seq1_str = “ACT”
+&gt;&gt;&gt; seq2_str = “ACGGT”
+&gt;&gt;&gt; seq3_str = “AT”</p>
+<p>To produce a pairwise alignment:
+&gt;&gt;&gt; aligner = PairwiseAligner()
+&gt;&gt;&gt; pwa = next(aligner.align(reference_str, seq1_str))</p>
+<p>To produce a three sequence alignment:
+&gt;&gt;&gt; coords = np.array([
+…     [0, 1, 2, 3, 3, 4],
+…     [0, 1, 2, 3, 4, 5],
+…     [0, 1, 1, 1, 1, 2]
+… ])</p>
+<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">not_pwa</span> <span class="o">=</span> <span class="n">Alignment</span><span class="p">([</span><span class="n">reference_str</span><span class="p">,</span> <span class="n">seq2_str</span><span class="p">,</span> <span class="n">seq3_str</span><span class="p">],</span> <span class="n">coords</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The pairwise alignment would look like
+&gt;&gt;&gt; print(f”Reference: {pwa[0]}”)
+Reference: ACGT
+&gt;&gt;&gt; print(f”Seq1:      {pwa[1]}”)
+Seq1:      AC-T</p>
+<p>The three sequence alignment would look like
+&gt;&gt;&gt; str(not_pwa[0])
+‘ACG-T’
+&gt;&gt;&gt; str(not_pwa[1])
+‘ACGGT’
+&gt;&gt;&gt; str(not_pwa[2])
+‘A—T’</p>
+<p>Now, we can combine these alignments into a multiple sequence alignment:
+&gt;&gt;&gt; msa = Alignment.from_alignments_with_same_reference([pwa, not_pwa])
+&gt;&gt;&gt; str(msa[0])
+‘ACG-T’
+&gt;&gt;&gt; str(msa[1])
+‘AC–T’
+&gt;&gt;&gt; str(msa[2])
+‘ACGGT’
+&gt;&gt;&gt; str(msa[3])
+‘A—T’</p>
+</dd>
+<dt>Example 2: Using SeqRecord Objects with Metadata</dt><dd><p>Consider the following reference and sequences with metadata:
+&gt;&gt;&gt; reference_seqr = SeqRecord(Seq(“ACGT”), id=”reference”, description=”desc 1”)
+&gt;&gt;&gt; seq1 = SeqRecord(Seq(“ACGGT”), id=”seq1”, description=”desc 2”)
+&gt;&gt;&gt; seq2 = SeqRecord(Seq(“AT”), id=”seq2”, description=”desc 3”)</p>
+<p>To produce pairwise alignments:
+&gt;&gt;&gt; aligner = PairwiseAligner()
+&gt;&gt;&gt; pwa1 = next(aligner.align(reference_seqr, seq1))
+&gt;&gt;&gt; pwa2 = next(aligner.align(reference_seqr, seq2))</p>
+<p>The msa retains the metadata from the original SeqRecord objects:
+&gt;&gt;&gt; msa = Alignment.from_alignments_with_same_reference([pwa1, pwa2])
+&gt;&gt;&gt; print(msa.format(“fasta”))
+&gt;reference desc 1
+ACG-T
+&gt;seq1 desc 2
+ACGGT
+&gt;seq2 desc 3
+A—T
+&lt;BLANKLINE&gt;</p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="Bio.Align.Alignment.__init__">
 <span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sequences</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">coordinates</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#Bio.Align.Alignment.__init__" title="Link to this definition"></a></dt>

dev/api/Bio.html

@@ -310,6 +310,7 @@ <h2>Subpackages<a class="headerlink" href="#subpackages" title="Link to this hea
 </li>
 <li class="toctree-l3"><a class="reference internal" href="Bio.Align.html#Bio.Align.Alignment"><code class="docutils literal notranslate"><span class="pre">Alignment</span></code></a><ul>
 <li class="toctree-l4"><a class="reference internal" href="Bio.Align.html#Bio.Align.Alignment.parse_printed_alignment"><code class="docutils literal notranslate"><span class="pre">Alignment.parse_printed_alignment()</span></code></a></li>
+<li class="toctree-l4"><a class="reference internal" href="Bio.Align.html#Bio.Align.Alignment.from_alignments_with_same_reference"><code class="docutils literal notranslate"><span class="pre">Alignment.from_alignments_with_same_reference()</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="Bio.Align.html#Bio.Align.Alignment.__init__"><code class="docutils literal notranslate"><span class="pre">Alignment.__init__()</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="Bio.Align.html#Bio.Align.Alignment.__array__"><code class="docutils literal notranslate"><span class="pre">Alignment.__array__()</span></code></a></li>
 <li class="toctree-l4"><a class="reference internal" href="Bio.Align.html#Bio.Align.Alignment.__add__"><code class="docutils literal notranslate"><span class="pre">Alignment.__add__()</span></code></a></li>

dev/genindex.html

@@ -6533,6 +6533,8 @@ <h2 id="F">F</h2>
       <li><a href="api/Bio.Align.html#Bio.Align.Alignment.frequencies">frequencies (Bio.Align.Alignment property)</a>
 </li>
       <li><a href="api/Bio.motifs.matrix.html#Bio.motifs.matrix.FrequencyPositionMatrix">FrequencyPositionMatrix (class in Bio.motifs.matrix)</a>
+</li>
+      <li><a href="api/Bio.Align.html#Bio.Align.Alignment.from_alignments_with_same_reference">from_alignments_with_same_reference() (Bio.Align.Alignment class method)</a>
 </li>
       <li><a href="api/Bio.Align.bigbed.html#Bio.Align.bigbed.AutoSQLTable.from_bytes">from_bytes() (Bio.Align.bigbed.AutoSQLTable class method)</a>
 </li>