include long description in DFE catalog entries

docs/_ext/speciescatalog.py

@@ -513,6 +513,7 @@ def dfe_section(self, species, dfe):
         section = nodes.section(ids=[dfe_id])
         section += nodes.title(text=dfe.id)
         section += nodes.paragraph(text=dfe.description)
+        section += nodes.paragraph(text=dfe.long_description)
         section += nodes.rubric(text="Citations")
         section += self.citation_list(dfe)
         section += nodes.rubric(text="DFE parameters")

stdpopsim/catalog/DroMel/dfes.py

@@ -13,12 +13,12 @@ def _HuberDFE():
     id = "Gamma_H17"
     description = "Deleterious Gamma DFE"
     long_description = """
-    Return neutral and negative MutationType()s representing a drosophila DFE.
-    Huber et al. (2017), https://doi.org/10.1073/pnas.1619508114.
-    DFE parameters are based on the Full model described in Table S2, in which
-    singletons are excluded and a recent mutation rate estimate is used
-    (mu=3x10e-9, Keightley 2014).
+    Deleterious, gamma-distributed DFE estimated from a D. melanogaster SFS in
+    Huber et al. (2017).  DFE parameters are based on the "full" model
+    described in Table S2, for which singletons were excluded and a recent
+    mutation rate estimate is used (3e-9, Keightley 2014).
     """
