Draft: work in progress. This recipe is not finished yet; sections may be incomplete and results may change.

Status: draft (2026-11-16), sections 1-9. Run with migrate-n 6.1.91 and 7.0.115 (identical results with the same seed); section 8 with 7.0.115, its loci series with 6.1.92 on HPC.

stdpopsim is a catalogue of published demographic models with their mutation rates and generation times. A data set simulated from one of them is a realistic test: the true values are given in generations, years and numbers of individuals, and the model is not one that Migrate was written for. This recipe takes the two-species orangutan model of Locke et al. (2011), simulates DNA loci with stdpopsim, analyses them with the closest Migrate model (a split with migration and growth), converts the estimates to population sizes, migration rates and years, and compares them with the published values. Read 02-divergence, 03-growth and 10-loci-and-units first.

Contents

  1. The model
  2. The data
  3. The Migrate model and the parmfile
  4. Results on Migrate’s scale
  5. Converting to individuals, migrants and years
  6. Growth or constant size?
  7. Joint and All
  8. An unsampled ancestor
  9. What next

1. The model

stdpopsim PonAbe, model TwoSpecies_2L11 (Locke et al. 2011, Nature 469:529), fitted to the joint site-frequency spectrum of ten Bornean and ten Sumatran orangutans. Forward in time:

  • an ancestral population of 17,934 individuals splits 20,160 generations ago (504,000 years at 25 years per generation);
  • after the split, Bornean orangutans shrink slowly from 10,617 to 8,805 individuals today, and Sumatran orangutans grow from 7,317 to 37,661;
  • both exchange migrants after the split: each generation a fraction 6.66e-6 of the Bornean population are immigrants from Sumatra, and 1.10e-5 of the Sumatran population are immigrants from Borneo;
  • mutation rate 2e-8 per site and generation.

2. The data

scripts/simulate_orangutans.py runs stdpopsim (0.3.0, msprime engine) for 20 independent loci of 5,000 sites with 5 diploid individuals (10 sequences) per species. Each locus is simulated separately, so the loci are unlinked.

DataRecombination within a locusSegregating sites per locus
data/norec.txtnone (Migrate’s assumption)16-41
data/rec.txtstdpopsim’s mean rate for PonAbe, 6.4e-9 per site and generation11-60

The two files are separate simulations (different genealogies), not the same genealogies with and without recombination. data/truth.json holds the model values and their versions on Migrate’s scale.

stdpopsim simulates with the Jukes-Cantor model, so the parmfiles use datamodel=JC69.

3. The Migrate model and the parmfile

Population 1 is Bornean, population 2 Sumatran. In Migrate’s split model one population continues the ancestral lineage: backward in time (lineage view), the Sumatran lineages move into population 1 at the split time. The model has

  • Theta and exponential growth for each population (03-growth);
  • migration in both directions after the split;
  • a split time D with a spread S (02-divergence).
custom-migration={** D*}
population-growth={1 2}
divergence-distrib=N
bayes-priors= THETA * * UNIFORMPRIOR: 0.0 0.01 0.001
bayes-priors= MIG * * UNIFORMPRIOR: 0.0 2000.0 200.0
bayes-priors= SPLIT * * GAMMAPRIOR: 0.0 0.001 0.005 2.0
bayes-priors= SPLITSTD * * EXPPRIOR: 0.0 0.0001 0.0005
bayes-priors= GROWTH * * UNIFORMPRIOR: -2000.0 10000.0 1000.0
long-sample=40000
joint-samples=10000
heating=YES:1:POWER:5

The constant-size model uses population-growth={0} (section 6). scripts/make_parmfiles.sh writes all four parmfiles (norec/rec x growth/const).

What Migrate’s model cannot express: stdpopsim’s ancestral population (17,934 individuals) differs from the population that continues it in Migrate, the Bornean population with its own size and growth rate. With the estimated growth (section 4), Migrate’s Bornean population is about 12,000 individuals at the split, two thirds of the true ancestral size.

