09 Mutation models and data types
Draft: work in progress. This recipe is not finished yet; sections may be incomplete and results may change.
Status: draft (2026-11-15), sections 1-8. DNA runs with migrate-n 6.1.90,
sequencing-error and microsatellite runs with 6.1.91 (the 6.1.91 fixes that
matter here: sequencing-error rates stay below 1/3, and rates=N with
prob-rates=laguerre:ALPHA works).
Migrate needs a model for how the markers mutate. This recipe simulates data under a realistic DNA model (unequal base frequencies, transitions more frequent than transversions, rate variation among sites), adds sequencing errors, keeps only the variable sites (SNPs), and simulates microsatellites, and analyses each with the right and with simpler models. Read 00-basics and 05-model-selection first.
Contents
- The data and the true values
- DNA models in the parmfile
- DNA: does the substitution model matter?
- Sequencing errors
- SNPs
- Microsatellites: Brownian, stepwise, and the allele model
- Choosing the model
- What next
1. The data and the true values
Two populations, North and South, 10 loci, 10 sequences (or 10 diploid
individuals) per population, simulated with msprime
(scripts/simulate_models.py; truth in data/truth.json):
| Data | Markers | Model of the simulation |
|---|---|---|
data/hkyg.txt | DNA, 1,000 sites per locus | HKY, kappa 10, base frequencies A 0.35, C 0.15, G 0.15, T 0.35, gamma site rates with shape 0.5 |
data/hkyg-err.txt | the same sequences | every base misread with probability 0.003 (0.001 for each of the three wrong bases) |
data/snp.txt | the variable sites of hkyg.txt | 1,507 of 10,000 sites (65-236 per locus) |
data/smm.txt | microsatellites | single-step mutations |
The true values on Migrate’s scale:
| Parameter | DNA | Microsatellites |
|---|---|---|
| Theta_1, Theta_2 | 0.01, 0.005 | 10, 5 |
| M_2->1 (into North from South) | 5 | 0.005 |
| M_1->2 (into South from North) | 10 | 0.01 |
| 4Nm into North, into South | 0.05, 0.05 | 0.05, 0.05 |
Both marker types share one demography; they differ in the mutation rate (1e-7 per site and generation for DNA, 1e-4 per locus and generation for the microsatellites), so Theta and M differ by the factor 1,000 but Theta x M (4Nm) is the same.
All runs: heating=YES:1:POWER:5, default run length (10,000 samples) unless
noted, 11 MPI processes. scripts/make_parmfiles.sh writes every parmfile.
2. DNA models in the parmfile
| Line | Meaning |
|---|---|
datamodel=JC69 | Jukes-Cantor: equal base frequencies, one rate for all changes |
datamodel=K2P | Kimura: equal frequencies, transitions kappa times as fast |
datamodel=F81 | unequal frequencies, one rate |
datamodel=F84 | unequal frequencies, transitions faster (Migrate’s default, kappa 2) |
datamodel=HKY | unequal frequencies, transitions kappa times as fast |
datamodel=TN | unequal frequencies, two transition rates |
ttratio=10.0 | kappa: the ratio of transition to transversion rates (not the observed ratio of counts) |
freqs-from-data=YES | base frequencies from the data (each locus) |
Migrate does not estimate kappa or the site-rate shape; take them from a program that does (for example a model-selection run in a phylogenetics package) and put them in the parmfile.
Rate variation among sites uses discrete categories. Gamma rates with shape 0.5 and 4 categories (Gauss-Laguerre quadrature, as the menu computes them):
rates=4: 0.290607 2.678195 7.853927 17.177271
prob-rates=4: 0.746025 0.234480 0.019270 0.000225
Since 6.1.91 and 7.0.115 the short form does the same:
rates=4
prob-rates=laguerre:0.5
(Migrate 6.1.90 and older accepted the short form silently and ran without rate variation; use the explicit lists with those versions.)
3. DNA: does the substitution model matter?
hkyg.txt analysed with four models (Joint medians, 95% intervals):
| Model | Theta_1 | Theta_2 | M_2->1 | M_1->2 | BTI |
|---|---|---|---|---|---|
| JC69 | 0.0104 [0.0078-0.0132] | 0.0046 | 5.7 [0-15.3] | 11.0 [0-21.3] | -22380.1 |
| F84, kappa 2 | 0.0105 [0.0077-0.0133] | 0.0047 | 4.3 [0-12.7] | 11.7 [2.0-22.0] | -20846.8 |
| HKY, kappa 10 | 0.0105 [0.0077-0.0131] | 0.0046 | 4.3 [0-12.7] | 11.7 [2.0-21.3] | -20839.3 |
| HKY + gamma | 0.0106 [0.0079-0.0136] | 0.0047 | 4.3 [0-11.3] | 7.0 [0.7-14.7] | -20785.2 |
True: 0.01, 0.005, 5, 10. Run times 3 minutes (HKY + gamma: 5).
With this little divergence (Theta 0.01: about one difference per 100 sites) the substitution model hardly changes the estimates: few sites have changed more than once, so how multiple changes are corrected matters little. The marginal likelihood sees the difference clearly: HKY + gamma is ahead by 54 log units of HKY, and JC69 is 1,500 log units behind (its equal base frequencies do not fit). With more divergent data (larger Theta, or loci that saturate) the model also changes the estimates; there, too, the marginal likelihood picks it.
4. Sequencing errors
A misread base looks like a new mutation on a terminal branch. Migrate can take this into account:
| Line | Meaning |
|---|---|
seqerror-rate={0,0,0,0} | no errors (the default) |
seqerror-rate={0.001,0.001,0.001,0.001} | fixed: the probability of reading each wrong base (here the true value) |
seqerror-rate=Estimate:1 | estimated, one rate per locus (prior Beta(1,10) on [0, 1/3)) |
The value is the probability of each wrong base: with 0.001 a base is misread with probability 0.003 in total.
hkyg-err.txt, HKY + gamma, 16 heated chains (heating=YES:1:POWER:16):
| Model | Theta_1 | Theta_2 | M_2->1 | M_1->2 | BTI |
|---|---|---|---|---|---|
| errors ignored | 0.0365 [0.0285-0.0451] | 0.0299 | 1.7 | 7.7 | -25630.3 |
| fixed at the true rate | 0.0104 [0.0077-0.0135] | 0.0047 | 5.0 | 7.0 | -25117.5 |
| estimated | 0.0106 [0.0079-0.0139] | 0.0048 | 3.7 | 7.7 | -25180.4 |
Ignoring the errors makes Theta 3.7 and 6 times too large: with 0.3% errors per base and Theta 0.01, a large part of the singletons are errors. Fixing or estimating the error rate gives the true Theta. The estimated rates are 0.0008-0.0013 per locus (true 0.001).
The model with the fixed rate has the higher marginal likelihood (by 63): estimating adds 10 rates with a prior that is wide compared with what the data allow (Beta(1,10): mean 0.09, the data pin each rate to about 0.0001), and each costs about 6 log units (the ratio of posterior to prior width). That is the price of not knowing the rate; when the error rate of the sequencing technology is known, fix it. With 5 chains the same comparison gave 85 (the hot chains wander to large error rates); 16 chains are needed for this comparison.
Before 6.1.91 and 7.0.115 the estimated error rate could go above 1/3 in the heated chains, which broke the marginal likelihood (values like -1e190).
5. SNPs
datatype=NucleotidePolymorphismData (SNP data) keeps only the variable
sites. snp.txt (HKY, kappa 10, Theta prior uniform 0-0.5):
| Parameter | DNA (all sites, HKY + gamma) | SNPs |
|---|---|---|
| Theta_1 | 0.0106 | 0.0278 [0.0197-0.0367] |
| Theta_2 | 0.0047 | 0.0125 [0.0087-0.0167] |
| M_2->1 | 4.3 | 1.7 [0-4.7] |
| M_1->2 | 7.0 | 3.0 [0-6.0] |
Theta is per site: without the invariant sites it is larger and cannot be
compared with the DNA value (06-assignment, section 6.3). The ratio
Theta_1/Theta_2 (2.2) and the M estimates are what one can use. Here M comes
out lower than with all sites. If the number of sites per locus is known,
the full sequences (or the SNPs with freqs-from-data=... totalsites) are
the better data.
6. Microsatellites: Brownian, stepwise, and the allele model
| Line | Model |
|---|---|
datatype=BrownianData | Brownian motion approximation of the stepwise model (fast) |
datatype=MicrosatelliteData | single-step model (exact, slower) |
datatype=AllelicData | allele model: K equal alleles (K = observed alleles + 1), meant for electrophoretic markers |
smm.txt, Theta prior uniform 0-50, M prior uniform 0-10, four replicates
per locus (replicate=YES:4, 41 MPI processes):
| Model | Theta_1 | Theta_2 | M_2->1 | M_1->2 | Minutes |
|---|---|---|---|---|---|
| Brownian | 16.1* [11.1-21.1] | 5.6* [4.0-7.4] | 0.010* [0-0.047] | 0.010* [0-0.073] | 34 |
| stepwise | 14.1* [8.7-20.7] | 6.7* [4.0-10.2] | 0.010* [0-0.127] | 0.037* [0-0.073] | 49 |
| allele | 8.5* [3.9-16.7] | 2.7* [0.6-6.2] | 0.28* [0.05-0.59] | 0.33* [0-2.36] | 28 |
True: 10, 5, 0.005, 0.01. () Joint rows: the Joint estimates of 10 microsatellite loci with this little gene flow are noisy even with four replicates per locus (reweighting ESS 20-85); with ten loci, read them as rough.
The stepwise model contains the truth for all four parameters; the Brownian approximation overestimates Theta_1 here (its interval just excludes 10). The allele model does not describe stepwise data: it treats two alleles of neighbouring lengths as unrelated as two alleles far apart, and its M is far too high.
The marginal likelihoods of the three models are not comparable: the Brownian model is a density on allele lengths, the others are probabilities of alleles.
7. Choosing the model
- DNA: start from the model a substitution-model selection suggests (with kappa and gamma shape), and compare it with simpler ones using marginal likelihoods (05-model-selection). The estimates of Theta and M are robust to the substitution model when the loci are not saturated.
- Sequencing errors matter far more than the substitution model when the diversity is low: an error rate of 0.1% per base and Theta of 1% are of the same order. Fix the error rate when it is known, estimate it otherwise.
- SNPs: Theta is per variable site; report ratios, or keep the invariant sites.
- Microsatellites: Brownian for speed, stepwise to check; not the allele model.
8. What next
- More microsatellite loci would make the Joint estimates usable.
- 10-loci-and-units: loci with different inheritance and mutation rates, and the conversion of Theta and M to population sizes and migration rates.