Automated doc build for refs/heads/main

main/_modules/stdpopsim/slim_engine.html

@@ -1005,7 +1005,7 @@ <h1>Source code for stdpopsim.slim_engine</h1><div class="highlight"><pre>
         <span class="n">extended_events</span> <span class="o">=</span> <span class="n">copy</span><span class="o">.</span><span class="n">deepcopy</span><span class="p">(</span><span class="n">extended_events</span><span class="p">)</span>
 
     <span class="c1"># Reassign event times according to integral SLiM ticks.</span>
-    <span class="c1"># This collapses the time deltas used in HomSap/AmericanAdmixture_4B11,</span>
+    <span class="c1"># This collapses the time deltas used in HomSap/AmericanAdmixture_4B18,</span>
     <span class="c1"># and calculates times for GenerationAfter objects.</span>
     <span class="k">def</span> <span class="nf">fix_time</span><span class="p">(</span><span class="n">event</span><span class="p">):</span>
         <span class="k">for</span> <span class="n">attr</span> <span class="ow">in</span> <span class="p">(</span><span class="s2">&quot;time&quot;</span><span class="p">,</span> <span class="s2">&quot;start_time&quot;</span><span class="p">,</span> <span class="s2">&quot;end_time&quot;</span><span class="p">):</span>

main/_modules/stdpopsim/species.html

@@ -82,6 +82,7 @@ <h1>Source code for stdpopsim.species</h1><div class="highlight"><pre>
 <span class="sd">&quot;&quot;&quot;</span>
 
 <span class="kn">import</span> <span class="nn">logging</span>
+<span class="kn">import</span> <span class="nn">warnings</span>
 
 <span class="kn">import</span> <span class="nn">attr</span>
 
@@ -335,6 +336,17 @@ <h1>Source code for stdpopsim.species</h1><div class="highlight"><pre>
             <span class="n">right</span><span class="o">=</span><span class="n">right</span><span class="p">,</span>
         <span class="p">)</span></div>
 
+    <span class="k">def</span> <span class="nf">_warn_browning</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">model_id</span><span class="p">):</span>
+        <span class="k">if</span> <span class="n">model_id</span> <span class="o">==</span> <span class="s2">&quot;AmericanAdmixture_4B11&quot;</span><span class="p">:</span>
+            <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span>
+                <span class="s2">&quot;In stdpopsim &lt;= 0.2.1, the AmericanAdmixture_4B18 model &quot;</span>
+                <span class="s2">&quot;was named AmericanAdmixture_4B11; but since it comes &quot;</span>
+                <span class="s2">&quot;from a 2018 paper, this is corrected. The model name &quot;</span>
+                <span class="s2">&quot;AmericanAdmixture_4B11 will work for now but is deprecated.&quot;</span>
+            <span class="p">)</span>
+            <span class="n">model_id</span> <span class="o">=</span> <span class="s2">&quot;AmericanAdmixture_4B18&quot;</span>
+        <span class="k">return</span> <span class="n">model_id</span>
+
 <div class="viewcode-block" id="Species.get_demographic_model"><a class="viewcode-back" href="../../api.html#stdpopsim.Species.get_demographic_model">[docs]</a>    <span class="k">def</span> <span class="nf">get_demographic_model</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Returns a demographic model with the specified ``id``.</span>
@@ -346,6 +358,8 @@ <h1>Source code for stdpopsim.species</h1><div class="highlight"><pre>
 <span class="sd">        :rtype: :class:`DemographicModel`</span>
 <span class="sd">        :return: A :class:`DemographicModel` that defines the requested model.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
+        <span class="c1"># TODO: remove this after a release or two. See #841.</span>
+        <span class="nb">id</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_warn_browning</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
         <span class="k">for</span> <span class="n">model</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">demographic_models</span><span class="p">:</span>
             <span class="k">if</span> <span class="n">model</span><span class="o">.</span><span class="n">id</span> <span class="o">==</span> <span class="nb">id</span><span class="p">:</span>
                 <span class="k">return</span> <span class="n">model</span>