M_2->1 here is migration from the daughter population into the ancestral lineage, forward in time. Backward in time a lineage can move into the Sumatran population only while it exists, that is, up to the split time. Since 7.0.115/6.1.91 the Joint combination (section 7) handles this; older versions used All for this model (7.0.x) or combined it wrongly (6.1.x).

joint-samples=10000 keeps up to 10,000 genealogies per locus for the Joint combination. The default keeps about 900 for this model (it is bounded by memory, and a split model with growth stores many numbers per genealogy), which left most Joint estimates flagged (Joint*, reweighting ESS about 24). With 10,000 the reweighting ESS was 77-112.

Run time on 21 MPI processes (one per locus, plus the master): 11-19 minutes.

4. Results on Migrate’s scale

Joint medians and 95% intervals. The true values on Migrate’s scale: Theta = 4 Ne u with today’s Ne, M = m / u, g = (growth rate per generation) / u, D = generations x u.

ParameterTruerec.txtnorec.txt
Theta_1 (Bornean)0.000700.00072 [0.00053-0.00090]0.00077 [0.00053-0.00107]
Theta_2 (Sumatran)0.003010.00269 [0.00172-0.00399]0.00222 [0.00148-0.00322]
M_2->1 (into Bornean)333517 [177-928]749 [89-1336]
M_1->2 (into Sumatran)550423 [145-749]562 [203-1029]
g_1 (Bornean)-464-412 [-768 to -88]148 [-784 to 3392]
g_2 (Sumatran)40652548* [792-4384]2356 [768-4800]
D (split)0.0004030.00067* [0.00052-0.00088]0.00146 [0.00038-0.00258]

() Joint rows: the reweighting check flags these as noisy (section 7).

Every interval contains the true value except the split time of rec.txt, which is too old (0.00067 against 0.00040). A possible reason, not checked: the ancestral population of the model is about 1.5 times as large as the population that continues it in Migrate (section 3), and a smaller ancestor coalesces the lineages faster after the split, which the model can accommodate by placing the split earlier (backward in time: at a greater age). Section 8 tests this with a separate ancestor. norec.txt gives a wide interval that contains the truth.

The Bornean growth rate is negative in the model (the population shrinks forward in time); rec.txt recovers the sign, norec.txt does not (its interval covers both signs). With 10 sequences per population, a growth rate that changes the population size by 20% over half a million years is hard to see.

Recombination within the 5,000-site loci (a crossover about every 31,000 generations along each lineage of a locus, so several in the genealogy of a locus) did not change the estimates noticeably in these two data sets.

5. Converting to individuals, migrants and years

Migrate’s parameters contain the mutation rate (10-loci-and-units, section 5). With u = 2e-8 per site and generation and 25 years per generation (rec.txt, Joint medians):

QuantityFormulaEstimatePublished
Ne Bornean (today)Theta_1 / (4u)9,0008,805
Ne Sumatran (today)Theta_2 / (4u)33,60037,661
m into BorneanM_2->1 u1.03e-56.66e-6
m into SumatranM_1->2 u8.5e-61.10e-5
4Nm into BorneanTheta_1 M_2->10.370.23
4Nm into SumatranTheta_2 M_1->21.141.66
growth Bornean, per generationg_1 u-8.2e-6-9.3e-6
growth Sumatran, per generationg_2 u5.1e-58.1e-5
split, generations agoD / u33,50020,160
split, years agoD / u x 25840,000504,000

The 4Nm values do not need the mutation rate at all: they are products of two estimated parameters. Everything else is only as good as u: a mutation rate that is off by a factor 2 changes every Ne, m, growth rate and time by the same factor 2.

6. Growth or constant size?

Marginal likelihoods (All (joint) row, log units; higher is better):

DataModelTIBTISS
norec.txtgrowth-145793.3-145728.2-145528.9
norec.txtconstant-145815.2-145747.9-145553.5
rec.txtgrowth-145994.9-145934.8-145773.6
rec.txtconstant-146020.4-145958.5-145787.9

