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-6. Run with migrate-n 6.1.90 (the fixes in 6.1.91 do not touch these models).

Real data sets combine loci that differ: nuclear, X-linked and mitochondrial loci have different effective population sizes, and loci mutate at different rates. This recipe shows how to tell Migrate about both, what goes wrong when one ignores them, and how to turn Migrate’s mutation-scaled parameters into population sizes, migration rates, numbers of migrants and years. Read 00-basics and 01-migration first.

Contents

  1. The data and the true values
  2. Loci with different inheritance: inheritance-scalars
  3. Results with and without inheritance scalars
  4. Loci with different mutation rates: the mutation option
  5. From parameters to biology
  6. What next

1. The data and the true values

Two populations, North and South, 10 loci of 1,000 sites, 10 sequences per population and locus, simulated with msprime under the Jukes-Cantor model (scripts/simulate_loci.py; truth in data/truth.json). The biology, forward in time:

QuantityNorthSouth
Ne (diploid individuals)250,000125,000
immigrants per generation, as a fraction of the population1e-6 (from South)2e-6 (from North)

with a mutation rate u = 1e-8 per site and generation. On Migrate’s scale, for an autosomal locus:

ParameterFormulaTrue
Theta_1, Theta_24 Ne u0.01, 0.005
M_2->1 (into North from South)m / u100
M_1->2 (into South from North)m / u200
4Nm into North, into SouthTheta M1, 1

Two data sets:

DataLoci
data/inherit.txt1-6 autosomal, 7-8 X-linked (Ne x 3/4), 9-10 mitochondrial (Ne x 1/4); the same m for every locus
data/rates.txt10 autosomal loci with mutation rates r u, r = 0.8, 1.0, 1.0, 0.4, 1.2, 0.6, 0.2, 1.8, 1.4, 1.6 (mean 1)

All runs: long-sample=40000, heating=YES:1:POWER:5, M prior uniform 0-1000; 11 MPI processes, 16-18 minutes each.

2. Loci with different inheritance: inheritance-scalars

The coalescence rate of a locus depends on how many copies of it the population carries. Relative to an autosomal locus (4 Ne copies), an X-linked locus has 3 Ne copies (scalar 0.75) and a mitochondrial locus Ne (scalar 0.25, with equal numbers of females and males). Migrate multiplies Theta of a locus by its scalar:

inheritance-scalars=YES:{1 1 1 1 1 1 0.75 0.75 0.25 0.25}

one value per locus, in the order of the infile. All reported Theta are on the scale of a scalar of 1 (here: autosomal, 4 Ne u). A scalar changes only Theta: M = m / u is the same for every locus, so Migrate assumes that migration is the same for all loci (no sex-specific migration).

With inheritance-scalars=NO every locus is treated as autosomal.

3. Results with and without inheritance scalars

Joint medians and 95% intervals (parmfiles/parmfile.inherit-none, parmfile.inherit-scalars):

ParameterTrueno scalarsscalars
Theta_10.0100.0120 [0.0085-0.0162]0.0150 [0.0107-0.0195]
Theta_20.0050.0034 [0.0020-0.0049]0.0045 [0.0029-0.0064]
M_2->110070* [3-143]76 [4-155]
M_1->2200198 [63-422]179 [57-379]
ModelTIBTISS
no scalars-18832.0-18792.8-18665.8
scalars-18818.0-18780.4-18657.2

The model with scalars is preferred by 12-14 log units, and it moves Theta_2 to the truth. Without scalars the mitochondrial and X-linked loci, which carry less diversity, are read as autosomal: the per-locus Theta_1 of the two mitochondrial loci is 0.004 and 0.008, and Theta_2 of the combination is too low. With scalars these two loci give 0.015 and 0.030 on the autosomal scale.

Theta_1 with scalars is too high in this data set (the interval just excludes 0.010). Whether that is chance in one data set or a bias is not known yet: a study with 20 simulated data sets would tell.

4. Loci with different mutation rates: the mutation option

A locus that mutates r times faster than average has r times the Theta, and its migration rate on the mutation scale is M / r (m stays the same, u is r times larger):

Theta_locus = r Theta      M_locus = M / r

The option mutation= tells Migrate about r:

mutation=Meaning
CONSTANTevery locus has r = 1 (the default)
OWN:10: 0.8 1.0 ...r given by the user, one per locus
DATAr from the data: Watterson’s Theta of each locus divided by the mean over loci (migration is ignored)
ESTIMATEone rate for all loci, estimated; needs dated samples (tipdate-file), see 02-divergence and 04-skyline. Without dates Migrate warns and uses CONSTANT

DATA prints its rates in the outfile. For rates.txt:

Locus12345678910
true r0.81.01.00.41.20.60.21.81.41.6
DATA0.780.860.860.351.580.550.311.721.521.48

Joint medians (parmfile.rates-constant, -own, -data):

ParameterTrueCONSTANTOWN (true r)DATA
Theta_10.0100.0102 [0.0071-0.0131]0.0103 [0.0077-0.0129]0.0105 [0.0078-0.0133]
Theta_20.0050.0037 [0.0024-0.0052]0.0038 [0.0025-0.0053]0.0040 [0.0025-0.0056]
M_2->110039 [0-175]22 [0-115]18 [0-100]
M_1->2200320 [129-557]319 [155-520]326 [151-531]
ModelTIBTISS
CONSTANT-18114.1-18084.9-17959.2
OWN-18098.5-18070.1-17947.3
DATA-18099.1-18070.8-17956.1

The Bayes factors pick the varying rates clearly: OWN and DATA are 14-15 log units ahead of CONSTANT, and DATA is as good as knowing the true rates. The estimates themselves barely change in this data set: with a mean rate of 1, the fast and the slow loci pull Theta in opposite directions. The migration rate into the larger population (M_2->1) is poorly estimated in every model; the data hold little information about it.

5. From parameters to biology

Migrate estimates parameters scaled by the mutation rate u (per site and generation for DNA, per locus for microsatellites). With u known from other sources:

Migrate parameterBiological quantityFormula
Theta = 4 Ne ueffective population size NeTheta / (4 u)
M = m / ufraction of immigrants per generation mM u
Theta M = 4 Ne mnumber of immigrants per generation (x4)no u needed
D (split time)generations before presentD / u; years: x generation time
g (growth)growth rate per generationg u

With dated samples (tipdate-file) Migrate uses mutationrate-per-generation and generation-per-year itself, to place the samples on the mutation scale (02-divergence, 04-skyline). Without dates it uses neither: every conversion in the table above is done by the reader.

The rates.txt runs with the true rates (OWN), u = 1e-8:

QuantityEstimateTrue
Ne North0.0103 / 4e-8 = 258,000250,000
Ne South0.0038 / 4e-8 = 96,000125,000
m into North22 x 1e-8 = 2.2e-71e-6
m into South319 x 1e-8 = 3.2e-62e-6
4Nm into North0.0103 x 22 = 0.231
4Nm into South0.0038 x 319 = 1.211

Two things to keep in mind. Every conversion inherits the error of u: a rate that is off by a factor 2 changes Ne, m and times by a factor 2, but not 4Nm. And a converted estimate is only as good as the Migrate estimate it comes from: the low M_2->1 makes m and 4Nm into North too low.

11a-stdpopsim-orangutans applies all conversions, including split times and growth rates, to a published model.

6. What next

  • A replicate study (20 simulated data sets) for the Theta_1 estimate with inheritance scalars.
  • A recipe with dated samples for mutation=ESTIMATE.
  • 09-mutation-models: what happens when the mutation model, rather than the rate, is wrong.

Available Materials