add docs for using DFEs in other species: closes #1495 (and, makes ca…

…talog sections referenceable)

docs/_ext/speciescatalog.py

@@ -565,7 +565,7 @@ def run(self):
         # species:
         species = stdpopsim.get_species(self.arguments[0])
         sid = f"sec_catalog_{species.id}"
-        species_target = self.get_target(sid)
+        species_target = self.get_target(sid.lower())
         section = nodes.section(ids=[sid], names=[sid])
         section += nodes.title(text=species.name)
         section += self.species_summary(species)
@@ -606,40 +606,48 @@ def run(self):
         section += nodes.transition()
         # genetic maps:
         if len(species.genetic_maps) > 0:
-            maps_section = nodes.section(ids=[f"sec_catalog_{species.id}_genetic_maps"])
+            map_id = f"sec_catalog_{species.id}_genetic_maps"
+            maps_section = nodes.section(ids=[map_id])
             maps_section += nodes.title(text="Genetic Maps")
             maps_section += self.genetic_maps_table(species)
             for gmap in species.genetic_maps:
                 maps_section += self.genetic_map_section(species, gmap)
+            section += self.get_target(map_id.lower())
             section += maps_section
             section += nodes.transition()
         # demographic models:
         if len(species.demographic_models) > 0:
-            models_section = nodes.section(ids=[f"sec_catalog_{species.id}_models"])
+            map_id = f"sec_catalog_{species.id}_models"
+            models_section = nodes.section(ids=[map_id])
             models_section += nodes.title(text="Demographic Models")
             models_section += self.models_table(species)
             for i, model in enumerate(species.demographic_models):
                 models_section += self.model_section(species, model)
                 models_section += self.model_image(species, model)
                 if i < len(species.demographic_models) - 1:
                     models_section += nodes.transition()
+            section += self.get_target(map_id.lower())
             section += models_section
         # annotation:
         if len(species.annotations) > 0:
-            annot_section = nodes.section(ids=[f"sec_catalog_{species.id}_annotations"])
+            map_id = f"sec_catalog_{species.id}_annotations"
+            annot_section = nodes.section(ids=[map_id])
             annot_section += nodes.title(text="Annotations")
             annot_section += self.annotation_table(species)
             for an in species.annotations:
                 annot_section += self.annotation_section(species, an)
+            section += self.get_target(map_id.lower())
             section += annot_section
             section += nodes.transition()
         # DFE:
         if len(species.dfes) > 0:
-            dfes_section = nodes.section(ids=[f"sec_catalog_{species.id}_dfe"])
+            map_id = f"sec_catalog_{species.id}_dfe"
+            dfes_section = nodes.section(ids=[map_id])
             dfes_section += nodes.title(text="Distribution of Fitness Effects (DFEs)")
             dfes_section += self.dfes_table(species)
             for i, dfe in enumerate(species.dfes):
                 dfes_section += self.dfe_section(species, dfe)
+            section += self.get_target(map_id.lower())
             section += dfes_section
             section += nodes.transition()
         return [species_target, section]

docs/conf.py

@@ -197,7 +197,7 @@
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    "https://docs.python.org/": None,
+    "python": ("https://docs.python.org/3", None),
     "tskit": ("https://tskit.dev/tskit/docs/stable", None),
     "msprime": ("https://tskit.dev/msprime/docs/stable", None),
     "pyslim": ("https://tskit.dev/pyslim/docs/latest", None),

docs/tutorial.rst

@@ -1379,6 +1379,57 @@ We can see that diversity is substantially reduced around the beneficial
 mutation (vertical dashed line), relative to what would be expected under
 neutrality.
 
+.. _sec_tute_moving_dfes:
+
+5.  Using a DFE from one species in another species
+---------------------------------------------------
+
+There are not very many empirically estimated DFEs in the literature
+(certainly not as many as demographic models!).
+How, then, to add selection to your simulation of a species without a published DFE?
+By diving into :ref:`the API <sec_api_dfes>` you could build one yourself.
+However, it's easier to borrow one from another species,
+and arguably biologically more plausible.
+(At least some aspects of the DFE should be shared at least by some species,
+such as the swath of deleterious mutations due to breakages in cellular machinery.)
+For some discussion of this,
+see `Kyriazis et al 2022 <https://www.biorxiv.org/content/10.1101/2022.08.12.503792v1>`_,
+which proposes a "generic" DFE for use in a variety of contexts.
+This DFE was estimated from human data, so it's under HomSap:
+
+.. code-block:: python
+
+    homsap = stdpopsim.get_species("HomSap")
+    dfe = homsap.get_dfe("Mixed_K23")
+    print(dfe.long_description)
+
+Even though the DFE is stored under HomSap in the catalogue,
+we can apply it to a contig from any species.
+For instance, we could apply it to the first 100Kb
+of the :ref:`Vaquita <sec_catalog_PhoSin>` chromosome 1:
+
+.. code-block:: python
+
+    vaquita = stdpopsim.get_species("PhoSin")
+    contig = vaquita.get_contig("1", right=1e5)
+    contig.add_dfe(intervals=[[0, 1e5]], DFE=dfe)
+    model = vaquita.get_demographic_model("Vaquita2Epoch_1R22")
+    samples = {"Vaquita": 50}
+
+    engine = stdpopsim.get_engine("slim")
+    ts = engine.simulate(
+        model,
+        contig,
+        samples,
+        seed=159,
+        slim_scaling_factor=10,
+        slim_burn_in=10,
+    )
+
+To make the example quick, we've only simulated the first 100Kb;
+a more realistic example would apply it to the exons, available
+as a :ref:`annotation <sec_catalog_phosin_annotations>`.
+
 .. _sec_tute_analyses:
 
 *******************************