All three estimators prefer growth, by 20-25 log units (BTI), in both data sets: the true model wins. The values of the two data sets are not comparable with each other (different data).

7. Joint and All

The All row multiplies the per-locus posteriors parameter by parameter (00-basics, section 8); the Joint row combines the loci with their genealogies. For the split time they disagree strongly (rec.txt):

ParameterTrueJointAll
D (split)0.0004030.00067 [0.00052-0.00088]0.00388 [0.00384-0.00399]
g_1 (Bornean)-464-412 [-768 to -88]8284 [1080-9992]
Theta_2 (Sumatran)0.003010.00269 [0.00172-0.00399]0.00215 [0.00143-0.00376]

Most single loci say little about the split time (few lineages reach it), so each locus’ posterior of D is wide and leans toward large values; their product (All) piles up near the upper end of the prior (0.005). The All estimate of D is ten times the truth and its interval is very narrow; the Joint estimate is within a factor 2. The same happens to the Bornean growth rate. Report the Joint rows; when they carry a star (Joint*), run longer, add replicates or raise joint-samples rather than fall back to All.

8. An unsampled ancestor

The model of sections 3-7 lets the Bornean population stand in for the ancestor. Migrate can instead add the ancestor as a third population without samples, from which both species split at the same time:

3 20 PonAbe TwoSpecies_2L11 with recombination, unsampled ancestor
...                                   (the two sampled populations as before)
0 Ancestor
custom-migration={**t **t 00*}
population-growth={1 2 0}

The infiles data/norec3.txt and data/rec3.txt are the same data with the empty third population. t marks tied splits: populations 1 and 2 split from population 3 with one shared split time (02-divergence); the two daughters exchange migrants, the ancestor gets its own Theta_3 and no growth. This is the structure of the stdpopsim model. Migration into either daughter (backward in time) is possible only up to the split, so both migration rates are gated (section 3). Parmfiles parmfile.norec-anc and parmfile.rec-anc; 21 MPI processes, 25-28 minutes.

Joint medians and 95% intervals, rec3.txt:

ParameterTruethree populationstwo populations (section 4)
Theta_1 (Bornean)0.000700.00082 [0.00047-0.00131]0.00072 [0.00053-0.00090]
Theta_2 (Sumatran)0.003010.00370 [0.00194-0.00621]0.00269 [0.00172-0.00399]
Theta_3 (ancestor)0.001430.00145 [0.00089-0.00200]-
M_2->1333470* [63-1037]517 [177-928]
M_1->2550358 [87-721]423 [145-749]
g_1-4641804 [-1968 to 7824]-412 [-768 to -88]
g_240656100* [2232-9968]2548* [792-4384]
D (split)0.0004030.00045* [0.00023-0.00078]0.00067* [0.00052-0.00088]

With its own ancestor the split time is right (0.00045 against 0.00040; the two-population model put it at 0.00067), and the ancestral size is recovered (Theta_3 0.00145 against 0.00143: 18,000 individuals against the published 17,934). This supports the explanation of section 4: the two-population model moved the split back in time because its ancestor was too small. The price is precision: the Bornean growth rate is no longer determined (its interval covers both signs), and the intervals of Theta_2 and g_2 are wider. In norec3.txt Theta_3 is not determined (0.0009, 0-0.008) and D stays wide (0.0014, 0.00023-0.0033).

DataModelTIBTISS
rec.txttwo populations, growth-145994.9-145934.8-145773.6
rec3.txtthree populations-146001.7-145940.5-145776.1
norec.txttwo populations, growth-145793.3-145728.2-145528.9
norec3.txtthree populations-145803.4-145737.3-145548.9

With five heated chains, as in these runs, the marginal likelihoods prefer the two-population model by 6-9 log units (BTI). That margin does not hold up with a longer ladder. With 16 chains (heating=YES:1:POWER:16, 6.1.92) the two models nearly tie on rec.txt, so five chains were too few for this comparison (05-model-selection).

