From 58e14ae587fde8f4fd8915860b74bf6d31281e24 Mon Sep 17 00:00:00 2001
From: "Kevin R. Thornton" <krthornt@uci.edu>
Date: Tue, 5 Dec 2023 17:55:42 -0800
Subject: [PATCH] Update vignetted on "recapitation". (#1241)

Closes #1152
---
 doc/short_vignettes/recapitation.md | 40 ++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/doc/short_vignettes/recapitation.md b/doc/short_vignettes/recapitation.md
index 032ea6ac8..46b7dc9e8 100644
--- a/doc/short_vignettes/recapitation.md
+++ b/doc/short_vignettes/recapitation.md
@@ -45,15 +45,53 @@ assert pop.generation == 10
 Now we use `msprime` to coalesce the founder generation roots back to a common ancestor:
 
 ```{code-cell} python
+import demes
 import msprime
 
+
 # Convert to tskit format
 ts = pop.dump_tables_to_tskit()
 
 num_roots_pre_recapitation = ts.first().num_roots
 
-recapitated_ts = msprime.simulate(from_ts=ts)
+yaml=f"""
+time_units: generations
+demes:
+ - name: deme0
+   epochs:
+    - start_size: {pop.N}
+"""
+graph = demes.loads(yaml)
+demography = msprime.Demography.from_demes(graph)
+
+recapitated_ts = msprime.sim_ancestry(demography=demography, initial_state=ts)
 
 print(num_roots_pre_recapitation, recapitated_ts.first().num_roots)
 ```
+## Important considerations
+
+The previous example was very simple.
+The model involved no recombination and a single deme.
+
+### Demography
+
+In the above example, we had to provide `msprime` a demographic model.
+That model must be the correct model for the first generation of your simulation!
+
+### Recombination/genetic maps
+
+You must take care to proved `msprime` with a correct genetic map!
+This software and `msprime` differ in some key ways:
+
+* Here, rates are per *genomic segment*.  In `msprime`, rates are per "base pair".
+* For forward simulations with unlinked regions, you must take special care when defining a recombination map in `msprime`
+
+### Using the proper backwards-time model
+
+`msprime` supports a few different models of the backwards process.
+The two most relevant to this discussion are the "Hudson" and "discrete-time Wright-Fisher" models.
+The former is the continuous approximation with recombination and is what most people think of when they think "coalescent simulation".
+The latter model allows you to couple Wright-Fisher dynamics to model the recent past with the Hudson algorithm to simulate more ancient events.
+You will want to read the msprime [documentation](https://tskit.dev/msprime/docs/stable/intro.html) and the literature cited therein to make a decision about how to best model the ancestry of the ancestral roots of your simulation.
+