main/_sources/tutorial.rst.txt

@@ -475,7 +475,7 @@ demographic models are available for humans:
    # OutOfAfrica_3G09
    # OutOfAfrica_2T12
    # Africa_1T12
-   # AmericanAdmixture_4B11
+   # AmericanAdmixture_4B18
    # OutOfAfricaArchaicAdmixture_5R19
    # Zigzag_1S14
    # AncientEurasia_9K19
@@ -1557,8 +1557,8 @@ This prints detailed information about all of the available models to
 the terminal.
 In this tutorial, we will use the model of African-American admixture from
 `Browning et al. (2018) <http://dx.doi.org/10.1371/journal.pgen.1007385>`_.
-From the help output (or the :ref:`Catalog <sec_catalog_homsap_models_americanadmixture_4b11>`),
-we can see that this model has id ``AmericanAdmixture_4B11``,
+From the help output (or the :ref:`Catalog <sec_catalog_homsap_models_americanadmixture_4b18>`),
+we can see that this model has id ``AmericanAdmixture_4B18``,
 and allows samples to be drawn from 4 contemporary populations representing African,
 European, Asian and African-American groups.
 
@@ -1577,7 +1577,7 @@ To check that we have set up the simulation correctly, we may first wish to perf
 dry run using the ``-D`` option.
 This will print information about the simulation to the terminal:
 
-.. command-output:: stdpopsim HomSap -c chr1 -o afr-america-chr1.trees -s 13 -g HapMapII_GRCh38 -d AmericanAdmixture_4B11 AFR:2 EUR:2 ASIA:2 ADMIX:2 -D
+.. command-output:: stdpopsim HomSap -c chr1 -o afr-america-chr1.trees -s 13 -g HapMapII_GRCh38 -d AmericanAdmixture_4B18 AFR:2 EUR:2 ASIA:2 ADMIX:2 -D
     :ellipsis: 18
 
 Once we're sure, we can remove the ``-D`` flag to run the simulation
@@ -1586,7 +1586,7 @@ Once we're sure, we can remove the ``-D`` flag to run the simulation
 .. code-block:: console
 
     $ stdpopsim HomSap -c chr1 -o afr-america-chr1.trees -s 13 -g HapMapII_GRCh38 \
-    $    -d AmericanAdmixture_4B11 AFR:2 EUR:2 ASIA:2 ADMIX:2
+    $    -d AmericanAdmixture_4B18 AFR:2 EUR:2 ASIA:2 ADMIX:2
 
 2. Calculating divergences
 --------------------------

main/catalog.html

@@ -214,7 +214,7 @@
 <li class="toctree-l4"><a class="reference internal" href="#sec_catalog_homsap_models_outofafrica_3g09">Three population out-of-Africa</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#sec_catalog_homsap_models_outofafrica_2t12">Two population out-of-Africa</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#sec_catalog_homsap_models_africa_1t12">African population</a></li>
-<li class="toctree-l4"><a class="reference internal" href="#sec_catalog_homsap_models_americanadmixture_4b11">American admixture</a></li>
+<li class="toctree-l4"><a class="reference internal" href="#sec_catalog_homsap_models_americanadmixture_4b18">American admixture</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#sec_catalog_homsap_models_outofafricaarchaicadmixture_5r19">Three population out-of-Africa with archaic admixture</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#sec_catalog_homsap_models_zigzag_1s14">Periodic growth and decline.</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#sec_catalog_homsap_models_ancienteurasia_9k19">Multi-population model of ancient Eurasia</a></li>
@@ -5776,7 +5776,7 @@ <h3>Genome<a class="headerlink" href="#sec_catalog_HomSap_genome" title="Permali
 <tr class="row-odd"><td><p><a class="reference internal" href="#sec_catalog_homsap_models_africa_1t12">Africa_1T12</a></p></td>
 <td><p>African population</p></td>
 </tr>
