added explanation for recombination rate and fixed issues in docs

popsim-consortium · Sep 14, 2023 · a2091db · a2091db
1 parent 5464292
commit a2091db
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 11 deletions.
diff --git a/docs/introduction.rst b/docs/introduction.rst
@@ -94,7 +94,7 @@ major additions to the catalog:
 
 Bibtex records::
 
-@article {10.7554/eLife.54967,
+    @article {10.7554/eLife.54967,
         article_type = {journal},
         title = {A community-maintained standard library of population genetic models},
         author = {Adrion, Jeffrey R and Cole, Christopher B and Dukler, Noah and Galloway, Jared
@@ -121,7 +121,7 @@ Bibtex records::
         publisher = {eLife Sciences Publications, Ltd},
     }
 
-@article{10.7554/eLife.84874.2,
+    @article{10.7554/eLife.84874.2,
         title={Expanding the stdpopsim species catalog, and lessons learned for realistic genome simulations},
 	author = {M. Elise Lauterbur and Maria Izabel A. Cavassim and Ariella L. Gladstein and Graham Gower and
            Nathaniel S. Pope and Georgia Tsambos and Jeff Adrion and Saurabh Belsare and Arjun Biddanda and

diff --git a/stdpopsim/catalog/PhoSin/species.py b/stdpopsim/catalog/PhoSin/species.py
@@ -28,11 +28,17 @@
     "X": _species_ploidy,
 }
 
-# There is no good justificaiton for this value for now.
-# We're using the value of 1e-8, which appears to be what
-# Morin et al. (2021) used in their PSMC analysis
-# (the default value), but I'm not sure, and this is not
-# well justified
+##########################
+# There is no direct estimate of recombination rate
+# for Vaquita or any closely related species.
+# Other studies that simulate data for Vaquita assume
+# a default mutation rate of 1e-8, which is what we
+# use here.
+# For example, Morin et al. (2021) assume a recombination
+# rate of 1e-8 when running PSMC, and Robinson et al. (2022)
+# use a recombination rate of 1e-8 when simulating data using
+# SLiM.
+##########################
 _overall_recombination_rate = 1e-8
 _recombination_rate = {
     "1": _overall_recombination_rate,
@@ -59,6 +65,7 @@
     "X": _overall_recombination_rate,
 }
 
+##########################
 # Genome-wide average mutation rate is estimated by Robinson et al. (2022)
 # by using divergence from two closely related species: harbor porpoise
 # (Phocoena phocoena) and Indo-Pacific finless porpoise (Neophocaena phocaenoides).
@@ -67,8 +74,8 @@
 # Eventually, the representative value used in most analyses in the paper was
 # 5.83e-9, which is on the high side of the range, to take into account previous
 # higher estimates of the mutation rate, cited by Morin et al. (2021).
+##########################
 _overall_mutation_rate = 5.83e-9
-
 _mutation_rate = {
     "1": _overall_mutation_rate,
     "2": _overall_mutation_rate,
@@ -99,9 +106,6 @@
     recombination_rate=_recombination_rate,
     mutation_rate=_mutation_rate,
     ploidy=_ploidy,
-    # [ Implementers: please insert citations for the papers you are basing
-    # the estimates for recombination and mutation rates. The assembly
-    # citation is optional and can be deleted if not needed.]
     citations=[
         stdpopsim.Citation(
             author="Morin et al.",
@@ -115,6 +119,12 @@
             doi="https://doi.org/10.1111/1755-0998.13284",
             reasons={stdpopsim.CiteReason.REC_RATE},
         ),
+        stdpopsim.Citation(
+            author="Morin et al.",
+            year=2021,
+            doi="https://doi.org/10.1111/1755-0998.13284",
+            reasons={stdpopsim.CiteReason.REC_RATE},
+        ),
         stdpopsim.Citation(
             author="Robinson et al.",
             year=2022,
@@ -130,6 +140,7 @@
     name="Phocoena sinus",
     common_name="Vaquita",
     genome=_genome,
+    ##########################
     # Robinson et al. (2022) and Morin et al. (2021) assumed an average
     # generation time of 11.9 years in their analyses/calibrations.
     # They cite Taylor et al. (2007) as a primary source.
@@ -138,13 +149,16 @@
     # the one inferred for the sister species of harbor porpoise (Phocoena
     # phocoena). The value estimated for Vaquita is slightly smaller (11.4),
     # but maybe it reflects a recent reducion in generation time (???)
+    ##########################
     generation_time=11.9,
+    ##########################
     # Demographic models inferred for Vaquita by Morin et al. (2021) and
     # Robinson et al. (2022) typically estimate small Ne of 2,000 - 5,000
     # in the past 500,000 years, likely followed by some sharp bottleneck.
     # We selected as a representative Ne a value of 3500, which is also
     # consistent with the average Ne inferred in the 2-epoch model of
     # Robinson et al. (2022)
+    ##########################
     population_size=3500,
     citations=[
         stdpopsim.Citation(