How many loci does the ancestor need?

scripts/simulate_series.py simulates 80 new loci from the same model (with recombination; its first 20 loci are rec.txt) and writes data/series/rec{40,80}.txt and rec{40,80}_3.txt. These files (24 MB) are not in the repository; run the script to make them. All runs below used 16 chains on beerli_q/backfill2 with 21-60 MPI processes. Values are BTI, ancestor model minus two-population model; positive favours the ancestor:

LociReplicatesAll (independent parameters)All (joint)Median reweighting ESS, two-pop / ancestor
20 (norec.txt)1+7.8-1.998 / 35
20 (rec.txt)1+3.6+0.975 / 76
401+13.3+2.253 / 70
801+45.9-13.145 / 37
804+20.8-5.763 / 36
808, joint-samples=40000+18.7-10.8111 / 33

The (independent parameters) row gives every locus its own parameters (the product of the per-locus marginal likelihoods). The (joint) row shares one set of parameters across all loci, which is the model being compared. The two rows disagree:

  • The independent row favours the ancestor, and more so with more loci. Its 80-locus margin halved from one to four replicates (+45.9 to +20.8), so a single run overstates it.
  • The joint row stays near zero up to 40 loci and turns negative at 80. At 80 loci, however, the ancestor model’s joint combination has a median reweighting ESS below 50, and all eleven of its parameters are Joint* (section 7). Its joint marginal likelihood therefore rests on too few effective genealogies per locus; the reported MC error (1.1-1.8) covers only part of that uncertainty.

The ancestor model’s Joint medians and 95% intervals (truth: Theta_3 0.00143, D 0.000403):

LociReplicatesTheta_3D
20 (rec.txt)10.00128 [0.00089-0.00184]0.00048* [0.00032-0.00059]
4010.00117 [0.00085-0.00154]0.00045* [0.00034-0.00059]
8010.00103* [0.00081-0.00131]0.00043* [0.00032-0.00059]
8040.00098* [0.00077-0.00135]0.00043* [0.00037-0.00062]
808, joint-samples=400000.00056* [0.00029-0.00131]0.00144* [0.00015-0.00200]

Up to four replicates the split time stays right and the ancestral Theta_3 drifts down as loci are added. At 80 loci all estimates are starred. With eight replicates and four times the genealogies per locus, the two-population model’s joint combination improved (median reweighting ESS 63 to 111; M_1->2 and g_2 lost their stars). The ancestor model’s did not: its reweighting ESS stayed at 33, and its D jumped to three times the truth. The bootstrap error of that D (0.00044) is larger than its posterior standard deviation (0.00039). The joint marginal likelihood of the ancestor model hardly moved between the 4- and 8-replicate runs (-584048.6 and -584048.5, BTI). The two-population model’s moved by 5 log units, more than its reported MC error of 1.1.

At 80 loci the question is not settled. The two-population model’s joint combination works; the ancestor model’s does not, and more genealogies per locus did not fix it. A model choice answers which model the data support, not which model is true; the true model has to earn its extra parameters.

A parametric skyline (04-skyline) for the Bornean population would be another way to give the ancestor its own size. Since 6.1.93 and 7.0.117 skyline=PARAM works with migration out of a daughter population (gated at the split, as M_2->1 in {* * D *}); 6.1.92 and 7.0.116 refuse it.

9. What next

  • More individuals or loci would sharpen the split time and the Bornean growth rate; the model mismatch of the ancestral size (section 3) remains.
  • Other stdpopsim models with two or three populations and migration (HomSap OutOfAfrica_2T12, AnaPla MallardBlackDuck_2L19) would make 11b and 11c.
  • 05-model-selection shows how many heated chains a reliable comparison needs; sections 3-7 used five, the loci series of section 8 sixteen.

References

Locke DP et al. (2011) Comparative and demographic analysis of orang-utan genomes. Nature 469:529-533.

Adrion JR et al. (2020) A community-maintained standard library of population genetic models. eLife 9:e54967.

Available Materials