-<tr class="row-even"><td><p><a class="reference internal" href="#sec_catalog_homsap_models_americanadmixture_4b11">AmericanAdmixture_4B11</a></p></td>
+<tr class="row-even"><td><p><a class="reference internal" href="#sec_catalog_homsap_models_americanadmixture_4b18">AmericanAdmixture_4B18</a></p></td>
 <td><p>American admixture</p></td>
 </tr>
 <tr class="row-odd"><td><p><a class="reference internal" href="#sec_catalog_homsap_models_outofafricaarchaicadmixture_5r19">OutOfAfricaArchaicAdmixture_5R19</a></p></td>
@@ -6265,8 +6265,8 @@ <h3>Genome<a class="headerlink" href="#sec_catalog_HomSap_genome" title="Permali
 </section>
 <img alt="_images/sec_catalog_homsap_models_africa_1t12.png" src="_images/sec_catalog_homsap_models_africa_1t12.png" />
 <hr class="docutils" />
-<section id="sec_catalog_homsap_models_americanadmixture_4b11">
-<span id="sec_catalog_homsap_models_americanadmixture_4b11"></span><h4>American admixture<a class="headerlink" href="#sec_catalog_homsap_models_americanadmixture_4b11" title="Permalink to this heading"></a></h4>
+<section id="sec_catalog_homsap_models_americanadmixture_4b18">
+<span id="sec_catalog_homsap_models_americanadmixture_4b18"></span><h4>American admixture<a class="headerlink" href="#sec_catalog_homsap_models_americanadmixture_4b18" title="Permalink to this heading"></a></h4>
 <p>
         Demographic model for American admixture, taken from Browning et al. 2018.
         This model extends the Gravel et al. (2011) model of African/European/Asian
@@ -6281,7 +6281,7 @@ <h3>Genome<a class="headerlink" href="#sec_catalog_HomSap_genome" title="Permali
 <p class="rubric">Details</p>
 <dl class="field-list simple">
 <dt class="field-odd">ID<span class="colon">:</span></dt>
-<dd class="field-odd"><p>AmericanAdmixture_4B11</p>
+<dd class="field-odd"><p>AmericanAdmixture_4B18</p>
 </dd>
 <dt class="field-even">Description<span class="colon">:</span></dt>
 <dd class="field-even"><p>American admixture</p>
@@ -6427,7 +6427,7 @@ <h3>Genome<a class="headerlink" href="#sec_catalog_HomSap_genome" title="Permali
 </tbody>
 </table>
 </section>
-<img alt="_images/sec_catalog_homsap_models_americanadmixture_4b11.png" src="_images/sec_catalog_homsap_models_americanadmixture_4b11.png" />
+<img alt="_images/sec_catalog_homsap_models_americanadmixture_4b18.png" src="_images/sec_catalog_homsap_models_americanadmixture_4b18.png" />
 <hr class="docutils" />
 <section id="sec_catalog_homsap_models_outofafricaarchaicadmixture_5r19">
 <span id="sec_catalog_homsap_models_outofafricaarchaicadmixture_5r19"></span><h4>Three population out-of-Africa with archaic admixture<a class="headerlink" href="#sec_catalog_homsap_models_outofafricaarchaicadmixture_5r19" title="Permalink to this heading"></a></h4>

main/changelogs.html

@@ -98,6 +98,9 @@ <h2>[0.2.1a] - 2024-07-06<a class="headerlink" href="#a-2024-07-06" title="Perma
 </ul>
 <p><strong>Breaking changes</strong>:</p>
 <ul class="simple">