+    # https://doi.org/10.1073/pnas.1619508114
     citations = [
         stdpopsim.Citation(
             author="Huber et al.",
@@ -54,19 +54,23 @@ def _RagsdaleDFE():
     id = "LognormalPlusPositive_R16"
     description = "Deleterious log-normal and beneficial mixed DFE"
     long_description = """
-    Return deleterious and beneficial MutationType()s representing a drosophila DFE
-    from Ragsdale et al. (2016), https://doi.org/10.1534/genetics.115.184812.
-    DFE parameters are given in Table S1, with deleterious mutations drawn from a
-    log-normal distribution and a point mass of positive selection. The DFE was
-    inferred assuming synonymous variants are neutral and a relative mutation
-    rate ratio of 2.5 nonsynonymous to 1 synonymous mutation. Results are given as
-    scaled parameters, so that S = 2*N*s, so an estimate of Ne is required to
-    convert the scaled selection coefficients to unscaled coefficients. Because the
-    original study did not report an estimated effective population size, we use
-    the estimate from Huber et al. (2017) of Ne=2.8e6, which was estimated from
-    observed genome-wide synonymous mutation diversity and assuming a mutation rate
-    of 3e-9.
+    Estimated DFE containing deleterious and beneficial mutations, estimated
+    by Ragsdale et al. (2016), with a log-normal distribution for deleterious
+    mutations and a single selection coefficient for positive mutations.  The
+    DFE was inferred in scaled units from the triallelic frequency spectrum in
+    D. melanogaster, here scaled to real units using an effective population
+    size of Ne=2.8e6 (Huber et al 2017).
     """
+    # DFE parameters are given in Table S1, with deleterious mutations drawn from a
+    # log-normal distribution and a point mass of positive selection.
+    # Uses only nonsynonymous changes, and assumes a ratio of 2.5 nonsynonymous
+    # to 1 synonymous mutation. Results are given as scaled parameters, so that
+    # S = 2*N*s, so an estimate of Ne is required to convert the scaled
+    # selection coefficients to unscaled coefficients. Because the original
+    # study did not report an estimated effective population size, we use the
+    # estimate from Huber et al. (2017) of Ne=2.8e6, which was estimated from
+    # observed genome-wide synonymous mutation diversity and assuming a
+    # mutation rate of 3e-9.
     citations = [
         stdpopsim.Citation(
             author="Ragsdale et al.",

stdpopsim/catalog/HomSap/dfes.py

@@ -14,14 +14,14 @@ def _KimDFE():
     id = "Gamma_K17"
     description = "Deleterious Gamma DFE"
     long_description = """
-    Return neutral and negative MutationType()s representing a human DFE.
-    Kim et al. (2017), https://doi.org/10.1534/genetics.116.197145
-    The DFE was inferred assuming synonymous variants are neutral and a relative
-    mutation rate ratio of 2.31 nonsynonymous to 1 synonymous mutation
-    (Huber et al. 2016). Gamma parameters are given as the shape and the mean
-    selection coefficient (E[s]) escaled, such that E[s] = -shape*scale*2/(2Na),
-    where Na is the ancestral population size (12378) as in Kim et al. (2017).
+    Deleterious, gamma-distributed DFE estimated using 'Fit∂a∂i' from the nonsynonymous
+    SFS in exons from a dataset of European humans by Kim et al. (2017).
     """
+    # The DFE was inferred assuming synonymous variants are neutral and a relative
+    # mutation rate ratio of 2.31 nonsynonymous to 1 synonymous mutation
+    # (Huber et al. 2016). Gamma parameters are given as the shape and the mean
+    # selection coefficient (E[s]) escaled, such that E[s] = -shape*scale*2/(2Na),
+    # where Na is the ancestral population size (12378) as in Kim et al. (2017).
     citations = [
         stdpopsim.Citation(
             author="Kim et al.",
@@ -62,11 +62,12 @@ def _HuberDFE():
     id = "Gamma_H17"
     description = "Deleterious Gamma DFE"
     long_description = """
-    Return neutral and negative MutationType()s representing a Homo sapiens DFE.
-    Huber et al. (2017), https://doi.org/10.1073/pnas.1619508114.
-    DFE parameters are based on the Full Model described in Table S2, in which
-    All Data (none of the listed filters) were used.
-    """  # [this was a different filtering scheme than the Huber et al DroMel DFE ]
+    Deleterious, gamma-distributed DFE estimated from the SFS of YRI samples in
+    the 1000 genomes project by Huber et al. (2017). DFE parameters are from
+    the "full" model in Table S2, in which all data (none of the listed
+    filters) were used.
+    """
+    # [this was a different filtering scheme than the Huber et al DroMel DFE ]
     citations = [
         stdpopsim.Citation(
             author="Huber et al.",
@@ -109,19 +110,16 @@ def _HuberLogNormalDFE():
     id = "LogNormal_H17"
     description = "Deleterious Log-normal DFE"
     long_description = """
-    Return neutral and negative MutationType()s representing a human DFE.
-    Huber et al. (2017), https://doi.org/10.1073/pnas.1619508114.
-    DFE parameters are based off the Full model in Table S3, Using recent
-    mutation rate estimates.
-    Log-normal distribution parameters were given as the
-    mean and standard deviation of the log.
+    Deleterious, log-normal-distributed DFE estimated from the SFS of YRI
+    samples in the 1000 genomes project by Huber et al. (2017).
+    Parameters as shown for the "full" model in Table S3.
     """
     citations = [
         stdpopsim.Citation(
             author="Huber et al.",
             year=2017,
             doi="https://doi.org/10.1073/pnas.1619508114",
-            reasons={stdpopsim.CiteReason.DFE},  # include the dfe_model reason
+            reasons={stdpopsim.CiteReason.DFE},
         )
     ]
     neutral = stdpopsim.MutationType()
@@ -153,13 +151,12 @@ def _KyriazisDFE():
     id = "Mixed_K23"
     description = "Deleterious Gamma DFE with additional lethals"
     long_description = """
-    The DFE estimated from human data recommended in Kyriazis et al.
-    (2023), https://doi.org/10.1086/726736, for general use.
-    This model is similar to the Kim et al. (2017) DFE based on human
-    genetic data, modified to include the dominance distribution from
-    Henn et al. (2016).
-    The model is also augmented with an additional proportion of 0.3% of
-    recessive lethals, based on the analysis of Wade et al. (2023).
+    The DFE estimated from human data recommended in Kyriazis et al.  (2023),
+    for general use.  This model is similar to the Kim et al. (2017) DFE based
+    on human genetic data, modified to include the dominance distribution from
+    Henn et al. (2016).  The model is also augmented with an additional
+    proportion of 0.3% of recessive lethals, based on the analysis of
+    Wade et al. (2023).
     """
     citations = [
         stdpopsim.Citation(

stdpopsim/catalog/MusMus/dfes.py

@@ -13,19 +13,16 @@ def _BookerDFE():
     id = "Gamma_B21"
     description = "Deleterious Gamma DFE CDS"
     long_description = """
-    Return negative MutationType()s representing a Mus
-    musculus subsp. castaneous DFE for protein coded exons or CDS. Booker et al. (2021),
-    https://doi.org/10.1101/2021.06.10.447924
-    DFE parameters are based on an analysis of the unfolded site frequency spectrum
-    (uSFS) using polyDFE v2 (Tataru and Bataillon 2019) as presented in Booker
-    et al. (2021).
+    A gamma-distributed DFE for deleterious mutations estimated from the SFS of
+    Mus musculus castaneous exons by Booker et al. (2021), using polyDFE v2
+    (Tataru and Bataillon 2019).
     """
     citations = [
         stdpopsim.Citation(
             author="Booker et al.",
             year=2021,
             doi="https://doi.org/10.1101/2021.06.10.447924",
-            reasons={stdpopsim.CiteReason.DFE},  # include the dfe_model reason
+            reasons={stdpopsim.CiteReason.DFE},
         )
     ]
     neutral = stdpopsim.MutationType()

stdpopsim/catalog/PhoSin/dfes.py

@@ -13,16 +13,15 @@ def _RobinsonDFE():
     id = "Gamma_R22"
     description = "Deleterious Gamma DFE"
     long_description = """
-    Vaquita DFE inferred by Robinson et al. (2022), and used in simulations.
-    The DFE was inferred assuming synonymous variants are neutral and a relative
-    mutation rate ratio of 2.31 nonsynonymous to 1 synonymous mutation
-    (Huber et al. 2017). The inference procedure is described in pages 9-10 of
-    the supplementary material of Robinson et al. (2022), and values used in
-    SLiM simulations based on this DFE are specified in pages 11-12.
-    Supplement URL:
-    https://www.ncbi.nlm.nih.gov/pmc/articles/PMC9881057/
-    bin/NIHMS1864134-supplement-Supplementary_material.pdf
+    Gamma-distributed deleterious DFE inferred by Robinson et al. (2022),
+    and used in their simulations, from the synonymous and nonsynonymous SFS from
+    Vaquita data, following the methods of Huber et al (2017).
     """
+    # The DFE was inferred assuming synonymous variants are neutral and a relative
+    # mutation rate ratio of 2.31 nonsynonymous to 1 synonymous mutation
+    # (Huber et al. 2017). The inference procedure is described in pages 9-10 of
+    # the supplementary material of Robinson et al. (2022), and values used in
+    # SLiM simulations based on this DFE are specified in pages 11-12.
     citations = [
         stdpopsim.Citation(
             author="Robinson et al.",