+<li><p>The 2018 Browning et al HomSap demographic model previously named
+“AmericanAdmixture_4B11” is now named “AmericanAdmixture_4B18”; the old name
+works but throws a deprecation warning. (<a class="reference external" href="https://github.com/petrelharp">&#64;petrelharp</a>, <a class="reference external" href="https://github.com/popsim-consortium/stdpopsim/pull/1603">#1603</a>)</p></li>
 <li><dl class="simple">
 <dt>The <cite>time_units</cite> attribute of tree sequence metadata is now set to “generations”</dt><dd><p>for SLiM output, avoiding the “time units mismatch warning”.
 (<a class="reference external" href="https://github.com/nspope">&#64;nspope</a>, <a class="reference external" href="https://github.com/popsim-consortium/stdpopsim/pull/1567">#1567</a>)</p>

main/cli_arguments.html

@@ -1866,8 +1866,8 @@ <h4>Named Arguments<a class="headerlink" href="#named-arguments_repeat17" title=
 <p>Default: False</p>
 </dd>
 <dt><kbd>-d, --demographic-model</kbd></dt>
-<dd><p>Possible choices: OutOfAfricaExtendedNeandertalAdmixturePulse_3I21, OutOfAfrica_3G09, OutOfAfrica_2T12, Africa_1T12, AmericanAdmixture_4B11, OutOfAfricaArchaicAdmixture_5R19, Zigzag_1S14, AncientEurasia_9K19, PapuansOutOfAfrica_10J19, AshkSub_7G19, OutOfAfrica_4J17, Africa_1B08, AncientEurope_4A21</p>
-<p>Specify a simulation model. If no model is specified, a single population constant size model is used. Available models: OutOfAfricaExtendedNeandertalAdmixturePulse_3I21, OutOfAfrica_3G09, OutOfAfrica_2T12, Africa_1T12, AmericanAdmixture_4B11, OutOfAfricaArchaicAdmixture_5R19, Zigzag_1S14, AncientEurasia_9K19, PapuansOutOfAfrica_10J19, AshkSub_7G19, OutOfAfrica_4J17, Africa_1B08, AncientEurope_4A21. Please see –help-models for details of these models.</p>
+<dd><p>Possible choices: OutOfAfricaExtendedNeandertalAdmixturePulse_3I21, OutOfAfrica_3G09, OutOfAfrica_2T12, Africa_1T12, AmericanAdmixture_4B18, OutOfAfricaArchaicAdmixture_5R19, Zigzag_1S14, AncientEurasia_9K19, PapuansOutOfAfrica_10J19, AshkSub_7G19, OutOfAfrica_4J17, Africa_1B08, AncientEurope_4A21</p>
+<p>Specify a simulation model. If no model is specified, a single population constant size model is used. Available models: OutOfAfricaExtendedNeandertalAdmixturePulse_3I21, OutOfAfrica_3G09, OutOfAfrica_2T12, Africa_1T12, AmericanAdmixture_4B18, OutOfAfricaArchaicAdmixture_5R19, Zigzag_1S14, AncientEurasia_9K19, PapuansOutOfAfrica_10J19, AshkSub_7G19, OutOfAfrica_4J17, Africa_1B08, AncientEurope_4A21. Please see –help-models for details of these models.</p>
 </dd>
 <dt><kbd>--dfe</kbd></dt>
 <dd><p>Possible choices: Gamma_K17, Gamma_H17, LogNormal_H17, Mixed_K23</p>

main/tutorial.html

@@ -324,7 +324,7 @@ <h4>Choose a model and a sampling scheme<a class="headerlink" href="#choose-a-mo
     Populations:
         AFR: African
 
-AmericanAdmixture_4B11: American admixture
+AmericanAdmixture_4B18: American admixture
      Demographic model for American admixture, taken from Browning et
     al. 2018. This model extends the Gravel et al. (2011) model of
     African/European/Asian demographic history to simulate an admixed
@@ -652,7 +652,7 @@ <h4>Pick a species and demographic model<a class="headerlink" href="#pick-a-spec
 <span class="c1"># OutOfAfrica_3G09</span>
 <span class="c1"># OutOfAfrica_2T12</span>
 <span class="c1"># Africa_1T12</span>
-<span class="c1"># AmericanAdmixture_4B11</span>
+<span class="c1"># AmericanAdmixture_4B18</span>
 <span class="c1"># OutOfAfricaArchaicAdmixture_5R19</span>
 <span class="c1"># Zigzag_1S14</span>
 <span class="c1"># AncientEurasia_9K19</span>
@@ -1602,8 +1602,8 @@ <h4>1. Simulating the dataset<a class="headerlink" href="#simulating-the-dataset
 the terminal.
 In this tutorial, we will use the model of African-American admixture from
 <a class="reference external" href="http://dx.doi.org/10.1371/journal.pgen.1007385">Browning et al. (2018)</a>.
-From the help output (or the <a class="reference internal" href="catalog.html#sec_catalog_homsap_models_americanadmixture_4b11"><span class="std std-ref">Catalog</span></a>),
-we can see that this model has id <code class="docutils literal notranslate"><span class="pre">AmericanAdmixture_4B11</span></code>,
+From the help output (or the <a class="reference internal" href="catalog.html#sec_catalog_homsap_models_americanadmixture_4b18"><span class="std std-ref">Catalog</span></a>),
+we can see that this model has id <code class="docutils literal notranslate"><span class="pre">AmericanAdmixture_4B18</span></code>,
 and allows samples to be drawn from 4 contemporary populations representing African,
 European, Asian and African-American groups.</p>
 <p>Using the <code class="docutils literal notranslate"><span class="pre">--help-genetic-maps</span></code> option, we can also see what genetic maps
@@ -1640,10 +1640,10 @@ <h4>1. Simulating the dataset<a class="headerlink" href="#simulating-the-dataset
 To check that we have set up the simulation correctly, we may first wish to perform a
 dry run using the <code class="docutils literal notranslate"><span class="pre">-D</span></code> option.
 This will print information about the simulation to the terminal:</p>
-<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ stdpopsim HomSap -c chr1 -o afr-america-chr1.trees -s 13 -g HapMapII_GRCh38 -d AmericanAdmixture_4B11 AFR:2 EUR:2 ASIA:2 ADMIX:2 -D
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>$ stdpopsim HomSap -c chr1 -o afr-america-chr1.trees -s 13 -g HapMapII_GRCh38 -d AmericanAdmixture_4B18 AFR:2 EUR:2 ASIA:2 ADMIX:2 -D
 Simulation information:
     Engine: msprime (1.3.3)
-    Model id: AmericanAdmixture_4B11
+    Model id: AmericanAdmixture_4B18
     Model description: American admixture
     Seed: 13
     Population: number_samples (sampling_time_generations):
@@ -1665,7 +1665,7 @@ <h4>1. Simulating the dataset<a class="headerlink" href="#simulating-the-dataset
 <p>Once we’re sure, we can remove the <code class="docutils literal notranslate"><span class="pre">-D</span></code> flag to run the simulation
 (this took around 8 minutes to run on a laptop).</p>
 <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>stdpopsim<span class="w"> </span>HomSap<span class="w"> </span>-c<span class="w"> </span>chr1<span class="w"> </span>-o<span class="w"> </span>afr-america-chr1.trees<span class="w"> </span>-s<span class="w"> </span><span class="m">13</span><span class="w"> </span>-g<span class="w"> </span>HapMapII_GRCh38<span class="w"> </span><span class="se">\</span>
-<span class="gp">$    </span>-d<span class="w"> </span>AmericanAdmixture_4B11<span class="w"> </span>AFR:2<span class="w"> </span>EUR:2<span class="w"> </span>ASIA:2<span class="w"> </span>ADMIX:2
+<span class="gp">$    </span>-d<span class="w"> </span>AmericanAdmixture_4B18<span class="w"> </span>AFR:2<span class="w"> </span>EUR:2<span class="w"> </span>ASIA:2<span class="w"> </span>ADMIX:2
 </pre></div>
 </div>
 </section>